OpenRM - RM Library (rmtxture.c)

## Index of OpenRM - RM Library

     RMtexture * rmTextureNew (int ntdims)

     int ntdims - an integer value specifying whether the new texture
        object will be a 2D texture or 3D texture. Must be either 2 or 3
        (input).

Creates a new RMtexture object, returning a handle to the caller upon success, or NULL upon failure.

Texture mapping in RM is accomplished by assigning an RMtexture object to an RMnode as a scene parameter (see rmNodeSetSceneTexture). Primitives that have texture coordinates (rmPrimitiveSetTexCoord2D and rmPrimitiveSetTexCoord3D) that are located within any descendent nodes, including the node containing the RMtexture object, that has an RMprimitive with texture coordinates, will be rendered with texture mapping active. The presence of the RMtexture object causes texture mapping to become active, and texture coordinates cause texture mapping to occur once active.

The RMtexture object is a container for both texture images (rmTextureSetImages) and texturing environment, so it encompasses both the OpenGL texture object as well as the OpenGL texturing environment. The texturing environment consists of wrap mode (rmTextureSetWrapMode), any texture filtering that occurs when textures get small or large (rmTextureSetFilterMode), selection of one of several environmental modes that control how the texture color is blended with the pixel fragment color (rmTextureSetEnv), manipulation over how the texture is physically represented in the OpenGL pipeline (rmTextureSetGLTexelFormat).

Upon creation, rmTextureNew sets the following defaults for both 2D and 3D texture objects:

1. Filtering mode set to GL_NEAREST, GL_NEAREST (rmTextureSetFilterMode).

2. Texturing environment (blending) set to GL_MODULATE (rmTextureSetEnv).

3. Wrap mode is set to GL_CLAMP (rmTextureSetWrapMode).

4. Texel storage format is GL_RGBA. Can be overridden by a subsequent call to rmTextureGLSetTexelFormat().

Before assigning an RMtexture object to an RMnode as a scene parameter with rmNodeSetSceneTexture, the application must populate the RMtexture object with RMimage object(s) that contain the texture data.

librm library source file: rmtxture.c

     RMenum rmTextureDelete (RMtexture *toDelete,
    		         RMenum deleteImagesBool)

     RMtexture *toDelete - a handle to an RMtexture object to delete.

     RMenum deleteImagesBool - an RMenum value, either RM_TRUE or
        RM_FALSE, that indicates whether or not to delete the underlying
        RMimage data.

Use this routine to free an RMtexture object when no longer needed. At this time (Jan 2000), it is the applications responsibility to dictate whether or not the underlying RMimage texture data will be deleted. This control may become obsolete with the addition of reference counting at the RMimage level, but this feature is not implemented at this time.

When the application specifies RM_TRUE for "deleteImagesBool", the underlying RMimage data will be deleted (using rmImageDelete). If the underlying RMimage's share management of the pixel data with the application (specified using RM_DONT_COPY_DATA with rmImageSetPixelData), the application-supplied callback will be invoked at this time to release the image pixel data.

This routine also deletes the underlying OpenGL texture object.

librm library source file: rmtxture.c

     RMenum rmTextureSetImages (RMtexture *toModify,
    		            RMimage **imageArray,
    			    int nimages,
    			    int borderWidth)

     RMtexture *toModify - a handle to the RMtexture object to which image
        texture data will be assigned (modified).

     RMimage **imageArray - a handle to an array of RMimage objects that
        will be assigned to the RMtexture object as texture data. This
        list will not be modified by this routine.

     int nimages - an integer value indicating both the length or size of
        the imageArray parameter.

     int borderWidth - an integer value specifying the texture border
        width. May be either 1 or 0.

Use this routine to assign texture image data to an RMtexture object. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

In OpenGL, all images that are used as textures MUST BE and even power of 2 in size, although image width and height need not be equal. Thus, one may have image data which is 512 pixels wide by 64 pixels high. Use rmImageResize or gluScaleImage to resize an image if needed to honor the power-of-two size restriction.

One or more images may be assigned to a single texture object. The practice of assigning multiple images to a single texture object is called "Mip-mapping." The basic idea behind mip-mapping is that when a single texel (pixel from the texture data) covers very few screen pixels, one can use a low-resolution version of the texture data since the high-frequency texture components are lost by the rasterization process. When a single texel covers many screen pixels, a high-resolution version of the texture data is used in order to preserve, as much as possible, the high-frequency component of the texture data.

While mip-map construction is both a science and an art, for the most part, applications may simply use scaled down versions of a high-resolution texture for each mipmap level.

When mipmapping is used (nImages > 1), the "proper" number of mipmaps to create and use is 1+log2(largest dimension size of source texture). So, if the original texture is 256x64, a total of 8 images are needed to make a complete mipmap. The eight images will be sized: 256x64 (the original image), 128x32, 64x16, 32x8, 16x4, 8x2, 4x1, 2x1, 1x1 for a total of 9 images (log2(256)+1). In other words, you must specify all images that are sized from the original image down to a 1x1 representation.

Inside this routine, each image of the RMimage array is COPIED into the texture object using the routine rmImageDup. A fine point to be aware of is the fact that rmImageDup does not necessarily duplicate the underlying pixel data, so duplication of the imageArray does not necessarily result in a significant use of memory. Whether or not the image pixel data is copied is a function of whether or not the pixel data is assigned to the RMimage using RM_COPY_DATA or RM_DONT_COPY_DATA.

The border width parameter (either 0 or 1) indicates whether or not the "edge" pixels of the texture image data are to be treated as border pixels. Above, we mentioned that OpenGL textures must be an even power of two in size. More precisely, for a two-dimensional texture, the size of the input image data is (2^n + 2b, 2^m + 2b) where n,m are positive integers, and "b" is the borderWidth parameter. The treatment of border pixels is more fully described in the OpenGL Red Book.

Note that the borderWidth parameter applies to ALL images in a set of Mipmaps, not just the first image.

librm library source file: rmtxture.c

     RMenum rmTextureGetImages (RMtexture *toQuery,
    		            RMimage **imageArray,
    			    int *nimages,
    			    int *borderWidth)

     RMtexture *toQuery - a handle to the RMtexture object to which image
        texture data will be assigned (input).

     RMimage **imageArray - a handle to an array of RMimage objects that
        will be assigned to the RMtexture object as texture data. This
        list will not be modified by this routine.

     int *nimages, *borderWidth - handles to an integers (results).

This routine is currently only a stub.

librm library source file: rmtxture.c

     RMenum rmTextureSetFilterMode (RMtexture *toModify,
    		                GLenum minMode,
    			        GLenum magMode)

     RMtexture *toModify - handle to an RMtexture object (modified).

     GLenum minMode - a GLenum value specifying a texture minification
        filter. May be one of GL_NEAREST, GL_LINEAR,
        GL_NEAREST_MIPMAP_NEAREST, GL_NEAREST_MIPMAP_LINEAR,
        GL_LINEAR_MIPMAP_NEAREST, GL_LINEAR_MIPMAP_LINEAR.

     GLenum magMode - a GLenum value specifying a texture magnification
        filter.  May be one of GL_NEAREST or GL_LINEAR.

Use this routine to set the texture filtering mode at of an RMtexture object. Returns RM_CHILL upon success, or RM_WHACKED upon failure. Note that the filter does not take effect until the texture object has been placed into the scene graph using either rmNodeSetSceneTexture or rmNodeUpdateSceneTexture.

When texels project to screen pixels, they rarely cover an integral number of pixels. The texture filtering mode is used to control how texels are interpolated to screen pixels. When a screen pixel covers a very small portion of the texture, the texture is said to be magnified. Conversely, when the screen pixel covers multiple texels, the texture is said to be minified.

By default, the RMtexture object uses the minification and magnification filters of GL_NEAREST, GL_NEAREST, respectively. These filters favor performance over quality. The minification filter modes, GL_NEAREST, GL_LINEAR, ... , GL_LINEAR_MIPMAP_LINEAR represent increasing levels of interpolation quality, but at increasing performance cost. Only two magnification filters, GL_NEAREST and GL_LINEAR, are available inside OpenGL. Please see the OpenGL red book for more information about texture filtering.

librm library source file: rmtxture.c

     RMenum rmTextureGetFilterMode (const RMtexture *toQuery,
    		                GLenum *minModeReturn,
    			        GLenum *magModeReturn)

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

     GLenum *minModeReturn, *magModeReturn - handles to GLenum's
        (modified, return).

Use this routine to get the texture filtering modes from an RMtexture object. Upon success, RM_CHILL is returned and the filtering modes are copied from the RMtexture object into caller-supplied memory. Otherwise, RM_WHACKED is returned.

librm library source file: rmtxture.c

     RMenum rmTextureSetWrapMode (RMtexture *toModify,
    		              GLenum wrapMode)

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

     GLenum wrapMode - a GLenum specifying a texture wrap mode
        (input). May be one of GL_CLAMP or GL_REPEAT (OpenGL 1.2 adds the
        new texture wrap mode of GL_CLAMP_TO_EDGE).

Use this routine to set the "wrap mode" of an RMtexture object. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

By definition, texture coordinates range from 0.0 to 1.0, and define a parametric index into a texture. The texture wrap mode comes into play when texture coordinates go outside the range 0..1.

When GL_CLAMP is used, texture coordinates greater than 1.0 are clamped to 1.0, and those less than 0.0 are clamped to 0.0. Texture coordinates within the range 0..1 remain unmodified.

When GL_REPEAT is used, texture coordinates outside the range 0..1 are treated as if they were inside the range 0..1. The exact method used to implement this interpretation is platform-dependent, but a safe assumption is that most implementations ingore all but the fractional part of the texture coordinate.

Note that when GL_REPEAT is used, the texture border color is always ignored (rmTextureSetEnv). Similarly, when the GL_NEAREST filtering mode is used, the border color is also always ignored.

Please refer to the OpenGL red book for more information about texture wrapping.

Note that the RM implementation allows specification of onlye a single wrap mode. The one wrap mode is used for all texture dimensions. In this API, it is not possible to specify different wrap policies for each texture axis, although OpenGL does allow for this possibility. This RM policy reflects a simplification to the OpenGL API.

librm library source file: rmtxture.c

     RMenum rmTextureGetWrapMode (const RMtexture *toQuery,
    		              GLenum *wrapModeReturn)

     const RMtexture *toQuery - a handle to an RMtexture object that will
       be queried (input).

     GLenum *wrapModeReturn - a handle to a GLenum (result).

Use this routine to obtain the texture wrap mode of an RMtexture object. Upon success, RM_CHILL is returned, and the texture wrap mode is copied from the RMtexture object into the caller-supplied GLenum. Otherwise, RM_WHACKED is returned.

librm library source file: rmtxture.c

     RMenum rmTextureSetEnv (RMtexture *toModify,
    		         GLenum envMode,
    			 const RMcolor4D *blendColor)

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

     GLenum envMode - a GLenum value specifying one of several texture
         mapping modes. May be one of GL_DECAL, GL_REPLACE, GL_MODULATE or
         GL_BLEND (input).

     const RMcolor4D *blendColor - an handle to an RMcolor4D object (NULL
         is acceptable) (input).

Sets texture environment parameters in an RMtexture object. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

The "texture environment" specifies how, precisely, the color of a texture is combined with the color of a pixel fragment. Please refer to the OpenGL Red Book for more information about the effect of each of the texture environment modes GL_DECAL, GL_REPLACE, GL_MODULATE and GL_BLEND.

The blendColor parameter is optional, and takes effect only when GL_BLEND is used for the texturing method. The default value for blendColor when left unspecified by the application is (0,0,0,0). If blendColor is NULL, the existing blendColor in the RMtexture object, if any, remains unmodified.

librm library source file: rmtxture.c

     RMenum rmTextureGetEnv (const RMtexture *toQuery,
    		         GLenum *envModeReturn,
    			 RMcolor4D *blendColorReturn)

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

     GLenum *envModeReturn - a handle to a GLenum (return).

     RMcolor4D *blendColorReturn - a handle to an RMcolor4D object
        (return).

Use this routine to obtain the texture environment parameters of an RMtexture object. Upon success, RM_CHILL is returned, and the texture environment mode and blend color are copied into caller-supplied memory. Otherwise, RM_WHACKED is returned.

librm library source file: rmtxture.c

     RMenum rmTextureSetGLTexelFormat (RMtexture *toModify,
    			           GLenum internalTexelFormat)

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

     GLenum internalTexelFormat - a GLenum pixel format descriptor. See
        below for acceptable values (input).

Use this routine to tell OpenGL how texture pixel data will be stored in OpenGL texture memory. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

The permissible values for internalTexelFormat are a function of the particular OpenGL implementation that you are using. The set of GL_LUMINANCE, GL_LUMINANCE_ALPHA, GL_RGB, GL_RGBA are supported across all implementations. Some implementations support more specific values, such as GL_RGBA4, meaning that 4 bits of space are used for each of the R, G, B and A components of the texture.

OpenGL converts from the source image format (in the RMimage object) to the format requested by this routine. The application need not be concerned with performing this pixel reformatting.

By default, RM uses GL_RGBA unless overridden by the application's use of this routine.

librm library source file: rmtxture.c

     RMenum rmTextureGetGLTexelFormat (const RMtexture *toQuery,
    			           GLenum *returnTexelFormat)

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

     GLenum *returnTexelFormat - a handle to a GLenum value (return).

Use this routine to obtain the texel storage format used by the RMtexture object toQuery. Upon success, the texel storage format will be copied into caller-supplied memory and RM_CHILL will be returned. Otherwise, RM_WHACKED is returned.

librm library source file: rmtxture.c