pfTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexture(3pf)NAME
pfNewTex, pfGetTexClassType, pfTexName, pfTexMultiName, pfGetTexName,
pfGetTexMultiName, pfTexImage, pfTexMultiImage, pfGetTexImage,
pfGetTexMultiImage, pfTexFormat, pfGetTexFormat, pfTexFilter,
pfTexAnisotropy, pfGetTexAnisotropy, pfGetTexFilter, pfTexRepeat,
pfGetTexRepeat, pfTexBorderColor, pfGetTexBorderColor, pfTexBorderType,
pfGetTexBorderType, pfTexSpline, pfGetTexSpline, pfTexDetail,
pfGetTexDetail, pfGetTexDetailTex, pfDetailTexTile, pfGetDetailTexTile,
pfTexList, pfGetTexList, pfTexFrame, pfGetTexFrame, pfTexLoadMode,
pfGetTexLoadMode, pfTexLevel, pfGetTexLevel, pfTexLODRange,
pfGetTexLODRange, pfGetCurTexLODRange, pfGetTexLODBias, pfTexLODBias,
pfGetCurTexLODBias, pfTexLoadOrigin, pfGetTexLoadOrigin, pfTexLoadSize,
pfGetTexLoadSize, pfApplyTex, pfFormatTex, pfLoadTex, pfTexLoadImage,
pfGetTexLoadImage, pfLoadTexLevel, pfLoadTexFile, pfLoadMultiTexFile,
pfSaveTexFile, pfSaveMultiTexFile, pfSubloadTex, pfSubloadMultiTex,
pfSubloadTexLevel, pfSubloadTexMultiLevel, pfFreeTexImage, pfIdleTex,
pfIsTexLoaded, pfIsTexFormatted, pfApplyTexMinLOD, pfApplyTexMaxLOD,
pfApplyTexLODBias, pfGetCurTex, pfApplyTMat - Create, modify and query
texture
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfTexture * pfNewTex(void *arena);
pfType * pfGetTexClassType(void);
void pfTexName(pfTexture *tex, const char *name);
void pfTexMultiName(pfTexture *tex, const char *name,
int imageIndex);
const char * pfGetTexName(const pfTexture *tex);
const char * pfGetTexMultiName(const pfTexture *tex, int imageIndex);
void pfTexImage(pfTexture *tex, uint* image, int comp, int ns,
int nt, int nr);
void pfTexMultiImage(pfTexture *tex, uint* image,
int imageIndex, int comp, int ns, int nt, int nr);
void pfGetTexImage(const pfTexture *tex, uint **image,
int *comp, int *ns, int *nt, int *nr);
void pfGetTexMultiImage(const pfTexture *tex, uint **image,
imageIndex, int *comp, int *ns, int *nt, int *nr);
void pfTexFormat(pfTexture *tex, int format, int type);
Page 1
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexture(3pf)
int pfGetTexFormat(const pfTexture *tex, int format);
void pfTexFilter(pfTexture *tex, int filt, int type);
void pfTexAnisotropy(pfTexture *tex, int degree);
int pfGetTexAnisotropy(pfTexture *tex);
int pfGetTexFilter(const pfTexture *tex, int filt);
void pfTexRepeat(pfTexture *tex, int wrap, int type);
int pfGetTexRepeat(const pfTexture *tex, int wrap);
void pfTexBorderColor(pfTexture* tex, pfVec4 clr);
void pfGetTexBorderColor(pfTexture* tex, pfVec4 *clr);
void pfTexBorderType(pfTexture* tex, int type);
int pfGetTexBorderType(pfTexture* tex);
void pfTexSpline(pfTexture *tex, int type, pfVec2 *pts,
float clamp);
void pfGetTexSpline(const pfTexture *tex, int type,
pfVec2 *pts, float *clamp);
void pfTexDetail(pfTexture *tex, int level, pfTexture *detail);
void pfGetTexDetail(const pfTexture *tex, int *level,
pfTexture **detail);
pfTexture * pfGetTexDetailTex(const pfTexture *tex);
void pfDetailTexTile(pfTexture *tex, int j, int k, int m,
int n, int scram);
void pfGetDetailTexTile(const pfTexture *tex, int *j, int *k,
int *m, int *n, int *scram);
void pfTexList(pfTexture *tex, pfList *list);
pfList * pfGetTexList(const pfTexture *tex);
void pfTexFrame(pfTexture *tex, float frame);
float pfGetTexFrame(const pfTexture *tex);
void pfTexLoadMode(pfTexture *tex, int mode, int val);
Page 2
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexture(3pf)
int pfGetTexLoadMode(const pfTexture *tex, int mode);
void pfTexLevel(pfTexture *tex, int level, pfTexture *ltex);
pfTexture * pfGetTexLevel(pfTexture *tex, int level);
void pfTexLODRange(pfTexture* tex, float min, float max);
void pfGetTexLODRange(pfTexture* tex, float *min, float *max);
void pfGetCurTexLODRange(pfTexture* tex, float *min,
float *max);
void pfGetTexLODRange(pfTexture* tex, float *biasS,
float *biasT, float *biasR);
void pfGetTexLODBias(pfTexture* tex, float *biasS,
float *biasT, float *biasR);
void pfTexLODBias(pfTexture* tex, float biasS, float biasT,
float biasR);
void pfGetCurTexLODBias(pfTexture* tex, float *biasS,
float *biasT, float *biasR);
void pfTexLoadOrigin(pfTexture *tex, int which, int xo,
int yo);
void pfGetTexLoadOrigin(pfTexture *tex, int which, int *xo,
int *yo);
void pfTexLoadSize(pfTexture *tex, int xs, int ys);
void pfGetTexLoadSize(const pfTexture *tex, int *xs, int *ys);
void pfApplyTex(pfTexture *tex);
void pfFormatTex(pfTexture *tex);
void pfLoadTex(pfTexture *tex);
void pfTexLoadImage(pfTexture* tex, uint *image);
uint * pfGetTexLoadImage(const pfTexture* tex);
void pfLoadTexLevel(pfTexture *tex, int level);
int pfLoadTexFile(pfTexture *tex, char *fname);
int pfLoadMultiTexFile(pfTexture *tex, char *fname,
int imageIndex);
Page 3
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexture(3pf)
void pfSaveTexFile(pfTexture *tex, char *fname);
void pfSaveMultiTexFile(pfTexture *tex, char *fname,
int imageIndex);
void pfSubloadTex(pfTexture* tex, int source, uint *image,
int xsrc, int ysrc, int srcwid, int xdst, int ydst,
int xsize, int ysize);
void pfSubloadMultiTex(pfTexture* tex, int source, uint *image,
int imageIndex, int xsrc, int ysrc, int srcwid,
int xdst, int ydst, int xsize, int ysize);
void pfSubloadTexLevel(pfTexture* tex, int source, uint *image,
int xsrc, int ysrc, int srcwid, int xdst, int ydst,
int xsize, int ysize, int level);
void pfSubloadTexMultiLevel(pfTexture* tex, int source,
uint *image, int imageIndex, int xsrc, int ysrc,
int srcwid, int xdst, int ydst, int xsize, int ysize,
int level);
void pfFreeTexImage(pfTexture *tex);
void pfIdleTex(pfTexture *tex);
int pfIsTexLoaded(const pfTexture *tex);
int pfIsTexFormatted(const pfTexture *tex);
void pfApplyTexMinLOD(float min);
void pfApplyTexMaxLOD(float min);
void pfApplyTexLODBias(float biasS, float biasT, float biasR);
pfTexture* pfGetCurTex(void);
void pfApplyTMat(pfMatrix *mat);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfTexture is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfTexture. Casting an object of
class pfTexture to an object of class pfObject is taken care of
automatically. This is also true for casts to objects of ancestor
classes of class pfObject.
void pfUserDataSlot(pfObject *obj, int slot, void *data);
void pfUserData(pfObject *obj, void *data);
Page 4
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexture(3pf)
void* pfGetUserDataSlot(pfObject *obj, int slot);
void* pfGetUserData(pfObject *obj);
int pfGetNumUserData(pfObject *obj);
int pfGetNamedUserDataSlot(const char *name);
const char* pfGetUserDataSlotName(int slot);
int pfGetNumNamedUserDataSlots(void);
int pfGetGLHandle(pfObject *obj);
int pfDeleteGLHandle(pfObject *obj);
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfTexture can also be used with these
functions designed for objects of class pfMemory.
pfType * pfGetType(const void *ptr);
int pfIsOfType(const void *ptr, pfType *type);
int pfIsExactType(const void *ptr, pfType *type);
const char * pfGetTypeName(const void *ptr);
int pfRef(void *ptr);
int pfUnref(void *ptr);
int pfUnrefDelete(void *ptr);
int pfUnrefGetRef(void *ptr);
int pfGetRef(const void *ptr);
int pfCopy(void *dst, void *src);
int pfDelete(void *ptr);
int pfIsFluxed(void *ptr);
int pfCompare(const void *ptr1, const void *ptr2);
void pfPrint(const void *ptr, uint which, uint verbose,
FILE *file);
void * pfGetArena(void *ptr);
PARAMETERS
tex identifies a pfTexture.
DESCRIPTION
pfNewTex creates and returns a handle to a pfTexture. arena specifies a
malloc arena out of which the pfTexture is allocated or NULL for
allocation off the process heap. pfTextures can be deleted with
pfDelete.
pfGetTexClassType returns the pfType* for the class pfTexture. The
pfType* returned by pfGetTexClassType is the same as the pfType* returned
by invoking pfGetType on any instance of class pfTexture. Because OpenGL
Performer allows subclassing of built-in types, when decisions are made
based on the type of an object, it is usually better to use pfIsOfType to
test if an object is of a type derived from a Performer type rather than
to test for strict equality of the pfType*'s.
pfLoadTexFile opens and loads the IRIS image file specified by fname,
using the global search paths set up by pfFilePath and the environment
variable PFPATH to find file. The loaded image is then formatted and
used as the image for tex. Image memory is allocated out of the malloc
Page 5
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexture(3pf)
arena in which the pfTexture was created. A return of FALSE indicates
failure, TRUE success.
pfLoadTexFile also sets the name of tex to the pathname of the file that
was loaded (see pfTexName).
pfSaveTexFile can be used to save a texture to an IRIS image file
specified by fname which contains the complete path and name of the file
to be created. A return of FALSE indicates failure, TRUE success.
pfTexImage sets the image used by tex. image is an array of texel data.
pfTexImage only copies the pointer to image and does not make a separate
copy of the texture data. image should be a pointer returned from
pfMalloc so the image may be properly reference counted (see pfMalloc and
pfObject).
The texture image is loaded from left to right, bottom to top. Texel
rows must be aligned on long word boundaries, so rows must be byte-padded
to the end of each row to get the proper alignment. comp is the number
of 8-bit components per image pixel. 1, 2, 3, and 4 component textures
are supported. ns, nt, nr are the number of texels in the s, t, and r
dimensions of image. See the OpenGL glTexImage(3g) man page for a more
detailed description of texture formats. pfGetTexImage returns the
texture image parameters of tex. Any or all of the arguments to
pfGetTexImage may be NULL, in which case those arguments are ignored.
pfFreeTexImage frees the texture image memory associated with tex after
the next pfApplyTex is called if the image's reference count is 0. The
texture image memory should be allocated by pfMalloc and may be shared
between multiple pfTextures. However, one should take care with
pfFreeTexImage if tex is to be used in multiple OpenGL windows. If the
image is freed on the first pfApplyTex then it will not be around when
tex is applied in a second window. In this case the image should be
freed only when tex has been applied in all windows.
pfTexName assigns the character string name to tex. Names are useful for
sharing textures in order to optimize texture memory usage. A
pfTexture's name is also set by pfLoadTexFile which sets the name to the
pathname of the file that was loaded. pfGetTexName returns the name of
tex.
pfTexFormat specifies how the texture image memory associated with tex is
formatted by pfFormatTex. format is a symbolic token specifying which
format to set and is PFTEX_INTERNAL_FORMAT, PFTEX_IMAGE_FORMAT,
PFTEX_EXTERNAL_FORMAT, or PFTEX_SUBLOAD_FORMAT. type is a symbolic token
specifying the format type appropriate to format. For all of the
following formats and token values, there are matching and additional
OpenGL tokens. See the OpenGL glTexImage2D(3g) man page for more
information on these and additional such tokens. The tokens for
PFTEX_EXTERNAL_FORMAT describe how the data in the image array is sized
and packed and can be one of PFTEX_PACK_8 for 8 bit components in packed
bytes (the default), or PFTEX_PACK_16 for images presented as 16bit
Page 6
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexture(3pf)
components, PFTEX_UNSIGNED_SHORT_5_5_5_1 or one of the OpenGL packed
pixels <type> tokens. The tokens for PFTEX_IMAGE_FORMAT describe the
type of image data in the array and can be PFTEX_LUMINANCE,
PFTEX_LUMINANCE_ALPHA, PFTEX_RGB, PFTEX_RGBA, or one of the OpenGL
<format> tokens. The tokens for PFTEX_INTERNAL_FORMAT include the
component names use in the format and number of bits per component in the
format. Internal formats with fewer bits per texel can have faster
performance. For reasonable texture loading performance, the
PFTEX_EXTERNAL_FORMAT and PFTEX_INTERNAL_FORMAT should be of
corresponding types (same number of components, if specified, and same
bits per component). If the PFTEX_EXTERNAL_FORMAT is set and the
PFTEX_INTERNAL_FORMAT has not been set, OpenGL Performer will
automatically select a matching PFTEX_INTERNAL_FORMAT token. The
internal formats, and the number of bits per texel for each, are:
PFTEX_RGB_5 16-bit texels. The default 3
component internal format.
PFTEX_RGB_4 16-bit texels. The default 3
component internal format if
PFTEX_RGB_5 is not available (IMPACT
systems).
PFTEX_RGB5_A1 16-bit texels.
PFTEX_RGBA_4 16-bit texels. The default 4
component internal format.
PFTEX_IA_8 16-bit texels.
PFTEX_I_12A_4 16-bit texels. The default 2
component internal format.
PFTEX_I_8 16-bit texels. The default 1
component internal format.
PFTEX_I_16 16-bit texels.
PFTEX_IA_12 24-bit texels.
PFTEX_RGBA_8 32-bit texels.
PFTEX_RGB_12 48-bit texels.
PFTEX_RGBA_12 48-bit texels.
PFTEX_RGBA_32 128-bit floating point texels.
PFTEX_RGB_32 96-bit floating point texels.
Page 7
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexture(3pf)
PFTEX_A_32 32-bit floating point texels (alpha
channel only).
PFTEX_I_32 32-bit floating point texels
(intensity).
PFTEX_L_32 32-bit floating point texels
(luminance).
PFTEX_IA_32 64-bit floating point texels
(intensity and alpha).
PFTEX_RGBA_F16 64-bit floating point texels.
PFTEX_RGB_F16 48-bit floating point texels.
PFTEX_A_F16 16-bit floating point texels (alpha).
PFTEX_I_F16 16-bit floating point texels
(intensity).
PFTEX_L_F16 16-bit floating point texels
(luminance).
PFTEX_IA_F16 16-bit floating point texels
(intensity and alpha).
Floating point formats are supported only on selected platforms,
including an Onyx 4.
There are additional boolean format options:
PFTEX_GEN_MIPMAP_FORMAT
Specifies whether or not MIPmap level should be
automatically created for a texture if a MIPmap
minification filter is in use. The default value is TRUE.
PFTEX_DETAIL_TEXTURE
specifies that the texture is to be used as a detail
texture. Once a texture has been specified to be a detail
texture, it can no longer be used as a base texture.
Calling pfApplyTex on a detail texture will bind the
texture to the detail target, not the base target.
PFTEX_SUBLOAD_FORMAT
is a boolean mode that specifies that texture is to be
able to be loaded in pieces, if supported on the current
machine. type should be either PF_ON or PF_OFF. If an
image has been assigned to the pfTexture, it will be
automatically downloaded upon formatting. This type of
texture may be formatted with a NULL image, in which case,
no image is automatically downloaded upon formatting. If
the texture is swapped out of hardware texture memory, the
Page 8
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexture(3pf)
image will not be automatically restored upon pfApplyTex
unless the PFTEX_BASE_AUTO_SUBLOAD mode has been specified
for the pfTexLoadMode. and can always be explicitly
reloaded with pfLoadTex. This format also specifies that
all loads of the texture will use the origin, size and
image specified by pfTexLoadOrigin, pfTexLoadSize, and
pfTexLoadImage. If the current graphics hardware
configuration cannot support texture subloading, this mode
will be ignored. In OpenGL, this requires the
EXT_subtexture extension; see the EXT_subtexture section
of the OpenGL glIntro(3g) man page for more information.
If PFTEX_SUBLOAD_FORMAT is enabled, pfFreeTexImage should
not be used as long as the texture is in use.
PFTEX_CUBE_MAP
The texture is a cube map texture that contains 6 images.
In this case the images are specified using method
pfTexMultiImage, where parameter imageIndex with value 0-5
specifies the cube face in the following order: min_x,
max_x, min_y, max_y, min_z, max_z. See sample program the
cube center to to each texel is computed. All six images
have to be specified, they have to have the same size, and
ns has to be equal to nt.
Other variants of the methods that are used by the cube
maps are: pfTexMultiName, pfGetTexMultiName,
pfLoadMultiTexFile, pfSaveMultiTexFile, pfSubloadMultiTex,
pfSubloadTexMultiLevel.
Other than having 6 images, the cube maps are used as any
other pfTexture. The exception is that subloads from
other sources than user specified memory are not
supported.
They are two new modes for pfTexGen: PFTG_REFLECTION_MAP
and PFTG_NORMAL_MAP. See man page for pfTexGen.
Cube maps are supported only on selected platforms,
including Onyx 4.
See the OpenGL glTexImage2D(3g) and glTexSubImage man pages for a
description of texture formats and corresponding texture loading
behavior. pfGetTexFormat returns the format mode corresponding to
format.
pfTexRepeat specifies a texture coordinate repeat function. wrap is a
symbolic token that specifies which texture coordinate(s) are affected by
the repeat function and is one of PFTEX_WRAP, PFTEX_WRAP_R, PFTEX_WRAP_S,
or PFTEX_WRAP_T. mode is a symbolic token that specifies how texture
coordinates outside the range 0.0 through 1.0 are handled. mode token
values may be one of: PFTEX_REPEAT or PFTEX_CLAMP. The default texture
repeat function is PFTEX_REPEAT for all texture coordinates.
Page 9
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexture(3pf)
pfGetTexRepeat returns the texture coordinate repeat function
corresponding to wrap.
pfTexFilter sets a filter function used by tex. type may be one of
PFTEX_MINFILTER, PFTEX_MAGFILTER, PFTEX_MAGFILTER_ALPHA, or
PFTEX_MAGFILTER_COLOR. filter is a combination of bitmask tokens which
specify a particular minification or magnification filter. Filters may
be partially specified, in which case, OpenGL Performer will use defaults
based on performance considerations for the current graphics platform.
PFTEX_FAST can be included in a texture filter and may cause a slightly
different filter to be substituted in texture application for fast
performance on the current graphics platform. All filters may include
basic interpolation tokens:
PFTEX_POINT
PFTEX_LINEAR
PFTEX_BILINEAR
PFTEX_TRILINEAR
PFTEX_QUADLINEAR - for 3D texture only.
Additionally, filters may specify additional minification or
magnification functions.
Texture Filter Table
___________________________________________
Filter PFTEX_ tokens
___________________________________________
PFTEX_MINFILTER PFTEX_MIPMAP
PFTEX_MAGFILTER PFTEX_DETAIL_LINEAR
PFTEX_MODULATE
PFTEX_ADD
PFTEX_DETAIL_COLOR
PFTEX_DETAIL_ALPHA
PFTEX_MAGFILTER_ALPHA PFTEX_DETAIL
PFTEX_MODULATE
PFTEX_ADD
PFTEX_DETAIL_ALPHA
PFTEX_SHARPEN
PFTEX_SHARPEN_ALPHA
PFTEX_MAGFILTER_COLOR PFTEX_DETAIL
PFTEX_MODULATE
PFTEX_ADD
PFTEX_DETAIL_COLOR
PFTEX_SHARPEN_COLOR
PFTEX_SHARPEN
|
For convenience, there are compound tokens that include the most of usual
filter combinations:
PFTEX_MIPMAP_POINT
Page 10
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexture(3pf)
PFTEX_MIPMAP_LINEAR
PFTEX_MIPMAP_BILINEAR
PFTEX_MIPMAP_TRILINEAR
PFTEX_MIPMAP_QUADLINEAR
PFTEX_MAGFILTER_COLOR
PFTEX_MAGFILTER_ALPHA
PFTEX_SHARPEN_COLOR
PFTEX_SHARPEN_ALPHA
PFTEX_DETAIL_COLOR
PFTEX_DETAIL_ALPHA
PFTEX_DETAIL_LINEAR
PFTEX_MODULATE_DETAIL
PFTEX_ADD_DETAIL
PFTEX_BICUBIC_LEQUAL
PFTEX_BICUBIC_GEQUAL
PFTEX_BICUBIC_LEQUAL
PFTEX_BICUBIC_GEQUAL
PFTEX_BILINEAR_LEQUAL
PFTEX_BILINEAR_GEQUAL
If the desired filter requires support that is not present on the current
graphics platform, that part of the specified filter will be ignored.
See the OpenGL glTexImage(3g) mans page for descriptions of texture
filter types. The default filter types are: magfilter = PFTEX_BILINEAR,
minfilter = PFTEX_MIPMAP_TRILINEAR for both InfiniteReality and Reality
Engine, and PFTEX_MIPMAP_LINEAR otherwise. pfGetTexFilter returns the
filter type of filter.
pfTexAnisotropy sets an anisotropic filter to be used by tex. The degree
argument is the degree of anisotropy to be applied. pfGetTexAnisotropy
will return the degree of anisotropy set by pfTexAnisotropy. The default
degree of anisotropy is 1 which is the same as the default isotropic
filter. A value of 2 will apply a 2:1 anisotropic filter. The maximum
degree of anisotopy can be queried with pfQuerySys(). Anisotropic
filtering is supported on OpenGL implementations that support the
GL_EXT_texture_filter_anisotropic extension. pfQueryFeature() can be
used to determine if anisotropic filtering is supported on the current
platform. If the environment variable PF_MAX_ANISOTROPY is set, then an
anisotropic filter of the value specified by PF_MAX_ANISOTROPY will be
applied to pfTextures that do not set the degree of anisotropy.
Textures are permitted to have explicit borders. By default, these
borders are not enabled. Texture borders can be enabled by setting a
texture border type with pfTexBorderType where type is one of the
following tokens: PFTEX_BORDER_NONE, PFTEX_BORDER_COLOR, or
PFTEX_BORDER_TEXELS. The default texture border type is
PFTEX_BORDER_NONE. If PFTEX_BORDER_COLOR is specified, the corresponding
texture border color may be set with pfTexBorderColor. The default
texture border color is black. If PFTEX_BORDER_TEXELS borders are
enabled on a pfTexture, it is assumed that the corresponding image for
that pfTexture includes the border texels and the corresponding size of
the pfTexture also includes the border texels. pfGetTexBorderType will
Page 11
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexture(3pf)
return the texture border type and pfGetTexBorderColor will return the
texture border color. If the current graphics hardware configuration
does not support the selected border type, it will be ignored. Texel
borders are only available in OpenGL operation. Texture borders should
be used only when there is strong motivation and with extreme caution.
Texel borders can add considerable texture storage requirements to the
pfTexture and cause subsequent performance degradations.
pfTexDetail sets detail as the detail texture of tex or disables
detailing of tex if detail is NULL. The level of magnification between
the base texture and detail texture is a non-positive number specified by
level and may be PFTEX_DEFAULT. The detail texture is replicated as
necessary to create a resulting texture that is 2^level times the size of
the base (level 0) texture. The default tex level is four which creates
a 16:1 mapping from detail texels to base texels. pfTexDetail will also
set the magnification filter of tex to PFTEX_MODULATE_DETAIL or
PFTEX_BILINEAR if detailing is enabled or disabled respectively. See the
OpenGL glDetailTexFuncSGIS man page for a description of detail texture
filters and splines. For use with OpenGL, the OpenGL
GL_SGIS_detail_texture extension is required. Once a texture has been
specified to be a detail texture, it can no longer be used as a base
texture. Calling pfApplyTex on a detail texture will bind the texture to
the detail target, not the base target. Please also see the additional
notes on using detail textures below.
pfGetTexDetail returns the detail texture of tex in detail or NULL if the
texture is not detailed, and the detail texture level in level. The
level of magnification at which detail is actually applied is controlled
by pfTexSpline. pfGetTexDetailTex returns the detail texture of tex, or
NULL if the texture is not detailed.
pfTexLevel sets a minification or magnification texture ltex for the
level level for the base texture tex. If level is positive, it is taken
to be a minification level and ltex is made the levelth MIPmap level for
the base texture. If level is zero or negative, ltex is taken to be a
detail texture whose corresponding magnification level will be -level.
pfGetTexLevel will return the texture for the specified level.
pfTexLODRange sets directly on the current texture the range of levels of
detail to be accessible. This has the same basic functionality as the
same control on the pfTexLOD attribute (see the pfTexLOD man page for
more information). The state enable for TEXLOD (PFSTATE_ENTEXLOD on a
pfGeoState or pfEnable(PFEN_TEXLOD)) is ignored for an LOD range set on a
pfTexture. A range set on a pfTexture will take priority over a
currently applied pfTexLOD attribute unless pfOverride has been set for
PFSTATE_TEXLOD. To completely unset the LOD range on a pfTexture, set
the min and max values both to PFTEX_DEFAULT. pfGetTexLODRange will
return the texture LOD range set on the pfTexture. If the range are
unset the value PFTEX_DEFAULT will be returned in min and max.
pfGetCurTexLODRange will return the current effective LOD range being
applied to the given pfTexture and considers values inherited from the
current global state. If the values are completely unset, GL defaults
Page 12
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexture(3pf)
will be returned. NULL arguments to pfGetTexLODRange and
pfGetCurTexLODRange are legal (they are ignored).
pfTexLODBias sets directly on the current texture bias parameters to be
used in the texture level of detail computation. This has the same basic
functionality as the same control on the pfTexLOD attribute (see the
pfTexLOD man page for more information). The state enable for TEXLOD (-
PFSTATE_ENTEXLOD on a pfGeoState or pfEnable(PFEN_TEXLOD)) is ignored for
an LOD bias set on a pfTexture. A bias setting on a pfTexture will take
priority over a currently applied pfTexLOD attribute unless pfOverride
has been set for PFSTATE_TEXLOD. To completely unset the LOD range on a
pfTexture, set the bias values both to PFTEX_DEFAULT. pfGetTexLODBias
will return the texture LOD bias values. If the bias values are unset,
PFTEX_DEFAULT will be returned in the bias values. pfGetCurTexLODBias
will return the current effective LOD bias being applied to the given
pfTexture and considers values inherited from the current global state.
If the values are completely unset, GL defaults will be returned. NULL
arguments to pfGetTexLODBias and pfGetCurTexLODBias are legal (they are
ignored).
pfTexSpline sets the parameters of a cubic interpolating spline used in
certain magnification filters. type is a symbolic token specifying a
particular filter spline and is either PFTEX_SHARPEN_SPLINE or
PFTEX_DETAIL_SPLINE which correspond to magfilters for sharpen (-
PFTEX_SHARPEN) and detail texture (PFTEX_MODULATE_DETAIL or
PFTEX_ADD_DETAIL) respectively. pts is an array of pfVec2 of length 4
which specifies the control points of the filter spline. A control point
is of the form (-LOD, scale). The specified LOD is negative since it
indicates a magnification LOD. The spline is clamped to clamp. If clamp
is PFTEX_DEFAULT, the spline will be automatically clamped to its maximum
value. If clamp is zero, no clamping will be done. See the notes below
on compatibility of texture splines with previous versions of OpenGL
Performer. See the OpenGL glDetailTexFuncSGIS and glSharpenTexFuncSGIS
man pages for a description of filter splines. pfGetTexSpline copies the
spline parameters of the filter designated by type into pts and clamp.
Please also see the additional notes on using detail textures below.
pfTexList sets a pfList of pfTexture*, list, on the pfTexture, tex.
pfGetTexList returns the texture list. pfTexFrame selects a frame from
the texture list of tex upon pfApplyTex. The default frame value is (-1)
which selects the base texture. pfGetTexFrame returns the current
pfTexture frame. pfTexList and pfTexFrame together provide a mechanism
for doing texture animations or managing multiple textures on geometry.
The base pfTexture is applied to the geometry, but different pfTextures
from the set in the list are selected based on the frame value in the
base texture. The PFTEX_LOAD_LIST mode to pfTexLoadMode controls how
textures replace previous texture from the same list for efficient
hardware texture memory management.
pfFormatTex creates a GL/hardware ready texture for the specified
pfTexture, tex. All pfTexture parameters are take into account.
Changing any parameter on a pfTexture will cause it to need to be re-
Page 13
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexture(3pf)
formatted. pfIsTexFormatted will return the formatted state of the
texture. pfGetGLHandle will return the handle to the resulting GL
texture, valid only for the current GL context.
pfLoadTex downloads the specified texture source to graphics hardware
texture memory allocated to tex. Repeated calls to pfLoadTex will reload
the image specified by pfTexLoadImage or else the main texture image set
by pfTexImage or pfLoadTexFile down into the graphics subsystem, allowing
the contents of the texture image to be changed dynamically. If a
reformatting of the texture is required, pfFormatTex will be called
automatically. If the texture is of format PFTEX_SUBLOAD_FORMAT and the
current graphics hardware configuration supports texture subloading, then
the origin and size specified with pfTexLoadOrigin and pfTexLoadSize will
be used. pfIsTexLoaded will return whether or not the specified
pfTexture is currently resident in hardware texture memory. However,
pfIsTexLoaded will not reflect whether or not additional changes made to
the contents of the texture image have been downloaded.
pfLoadTexLevel will load a specific level of the pfTexture and is
available in OpenGL only. The level may be a non-zero positive number to
refer to a minification level, or may be PFTEX_LEVEL_BASE to refer to the
base texture level, PFTEX_LEVEL_ALL to refer to all levels, or may be a
non-positive number to refer to a detail level. pfLoadTex and
pfLoadTexLevel change the current pfTexture to be undefined.
pfSubloadTex downloads a specified texture source to graphics hardware
memory allocated to tex according to the specified source, image, origin,
width of complete image, destination, and subload size, which may be
different than the load parameters in tex. The width of the source
images is specified in srcwidth and may be (-1) to refer to the width of
the base texture. srcwidth is used for the tiling of image textures when
the source x origin is greater than 0. This routine will not change any
of these load parameters for future texture loads. If the current
graphics hardware configuration cannot support texture subloading, this
command will have no effect. pfSubloadTexLevel will load a specific
level of the pfTexture and is available in OpenGL only. The level may be
a non-zero positive number to refer to a minification level, or may be
PFTEX_LEVEL_BASE to refer to the base texture level, PFTEX_LEVEL_ALL to
refer to all levels, or may be a non-positive number to refer to a detail
level. pfSubloadTex and pfSubloadTexLevel change the current pfTexture
to be undefined.
pfTexLoadImage can be used to update a location for texels to be
downloaded from without causing a reformatting of the pfTexture and
without loosing the main image pointer on the pfTexture. This specified
image pointer will then be used for texture downloads triggered by
pfApplyTex and pfLoadTex. If image is NULL, then texture downloads will
go back to using the main image pointer on the pfTexture, set through
pfTexImage or pfLoadTexFile. pfGetTexLoadImage will return the
previously set load image of tex.
Portions of a texture images may be updated by specifying a
Page 14
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexture(3pf)
pfTexLoadOrigin and pfTexLoadSize. pfTexLoadOrigin sets the origin of
the texture image source or destination, according to which.
pfTexLoadSize sets the texture area size, in texels, that is to be
downloaded. These settings will affect future texture loads that are
triggered by pfApplyTex and pfLoadTex. pfGetTexLoadSize will return the
previously set load size of tex. pfGetTexLoadOrigin will return the
source or destination load origin, as specified by which of tex. The x
or y argument to pfGetTexLoadSize pfGetTexLoadOrigin may be NULL, in
which case it is ignored.
pfTexLoadMode sets parameters that configure texture downloading,
specified by mode to val. mode may be one of PFTEX_LOAD_SOURCE,
PFTEX_LOAD_BASE, or PFTEX_LOAD_LIST. Values for the PFTEX_LOAD_SOURCE
select the source for the texture image data and may be one of
PFTEX_SOURCE_IMAGE to select the image specified by pfTexImage,
PFTEX_SOURCE_VIDEO for video texture, or PFTEX_SOURCE_FRAMEBUFFER. The
default texture load source is PFTEX_SOURCE_IMAGE. Texture sources of
PFTEX_SOURCE_VIDEO and PFTEX_SOURCE_FRAMEBUFFER also require the
PFTEX_SUBLOAD_FORMAT and set it automatically. The PFTEX_LOAD_BASE mode
controls how base textures are loaded. The default, PFTEX_BASE_APPLY
will do a load of the specified texture source when the texture is dirty
upon a pfApplyTex of the pfTexture. The PFTEX_BASE_AUTO_SUBLOAD will
automatically replace the texture from the specified texture source upon
every call to pfApplyTex. The PFTEX_LOAD_LIST mode controls how textures
from the texture list are loaded. New selections from the texture list
may be loaded in the following ways: PFTEX_LIST_APPLY, the default, will
apply the selected pfTexture from the texture list; PFTEX_LIST_AUTO_IDLE
will idle the previous pfTexture selected from the list so that its
graphics texture memory will be freed. If the base texture is formatted
with PFTEX_SUBLOAD_FORMAT, PFTEX_LIST_SUBLOAD will replace the texture
image of the base texture with the texture image from the selected
pfTexture of the texture list. PFTEX_LIST_AUTO_SUBLOAD re-uses the
hardware texture memory of the base texture and so is the most efficient
means of sharing graphics memory amongst pfTextures. However,
PFTEX_LIST_SUBLOAD is not available on all graphics platforms (see notes
below) and it requires that the pfTextures be identical in number of
components and formats. PFTEX_LIST_AUTO_SUBLOAD will obey the origin and
size set by pfTexLoadOrigin and pfTexLoadSize. pfGetTexLoadMode will
return the value of mode for tex.
pfApplyTex makes tex the current texture. When texturing is enabled (see
below), this texture will be applied to all geometry drawn after
pfApplyTex is called. Only one pfTexture may be active at a time
although many may be defined. If formatting or downloading of the
texture is required at the time of the call to pfApplyTex, pfFormatTex
and pfLoadTex will be called automatically. Modifications to tex, such
as changing the filter type, will not have effect until pfApplyTex is
called with tex. pfGetCurTex returns the currently active pfTexture.
pfApplyTex will automatically apply the detail texture associated with
tex and will disable detail texturing if tex has no associated detail
texture.
Page 15
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexture(3pf)
For geometry to be textured, the following must be true:
1. Texturing must be enabled: pfEnable(PFEN_TEXTURE)
2. A pfTexEnv must be applied: pfApplyTEnv
3. A pfTexture must be applied: pfApplyTex
4. Geometry must have texture coordinates: pfGSetAttr,
PFGS_TEXCOORD2
The texture state element is identified by the PFSTATE_TEXTURE token.
Use this token with pfGStateAttr to set the texture of a pfGeoState and
with pfOverride to override subsequent texture changes:
Example 1:
/* Apply texture environment to be used by textured geometry */
pfApplyTEnv(tev);
/* Set up textured pfGeoState */
pfGStateMode(gstate, PFSTATE_ENTEXTURE, PF_ON);
pfGStateAttr(gstate, PFSTATE_TEXTURE, tex);
/* Attach gstate to gset */
pfGSetGState(gset, gstate);
/* Set texture coordinate array. 'gset' is non-indexed */
pfGSetAttr(gset, PFGS_TEXCOORD2, PFGS_PER_VERTEX, tcoords,NULL);
/* Draw textured gset */
pfDrawGSet(gset);
Example 2:
pfApplyTex(tex);
/* Override so that all textured geometry uses 'tex' */
pfOverride(PFSTATE_TEXTURE, PF_ON);
pfGetCurTex returns the current pfTexture or NULL if no pfTexture is
active.
pfIdleTex and pfIsTexLoaded can help you efficiently manage hardware
texture memory. pfIdleTex signifies that tex is no longer needed in
texture memory and may be replaced by new textures. pfIsTexLoaded
returns TRUE or FALSE depending on whether tex is already loaded in
texture memory or not. With these two commands it is possible to
Page 16
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexture(3pf)
implement a rudimentary texture paging mechanism.
pfApplyTex and pfIdleTex are display-listable commands. If a pfDispList
has been opened by pfOpenDList, pfApplyTex and pfIdleTex will not have
immediate effect but will be captured by the pfDispList and will only
have effect when that pfDispList is later drawn with pfDrawDList.
pfApplyTexMinLOD sets the minLOD value in the graphics context in a frame
accurate manner. The command passes its argument directly to the DRAW
process by storing the minLOD value in a display list. In the DRAW
process, the OpenGL context is directly set with the minLOD value; the
minLOD value in the parent pfTexture class is unaffected. This command is
useful when the minLOD value must be changed multiple times per frame
during scene graph traversal; for example, in scene graph callbacks
supporting virtual cliptexures.
pfApplyTexMaxLOD sets the maxLOD value in the graphics context in a frame
accurate manner. The command passes its argument directly to the DRAW
process by storing the maxLOD value in a display list. In the DRAW
process, the OpenGL context is directly set with the maxLOD value; the
maxLOD value in the parent pfTexture class is unaffected. This command is
useful when the maxLOD value must be changed multiple times per frame
during scene graph traversal; for example, in scene graph callbacks
supporting virtual cliptexures.
pfApplyTexLODBias sets the S, T and R bias values in the graphics context
in a frame accurate manner. The command passes its arguments directly to
the DRAW process by storing the bias values in a display list. In the
DRAW process, the OpenGL context is directly set with the bias values;
the S, T, and R bias values in the parent pfTexture class are
unaffected. This command is useful when the bias values must be changed
multiple times per frame during scene graph traversal; for example, in
scene graph callbacks supporting virtual cliptexures.
pfApplyTMat will apply the pfMatrix mat to the global state and the
current GL texture matrix to transform texture coordinates. The GL
matrix mode will be left in model view mode.
NOTES
Since textures are an expensive hardware resource, the sharing of
textures is highly recommended. For best performance on machines which
support hardware texturing, all textures should fit in hardware texture
memory. Otherwise, the GL must page textures from main memory into the
graphics pipeline with a corresponding performance hit. For best
performance and use of memory:
Use the PFTEX_INTERNAL_FORMATS that have 16bit texels.
Keep textures of size an even power of two since they are always
rounded up to the next power of two for storage in hardware texture
Page 17
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexture(3pf)
memory in OpenGL will simply fail to work if they do not have sizes
that are a power of two.
Share pfTextures between pfGeoStates and share pfGeoStates between
pfGeoSets whenever possible.
Minimize the number of distinct detail and sharpen splines.
Check the graphics state statistics (see the pfStats man page) to
see if hardware texture memory is being swapped. As an additional
diagnostic, pfIsTexLoaded can be used in a pfGeoState callback
before applying a pfTexture to see if a load or swap will be
required.
For OpenGL operation, detail texturing requires the
GL_SGIS_detail_texture OpenGL extension and the sharpen filter requires
the GL_SGIS_sharpen_texture extension. pfIsTexLoaded requires the
EXT_texture_object OpenGL extension. See the EXT_texture_object section
of the OpenGL glIntro(3g) man page for more information.
A texture source of PFTEX_VIDEO is supported only on InfiniteReality and
RealityEngine graphics systems.
BUGS
MIPmap levels cannot be loaded or subloaded unless the have been
explicitly defined with pfTexLevel.
For PFTEX_SOURCE_VIDEO textures under OpenGL operation, the GL read
source will need to be reset whenever the current GL window is changed.
Additionally, Libpf applications will need to reset their GL read source
(glXMakeCurrentReadSGI) every frame in the drawing process.
SEE ALSO
pfDelete, pfDispList, pfEnable, pfFilePath, pfGeoState, pfGetGLHandle,
pfMalloc, pfObject, pfOverride, pfState, pfStats, pfTexEnv, pfTexGen,
pfTexLOD, tevbind, tevdef, texbind, texdef, glTexImage,
glDetailTexFuncSGIS, glSharpenTexFuncSGIS, glXMakeCurrentReadSGI
Page 18
