<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html><head><title>OpenRM - RM Library (rmtxture.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="rmTextureNew">
<pre><b>
RMtexture * rmTextureNew (int ntdims)
</b></pre>
<pre>
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).
</pre>
<menu><P>
Creates a new RMtexture object, returning a handle to the caller upon
success, or NULL upon failure.
</P>
<P>
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.
</P>
<P>
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).
</P>
<P>
Upon creation, rmTextureNew sets the following defaults for both 2D
and 3D texture objects:
</P>
<P>
1. Filtering mode set to GL_NEAREST, GL_NEAREST
(rmTextureSetFilterMode).
</P>
<P>
2. Texturing environment (blending) set to GL_MODULATE
(rmTextureSetEnv).
</P>
<P>
3. Wrap mode is set to GL_CLAMP (rmTextureSetWrapMode).
</P>
<P>
4. Texel storage format is GL_RGBA. Can be overridden by a subsequent
call to rmTextureGLSetTexelFormat().
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmtxture.c </i><hr width="75%">
<a name="rmTextureDelete">
<pre><b>
RMenum rmTextureDelete (RMtexture *toDelete,
RMenum deleteImagesBool)
</b></pre>
<pre>
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.
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
This routine also deletes the underlying OpenGL texture object.
</P></menu>
<i>librm library source file: rmtxture.c </i><hr width="75%">
<a name="rmTextureSetImages">
<pre><b>
RMenum rmTextureSetImages (RMtexture *toModify,
RMimage **imageArray,
int nimages,
int borderWidth)
</b></pre>
<pre>
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.
</pre>
<menu><P>
Use this routine to assign texture image data to an RMtexture object.
Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
Note that the borderWidth parameter applies to ALL images in a set of
Mipmaps, not just the first image.
</P></menu>
<i>librm library source file: rmtxture.c </i><hr width="75%">
<a name="rmTextureGetImages">
<pre><b>
RMenum rmTextureGetImages (RMtexture *toQuery,
RMimage **imageArray,
int *nimages,
int *borderWidth)
</b></pre>
<pre>
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).
</pre>
<menu><P>
This routine is currently only a stub.
</P></menu>
<i>librm library source file: rmtxture.c </i><hr width="75%">
<a name="rmTextureSetFilterMode">
<pre><b>
RMenum rmTextureSetFilterMode (RMtexture *toModify,
GLenum minMode,
GLenum magMode)
</b></pre>
<pre>
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.
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmtxture.c </i><hr width="75%">
<a name="rmTextureGetFilterMode">
<pre><b>
RMenum rmTextureGetFilterMode (const RMtexture *toQuery,
GLenum *minModeReturn,
GLenum *magModeReturn)
</b></pre>
<pre>
const RMtexture *toQuery - a handle to an RMtexture object to query
(input).
GLenum *minModeReturn, *magModeReturn - handles to GLenum's
(modified, return).
</pre>
<menu><P>
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.
</P></menu>
<i>librm library source file: rmtxture.c </i><hr width="75%">
<a name="rmTextureSetWrapMode">
<pre><b>
RMenum rmTextureSetWrapMode (RMtexture *toModify,
GLenum wrapMode)
</b></pre>
<pre>
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).
</pre>
<menu><P>
Use this routine to set the "wrap mode" of an RMtexture
object. Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
Please refer to the OpenGL red book for more information about
texture wrapping.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmtxture.c </i><hr width="75%">
<a name="rmTextureGetWrapMode">
<pre><b>
RMenum rmTextureGetWrapMode (const RMtexture *toQuery,
GLenum *wrapModeReturn)
</b></pre>
<pre>
const RMtexture *toQuery - a handle to an RMtexture object that will
be queried (input).
GLenum *wrapModeReturn - a handle to a GLenum (result).
</pre>
<menu><P>
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.
</P></menu>
<i>librm library source file: rmtxture.c </i><hr width="75%">
<a name="rmTextureSetEnv">
<pre><b>
RMenum rmTextureSetEnv (RMtexture *toModify,
GLenum envMode,
const RMcolor4D *blendColor)
</b></pre>
<pre>
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).
</pre>
<menu><P>
Sets texture environment parameters in an RMtexture object. Returns
RM_CHILL upon success, or RM_WHACKED upon failure.
</P>
<P>
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.
</P>
<P>
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.
</P></menu>
<i>librm library source file: rmtxture.c </i><hr width="75%">
<a name="rmTextureGetEnv">
<pre><b>
RMenum rmTextureGetEnv (const RMtexture *toQuery,
GLenum *envModeReturn,
RMcolor4D *blendColorReturn)
</b></pre>
<pre>
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).
</pre>
<menu><P>
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.
</P></menu>
<i>librm library source file: rmtxture.c </i><hr width="75%">
<a name="rmTextureSetGLTexelFormat">
<pre><b>
RMenum rmTextureSetGLTexelFormat (RMtexture *toModify,
GLenum internalTexelFormat)
</b></pre>
<pre>
RMtexture *toModify - a handle to an RMtexture object (modified).
GLenum internalTexelFormat - a GLenum pixel format descriptor. See
below for acceptable values (input).
</pre>
<menu><P>
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.
</P>
<P>
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.
</P>
<P>
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.
</P>
<P>
By default, RM uses GL_RGBA unless overridden by the application's
use of this routine.
</P></menu>
<i>librm library source file: rmtxture.c </i><hr width="75%">
<a name="rmTextureGetGLTexelFormat">
<pre><b>
RMenum rmTextureGetGLTexelFormat (const RMtexture *toQuery,
GLenum *returnTexelFormat)
</b></pre>
<pre>
const RMtexture *toQuery - a handle to an RMtexture object (input).
GLenum *returnTexelFormat - a handle to a GLenum value (return).
</pre>
<menu><P>
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.
</P></menu>
<i>librm library source file: rmtxture.c </i><hr width="75%">
</body></html>
