OpenRM - RM Library (rmutil.c)

## Index of OpenRM - RM Library

     int rmNearestPowerOfTwo (int n)

     int n - an integer value.

This routine computes the integer that is the closest power of two to the input integer "n". The algorithm works only for non-negative input.

This routine will come in handy if you have to scale an image so it's size is an even power of two.

librm library source file: rmutil.c

     int rmIntMagnitude (int m)

     int m - an integer value.

This routine computes log2(m) for some integer m, and returns an integer. It is not an exact log2() replacement. It is useful for determining the position of the uppermost "on" bit in an integer.

librm library source file: rmutil.c

     void rmHSVtoRGB (float hue,
    	          float saturation,
    		  float value,
    		  float *redReturn,
    		  float *greenReturn,
    		  float *blueReturn)

     float hue, saturation, value - floating point values in the range
        [0..1] (input).

     float *redReturn, *greenReturn, *blueReturn - handles to floats. will
        contain floats in the range [0..1] (return).

Convert a three-component pixel from HSV space to RGB space. Input hue is in the range 0..1, with 0 corresponding to 0 degrees on the HSV circle, and 1.0 corresponding to 360 degrees on the HSV circle. Saturation is in the range 0..1, where 0 is fully desaturated and 1 is fully saturated. Value, or brightness, is in the range 0..1. A brightness value of 0 is black (not very bright), and a value of 1.0 is full brightness.

The results of the conversion are placed into caller-supplied memory. The return RGB values are also in the range 0..1, with 0 representing "full off" and 1 representing "full on."

librm library source file: rmutil.c

     void rmRGBtoHSV (float red,
    	          float green,
    		  float blue,
    		  float *hueReturn,
    		  float *saturationReturn,
    		  float *valueReturn)

     float red, green, blue - floating point values in the range 0..1 that
        represent a 3-component RGB pixel.

     float *hueReturn, *saturationReturn, *valueReturn - handles to floats
        that will contain the HSV representation of the input RGB pixel
        upon return. The return values are in the range 0..1 (result).

Converts an RGB 3-tuple into HSV space.

Output hue is in the range 0..1, with 0 corresponding to 0 degrees on the HSV circle, and 1.0 corresponding to 360 degrees on the HSV circle. Saturation is in the range 0..1, where 0 is fully desaturated and 1 is fully saturated. Value, or brightness, is in the range 0..1. A brightness value of 0 is black (not very bright), and a value of 1.0 is full brightness.

librm library source file: rmutil.c

     RMenum rmUnionBoundingBoxes (const RMvertex3D *s1min,
    		              const RMvertex3D *s1max,
    			      const RMvertex3D *s2min,
    			      const RMvertex3D *s2max,
    			      RMvertex3D *dmin,
    			      RMvertex3D *dmax)

     const RMvertex3D *s1min, *s1max, *s2min, *s2max - handles to
        RMvertex3D objects (input).

     RMvertex3D *dmin, *dmax - handles to RMvertex3D objects (modified).

This routine performs a "union" operation of two, 3D boxes, returning the minimum and maximum coordinates of the resulting box into caller-supplied memory. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

librm library source file: rmutil.c

     int rmGLGetError (const char *string)

     const char *string - a handle to a string (input).

This routine is a wrapper for the routine glGetError(), and is used to obtain OpenGL error codes. If there are no errors, a value of zero is returned by rmGLGetError(). Otherwise, the error code is returned to the caller, and the error code, along with the message contained in the parameter "string" is reported via rmWarning(). Refer to gl.h in your OpenGL distribution for definitions of the OpenGL error codes, as well as the man page for glGetError().

This routine was used extensively for debugging during the development of RM Scene Graph.

librm library source file: rmutil.c

     int rmImageBuildMipmaps (const RMimage *src,
    		          RMimage ***mapsReturn,
    			  RMenum hardwareEnum,
    			  RMpipe *hwPipe)

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

     RMimage ***mapsReturn - a pointer to an array of RMimage pointer (return).

     RMenum hardwareEnum - an RMenum value, may be either RM_HARDWARE or
        RM_SOFTWARE (input).

     RMpipe *hwPipe - a handle to an RMpipe (input). A valid RMpipe handle
        is required when RM_HARDWARE is requested via hardwareEnum. When
        RM_SOFTWARE image resizing for mipmap generation is requested,
        callers should specify NULL for the hwPipe parameter.

This convenience routine will generate a full set of mipmaps given an input image. The number of mipmaps generated is returned to the caller. This value will be positive and non-zero upon success, otherwise zero is returned.

When RM_SOFTWARE is selected, RM will repeatedly call gluScaleImage to produce the mipmaps, a software operation. When RM_HARDWARE is set, the framebuffer itself is used to scale the image data. In some cases, RM_HARDWARE will run faster by an order of magnitude than RM_SOFTWARE.

Inside this routine, an array of RMimage pointer is allocated. The number of entries in this array is log2(max(width,height)) of the input image, and is the number of mipmaps that will be generated. Then, each of these N images is created using RM_COPY_DATA, including the first image (which is a duplicate of the input image). The second image will be 1/4 the size of the first, and so forth down to a 1x1 image.

At this time (January 2000), RM_HARDWARE occasionally has problems with the pixel reads on some framebuffers (esp. nVidia cards under Linux).

At this time (January 2000), rmImageBuildMipmaps works ONLY on RMimage objects containing a two-dimensional image. There is no support at present for generating 3D mipmaps.

At this time (January 2000), the scaled images are drawn to the framebuffer for debugging purposes, regardless of whether or not RM_SOFTWARE or RM_HARDWARE is specified by the caller.

It is assumed that the input image is an even power of two in size.

The following code snippet shows how to free the images returned by rmImageBuildMipmaps.

     RMimage  *source;
     RMimage **dstMipmaps;
     int       nMipmaps, i;

     ... stuff is assigned to source here (omitted) ...

     nMipmaps = rmImageBuildMipmaps(source, &dstMipmaps, RM_HARDWARE);

     .... do some stuff with the mipmaps (omitted) ...

     // delete the images
     for (i = 0; i < nMipmaps; i++)
         rmImageDelete(dstMipmaps[i]);
     free((void *)dstMipmaps);

librm library source file: rmutil.c