pfTexLoad(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexLoad(3pf)NAME
pfNewTLoad, pfGetTLoadClassType, pfTLoadAttr, pfGetTLoadAttr,
pfTLoadMode, pfGetTLoadMode, pfTLoadVal, pfGetTLoadVal, pfTLoadSrcOrg,
pfGetTLoadSrcOrg, pfTLoadDstOrg, pfGetTLoadDstOrg, pfTLoadSrc,
pfGetTLoadSrc, pfTLoadSrcLevel, pfGetTLoadSrcLevel, pfTLoadDst,
pfGetTLoadDst, pfTLoadDstLevel, pfGetTLoadDstLevel, pfTLoadSize,
pfGetTLoadSize, pfTLoadFrame, pfGetTLoadFrame,
pfGetTLoadPrevLoadedTexels, pfGetTLoadDirty, pfTLoadDirty,
pfGetTLoadStatus, pfApplyTLoad, pfApplyPartial - Create, modify, and
apply a texture load. Several sources can be loaded into a GL texture
(pfTexture).
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfTexLoad * pfNewTLoad(void *arena);
pfType * pfGetTLoadClassType(void);
void pfTLoadAttr(pfTexLoad* texload, int attr, void *val);
void * pfGetTLoadAttr(pfTexLoad* texload, int attr);
void pfTLoadMode(pfTexLoad* texload, int mode, int val);
int pfGetTLoadMode(pfTexLoad* texload, int mode);
void pfTLoadVal(pfTexLoad* texload, int which, float val);
float pfGetTLoadVal(pfTexLoad* texload, int which);
void pfTLoadSrcOrg(pfTexLoad* texload, int s, int t, int r);
void pfGetTLoadSrcOrg(pfTexLoad* texload, int *s, int *t,
int *r);
void pfTLoadDstOrg(pfTexLoad* texload, int s, int t, int r);
void pfGetTLoadDstOrg(pfTexLoad* texload, int *s, int *t,
int *r);
void pfTLoadSrc(pfTexLoad* texload, void *src);
void * pfGetTLoadSrc(pfTexLoad* texload);
void pfTLoadSrcLevel(pfTexLoad* texload, int lvl);
int pfGetTLoadSrcLevel(pfTexLoad* texload);
void pfTLoadDst(pfTexLoad* texload, void *tex);
Page 1
pfTexLoad(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexLoad(3pf)
void * pfGetTLoadDst(pfTexLoad* texload);
void pfTLoadDstLevel(pfTexLoad* texload, int lvl);
int pfGetTLoadDstLevel(pfTexLoad* texload);
void pfTLoadSize(pfTexLoad* texload, int w, int h, int d);
void pfGetTLoadSize(pfTexLoad* texload, int *w, int *h, int *d);
void pfTLoadFrame(pfTexLoad* texload, int frameCount);
int pfGetTLoadFrame(pfTexLoad* texload);
int pfGetTLoadPrevLoadedTexels(pfTexLoad* texload);
int pfGetTLoadDirty(pfTexLoad* texload);
int pfTLoadDirty(pfTexLoad* texload, int dirtmask);
int pfGetTLoadStatus(pfTexLoad* texload);
int pfApplyTLoad(pfTexLoad* texload);
int pfApplyPartial(pfTexLoad* texload, int texels);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfTexLoad is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfTexLoad. Casting an object of
class pfTexLoad 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);
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 pfTexLoad can also be used with these
functions designed for objects of class pfMemory.
Page 2
pfTexLoad(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexLoad(3pf)
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);
DESCRIPTION
pfTexLoad is used to control the mapping from texture images external to
the GL to texture images currently loaded into the GL. Each pfTexLoad
defines a load of a certain size from the origin of one of several
sources to a origin in a destination pfTexture which corresponds to a GL
texture. The functionality of this structure is to provide robust
support for glTexImage2D and glTexSubImage2DEXT.
pfNewTLoad creates and returns a handle to a new pfTexLoad. arena
specifies a malloc arena out of which the pfTexLoad is allocated or NULL
for allocation from the calling process' heap. pfTexLoads can be deleted
with pfDelete.
pfGetTLoadClassType returns the pfType* for the class pfTexLoad. The
pfType* returned by pfGetTLoadClassType is the same as the pfType*
returned by invoking pfGetType on any instance of class pfTexLoad. When
decisions are made based on the type of an object, it is usually better
to us 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.
The pfTLoadMode and pfGetTLoadMode routines set and get the modes of
operation for a pfTexLoad. Current modes include:
PFTLOAD_SOURCE
PFTLOAD_DEST
PFTLOAD_SYNC
PFTLOAD_SYNC_SOURCE
PFTLOAD_AUTOREF
PFTLOAD_SOURCE defines the nature of the source of imagery for the
texture download. The only currently supported value is:
PFTLOAD_SOURCE_IMAGETILE
but in future releases the following sources will be supported:
Page 3
pfTexLoad(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexLoad(3pf)
PFTLOAD_SOURCE_IMAGEARRAY
PFTLOAD_SOURCE_IMAGETILE
PFTLOAD_SOURCE_TEXTURE
PFTLOAD_SOURCE_VIDEO
PFTLOAD_SOURCE_FRAMEBUFFER
PFTLOAD_DEST currently only supports the PFTLOAD_DEST_TEXTURE as a
destination type.
PFTLOAD_SYNC defines when the pfTexLoad needs to take place. Currently
the only supported value for this mode is PFTLOAD_SYNC_IMMEDIATE -
meaning the download should take place immediately.
PFTLOAD_SYNC_SOURCE defines whether the load should require confirmation
of valid data from the source before loading. Possible values are PF_ON
and PF_OFF where a value of PF_ON means the load will only take place
after valid data is available from the load source. A value of PF_OFF
will cause the pfTexLoad to complete its download with whatever data is
available from the source regardless of its validity.
PFTLOAD_AUTOREF defines whether pfTexLoads should use pfUnref when they
get applied in pfDispList's. This mode allows users to keep track via a
reference count when the texture load actually took place. This in turn
facilitates reuse of pfTexLoad structures.
pfTLoadAttr and pfGetTLoadAttr set and get attributes of a pfTexLoad.
PFTLOAD_SOURCE and PFTLOAD_DEST allow the user to specify the source and
destination for a pfTexLoad. These attributes are equivalent to making
respective calls to pfTLoadSrc and pfTLoadDst.
pfTLoadVal allows the user to specify all of the values associated with a
pfTexLoad. This is redundant api allowing for the generic setting of
values that otherwise have individual explicit sets/gets associated with
them. Current value tokens:
PFTLOAD_SOURCE_LEVEL
PFTLOAD_SOURCE_S
PFTLOAD_SOURCE_T
PFTLOAD_SOURCE_T
PFTLOAD_SOURCE_R
PFTLOAD_DEST_LEVEL
PFTLOAD_DEST_S
PFTLOAD_DEST_T
PFTLOAD_DEST_R
PFTLOAD_WIDTH
PFTLOAD_HEIGHT
PFTLOAD_DEPTH
pfTLoadSrc sets the source data for the pfTexLoad. Currently the only
supported source type for pfTexLoads is PFTLOAD_SOURCE_IMAGETILE and
therefore _src must point to a pfImageTile. pfGetTLoadSrc returns the
Page 4
pfTexLoad(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexLoad(3pf)
pointer (if any) to the source data for the pfTexLoad.
pfTLoadDst sets the destination texture for the pfTexLoad. pfGetTLoadDst
returns a pointer to the pfTexture destination.
pfTLoadDstLevel sets a specific mipmap level in the destination pfTexture
for this texture load. pfGetTLoadDstLevel returns the currently
specified target mipmap level for the pfTexLoad.
pfTLoadSrcLevel sets a specific level from which to get data from the
source object. This value will not be used until pfTexture's are
supported as source's for pfTexLoads. pfGetTLoadSrcLevel will return the
current source level from which to retrieve load data if the source type
is PFTLOAD_SOURCE_TEXTURE.
pfTLoadSize sets the size of the pfTexLoad. w*h*d texels will be
downloaded when the pfTexLoad is applied. pfGetTLoadSize returns the
currently configured size of the pfTexLoad.
pfTLoadSrcOrg sets the origin inside a larger image from which to
retrieve the imagery that should be downloaded. pfGetTLoadSrcOrg returns
the origin of the download data within the possibly larger source
imagery.
pfTLoadDstOrg sets the origin inside the destination pfTexture where the
pfTexLoad should place its rectangular download region.
The above routines could be used to easily configure a download of a
256x256x1 sub-region of a 2048x1024x1 source image into a specific tile
within a 512x512x1 texture. In the above example if a user wished to
download the top right-hand corner of the source imagery into the middle
of the destination 512x512x1 texture, pfTLoadSrc would be called with a
pfImageTile representing the 2048x1024x1 source data, pfTLoadDst would be
called with the appropriate 512x512x1 pfTexture, pfTLoadSize would be
called with parameters 256,256,1. pfTLoadSrcOrg would be called with a
value of 1792,768,0 and pfTLoadDstOrg would be called with a value of
128,128,0.
pfApplyTLoad causes the preconfigured texture download to take place. If
there is a current pfDispList active then the pfTexLoad will place itself
into the pfDispList and the pfTexLoad apply which will perform the
download will happen when the pfDispList is drawn. Otherwise the texture
download will happen immediately.
pfApplyPartialTLoad acts just like the normal apply except that nTexels
is used to describe a subset of texels to download in the current apply.
Note that the actual apply can only download on row boundaries and so the
actual downloaded number of texels may differ slightly from that dictated
by the user. Partial applies always start at the bottom, lower left-hand
corner of the image and count to the right and then up where each row
must be loaded before the next is started. For example in the case of a
4x4 texture, a partial download of 4 texels will cause the bottom row of
Page 5
pfTexLoad(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfTexLoad(3pf)
the texture to be downloaded and not the bottom left 2x2 region. A
subsequent call causing another partial download of 4 texels would
download the 2nd row, and so on.
SEE ALSO
pfTexture, pfImageTile, glTexImage2D, glTexSubImage2DEXT
Page 6
