Sophie: libopenrm1-1.5.2-2mdv2007.0 i586

libopenrm1-1.5.2-2mdv2007.0.i586.rpm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html><head><title>OpenRM - RM Library (rmfog.c)</title></head>
<body bgcolor=white fgcolor=black>
<table width="100%" border=2 cellspacing=0 cellpadding=0 bgcolor="khaki" valign="center">
<th><img src="./images/ormsg.gif">
</th>
</table>
<spacer type=vertical size=15>
<h2>Index of OpenRM - RM Library</h2>
<spacer type=vertical size=15>
<a name="rmFogNew"> 
<pre><b>
 RMfog * rmFogNew (void)
</b></pre>
<pre>
 No arguments.
</pre>
<menu><P>
 Creates a new RMfog object, returning a handle to the caller upon
 success, or NULL upon failure.
</P>
<P>
 The RMfog object provides access to a visual simulation technique
 that approximates the atmospheric effect of light absorption and
 scattering. To enable fogging, applications must first create an
 RMfog object, set parameters to desired values, then assign the RMfog
 object as a scene parameter to an RMnode. All objects that are
 descendents in the scene graph of the RMnode containing the RMfog
 scene parameter will be rendered with fogging activated.
</P>
<P>
 rmFogNew assigns OpenGL defaults to the RMfog object. Specifically:
</P>
<P>
 Fogging mode is set to GL_EXP, fog density is set to 1.0, fog start
 and end are set to 0.0 and 1.0, and the fog color is set to
 (0,0,0,0).
</P>
<P>
 See the rmFogSet* family of routines for detailed descriptions of fog
 parameters. In addition, the OpenGL red book is a good reference.
</P>
<P>
 Use rmFogDelete to remove the RMfog object when no longer needed.
</P></menu>
<i>librm library source file: rmfog.c </i><hr width="75%">
<a name="rmFogDup"> 
<pre><b>
 RMfog * rmFogDup (const RMfog *toDuplicate)
</b></pre>
<pre>
 const RMfog *toDuplicate - a handle to an RMfog object to duplicated
    (input).
</pre>
<menu><P>
 Creates a new RMfog object, copying the parameters from an existing
 RMfog object into the new RMfog object, and returns a handle to the
 new object to the caller upon success.  Otherwise, NULL is returned
 upon failure.
</P>
<P>
 Use rmFogDelete to free the RMfog object when no longer needed.
</P></menu>
<i>librm library source file: rmfog.c </i><hr width="75%">
<a name="rmFogDelete"> 
<pre><b>
 RMenum rmFogDelete (RMfog *toDelete)
</b></pre>
<pre>
 RMfog *toDelete - a handle to an RMfog object to be deleted
    (modified).
</pre>
<menu><P>
 Use this routine to release resources associated with an RMfog
 object.  Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P></menu>
<i>librm library source file: rmfog.c </i><hr width="75%">
<a name="rmFogSetMode"> 
<pre><b>
 RMenum rmFogSetMode (RMfog *toModify,
	              GLenum newMode)
</b></pre>
<pre>
 RMfog *toModify - a handle to an RMfog object to modify (modified).

 GLenum newMode - an OpenGL fog mode enumerator. Must be one of
    GL_LINEAR, GL_EXP or GL_EXP2.
</pre>
<menu><P>
 Use this routine to set the fogging mode of an RMfog object. Returns
 RM_CHILL upon success, or RM_WHACKED upon failure.
</P>
<P>
 Objects that are rendered using fogging appear to fade into the fog
 color (rmFogSetColor) as a function of distance from the
 viewpoint. Objects closer to the viewer are rendered with less fog
 color, objects further away appear to be rendered with more fog
 color.
</P>
<P>
 The three fogging parameters that may be controlled by applications
 are the fog color (rmFogSetColor), the front and back boundaries of
 the fogging itself (rmFogSetStartEnd) and the weighting function used
 for computing fog density (rmFogSetMode).
</P>
<P>
 The fogging functions are specified as one of GL_LINEAR, GL_EXP and
 GL_EXP2. In all methods, fog density is computed using the fog start
 and fog end, along with the Z coordinate of the object (pixel
 fragment) in eye-coordinates (after the model and view
 transformations have been applied, but before the projection matrix).
</P>
<P>
 In GL_LINEAR fogging, the fog density is computed as fogDensity =
 (fogEnd - Z)/(fogEnd-fogStart), then clamped to the range [0..1]. A
 value of Z that is less than fogStart will result in no fogging,
 while a value of Z that is greater than fogEnd will be fully
 fogged. Z values between fogEnd and fogStart are scaled linearly
 between 0.0 and 1.0.
</P>
<P>
 In GL_EXP fogging, the fog density is computed as fogDensity = e ^
 (-density * z), where density is one of the fogging parameters that
 may be controlled by applications.
</P>
<P>
 GL_EXP2 fogging is computed as fogDensity = e ^ ((-density * z)^2).
</P>
<P>
 The OpenGL red book has a nice picture of a graph showing the
 response curves of these functions.
</P></menu>
<i>librm library source file: rmfog.c </i><hr width="75%">
<a name="rmFogGetMode"> 
<pre><b>
 GLenum rmFogGetMode (const RMfog *toQuery)
</b></pre>
<pre>
 const RMfog *toQuery - a handle to an RMfog object to query (input).
</pre>
<menu><P>
 Use this routine to obtain the current fogging mode of an RMfog
 object.  Returns one of GL_LINEAR, GL_EXP or GL_EXP2 upon success, or
 GL_INVALID_VALUE upon failure.
</P></menu>
<i>librm library source file: rmfog.c </i><hr width="75%">
<a name="rmFogSetColor"> 
<pre><b>
 RMenum rmFogSetColor (RMfog *toModify,
	               const RMcolor4D *newColor)
</b></pre>
<pre>
 RMfog *toModify - a handle to an RMfog object to modify (modified).

 RMcolor4D *newColor - a handle to an RMcolor4D object (input).
</pre>
<menu><P>
 This routine copies a color from the caller-supplied RMcolor4D object
 into the RMfog object, returning RM_CHILL upon success. RM_WHACKED
 indicates failure.
</P>
<P>
 The fog color is a 4-component RGBA tuple. When fogging is enabled,
 objects that are further away from the viewer will appear to be more
 consumed by the fog, or appear in more of the fog color and in less
 of their own color. Objects closer to the viewer will appear to be
 more visible, and be shaded with less fog color.
</P></menu>
<i>librm library source file: rmfog.c </i><hr width="75%">
<a name="rmFogGetColor"> 
<pre><b>
 RMenum rmFogGetColor (const RMfog *toQuery,
	               RMcolor4D *returnColor)
</b></pre>
<pre>
 const RMfog *toQuery - a handle to an RMfog object to query (input).

 RMcolor4D *returnColor - a handle to an RMcolor4D object (modified).
</pre>
<menu><P>
 Copies the fog color from an RMfog object into caller-supplied
 memory, returning RM_CHILL upon success. Otherwise, RM_WHACKED is
 returned.
</P></menu>
<i>librm library source file: rmfog.c </i><hr width="75%">
<a name="rmFogSetDensity"> 
<pre><b>
 RMenum rmFogSetDensity (RMfog *toModify,
		         GLfloat newDensity)
</b></pre>
<pre>
 RMfog *toModify - a handle to an RMfog object to modify (modified).

 GLfloat newDensity - a floating point value in (input)
</pre>
<menu><P>
 Assigns a new value to the fog density attribute of an RMfog object,
 returning RM_CHILL upon success, or RM_WHACKED upon failure.
</P>
<P>
 Fog density controls the relative thickness of the fog. Thicker, or
 more dense fog, will tend to obscure objects more quickly than
 lighter, or less dense fog. Density values should probably be in the
 range 0.0 to 1.0, although the specification is not clear on this
 matter.
</P>
<P>
 Fog density has no effect when the fog mode is set to GL_LINEAR.
</P></menu>
<i>librm library source file: rmfog.c </i><hr width="75%">
<a name="rmFogGetDensity"> 
<pre><b>
 GLfloat rmFogGetDensity (const RMfog *toQuery)
</b></pre>
<pre>
 const RMfog *toQuery - a handle to an RMfog object to query (input).
</pre>
<menu><P>
 Returns a floating point value representing the fog density parameter
 of an RMfog object. Upon failure, an error message is issued and 1.0
 is returned.
</P>
<P>
 See rmFogSetDensity for an explanation of this parameter.
</P></menu>
<i>librm library source file: rmfog.c </i><hr width="75%">
<a name="rmFogSetStartEnd"> 
<pre><b>
 RMenum rmFogSetStartEnd (RMfog *toModify,
		          GLfloat newStart,
			  GLfloat newEnd)
</b></pre>
<pre>
 RMfog *toModify - a handle to an RMfog object to modify (modified).

 GLfloat newStart, newEnd - floating point values that specify the
    z-value of starting and ending point of the fog, respectively, in
    eye-coordinates (input). 
</pre>
<menu><P>
 Assigns new values to the fog start and end attributes of an RMfog
 object, returning RM_CHILL upon success. Upon failure, RM_WHACKED is
 returned and the start/end parameters are not modified.
</P>
<P>
 The fog start and end parameters define a region of space in which
 fogging occurs. The most confusing thing about fogging (to me,
 anyway) is that the values for fog start and end are z-coordinate
 values in eye coordinates. They are not distances from the
 viewer. Fogging is applied at the pixel fragment level, not when
 vertices are shaded.  A pixel fragment is generated with an
 eye-coordinate z-value that is then later projected using the
 projection matrix. The z-coordinate of the pixel fragment in eye
 coordinates is used as input to the fogging equations (described in
 rmFogSetMode).
</P>
<P>
 Pixel fragments with a eye-space z-coordinate that are less than the
 "fog start" value will not be fogged. Those with z-coordinates
 greater than the "fog end" value will be fully fogged (subject to the
 limits of the fog function and fog density parameters; it is possible
 for a pixel with a z-coordinate greater than "fog end" to not be
 fully fogged due to the asymptotic behavior of the inverse
 exponential function).
</P>
<P>
 Intuitively, these values can be thought of as distances. Set the fog
 start value to be the approximate distance, along the line of sight,
 where you want fogging to begin. Likewise, the the fog end value to
 some point further away where you want full fogging saturation to
 occur.
</P>
<P>
 (Need to double-check this discussion, Jan 2000)
</P></menu>
<i>librm library source file: rmfog.c </i><hr width="75%">
<a name="rmFogGetStartEnd"> 
<pre><b>
 RMenum rmFogGetStartEnd (const RMfog *toModify,
		          GLfloat *startReturn,
			  GLfloat *endReturn)
</b></pre>
<pre>
 const RMfog *toModify - a handle to an RMfog object to query (input).

 GLfloat *startReturn, *endReturn - handles to caller-supplied
    GLfloat's (modified). Use of NULL is acceptable. 
</pre>
<menu><P>
 Use this routine to obtain the "fog start" and "fog end" attributes
 from an RMfog object. Upon success, the fog start and end attributes
 are copied into caller supplied memory, and RM_CHILL is
 returned. Otherwise, RM_WHACKED is returned.
</P>
<P>
 Callers may specify NULL for either return parameter, in which case
 that attribute will not be returned to the caller.
</P>
<P>
 See rmFogSetStartEnd for more information about these RMfog
 attributes.
</P></menu>
<i>librm library source file: rmfog.c </i><hr width="75%">
</body></html>