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 (rmimage.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="rmImageNew"> 
<pre><b>
 RMimage * rmImageNew (int ndims,
	               int width,
		       int height,
		       int depth,
		       RMenum formatEnum,
		       RMenum typeEnum,
		       RMenum copyFlag)
</b></pre>
<pre>
 int ndims - integer value specifying the number of dimensions in the
    new image. Must be either 2 (for regular images) or 3 (for 3D
    volumes) (input).

 int width, height - integer values specifying the width and height of
    the new image (input).

 int depth - integer value specifying the size of the 3rd image
    dimension for 3D images. When "ndims" is 2, this parameter is
    ignored (input).

 RMenum formatEnum - an RMenum value specifying the pixel format for
    the new image. Use one of the following values (input):

    RM_IMAGE_ALPHA - alpha-only pixels, one component per pixel.
    RM_IMAGE_LUMINANCE - luminance only pixels, one component per pixel.
    RM_IMAGE_LUMINANCE_ALPHA - each pixel is considered to be a luminance-alpha
       pair, two components per pixel. Pixel data organized as LALALA...
    RM_IMAGE_RGB - each pixel is considered to be an RGB 3-tuple, organized
       as RGBRGB...
    RM_IMAGE_RGBA - each pixel is considered to be an RGBA 4-tuple, organized
       as RGBARGBA...
    RM_IMAGE_DEPTH - identifies the pixel data as depth buffer pixels. Each
       pixel consists of a single component.
    
 RMenum typeEnum - an RMenum value specifying the type of each pixel
    component.  Use one of the following enumerators (input):
    RM_UNSIGNED_BYTE, RM_FLOAT, RM_SHORT, or RM_UNSIGNED_SHORT.

 RMenum copyFlag - an RMenum value specifying whether or not RM will
    make a copy of the pixel data. Use one of RM_COPY_DATA or
    RM_DONT_COPY_DATA (input).
</pre>
<menu><P>
 Creates a new RMimage object according to the caller's
 specifications, and returns an RMimage handle to the caller upon
 success, or NULL upon failure.
</P>
<P>
 Once created, the size and pixel format/type of an RMimage object may
 not be changed by the application. However, the pixel storage mode
 may change over the lifetime of the RMimage object.
</P>
<P>
 Win32 peculiarities: due to bugs in the Win32 OpenGL, all pixel data
 in an RMimage object is padded to 4-byte boundaries on a per-scanline
 basis. This will become significant when transferring pixel data to
 the RMimage object. Use the routine rmImageGetBytesPerScanline to
 obtain the computed number of bytes per scanline (that value is
 computed by RM by rmImageNew and remains constant for the lifetime of
 the RMimage object).
</P>
<P>
 When copyFlag is set to RM_COPY_DATA, rmImageNew creates a pixel
 buffer internal to the RMimage object. When set to RM_DONT_COPY_DATA,
 no pixel buffer is created. However, the bytes-per-scanline value is
 computed and assigned to the new RMimage object.
</P>
<P>
 Important! Applications must honor the bytes-per-scanline attribute
 of the RMimage object, otherwise the application's notion of pixel
 data organization will not jibe with RM's notion, leading potentially
 to garbage images on screen (at best) to possible seg faults (at
 worst).
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageDup"> 
<pre><b>
 RMimage * rmImageDup (const RMimage *toDuplicate)
</b></pre>
<pre>
 const RMimage *toDuplicate - a handle to an RMimage object (input).
</pre>
<menu><P>
 Use this routine to create a duplicate of an RMimage object. Returns
 a handle to the new object upon success, or NULL upon failure.
</P>
<P>
 A new RMimage object is created that is an exact duplicate of the
 input object. When the pixel data is under the purview of
 RM_COPY_DATA, a copy of the pixel data from the source RMimage is
 created and placed into the new RMimage object's pixel buffer.
 Otherwise (RM_DONT_COPY_DATA), the handle to the application pixel
 data is copied to the new RMimage object, along with the handle to
 the application callback used to free pixel data.
</P>
<P>
 The RMvisMap object, if present in source, is duplicated and copied
 to the new object. RMimage object's do not share data management of
 RMvisMap objects with the application.
</P>
<P>
 All size and other configuration information from the source is used
 to create the new object. Pixel zoom, bias and scale are also copied
 from the source to the new object.
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageDelete"> 
<pre><b>
 RMenum rmImageDelete (RMimage *toDelete)

</b></pre>
<pre>
 RMimage *toDelete - a handle to an RMimage object.
</pre>
<menu><P>
 Releases resources associated with an RMimage object (the opposite of
 rmImageNew). Returns RM_CHILL upon success, or RM_WHACKED upon
 failure.
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageSetPixelData"> 
<pre><b>
 RMenum rmImageSetPixelData (RMimage *toModify,
                             void *pixelData,
			     RMenum copyEnum,
			     void (*appFreeFunc)(void *))
</b></pre>
<pre>
 RMimage *toModify - a handle to an RMimage object (modified).

 void *pixelData - a handle to the raw pixel data supplied by the
    caller.  The contents of this buffer will become the pixel data
    for the RMimage object (input).

 RMenum copyEnum - an RMenum value specifying whether or not RM should
    make a copy of this data. Must be either RM_COPY_DATA or
    RM_DONT_COPY_DATA.

 void (*appFreeFunc)(void *) - a handle to an application callback
    used to free the pixel data when the RMimage object is
    deleted. When copyEnum is RM_COPY_DATA, this parameter is ignored.
</pre>
<menu><P>
 Assigns raw pixel data to an RMimage object. Returns RM_CHILL upon
 success, or RM_WHACKED upon failure.
</P>
<P>
 The expected size of the pixel buffer is:
</P>
<P>
 (bytes_per_scanline)*height*depth * num_pixel_components
</P>
<P>
 The type of each pixel component may be obtained with rmImageGetType.
</P>
<P>
 The RMimage object's internal pixel buffer created with rmImageNew
 using RM_COPY_DATA should be considered READ ONLY. It is possible for
 applications to write directly into this pixel buffer, but this
 practice is highly discouraged. The reason is that RM will attempt to
 cache the RMimage object pixel buffer into OpenGL display lists
 wherever possible, and is capable of detecting changes to the pixel
 buffer (implying the need to refresh the display list data) only when
 the RM interface is used to update the pixel data
 (rmImageSetPixelData).
</P>
<P>
 In order to avoid multiple copies of pixel data in memory, use
 RM_DONT_COPY_DATA when creating the RMimage object. In that case, the
 application manages the pixel data. A call to rmImageSetPixelData
 will result in a pointer copy (not a block pixel copy), and will
 correctly cause any dependent display lists to be refreshed.
</P>
<P>
 When rmImageSetPixelData is called using RM_COPY_DATA, RM makes a
 copy of the pixel buffer and stores it in the RMimage object. When
 called with RM_DONT_COPY_DATA, RM copies only the pointer to the
 pixel data.
</P>
<P>
 When using RM_DONT_COPY_DATA, applications must provide a callback
 that will be invoked when the RMimage object is deleted with
 rmImageDelete.  The application callback will be passed a single
 parameter, a handle to the raw pixel data cast to a void *.
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageGetPixelData"> 
<pre><b>
 void * rmImageGetPixelData (const RMimage *toQuery)
</b></pre>
<pre>
 const RMimage *toQuery
</pre>
<menu><P>
 Returns to the caller a handle to the raw pixel data inside an
 RMimage object, cast to a void * upon success. Otherwise, returns
 NULL.
</P>
<P>
 The size of the returned pixel buffer is:
</P>
<P>
 (bytes_per_scanline)*height*depth * num_pixel_components
</P>
<P>
 The type of each pixel component may be obtained with rmImageGetType.
</P>
<P>
 The RMimage object's internal pixel buffer created with rmImageNew
 using RM_COPY_DATA should be considered READ ONLY. It is possible for
 applications to write directly into this pixel buffer, but this
 practice is highly discouraged. The reason is that RM will attempt to
 cache the RMimage object pixel buffer into OpenGL display lists
 wherever possible, and is capable of detecting changes to the pixel
 buffer (implying the need to refresh the display list data) only when
 the RM interface is used to update the pixel data
 (rmImageSetPixelData).
</P>
<P>
 In order to avoid multiple copies of pixel data in memory, use
 RM_DONT_COPY_DATA when creating the RMimage object. In that case, the
 application manages the pixel data. A call to rmImageSetPixelData
 will result in a pointer copy (not a block pixel copy), and will
 correctly cause any dependent display lists to be refreshed.
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageGetBytesPerScanline"> 
<pre><b>
 unsigned int rmImageGetBytesPerScanline (const RMimage *toQuery)
</b></pre>
<pre>
 const RMimage *toQuery - a handle to an RMimage object (input).
</pre>
<menu><P>
 Returns to the caller the computed number of bytes per scanline of
 image data. Some OpenGL implementations silently require that all
 image data is padded to 4-byte boundaries on a per-scanline basis.
</P>
<P>
 This read-only value, bytes-per-scanline, is computed by rmImageNew
 at RMimage creation time and remains constant for the lifetime of the
 RMimage object.
</P>
<P>
 Note that there is no corresponding rmImageSetBytesPerScanline
 routine. The bytes per scanline of an RMimage object is established
 at the time the RMimage object is created with rmImageNew and remains
 immutable for the lifetime of the object.
</P>
<P>
 See also rmImageGetImageSize.
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageGetCopyFlag"> 
<pre><b>
 RMenum rmImageGetCopyFlag (const RMimage *toQuery)
</b></pre>
<pre>
 const RMimage *toQuery - a handle to an RMimage object object
    (input). 
</pre>
<menu><P>
 Returns to the caller an RMenum value indicating the RMimage object's
 notion of who manages the pixel data. Either RM_COPY_DATA or
 RM_DONT_COPY_DATA will be returned, indicating that RM manages the
 data or the application manages the data, respectively.  If the input
 RMimage is NULL, then RM_WHACKED is returned.
</P>
<P>
 There is no corresponding rmImageSetCopyFlag routine.  The copy flag
 attribute is established at the time the RMimage is created with
 rmImageNew is called and is immutable for the lifetime of the object.
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageGetType"> 
<pre><b>
 RMenum rmImageGetType (const RMimage *toQuery)
</b></pre>
<pre>
 const RMimage *toQuery
</pre>
<menu><P>
 Returns to the caller an RMenum value indicating the RMimage pixel
 type.  Upon success, the RMenum value will be one of the RM pixel
 types, such as RM_UNSIGNED_BYTE, RM_FLOAT, RM_SHORT, or
 RM_UNSIGNED_SHORT. Otherwise, RM_WHACKED is returned.
</P>
<P>
 There is no corresponding rmImageSetType routine. The pixel type of
 an RMimage object is established at the time the RMimage object is
 created with rmImageNew, and remains immutable for the lifetime of
 the object.
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageGetFormat"> 
<pre><b>
 RMenum rmImageGetFormat (const RMimage *toQuery)
</b></pre>
<pre>
 const RMimage *toQuery
</pre>
<menu><P>
 Returns to the caller an RMenum value indicating the pixel format of
 the RMimage object. Upon success, the return value will be one of the
 RM pixel format enumerators, such as RM_IMAGE_ALPHA,
 RM_IMAGE_LUMINANCE, RM_IMAGE_LUMINANCE_ALPHA, RM_IMAGE_RGB,
 RM_IMAGE_RGBA or RM_IMAGE_DEPTH.  Upon failure, RM_WHACKED is
 returned to the caller.
</P>
<P>
 Note that there is no corresponding rmImageSetFormat routine. The
 pixel format of an RMimage object is established at the time the
 RMimage object is created with rmImageNew and remains immutable for
 the lifetime of the object.
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageGetImageSize"> 
<pre><b>
 RMenum rmImageGetImageSize (const RMimage *toQuery,
                             int *returnNDims,
		             int *returnWidth,
			     int *returnHeight,
			     int *returnDepth,
			     int *returnElements,
			     int *returnBytesPerScanline)

</b></pre>
<pre>
 const RMimage *toQuery - a handle to an RMimage object to query
    (input).

 int *returnNDims, *returnWidth, *returnHeight, *returnDepth,
    *returnElements, *returnBytesPerScanline - handles to integers
    supplied by the caller. Parameters from the RMimage object will be
    copied into these caller-supplied memory areas. Specifying NULL
    for one or more of these values is permissible.
</pre>
<menu><P>
 Use rmImageGetImageSize to obtain configuration information about an
 RMimage object.
</P>
<P>
 If not NULL, upon return, "returnNDims" will contain the number of
 dimensions in the RMimage object, either 2 or 3.
</P>
<P>
 If not NULL, upon return, "returnWidth", "returnHeight" and
 "returnDepth" will contain the width, height and depth of the RMimage
 object. When the dimensionality of the RMimage object is 2,
 "returnDepth" will be set to 1.
</P>
<P>
 If not NULL, upon return, "returnElements" will contain the number of
 components per pixel. For example, if the pixel format is
 RM_IMAGE_RGB, "returnElements" will contain 3.
</P>
<P>
 If not NULL, upon return, "returnBytesPerScanline" will contain the
 value computed by RM indicating the actual number of bytes per
 scanline in the pixel buffer. That value is computed to honor
 scanline padding requirements of some OpenGL implementations. This
 read-only value is computed by rmImageNew.
</P>
<P>
 Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P>
<P>
 Note that there is no corresponding rmImageSetImageSize routine. The
 size of an RMimage object is established at the time the RMimage
 object is created with rmImageNew and remains immutable for the
 lifetime of the object.
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageSetPixelZoom"> 
<pre><b>
 RMenum rmImageSetPixelZoom (RMimage *toModify,
		             float xzoom,
		             float yzoom)
</b></pre>
<pre>
 RMimage *toModify - a handle to an RMimage object (modified).

 float xzoom, yzoom - floating point values used to specify the x- and y-axis
    pixel replication, or zoom, factors (input).
</pre>
<menu><P>
 This routine is used to set the x- and y-axis pixel zoom parameters
 of an RMimage object.  Returns RM_CHILL upon success, or RM_WHACKED
 upon failure.
</P>
<P>
 In OpenGL, image-based data is usually drawn pixel-for-pixel, so that
 one pixel in the source image maps to one pixel on the screen. That
 mapping can be modified by changing the "pixel zoom". Setting the
 x-axis pixel zoom to 2.0 will cause each input pixel to map to two
 on-screen pixels.  Setting the x-axis pixel zoom to 0.5 will cause
 each two pixels of input to map to one pixel of output.
</P>
<P>
 Pixel zoom operations apply to RM_SPRITE primitives, and background
 image tiles. The pixel zoom values are not used when the RMimage
 object is the source of pixel data in an RMtexture (used in texture
 mapping).
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageGetPixelZoom"> 
<pre><b>
 RMenum rmImageGetPixelZoom (const RMimage *toQuery,
		             float *returnXZoom,
		             float *returnYZoom)
</b></pre>
<pre>
 RMimage *toQuery - a handle to an RMimage object that will be queried
    by this routine (input).

 float *returnXZoom, *returnYZoom - handles to floating point values
    that will contain the x- and y-axis pixel zoom factors of the
    RMimage object toQuery (modified).
</pre>
<menu><P>
 This routine is used to obtain the x- and y-axis pixel zoom
 parameters of an RMimage object. The pixel zoom factors are copied
 into caller-supplied memory.  Returns RM_CHILL upon success, or
 RM_WHACKED upon failure.
</P>
<P>
 In OpenGL, image-based data is usually drawn pixel-for-pixel, so that
 one pixel in the source image maps to one pixel on the screen. That
 mapping can be modified by changing the "pixel zoom". Setting the
 x-axis pixel zoom to 2.0 will cause each input pixel to map to two
 on-screen pixels.  Setting the x-axis pixel zoom to 0.5 will cause
 each two pixels of input to map to one pixel of output.
</P>
<P>
 Pixel zoom operations apply to RM_SPRITE primitives, and background
 image tiles. The pixel zoom values are not used when the RMimage
 object is the source of pixel data in an RMtexture (used in texture
 mapping).
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageSetVismap"> 
<pre><b>
 RMenum rmImageSetVismap (RMimage *toModify,
		          const RMvisMap *vismap)
</b></pre>
<pre>
 RMimage *toModify - a handle to an RMimage object (modified).

 const RMvisMap *vismap - a handle to an RMvisMap object (input).
</pre>
<menu><P>
 Use this routine to set, or delete, the colormap associated with an
 RMimage object.  This routine will return RM_CHILL upon success, or
 RM_WHACKED upon failure. A  copy of the caller's RMvisMap object is
 created inside this routine, and assigned to the RMimage object. If the
 input RMvisMap parameter is NULL, any RMvisMap associated with the
 RMimage object will be deleted.  Application changes to the
 application RMvisMap object made after this call will not affect the
 RMimage object.
</P>
<P>
 The colormap is used at pixel expansion time within the OpenGL pixel
 pipeline. Inside OpenGL, application pixel components are first
 converted to the range [0..1] using an algorithm that is a function
 of the source pixel type (byte, short, etc.). Next, pixels are
 converted from the source pixel format (luminance-alpha, RGB, etc.)
 into RGBA. Next, each pixel component is multiplied by the "scale"
 factor, then "bias" is added. Finally, each pixel component undergoes
 a color->color lookup.
</P>
<P>
 This routine is used to control that color->color lookup. Pixel
 scale, bias and color lookup operations are applied to all imaging
 operations, including both pixel draws and during transfer of pixel
 data to texture memory. Therefore, this routine may be used to
 perform false-coloring of scalar image data either for direct display
 using an RM_SPRITE primitive or in the form of texture-mapping.
</P>
<P>
 Note that scale and bias parameters operate on pixel data that has
 been converted to the range [0..1] according to a type-specific
 algorithm.  Source pixels that are in floating point are not
 converted, but are clamped to the range [0..1]. Clamping occurs late
 in the pixel pipeline, only after scale, bias and color lookup have
 been performed.
</P>
<P>
 False coloring with the RMvisMap object is implemented by
 manipulating OpenGL pixel transfer modes with glPixelTransferi().
</P>
<P>
 January 2000 - RMvisMap objects contain a transfer function. The
 transfer function is effectively ignored during the false coloring
 process inside the OpenGL pixel pipeline. Use the scale and bias
 attributes of the RMimage object to implement a transfer function.
 However, the RMvisMap object's transfer function is used inside the
 RMV visualization routines.
</P>
<P>
 April 2002 - NULL is now permitted as a parameter for the vismap.
 this will permit applications to "clear" the vismap associated with
 an RMimage object.
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageGetVismap"> 
<pre><b>
 RMenum rmImageGetVismap (const RMimage *toQuery,
		          RMvisMap **vismapReturn)
</b></pre>
<pre>
 const RMimage *toQuery - a handle to an RMimage object (input).

 RMvisMap **vismapReturn - a handle to an RMvisMap pointer (modified).
</pre>
<menu><P>
 Use this routine to set the obtain a copy of the colormap associated
 with an RMimage object. If a RMvisMap object exists inside the
 RMimage object, a copy of the RMvisMap object will be created and
 returned to the caller, and RM_CHILL will be returned. Otherwise,
 RM_WHACKED is returned.
</P>
<P>
 The RMvisMap object returned to the caller is a duplicate of the one
 inside the RMimage object. Application changes to the returned
 RMvisMap will not affect the RMimage object. When applications are
 finished with the returned RMvisMap object, resources should be freed
 with rmVismapDelete().
</P>
<P>
 The colormap is used at pixel expansion time within the OpenGL pixel
 pipeline. Inside OpenGL, application pixel components are first
 converted to the range [0..1] using an algorithm that is a function
 of the source pixel type (byte, short, etc.). Next, pixels are
 converted from the source pixel format (luminance-alpha, RGB, etc.)
 into RGBA. Next, each pixel component is multiplied by the "scale"
 factor, then "bias" is added. Finally, each pixel component undergoes
 a color->color lookup.
</P>
<P>
 This routine is used to control that color->color lookup. Pixel
 scale, bias and color lookup operations are applied to all imaging
 operations, including both pixel draws and during transfer of pixel
 data to texture memory. Therefore, this routine may be used to
 perform false-coloring of scalar image data either for direct display
 using an RM_SPRITE primitive or in the form of texture-mapping.
</P>
<P>
 Note that scale and bias parameters operate on pixel data that has
 been converted to the range [0..1] according to a type-specific
 algorithm.  Source pixels that are in floating point are not
 converted, but are clamped to the range [0..1]. Clamping occurs late
 in the pixel pipeline, only after scale, bias and color lookup have
 been performed.
</P>
<P>
 False coloring with the RMvisMap object is implemented by
 manipulating OpenGL pixel transfer modes with glPixelTransferi().
</P>
<P>
 January 2000 - RMvisMap objects contain a transfer function. The
 transfer function is effectively ignored during the false coloring
 process inside the OpenGL pixel pipeline. Use the scale and bias
 attributes of the RMimage object to implement a transfer function.
 However, the RMvisMap object's transfer function is used inside the
 RMV visualization routines.
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageMirror"> 
<pre><b>
 RMenum rmImageMirror (RMimage *toMirror,
	               RMenum mirrorAxisEnum)
</b></pre>
<pre>
 RMimage *toMirror - a handle to an RMimage object (modified).

 RMenum mirrorAxisEnum - an RMenum value specifying along which axis
    mirroring will occur (input). (January 2000, this parameter is
    ignored)
</pre>
<menu><P>
 This routine is used to perform reflection of pixel data in an
 RMimage object. Returns RM_CHILL upon success, or RM_WHACKED upon
 failure.
</P>
<P>
 January 2000 - at this time, this routine will perform ONLY mirroring
 of 2D images about the horizontal axis (top-to-bottom mirroring).
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageResize"> 
<pre><b>
 RMenum rmImageResize (const RMimage *src,
	               RMimage *dst,
	               RMenum hardwareEnum,
		       RMpipe *hwPipe)
</b></pre>
<pre>
 const RMimage *src - a handle to an RMimage object. Used as the
    source image in an image resize operation.

 RMimage *dst - a handle to an RMimage object. The resized image will
    be placed into this object.

 RMenum hardwareEnum - an RMenum value specifying whether or not to
    use the graphics hardware for performing the pixel resize
    operation.  Must be either RM_HARDWARE or RM_SOFTWARE.

 RMpipe *hwPipe - a handle to an RMpipe (input). This parameter must be
    non-NULL whenever the hardwareEnum parameter is set to RM_HARDWARE,
    and must refer to a fully initialized RMpipe. When RM_SOFTWARE
    image resizing is specified, this parameter is ignored, and may
    be set to NULL by the caller.
</pre>
<menu><P>
 Use this routine to scale an image. The source image is scaled to
 match the dimensions specified by the destination image. Thus, the
 destination image must have been first created with rmImageNew,
 implying that it's size, pixel format and type attributes have been
 set. This routine does not create a new image. This routine is useful
 for resizing images to be an even power of 2 in size, as required for
 OpenGL texture mapping.
</P>
<P>
 Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P>
<P>
 When hardwareEnum is set to RM_SOFTWARE, the routine gluScaleImage is
 used to perform the image resize operation, therefore it is a
 software operation.
</P>
<P>
 When hardwareEnum is set to RM_HARDWARE, the underlying graphics
 hardware is used to perform the resizing operation. This is
 accomplished by writing pixels to the framebuffer using appropriate
 pixel zoom values, then reading the image back into the RMimage pixel
 data memory. In many cases, use of RM_HARDWARE will greatly
 accelerate image resizing operations, such as resizing a giga-scale
 volume down to something more manageable.
</P>
<P>
 A valid, initialized RMpipe is required in the hwPipe parameter when
 using RM_HARDWARE image resize methods.
</P>
<P>
 During RM_HARDWARE image resize operations, pixels are written into
 the back buffer, then read back. After the readback, a swapbuffers
 is performed to provide visual feedback. Since the backbuffer is used
 for write/read operations, the display window need not be on top in
 stacking order.
</P>
<P>
 When using RM_HARDWARE, the size of the window used by the hwPipe
 RMpipe must be greater than or equal in size to the size of the
 destination image dimensions. If this condition does not hold, an
 error message is issued, and RM_WHACKED is returned.
</P>
<P>
 Note about RM_HARDWARE and using RM_PIPE_MULTISTAGE_PARALLEL RMpipe
 processing modes: use of RM_HARDWARE in conjunction with
 RM_PIPE_MULTISTAGE_PARALLEL is guaranteed to work only if the image
 resize operation is performed before the first rmFrame() call. After
 the first rmFrame() call, an image resize operation that uses RM_HARDWARE
 on an RMpipe using the RM_PIPE_MULTISTAGE_PARALLEL processing mode
 may produce unexpected results, including an application crash.
</P>
<P>
 As of the time of this writing (January 2000), only RM_HARDWARE is
 supported for 3D RMimage objects.
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageSetScale"> 
<pre><b>
 RMenum rmImageSetScale (RMimage *toModify,
		         float newScale)

</b></pre>
<pre>
 RMimage *toModify - a handle to an RMimage object to modify.

 float newScale - a floating point value that represents the new pixel
    scale that will be applied to the RMimage object.
</pre>
<menu><P>
 Use this routine to set the pixel scale parameter of an RMimage
 object.  Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P>
<P>
 Pixel scale and bias are used in the OpenGL pixel pipeline to modify
 pixel values as they move from the application into the framebuffer.
 Inside OpenGL, application pixel components are first converted to
 the range [0..1] using an algorithm that is a function of the source
 pixel type (byte, short, etc.). Next, pixels are converted from the
 source pixel format (luminance-alpha, RGB, etc.) into RGBA. Next,
 each pixel component is multiplied by the "scale" factor, then "bias"
 is added.
</P>
<P>
 The scale value is simply a linear multiplier that is applied to each
 pixel value.
</P>
<P>
 Note that scale and bias parameters operate on pixel data that has
 been converted to the range [0..1] according to a type-specific
 algorithm.  Source pixels that are in floating point are not
 converted, but are clamped to the range [0..1]. Clamping occurs late
 in the pixel pipeline, only after scale, bias and color lookup have
 been performed.
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageGetScale"> 
<pre><b>
 RMenum rmImageGetScale (const RMimage *toQuery,
		         float *returnScale)

</b></pre>
<pre>
 const RMimage *toQuery - a handle to an RMimage object to query
    (input). 

 float *returnScale - a handle to a float that will be set to contain
    the RMimage object's pixel scale attribute (modified).
</pre>
<menu><P>
 Use this routine to obtain the pixel scale parameter of an RMimage
 object.  Returns RM_CHILL upon success, and copies the RMimage
 object's pixel scale attribute into the caller-supplied
 memory. Returns RM_WHACKED upon failure.
</P>
<P>
 Pixel scale and bias are used in the OpenGL pixel pipeline to modify
 pixel values as they move from the application into the framebuffer.
 Inside OpenGL, application pixel components are first converted to
 the range [0..1] using an algorithm that is a function of the source
 pixel type (byte, short, etc.). Next, pixels are converted from the
 source pixel format (luminance-alpha, RGB, etc.) into RGBA. Next,
 each pixel component is multiplied by the "scale" factor, then "bias"
 is added.
</P>
<P>
 The scale value is simply a linear multiplier that is applied to each
 pixel value.
</P>
<P>
 Note that scale and bias parameters operate on pixel data that has
 been converted to the range [0..1] according to a type-specific
 algorithm.  Source pixels that are in floating point are not
 converted, but are clamped to the range [0..1]. Clamping occurs late
 in the pixel pipeline, only after scale, bias and color lookup have
 been performed.
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageSetBias"> 
<pre><b>
 RMenum rmImageSetBias (RMimage *toModify,
		        float newBias)

</b></pre>
<pre>
 RMimage *toModify - a handle to an RMimage object (modified).

 float newBias - a floating point value that represents the new pixel
    bias that will be applied to the RMimage object (input).
</pre>
<menu><P>
 Use this routine to set the pixel bias parameter of an RMimage
 object.  Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P>
<P>
 Pixel scale and bias are used in the OpenGL pixel pipeline to modify
 pixel values as they move from the application into the framebuffer.
 Inside OpenGL, application pixel components are first converted to
 the range [0..1] using an algorithm that is a function of the source
 pixel type (byte, short, etc.). Next, pixels are converted from the
 source pixel format (luminance-alpha, RGB, etc.) into RGBA. Next,
 each pixel component is multiplied by the "scale" factor, then "bias"
 is added.
</P>
<P>
 The bias value is simply an offset that is added to each pixel value.
</P>
<P>
 Note that scale and bias parameters operate on pixel data that has
 been converted to the range [0..1] according to a type-specific
 algorithm.  Source pixels that are in floating point are not
 converted, but are clamped to the range [0..1]. Clamping occurs late
 in the pixel pipeline, only after scale, bias and color lookup have
 been performed.
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
<a name="rmImageGetBias"> 
<pre><b>
 RMenum rmImageGetBias (const RMimage *toQuery,
		        float *returnBias)

</b></pre>
<pre>
 const RMimage *toQuery - a handle to an RMimage object to query
    (input).

 float *returnBias - a handle to a float that will be set to contain
    the RMimage object's bias attribute (modified).
</pre>
<menu><P>
 Use this routine to obtain the pixel bias parameter of an RMimage
 object.  Returns RM_CHILL upon success, and copies the RMimage
 object's bias attribute into the caller-supplied memory. Returns
 RM_WHACKED upon failure.
</P>
<P>
 Pixel scale and bias are used in the OpenGL pixel pipeline to modify
 pixel values as they move from the application into the framebuffer.
 Inside OpenGL, application pixel components are first converted to
 the range [0..1] using an algorithm that is a function of the source
 pixel type (byte, short, etc.). Next, pixels are converted from the
 source pixel format (luminance-alpha, RGB, etc.) into RGBA. Next,
 each pixel component is multiplied by the "scale" factor, then "bias"
 is added.
</P>
<P>
 The bias value is simply an offset that is added to each pixel value.
</P>
<P>
 Note that scale and bias parameters operate on pixel data that has
 been converted to the range [0..1] according to a type-specific
 algorithm.  Source pixels that are in floating point are not
 converted, but are clamped to the range [0..1]. Clamping occurs late
 in the pixel pipeline, only after scale, bias and color lookup have
 been performed.
</P></menu>
<i>librm library source file: rmimage.c </i><hr width="75%">
</body></html>