pfTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
NAME
pfTexture, pfGetCurTex, pfApplyTMat - Create, modify and query texture
FUNCTION SPECIFICATION
#include <Performer/pr/pfTexture.h>
pfTexture::pfTexture();
static pfType * pfTexture::getClassType(void);
void pfTexture::setName(const char *name);
void pfTexture::setMultiName(const char *name,
int imageIndex);
const char * pfTexture::getName(void);
const char * pfTexture::getMultiName(int imageIndex);
void pfTexture::setImage(uint* image, int comp, int ns,
int nt, int nr);
void pfTexture::setMultiImage(uint* image, int imageIndex,
int comp, int ns, int nt, int nr);
void pfTexture::getImage(uint **image, int *comp, int *ns,
int *nt, int *nr);
void pfTexture::getMultiImage(uint **image, int imageIndex,
int *comp, int *ns, int *nt, int *nr);
void pfTexture::setFormat(int format, int type);
int pfTexture::getFormat(int format);
void pfTexture::setFilter(int filt, int type);
int pfTexture::getFilter(int filt);
void pfTexture::setAnisotropy(int degree);
int pfTexture::getAnisotropy();
void pfTexture::setRepeat(int wrap, int type);
int pfTexture::getRepeat(int wrap);
void pfTexture::setBorderColor(pfVec4 clr);
void pfTexture::getBorderColor(pfVec4 *clr);
Page 1
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
void pfTexture::setBorderType(int type);
int pfTexture::getBorderType(void);
void pfTexture::setSpline(int type, pfVec2 *pts,
float clamp);
void pfTexture::getSpline(int type, pfVec2 *pts,
float *clamp);
void pfTexture::setDetail(int level, pfTexture *detail);
void pfTexture::getDetail(int *level, pfTexture **detail);
pfTexture * pfTexture::getDetailTex(void);
void pfTexture::setDetailTexTile(int j, int k, int m, int n,
int scram);
void pfTexture::getDetailTexTile(int *j, int *k, int *m,
int *n, int *scram);
void pfTexture::setList(pfList *list);
pfList * pfTexture::getList(void);
void pfTexture::setFrame(float frame);
float pfTexture::getFrame(void);
void pfTexture::setLoadMode(int mode, int val);
int pfTexture::getLoadMode(int mode);
void pfTexture::setLevel(int level, pfTexture *ltex);
pfTexture * pfTexture::getLevel(int level);
void pfTexture::setLODRange(float min, float max);
void pfTexture::getLODRange(float *min, float *max);
void pfTexture::getCurLODRange(float *min, float *max);
void pfTexture::setLODBias(float biasS, float biasT,
float biasR);
void pfTexture::getLODBias(float *biasS, float *biasT,
float *biasR);
Page 2
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
void pfTexture::getCurLODBias(float *biasS, float *biasT,
float *biasR);
void pfTexture::setLoadImage(uint* image);
uint * pfTexture::getLoadImage(void);
void pfTexture::setLoadOrigin(int which, int xo, int yo);
void pfTexture::getLoadOrigin(int which, int *xo, int *yo);
void pfTexture::setLoadSize(int xs, int ys);
void pfTexture::getLoadSize(int *xs, int *ys);
void pfTexture::apply(void);
void pfTexture::format(void);
void pfTexture::load(void);
void pfTexture::loadLevel(int level);
void pfTexture::subload(int source, uint *image, int xsrc,
int ysrc, int srcwid, int xdst, int ydst,
int xsize, int ysize);
void pfTexture::subloadMulti(int source, uint *image,
int imageIndex, int xsrc, int ysrc, int srcwid,
int xdst, int ydst, int xsize, int ysize);
void pfTexture::subloadLevel(int source, uint *image,
int xsrc, int ysrc, int srcwid, int xdst, int ydst,
int xsize, int ysize, int level);
void pfTexture::subloadMultiLevel(int source, uint *image,
imageIndex, int xsrc, int ysrc, int srcwid,
int xdst, int ydst, int xsize, int ysize,
int level);
int pfTexture::loadFile(char *fname);
int pfTexture::loadMultiFile(char *fname, int imageIndex);
int pfTexture::saveFile(char *fname);
int pfTexture::saveMultiFile(char *fname, int imageIndex);
void pfTexture::freeImage(void);
Page 3
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
void pfTexture::idle(void);
int pfTexture::isLoaded(void);
int pfTexture::isFormatted(void);
void pfTexture::applyMinLOD(float min);
void pfTexture::applyMaxLOD(float min);
void pfTexture::applyLODBias(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. This is also true for
ancestor classes of class pfObject.
void* pfObject::operator new(size_t);
void* pfObject::operator new(size_t, void *arena);
void* pfObject::operator new(size_t, pfFluxMemory *fmem);
void pfObject::setUserData(void *data);
void pfObject::setUserData(int slot, void *data);
void* pfObject::getUserData(pfObject *obj);
void* pfObject::getUserData(pfObject *obj, int slot);
int pfObject::getNumUserData();
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.
void* pfMemory::getData(const void *ptr);
pfType * pfMemory::getType();
int pfMemory::isOfType(pfType *type);
int pfMemory::isExactType(pfType *type);
const char * pfMemory::getTypeName();
int pfMemory::copy(pfMemory *src);
int pfMemory::compare(const pfMemory *mem);
void pfMemory::print(uint which, uint verbose, char *prefix,
FILE *file);
int pfMemory::getArena(void *ptr);
void* pfMemory::getArena();
int pfMemory::ref();
int pfMemory::unref();
Page 4
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
int pfMemory::unrefDelete();
int pfMemory::unrefGetRef();
int pfMemory::getRef();
int pfMemory::checkDelete();
int pfMemory::isFluxed();
void * pfMemory::getArena();
int pfMemory::getSize();
PARAMETERS
tex identifies a pfTexture.
DESCRIPTIONnew(arena) allocates a pfTexture from the specified memory arena, or from
the process heap if arena is NULL. new allocates a pfTexture from the
default memory arena (see pfGetSharedArena). Like other pfObjects,
pfTextures cannot be created statically, automatically on the stack or in
arrays. pfTextures should be deleted with pfDelete rather than the
delete operator.
pfTexture::getClassType returns the pfType* for the class pfTexture. The
pfType* returned by pfTexture::getClassType is the same as the pfType*
returned by invoking the virtual function getType 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 the member function isOfType 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.
pfTexture::loadFile 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 the pfTexture. Image memory is
allocated out of the malloc arena in which the pfTexture was created. A
return of FALSE indicates failure, TRUE success.
pfTexture::loadFile also sets the name of the pfTexture to the pathname
of the file that was loaded (see pfTexture::setName).
pfTexture::saveFile 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.
pfTexture::setImage sets the image used by the pfTexture. image is an
array of texel data. pfTexture::setImage 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
Page 5
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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. pfTexture::getImage returns the
texture image parameters of the pfTexture. Any or all of the arguments
to pfTexture::getImage may be NULL, in which case those arguments are
ignored.
pfTexture::freeImage frees the texture image memory associated with the
pfTexture after the next pfTexture::apply 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 pfTexture::freeImage if the pfTexture is to be used
in multiple OpenGL windows. If the image is freed on the first
pfTexture::apply then it will not be around when the pfTexture is applied
in a second window. In this case the image should be freed only when the
pfTexture has been applied in all windows.
pfTexture::setName assigns the character string name to the pfTexture.
Names are useful for sharing textures in order to optimize texture memory
usage. A pfTexture's name is also set by pfTexture::loadFile which sets
the name to the pathname of the file that was loaded. pfTexture::getName
returns the name of the pfTexture.
pfTexture::setFormat specifies how the texture image memory associated
with the pfTexture is formatted by pfTexture::format. 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 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.
Page 6
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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.
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).
Page 7
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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 pfTexture::apply 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
image will not be automatically restored upon pfApplyTex
unless the PFTEX_BASE_AUTO_SUBLOAD mode has been specified
for the pfTexture::setLoadMode. and can always be
explicitly reloaded with pfTexture::load. This format
also specifies that all loads of the texture will use the
origin, size and image specified by
pfTexture::setLoadOrigin, pfTexture::setLoadSize, and
pfTexture::setLoadImage. 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, pfTexture::freeImage
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
Page 8
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfTexture::setMultiImage, 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: pfTexture::setMultiName,
pfTexture::getMultiName, pfTexture::loadMultiFile,
pfTexture::saveMultiFile, pfTexture::subloadMulti,
pfTexture::subloadMultiLevel.
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. pfTexture::getFormat returns the format mode corresponding to
format.
pfTexture::setRepeat 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. pfTexture::getRepeat returns the texture coordinate repeat
function corresponding to wrap.
pfTexture::setFilter sets a filter function used by the pfTexture. 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
Page 9
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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
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
Page 10
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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. pfTexture::getFilter returns
the filter type of filter.
pfTexture::setAnisotropy sets an anisotropic filter to be used by the
pfTexture. The degree argument is the degree of anisotropy to be
applied. pfTexture::getAnisotropy will return the degree of anisotropy
set by pfTexture::setAnisotropy. 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 pfTexture::setBorderType 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 pfTexture::setBorderColor. 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.
pfTexture::getBorderType will return the texture border type and
pfTexture::getBorderColor 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.
pfTexture::setDetail sets detail as the detail texture of the pfTexture
or disables detailing of the pfTexture 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
Page 11
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
level is four which creates a 16:1 mapping from detail texels to base
texels. pfTexture::setDetail will also set the magnification filter of
the pfTexture 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 pfTexture::apply 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.
pfTexture::getDetail returns the detail texture of the pfTexture 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 pfTexture::setSpline. pfTexture::getDetailTex
returns the detail texture of the pfTexture, or NULL if the texture is
not detailed.
pfTexture::setLevel sets a minification or magnification texture ltex
for the level level for the base texture. 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. pfTexture::getLevel will return the texture for the specified
level.
pfTexture::setLODRange 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. pfTexture::getLODRange
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.
pfTexture::getCurLODRange 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 will be returned. NULL arguments to pfTexture::getLODRange and
pfTexture::getCurLODRange are legal (they are ignored).
pfTexture::setLODBias 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
Page 12
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
to PFTEX_DEFAULT. pfTexture::getLODBias will return the texture LOD bias
values. If the bias values are unset, PFTEX_DEFAULT will be returned in
the bias values. pfTexture::getCurLODBias 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
pfTexture::getLODBias and pfTexture::getCurLODBias are legal (they are
ignored).
pfTexture::setSpline 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. pfTexture::getSpline
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.
pfTexture::setList sets a pfList of pfTexture*, list, on the pfTexture.
pfTexture::getList returns the texture list. pfTexture::setFrame selects
a frame from the texture list of the pfTexture upon pfTexture::apply.
The default frame value is (-1) which selects the base texture.
pfTexture::getFrame returns the current pfTexture frame.
pfTexture::setList and pfTexture::setFrame 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 pfTexture::setLoadMode controls
how textures replace previous texture from the same list for efficient
hardware texture memory management.
pfTexture::format creates a GL/hardware ready texture for the specified
pfTexture, the pfTexture. All pfTexture parameters are take into
account. Changing any parameter on a pfTexture will cause it to need to
be re-formatted. pfTexture::isFormatted will return the formatted state
of the texture. pfObject::getGLHandle will return the handle to the
resulting GL texture, valid only for the current GL context.
pfTexture::load downloads the specified texture source to graphics
hardware texture memory allocated to the pfTexture. Repeated calls to
pfTexture::load will reload the image specified by
pfTexture::setLoadImage or else the main texture image set by
pfTexture::setImage or pfTexture::loadFile down into the graphics
Page 13
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
subsystem, allowing the contents of the texture image to be changed
dynamically. If a reformatting of the texture is required,
pfTexture::format 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 pfTexture::setLoadOrigin and pfTexture::setLoadSize will
be used. pfTexture::isLoaded will return whether or not the specified
pfTexture is currently resident in hardware texture memory. However,
pfTexture::isLoaded will not reflect whether or not additional changes
made to the contents of the texture image have been downloaded.
pfTexture::loadLevel 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. pfTexture::load and
pfTexture::loadLevel change the current pfTexture to be undefined.
pfTexture::subload downloads a specified texture source to graphics
hardware memory allocated to the pfTexture according to the specified
source, image, origin, width of complete image, destination, and subload
size, which may be different than the load parameters in the pfTexture.
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.
pfTexture::subloadLevel 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. pfTexture::subload and
pfTexture::subloadLevel change the current pfTexture to be undefined.
pfTexture::setLoadImage 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
pfTexture::apply and pfTexture::load. If image is NULL, then texture
downloads will go back to using the main image pointer on the pfTexture,
set through pfTexture::setImage or pfTexture::loadFile.
pfTexture::getLoadImage will return the previously set load image of the
pfTexture.
Portions of a texture images may be updated by specifying a
pfTexture::setLoadOrigin and pfTexture::setLoadSize.
pfTexture::setLoadOrigin sets the origin of the texture image source or
destination, according to which. pfTexture::setLoadSize sets the texture
area size, in texels, that is to be downloaded. These settings will
affect future texture loads that are triggered by pfTexture::apply and
pfTexture::load. pfTexture::getLoadSize will return the previously set
Page 14
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
load size of the pfTexture. pfTexture::getLoadOrigin will return the
source or destination load origin, as specified by which of the
pfTexture. The x or y argument to pfTexture::getLoadSize
pfTexture::getLoadOrigin may be NULL, in which case it is ignored.
pfTexture::setLoadMode 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
pfTexture::setImage, 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 pfTexture::apply of the
pfTexture. The PFTEX_BASE_AUTO_SUBLOAD will automatically replace the
texture from the specified texture source upon every call to
pfTexture::apply. 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
pfTexture::setLoadOrigin and pfTexture::setLoadSize.
pfTexture::getLoadMode will return the value of mode for the pfTexture.
pfTexture::apply makes the pfTexture the current texture. When texturing
is enabled (see below), this texture will be applied to all geometry
drawn after pfTexture::apply 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 pfTexture::apply,
pfTexture::format and pfTexture::load will be called automatically.
Modifications to the pfTexture, such as changing the filter type, will
not have effect until pfTexture::apply is called with the pfTexture.
pfGetCurTex returns the currently active pfTexture.
pfTexture::apply will automatically apply the detail texture associated
with the pfTexture and will disable detail texturing if the pfTexture has
no associated detail texture.
For geometry to be textured, the following must be true:
Page 15
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
1. Texturing must be enabled: pfEnable(PFEN_TEXTURE)
2. A pfTexEnv must be applied: pfTexEnv::apply
3. A pfTexture must be applied: pfTexture::apply
4. Geometry must have texture coordinates: pfGeoSet::setAttr,
PFGS_TEXCOORD2
The texture state element is identified by the PFSTATE_TEXTURE token.
Use this token with pfGeoState::setAttr 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 */
tev->apply();
/* Set up textured pfGeoState */
gstate->setMode(PFSTATE_ENTEXTURE, PF_ON);
gstate->setAttr(PFSTATE_TEXTURE, tex);
/* Attach gstate to gset */
gset->setGState(gstate);
/* Set texture coordinate array. 'gset' is non-indexed */
gset->setAttr(PFGS_TEXCOORD2, PFGS_PER_VERTEX, tcoords,NULL);
/* Draw textured gset */
gset->draw();
Example 2:
tex->apply();
/* 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.
pfTexture::idle and pfTexture::isLoaded can help you efficiently manage
hardware texture memory. pfTexture::idle signifies that the pfTexture is
no longer needed in texture memory and may be replaced by new textures.
pfTexture::isLoaded returns TRUE or FALSE depending on whether the
pfTexture is already loaded in texture memory or not. With these two
commands it is possible to implement a rudimentary texture paging
mechanism.
Page 16
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfTexture::apply and pfTexture::idle are display-listable commands. If a
pfDispList has been opened by pfDispList::open, pfTexture::apply and
pfTexture::idle will not have immediate effect but will be captured by
the pfDispList and will only have effect when that pfDispList is later
drawn with pfDispList::draw.
pfTexture::applyMinLOD 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.
pfTexture::applyMaxLOD 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.
pfTexture::applyLODBias 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
memory in OpenGL will simply fail to work if they do not have sizes
Page 17
pfTexture(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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, pfTexture::isLoaded 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. pfTexture::isLoaded 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
