OpenRM - RM Library (rmimage.c)

## Index of OpenRM - RM Library

     RMimage * rmImageNew (int ndims,
    	               int width,
    		       int height,
    		       int depth,
    		       RMenum formatEnum,
    		       RMenum typeEnum,
    		       RMenum copyFlag)

     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).

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.

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.

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).

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.

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).

librm library source file: rmimage.c

     RMimage * rmImageDup (const RMimage *toDuplicate)

     const RMimage *toDuplicate - a handle to an RMimage object (input).

Use this routine to create a duplicate of an RMimage object. Returns a handle to the new object upon success, or NULL upon failure.

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.

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.

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.

librm library source file: rmimage.c

     RMenum rmImageDelete (RMimage *toDelete)

     RMimage *toDelete - a handle to an RMimage object.

Releases resources associated with an RMimage object (the opposite of rmImageNew). Returns RM_CHILL upon success, or RM_WHACKED upon failure.

librm library source file: rmimage.c

     RMenum rmImageSetPixelData (RMimage *toModify,
                                 void *pixelData,
    			     RMenum copyEnum,
    			     void (*appFreeFunc)(void *))

     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.

Assigns raw pixel data to an RMimage object. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

The expected size of the pixel buffer is:

(bytes_per_scanline)*height*depth * num_pixel_components

The type of each pixel component may be obtained with rmImageGetType.

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).

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.

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.

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 *.

librm library source file: rmimage.c

     void * rmImageGetPixelData (const RMimage *toQuery)

     const RMimage *toQuery

Returns to the caller a handle to the raw pixel data inside an RMimage object, cast to a void * upon success. Otherwise, returns NULL.

The size of the returned pixel buffer is:

(bytes_per_scanline)*height*depth * num_pixel_components

The type of each pixel component may be obtained with rmImageGetType.

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).

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.

librm library source file: rmimage.c

     unsigned int rmImageGetBytesPerScanline (const RMimage *toQuery)

     const RMimage *toQuery - a handle to an RMimage object (input).

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.

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.

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.

See also rmImageGetImageSize.

librm library source file: rmimage.c

     RMenum rmImageGetCopyFlag (const RMimage *toQuery)

     const RMimage *toQuery - a handle to an RMimage object object
        (input).

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.

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.

librm library source file: rmimage.c

     RMenum rmImageGetType (const RMimage *toQuery)

     const RMimage *toQuery

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.

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.

librm library source file: rmimage.c

     RMenum rmImageGetFormat (const RMimage *toQuery)

     const RMimage *toQuery

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.

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.

librm library source file: rmimage.c

     RMenum rmImageGetImageSize (const RMimage *toQuery,
                                 int *returnNDims,
    		             int *returnWidth,
    			     int *returnHeight,
    			     int *returnDepth,
    			     int *returnElements,
    			     int *returnBytesPerScanline)

     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.

Use rmImageGetImageSize to obtain configuration information about an RMimage object.

If not NULL, upon return, "returnNDims" will contain the number of dimensions in the RMimage object, either 2 or 3.

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.

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.

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.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

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.

librm library source file: rmimage.c

     RMenum rmImageSetPixelZoom (RMimage *toModify,
    		             float xzoom,
    		             float yzoom)

     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).

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.

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.

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).

librm library source file: rmimage.c

     RMenum rmImageGetPixelZoom (const RMimage *toQuery,
    		             float *returnXZoom,
    		             float *returnYZoom)

     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).

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.

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.

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).

librm library source file: rmimage.c

     RMenum rmImageSetVismap (RMimage *toModify,
    		          const RMvisMap *vismap)

     RMimage *toModify - a handle to an RMimage object (modified).

     const RMvisMap *vismap - a handle to an RMvisMap object (input).

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.

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.

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.

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.

False coloring with the RMvisMap object is implemented by manipulating OpenGL pixel transfer modes with glPixelTransferi().

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.

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.

librm library source file: rmimage.c

     RMenum rmImageGetVismap (const RMimage *toQuery,
    		          RMvisMap **vismapReturn)

     const RMimage *toQuery - a handle to an RMimage object (input).

     RMvisMap **vismapReturn - a handle to an RMvisMap pointer (modified).

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.

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().

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.

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.

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.

False coloring with the RMvisMap object is implemented by manipulating OpenGL pixel transfer modes with glPixelTransferi().

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.

librm library source file: rmimage.c

     RMenum rmImageMirror (RMimage *toMirror,
    	               RMenum mirrorAxisEnum)

     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)

This routine is used to perform reflection of pixel data in an RMimage object. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

January 2000 - at this time, this routine will perform ONLY mirroring of 2D images about the horizontal axis (top-to-bottom mirroring).

librm library source file: rmimage.c

     RMenum rmImageResize (const RMimage *src,
    	               RMimage *dst,
    	               RMenum hardwareEnum,
    		       RMpipe *hwPipe)

     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.

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.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

When hardwareEnum is set to RM_SOFTWARE, the routine gluScaleImage is used to perform the image resize operation, therefore it is a software operation.

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.

A valid, initialized RMpipe is required in the hwPipe parameter when using RM_HARDWARE image resize methods.

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.

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.

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.

As of the time of this writing (January 2000), only RM_HARDWARE is supported for 3D RMimage objects.

librm library source file: rmimage.c

     RMenum rmImageSetScale (RMimage *toModify,
    		         float newScale)

     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.

Use this routine to set the pixel scale parameter of an RMimage object. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

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.

The scale value is simply a linear multiplier that is applied to each pixel value.

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.

librm library source file: rmimage.c

     RMenum rmImageGetScale (const RMimage *toQuery,
    		         float *returnScale)

     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).

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.

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.

The scale value is simply a linear multiplier that is applied to each pixel value.

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.

librm library source file: rmimage.c

     RMenum rmImageSetBias (RMimage *toModify,
    		        float newBias)

     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).

Use this routine to set the pixel bias parameter of an RMimage object. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

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.

The bias value is simply an offset that is added to each pixel value.

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.

librm library source file: rmimage.c

     RMenum rmImageGetBias (const RMimage *toQuery,
    		        float *returnBias)

     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).

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.

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.

The bias value is simply an offset that is added to each pixel value.

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.

librm library source file: rmimage.c