pfNewESky man page on IRIX

Printed from http://www.polarhome.com/service/man/?qf=pfNewESky&af=0&tf=2&of=IRIX



pfEarthSky(3pf)			OpenGL Performer 3.2.2 libpf C Reference Pages

NAME
     pfNewESky, pfGetESkyClassType, pfESkyMode, pfGetESkyMode, pfESkyAttr,
     pfGetESkyAttr, pfESkyColor, pfGetESkyColor, pfESkyFog, pfGetESkyFog,
     pfESkyFogDensities, pfGetESkyFogDensities, pfESkyFogTextureElevations,
     pfGetESkyFogTextureElevations, pfESkyFogTexture, pfGetESkyFogTexture,
     pfESkyFogTextureColorTable, pfGetESkyFogTextureColorTable,
     pfESkyLoadFogTextureColorTable, pfESkyMakeFogTexture - Create and control
     weather, Earth-Sky model, and screen clearing.

FUNCTION SPECIFICATION
     #include <Performer/pf.h>

     pfEarthSky *   pfNewESky(void);

     pfType *	    pfGetESkyClassType(void);

     void	    pfESkyMode(pfEarthSky *esky, int mode, int val);

     int	    pfGetESkyMode(pfEarthSky *esky, int	 mode);

     void	    pfESkyAttr(pfEarthSky *esky, int attr, float val);

     float	    pfGetESkyAttr(pfEarthSky *esky, int	 mode);

     void	    pfESkyColor(pfEarthSky *esky, int which, float r, float g,
		      float b, float a);

     void	    pfGetESkyColor(pfEarthSky *esky, int  which, float *r,
		      float *g, float *b, float *a);

     void	    pfESkyFog(pfEarthSky *esky, int which, pfFog *fog);

     pfFog *	    pfGetESkyFog(pfEarthSky *esky, int	which);

     void	    pfESkyFogDensities(pfEarthSky* _esky, int numpt,
		      float *elevations, float *densities);

     void	    pfGetESkyFogDensities(pfEarthSky* _esky, int *numpt,
		      float **elevations, float **densities);

     void	    pfESkyFogTextureElevations(pfEarthSky* _esky, int n,
		      float *elev);

     void	    pfGetESkyFogTextureElevations(pfEarthSky* _esky, int *n,
		      float **elev);

     void	    pfESkyFogTexture(pfEarthSky* _esky, pfTexture *tex);

     pfTexture*	    pfGetESkyFogTexture(pfEarthSky* _esky);

									Page 1

pfEarthSky(3pf)			OpenGL Performer 3.2.2 libpf C Reference Pages

     void	    pfESkyFogTextureColorTable(pfEarthSky* _esky, int n,
		      unsigned char *table);

     void	    pfGetESkyFogTextureColorTable(pfEarthSky* _esky, int *n,
		      unsigned char **table);

     void	    pfESkyLoadFogTextureColorTable(pfEarthSky* _esky);

     void	    pfESkyMakeFogTexture(pfEarthSky* _esky);

PARENT CLASS FUNCTIONS
     The OpenGL Performer class pfEarthSky is derived from the parent class
     pfObject, so each of these member functions of class pfObject are also
     directly usable with objects of class pfEarthSky.	Casting an object of
     class pfEarthSky to an object of class pfObject is taken care of
     automatically.  This is also true for casts to objects of ancestor
     classes of class pfObject.

     void	   pfUserDataSlot(pfObject *obj, int slot, void *data);
     void	   pfUserData(pfObject *obj, void *data);
     void*	   pfGetUserDataSlot(pfObject *obj, int slot);
     void*	   pfGetUserData(pfObject *obj);
     int	   pfGetNumUserData(pfObject *obj);
     int	   pfGetNamedUserDataSlot(const char *name);
     const char*   pfGetUserDataSlotName(int slot);
     int	   pfGetNumNamedUserDataSlots(void);
     int	   pfDeleteGLHandle(pfObject *obj);

     Since the class pfObject is itself derived from the parent class
     pfMemory, objects of class pfEarthSky can also be used with these
     functions designed for objects of class pfMemory.

     pfType *	    pfGetType(const void *ptr);
     int	    pfIsOfType(const void *ptr, pfType *type);
     int	    pfIsExactType(const void *ptr, pfType *type);
     const char *   pfGetTypeName(const void *ptr);
     int	    pfRef(void *ptr);
     int	    pfUnref(void *ptr);
     int	    pfUnrefDelete(void *ptr);
     int	    pfUnrefGetRef(void *ptr);
     int	    pfGetRef(const void *ptr);
     int	    pfCopy(void *dst, void *src);
     int	    pfDelete(void *ptr);
     int	    pfIsFluxed(void *ptr);
     int	    pfCompare(const void *ptr1, const void *ptr2);
     void	    pfPrint(const void *ptr, uint which, uint verbose,
		      FILE *file);
     void *	    pfGetArena(void *ptr);

									Page 2

pfEarthSky(3pf)			OpenGL Performer 3.2.2 libpf C Reference Pages

PARAMETERS
     esky  identifies a pfEarthSky.

DESCRIPTION
     These functions provide a means to clear the frame and Z-buffer, draw a
     sky, horizon and ground plane, and to implement various weather effects.
     Once the earth-sky is set in a channel, it should be the first thing
     drawn when a scene is rendered.

     pfNewESky creates and returns a handle to a pfEarthSky.  Like other
     pfNodes, pfEarthSky nodes are always allocated from shared memory and can
     be deleted using pfDelete.

     pfNewESky creates a pfEarthSky and sets up reasonable defaults.  To
     render the earth and sky model, it must be added to a pfChannel.  By
     default, the mode is to render a full screen clear unless either the sky
     or ground is turned on.  pfEarthSky is called automatically in the draw
     process, unless a draw callback is present, in which case, it must be
     explicitly called using pfClearChan.

     pfGetESkyClassType returns the pfType* for the class pfEarthSky.  The
     pfType* returned by pfGetESkyClassType is the same as the pfType*
     returned by invoking pfGetType on any instance of class pfEarthSky.
     Because OpenGL Performer allows subclassing of built-in types, when
     decisions are made based on the type of an object, it is usually better
     to use pfIsOfType to test if an object is of a type derived from a
     Performer type rather than to test for strict equality of the pfType*'s.

     pfESkyMode is used to set the earth-sky rendering mode.  pfGetESkyMode is
     used to obtain the earth-sky rendering mode. These functions currently
     accept the two mode arguments PFES_BUFFER_CLEAR, and PFES_CLOUDS.
	  PFES_BUFFER_CLEAR may have the following values:

	       PFES_FAST
		    The default mode.  This simply clears the color and Z
		    buffers.  The clear color can be set using pfESkyColor.
		    Dithering is turned off during the clear.

	       PFES_TAG Initializes the framebuffer to a known state very
		    rapidly.  Has an effect only when multisampling.  Often,
		    this mode is used as an optimization before rendering a
		    background that covers the entire screen.  See pfClear for
		    the details and restrictions of the mode PFCL_MSDEPTH.

	       PFES_SKY
		    Causes a sky and horizon backdrop to be drawn.  These are
		    drawn using large polygons that are recalculated each
		    frame, using information about the clipping planes, field
		    of view, and eyepoint vertical position for the selected
		    channel.  They are drawn instead of a screen clear,
		    forcing the Z buffer to a known state.  If the viewpoint
		    goes below the ground plane, the area below the horizon

									Page 3

pfEarthSky(3pf)			OpenGL Performer 3.2.2 libpf C Reference Pages

		    will not be cleared.  In the case of PFES_SKY, the screen
		    is never cleared below the lower edge of the horizon.

	       PFES_SKY_GRND
		    Add a ground plane to the sky and horizon model drawn by
		    PFES_SKY.

	       PFES_SKY_CLEAR
		    Draw the sky and horizon, and clear the screen below the
		    edge of the horizon.

	  PFES_CLOUDS is used to set the type of cloud layer.  Currently, the
	  only value supported is:

	       PFES_OVERCAST
		    This cloud type is a non-textured, opaque region that has
		    a color and both top and bottom dimensions.	 This, being
		    the only choice at present, is the default type.

     pfESkyColor is used to set the colors referenced by the earth-sky
     rendering routines.  pfGetESkyColor returns the indicated color component
     of the earth-sky mode. The components are:

	  PFES_SKY_TOP	      The color of the sky directly above the
			      viewpoint.

	  PFES_SKY_BOT	      The color of the sky where it joins the horizon.

	  PFES_HORIZ	      The color of the bottom edge of the horizon.

	  PFES_GRND_FAR	      The color of the ground plane where it meets the
			      horizon.

	  PFES_GRND_NEAR      The color of the ground plane directly below the
			      viewer.

	  PFES_CLOUD_BOT      The color of the bottom of the opaque cloud
			      layer.

	  PFES_CLOUD_TOP      The color of the top of the opaque cloud layer.

	  PFES_CLEAR	      The color for simple screen clearing.

     The fog color is set as explained in the pfFog man page.

     pfESkyAttr is used to set a number of attributes.	The companion function
     pfGetESkyAttr is used to return these same attribute values. The tokens
     and their meanings are listed below:

	  PFES_GRND_HT Set the ground height for the ground plane that is
	       used when PFES_SKY_GRND is enabled and defines the bottom edge
	       of the horizon which is used in all of the modes that draw a

									Page 4

pfEarthSky(3pf)			OpenGL Performer 3.2.2 libpf C Reference Pages

	       sky.  The ground plane extends from the eyepoint to the horizon
	       with a width greater than the field of view.  Note that objects
	       placed on the ground with the same height may not Z buffer
	       correctly.  Also, as objects move into the distance, the Z
	       buffer resolution for those pixels will decrease, making proper
	       priority resolution of small distances between the ground plane
	       and objects less likely.

	  PFES_HORIZ_ANGLE Set the vertical displacement of the horizon band
	       in degrees.  The horizon band is blended into the sky bottom
	       color so it may appear to be less than this angle.  This angle
	       remains constant for any heading.  To simulate directional
	       horizon glow, the angle and color can be changed each frame to
	       achieve the correct appearance.

	  PFES_CLOUD_TOP Set the cloud layer upper position.  The cloud layer
	       is enabled when the cloud base is less than the cloud top.  By
	       default, it is disabled (base > top).  Each token is followed
	       by a height value.  The cloud layer is opaque.  The cloud layer
	       thickness is simply (top - bottom).

	  PFES_CLOUD_BOT Set the cloud layer lower position.  The cloud layer
	       is enabled when the cloud base is less than the cloud top.  By
	       default, it is disabled (base > top).  Each token is followed
	       by a height value.  The cloud layer is opaque.  The cloud layer
	       thickness is simply (top - bottom).

	  PFES_TZONE_TOP Set the transition zone for exiting a cloud layer.
	       Provided to allow a smooth transition out of clouds.  This
	       transition is enabled by making the transition height greater
	       than the cloud top.  It is disabled by doing the opposite or by
	       disabling the cloud layer.  By default, the transition zone is
	       disabled.

	  PFES_TZONE_BOT Set the transition zone for entering a cloud layer.
	       Provided to allow a smooth transition into clouds.  This
	       transition is enabled by making the transition height less than
	       the cloud bottom.  It is disabled by doing the opposite or by
	       disabling the cloud layer.  By default, the transition zone is
	       disabled.

	  PFES_GRND_FOG_TOP Set the height of the ground fog layer.  Ground
	       fog is enabled when a valid pfFog is set.  By default ground
	       fog is disabled.

	  PFES_TENT_DISTANCE_FACTOR sets a factor for pulling the pfEarthSky
	       geometry towards the camera and away from the far clipping
	       plane. When using pfChannel offsets, the pfEarthSky geometry
	       may be clipped against the far clipping plane. In order to
	       avoid this artifact, the application may request to draw the
	       pfEarthSky geometry closer to the camera. A value of 1.0 means
	       drawing the geometry at the far clipping plane. a value of 0.0

									Page 5

pfEarthSky(3pf)			OpenGL Performer 3.2.2 libpf C Reference Pages

	       means drawing the geometry at the near plane. The default value
	       is 1.0.

     pfESkyFog sets which type of fog to use when in ground fog or general
     visibility.  The token may be one of the following values:
	  PFES_GRND
	  PFES_GENERAL
     pfGetESkyFog returns the indicated fog selection.

     Several different fog functions may be defined at initialization, then
     just switched in using this routine.  Distant haze and different curves
     would be done this way.  If ground fog is enabled, and the viewer is
     transitioning out of the ground fog layer, the fog will be blended into
     clear visibility or PFES_GENERAL fog.

     Due to the design of the graphics library, fog would be discontinuous in
     adjacent channels which use rotational viewing offsets (See
     pfChanViewOffsets).  However, when attached to a pfChannel (see
     pfChanESky) that has a rotational viewing offset, a pfEarthSky will
     automatically adjust the ranges of the pfFog set by pfESkyFog to account
     for any rotational offsets so that fog is continuous across adjacent
     channels.

NOTES
     pfEarthSky does not work properly for off-axis viewing frusta.

     Because PFES_TAG only has effect when multisampling, care must be taken
     for cross-platform portability.  Background renderings that rely on the
     depth buffer having been reset (e.g. backgrounds that do not disable z
     buffering with glDepthFunc(GL_ALWAYS) in OpenGL) may need to request a
     normal depth buffer clear when not multisampling.

     When multisampling, PFES_SKY_GND and PFES_SKY are significantly faster
     than PFES_SKY_CLEAR.

Layered Fog Support
     pfEarthSky provides basic support for creating a layered fog model based
     on the defined elevations and densities of the different atomospheric
     layers.  The resulting model is stored in a 3D texture where each slice
     of the 3D texture represents summed fog densities for an eye at a given
     elevation and  points at d,h where d is a horizontal distance from the
     eye and h is the height of the given point along a defined "up" vector. A
     texture lookup table (texture color table) is then use to exponentiate
     this value to turn the fog density into a fog blending factor.  pfTexGen
     functions are used to do the proper indexing into the fog model when
     rendering.	 This 3D texture can be used to apply a layered fog model as a
     second pass after first rendering an unfogged scene.
     pfESkyMakeFogTexture will create the fog texture and create it just based
     on the normal pfEarthSky definition, or use additional information, such
     as your own provided layers and densities for finer resolution. The
     following routines allow you to set and get the different parts of the

									Page 6

pfEarthSky(3pf)			OpenGL Performer 3.2.2 libpf C Reference Pages

     elements used to create the model:

	  pfESkyFogDensities

	  pfGetESkyFogDensities

	  pfESkyFogTextureElevations

	  pfGetESkyFogTextureElevations

	  pfESkyFogTexture

	  pfGetESkyFogTexture

	  pfESkyFogTextureColorTable

	  pfGetESkyFogTextureColorTable

	  pfESkyLoadFogTextureColorTable

	  /usr/share/Performer/src/sample/C/fogfly/
	  For an example of layerd fog look at the
	       demonstration program.

BUGS
     The layered fog model on pfEarthSky doesn't work with the pfEarthSky
     geometry.	Instead, you should define your own enviornmental geometry.

SEE ALSO
     pfChanViewOffsets, pfClear, pfFog, pfNewChan, zfunction, glDepthFunc,
     pfDelete

									Page 7

[top]

List of man pages available for IRIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net