pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
NAME
pfNewImageTile, pfGetImageTileClassType, pfImageTileSize,
pfGetImageTileSize, pfImageTileOrigin, pfGetImageTileOrigin,
pfImageTileMem, pfGetImageTileMem, pfGetImageTileUnalignedMem,
pfGetImageTileNumImageComponents, pfImageTileMemImageFormat,
pfGetImageTileMemImageFormat, pfImageTileMemImageType,
pfGetImageTileMemImageType, pfGetImageTileMemImageTexelSize,
pfImageTileMemInfo, pfGetImageTileMemInfo, pfImageTileName,
pfGetImageTileName, pfImageTileFileName, pfGetImageTileFileName,
pfGetImageTileFileImageTexelSize, pfImageTileFileTile,
pfGetImageTileFileTile, pfImageTileNumFileTiles,
pfGetImageTileNumFileTiles, pfImageTileFileImageFormat,
pfGetImageTileFileImageFormat, pfImageTileFileImageType,
pfGetImageTileFileImageType, pfImageTileHeaderOffset,
pfGetImageTileHeaderOffset, pfImageTileDefaultTile,
pfGetImageTileDefaultTile, pfImageTileDefaultTileMode,
pfGetImageTileDefaultTileMode, pfGetImageTileSubTile,
pfGetImageTileValidSubTile, pfImageTileReadQueue,
pfGetImageTileReadQueue, pfGetImageTileTotalBytes,
pfGetImageTileValidBytes, pfGetImageTileValidTexels,
pfImageTileValidTexels, pfImageTileIsValid, pfImageTileIsDirty,
pfImageTileReadFunc, pfGetImageTileReadFunc, pfLoadImageTile,
pfLoadPartialImageTile, pfLoadImageTileFile, pfLoadPartialImageTileFile,
pfFreeImageTileMem, pfImageTileMemQueue, pfGetImageTileMemQueue,
pfImageTilePriority, pfGetImageTilePriority, pfImageTileSortFunc,
pfImageTileIsLoading, pfImageTileUseMemQueue, pfGetImageTileUseMemQueue,
pfImageTileFileNameFunc, pfGetImageTileFileNameFunc,
pfImageTileImageCache, pfGetImageTileImageCache, pfImageTileTileIndex,
pfGetImageTileTileIndex, pfProcessOneReadImageTile,
pfReadDirectImageTile, pfReadNormalImageTile, pfGetGlobalReadQueue,
pfDeleteGlobalReadQueue - Memory representation for rectangular
(sub)section of texture image.
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfImageTile * pfNewImageTile(void *arena);
pfType * pfGetImageTileClassType(void);
void pfImageTileSize(pfImageTile *tile, int w, int h,
int d);
void pfGetImageTileSize(pfImageTile *tile, int *w, int *h,
int *d);
void pfImageTileOrigin(pfImageTile *tile, int s, int t,
int r);
void pfGetImageTileOrigin(pfImageTile *tile, int *s, int *t,
int *r);
Page 1
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
void pfImageTileMem(pfImageTile *tile, unsigned char *img,
int nBytes);
unsigned char * pfGetImageTileMem(pfImageTile *tile);
unsigned char * pfGetImageTileUnalignedMem(pfImageTile *tile);
int pfGetImageTileNumImageComponents(pfImageTile *tile);
void pfImageTileMemImageFormat(pfImageTile *tile,
int format);
int pfGetImageTileMemImageFormat(pfImageTile *tile);
void pfImageTileMemImageType(pfImageTile *tile, int type);
int pfGetImageTileMemImageType(pfImageTile *tile);
int pfGetImageTileMemImageTexelSize(pfImageTile *tile);
void pfImageTileMemInfo(pfImageTile *tile, int psize,
int lock);
void pfGetImageTileMemInfo(pfImageTile *tile, int *psize,
int *lock);
void pfImageTileName(pfImageTile *tile, const char *fname);
const char * pfGetImageTileName(pfImageTile *tile);
void pfImageTileFileName(pfImageTile *tile,
const char *fname);
const char * pfGetImageTileFileName(pfImageTile *tile);
int pfGetImageTileFileImageTexelSize(pfImageTile *tile);
void pfImageTileFileTile(pfImageTile *tile, int tileS,
int tileT, int tileR);
void pfGetImageTileFileTile(pfImageTile *tile, int *tileS,
int *tileT, int *tileR);
void pfImageTileNumFileTiles(pfImageTile *tile, int nTilesS,
int nTilesT, int nTilesR);
void pfGetImageTileNumFileTiles(pfImageTile *tile,
int *nTilesS, int *nTilesT, int *nTilesR);
void pfImageTileFileImageFormat(pfImageTile *tile,
int fileFmt);
Page 2
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
int pfGetImageTileFileImageFormat(pfImageTile *tile);
void pfImageTileFileImageType(pfImageTile *tile,
int fileType);
int pfGetImageTileFileImageType(pfImageTile *tile);
void pfImageTileHeaderOffset(pfImageTile *tile, int offset);
int pfGetImageTileHeaderOffset(pfImageTile *tile);
void pfImageTileDefaultTile(pfImageTile *tile,
pfImageTile *default);
pfImageTile * pfGetImageTileDefaultTile(pfImageTile *tile);
void pfImageTileDefaultTileMode(pfImageTile *tile,
int useDefault);
int pfGetImageTileDefaultTileMode(pfImageTile *tile);
unsigned char * pfGetImageTileSubTile(pfImageTile *tile, int s, int t,
int r);
unsigned char * pfGetImageTileValidSubTile(pfImageTile *tile, int s,
int t, int r);
void pfImageTileReadQueue(pfImageTile *tile, pfQueue *q);
pfQueue * pfGetImageTileReadQueue(pfImageTile *tile);
int pfGetImageTileTotalBytes(pfImageTile *tile);
int pfGetImageTileValidBytes(pfImageTile *tile);
int pfGetImageTileValidTexels(pfImageTile *tile);
void pfImageTileValidTexels(pfImageTile *tile, int nTexels);
int pfImageTileIsValid(pfImageTile *tile);
int pfImageTileIsDirty(pfImageTile *tile);
void pfImageTileReadFunc(pfImageTile *tile,
pfReadImageTileFuncType func);
pfReadImageTileFuncType
pfGetImageTileReadFunc(pfImageTile *tile);
int pfLoadImageTile(pfImageTile *tile);
Page 3
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
int pfLoadPartialImageTile(pfImageTile *tile, int nTexels);
int pfLoadImageTileFile(pfImageTile *tile,
const char *fname);
int pfLoadPartialImageTileFile(pfImageTile *tile,
const char *fname, int nTexels);
void pfFreeImageTileMem(pfImageTile *tile);
void pfImageTileMemQueue(pfImageTile *tile, pfQueue *q);
pfQueue * pfGetImageTileMemQueue(pfImageTile *tile);
void pfImageTilePriority(pfImageTile *tile, int priority);
int pfGetImageTilePriority(pfImageTile *tile);
void pfImageTileSortFunc(pfQueueSortFuncData *data);
int pfImageTileIsLoading(pfImageTile *tile);
void pfImageTileUseMemQueue(short useMemTile);
short pfGetImageTileUseMemQueue(void);
void pfImageTileFileNameFunc(pfTileFileNameFuncType funptr);
pfTileFileNameFunc
pfGetImageTileFileNameFunc(void);
void pfImageTileImageCache(pfImageCache *icache);
pfImageCache * pfGetImageTileImageCache(void);
void pfImageTileTileIndex(int s, int t, int r);
void pfGetImageTileTileIndex(int *s, int *t, int *r);
int pfProcessOneReadImageTile(void *data);
int pfReadDirectImageTile(pfImageTile *itile, int ntexels);
int pfReadNormalImageTile(pfImageTile *itile, int ntexels);
pfQueue* pfGetGlobalReadQueue(void);
void pfDeleteGlobalReadQueue(void);
typedef int (*pfReadImageTileFuncType)(pfImageTile *itile,
int nTexels);
Page 4
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfImageTile is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfImageTile. Casting an object of
class pfImageTile 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 pfImageTile 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);
DESCRIPTION
A pfImageTile is representation of a texture image in main memory. A
pfImageTile can be used to load textures or pieces of texture from disk
and store them in certain byte configurations in main memory. Further
these pfImageTiles can then be used as the src for pfTextures or
pfTexLoads in order to load imagery into a GL texture from main memory.
pfNewImageTile creates and returns a handle to a new pfImageTile. The
argument arena specifies a malloc arena out of which the pfQueue is to be
allocated or NULL for allocation from the process heap. pfImageTiles can
be deleted with pfDelete.
Page 5
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
pfImageTileSize sets the size of this tile in each of the three supported
image dimensions. pfGetImageTileSize fills in its arguments with the
sizes for each of the three supported image dimensions. Any of the
arguments w,h,d may be NULL, in which case it will be ignored.
pfImageTileOrigin sets the origin of the subregion of the imagetile with
respect to the possibly larger whole image. pfGetImageTileOrigin fills
in its arguments with the imagetile's origin in each of the three
supported image dimensions. Any of the arguments s,t,r may be NULL, in
which case it will be ignored.
Thus one example of a pfImageTile might be representing a subregion of
2048x2048x1 image that was 256x256x1 in size starting at location
1024,512,0 in the larger image. In this case the origin of the imagetile
would be 1024,512,0 and the size would be 256,256,1.
pfGetImageTileMem returns a pointer to the memory used to represent the
actual image for the imagetile. This routine is used to allow routines
external to the imagetile to copy the image from external devices or
other memory into the imagetile efficiently. Note, this routine always
returns memory aligned on page boundaries - even if the memory was given
to the imagetile via pfImageTileMem.
pfGetImageTileUnalignedMem returns a pointer to the memory used to
represent the image for the imagetile. This routine returns the non-page
aligned version of the imagetile's memory; however, the data is
considered to start on the first page boundary - see pfGetImageTileMem.
This routine is useful for directly getting the memory pointer set on the
imagetile via pfImageTileMem.
pfImageTileMem assigns the memory that should be used to represent the
actual image for the imagetile. nBytes refers to the number of bytes
that can be stored in img - this information is useful if the imagetile
needs to be resized. Note that generically this memory will be allocated
and destroyed automatically and this piece of api need not be used for
normal applications.
pfImageTileMemImageFormat is used to set the memory format and number of
components used to represent an image texel in memory within the image
tile. The memory formats correspond to GL and Performer tokens used to
define the external formats of textures. See pfTexture and glTexImage2D.
pfGetImageTileMemImageFormat returns the memory format used to represent
each image texel within the imagetile. Possible memory formats include:
PFTEX_LUMINANCE, PFTEX_LUMINANCE_ALPHA, PFTEX_RGB, and PFTEX_RGBA.
pfImageTileMemImageType is used to set the data type of each
component/texel stored with the memory of the imagetile. The memory type
corresponds directly to the external memory type tokens passed into GL
and Performer when defining external memory representation of textures.
See pfTexture and glTexImage2D. pfGetImageTileMemImageType returns the
memory type used to represent each image texel within the imagetile.
Page 6
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
pfGetImageTileMemImageTexelSize returns the size in bytes of each texel
of the imagetile. This size is determined through knowing the number of
components within the image and the size of each component. This
information is directly derived from the memory format and memory type of
the imagetile.
pfGetImageTileNumImageComponents returns the number of color components
in each image texel, based on the imagetile's memory format and memory
type.
pfImageTileMemInfo is used to set two important characteristics about the
memory used to represent the texture image with the imagetile. psize is
used to describe the modulo on which the address of the actual data
representing the texture image must start. For instance if psize is set
to 4096 then the effective address if the texture image must be modulo
4096. The default psize is in fact 4096 which is the current onyx page
size. Also note that this causes slightly more memory to be used for the
image because in order to guarantee a modulo psize memory alignment from
malloc, malloc must be requested with a psize extra bytes and then when
the actual address from malloc is returned, it is effectively incremented
to the next psize boundary. lock specifies whether the memory should be
pinned down via mpin when allocated. Both of these parameters are
necessary if the memory will be used for direct IO reads from disk in
which case strict alignment requirements are needed because no
intermediate memory buffer is used when copying data from the disk.
pfGetImageTileMemInfo returns the information about whether the imagetile
should attempt to mpin memory it creates and what modulo should be used
as an alignment requirement for the memory representing the texture
image. Either of the arguments psize,lock may be NULL, in which case it
will be ignored.
pfImageTileName and pfGetImageTileName set and get the name of a
particular image tile. The name is useful for nothing other than to
represent a possible image name associated with all of the tiles of a
particular image.
pfImageTileFileName and pfGetImageTileFileName set and get the filename
associated with a particular image tile. This filename is used when the
imagetile is loaded via pfLoadImageTile.
pfImageTileFileImageFormat is used to set the texel format and number of
components used to represent an image texel in memory within the image
tile. The formats correspond to GL and Performer tokens used to define
the external formats of textures. See pfTexture and glTexImage2D.
pfGetImageTileFileImageFormat returns the format used to represent each
image texel within the imagetile on disk. Possible formats include:
PFTEX_LUMINANCE, PFTEX_LUMINANCE_ALPHA, PFTEX_RGB, and PFTEX_RGBA.
pfImageTileFileImageType is used to set the data type of each
component/texel stored within the imagetile data. The memory type
corresponds directly to the external memory type tokens passed into GL
and Performer when defining external memory representation of textures.
Page 7
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
See pfTexture and glTexImage2D. pfGetImageTileFileImageType returns the
data type used to represent each image texel within the imagetile as
stored externally to the tile.
pfGetImageTileFileImageTexelSize returns the size in bytes of each texel
of the imagetile. This size is determined through knowing the number of
components within the image and the size of each component. This
information is directly derived from the file format and file type of the
imagetile.
pfImageTileFileTile sets the subtile of the file in which the imagetile
exists. pfGetImageTileFileTile returns the file subtile for this
imagetile. Any of the arguments tileS,tileT,tileR may be NULL, in which
case it will be ignored. pfImageTileNumFileTiles sets the number of
tiles in each dimension within the file containing the pfImageTile.
pfGetImageTileNumFileTiles returns the number of tiles in each dimension
within the file containing the pfImageTile. Any of the arguments
nTilesS,nTilesT,nTilesR may be NULL, in which case it will be ignored.
pfImageTileHeaderOffset and pfGetImageTileHeaderOffset sets and gets the
header offset to be ignored at the beginning of reading pfImageTile's
from disk.
pfImageTileDefaultTile sets an alternate pfImageTile to use when data is
requested from this tile and is not available. pfGetImageTileDefaultTile
returns the alternate pfImageTile that was specified to be used when
image data is requested and is not available.
pfImageTileDefaultTileMode and pfGetImageTileDefaultTileMode set and gets
the mode associated with the use of the default pfImageTile associated
with this pfImageTile. PF_ON specifies to use the default when data is
unavailable, PF_OFF specifies to ignore the default tile.
pfGetImageTileSubTile returns a pointer to the texel corresponding to
s,t,r.
pfGetImageTileValidSubTile also returns a pointer to the texel
corresponding to s,t,r; however, this function will spin waiting for that
texel data to be validated before it returns. This is useful for
synchronizing texel data being loaded asynchronously.
pfImageTileValidTexels is used to explicitly set the valid portion of an
imagetile. When the number of valid texels is equal to the total number
of texels in the imagetile then the entire imagetile is marked as valid.
pfGetImageTileValidTexels returns the number of currently valid texels.
This number is determined by either the number of texels marked valid
through a pfLoadImageTile or explicitly set via pfImageTileValidTexels.
pfGetImageTileTotalBytes returns the total number of bytes required to
store a texture image within the imagetile. The value is calculated by
multiplying the total number of texels in the texture image by the size
Page 8
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
of each texel.
pfGetImageTileValidBytes returns the total number of valid bytes
available currently loaded of the image stored with the imagetile. The
value is calculated by multiplying the number of currently valid texels
by the size of each texel.
pfIsImageTileValid returns whether the entire texture image stored within
the imagetile has been loaded.
pfIsImageTileDirty returns whether something about the imagetile has
changed that could cause it have to be loaded.
pfImageTileReadFunc sets a function to call in order to perform the
actual read of data from disk or other external device into the
imagetile. The default function supports fast reading of several raw
data formats and will eventually support slow reading for a large number
of image formats. pfGetImageTileReadFunc returns the current function
used to read data into an imagetile when pfLoadImageTile is called.
pfImageTileReadQueue sets the queue the imagetile should be appended to
when it needs to be read. Setting q to NULL (the default) causes reads
to take place when load is called, in a synchronous process. Setting a q
to a valid read queue allows the read to happen asynchronously. See the
pfQueue man page for more information about queues.
pfHalveImageTile returns a new pfImageTile that contains a half
resolution version of the imagetile. This will be useful for creating
mipmaps but is currently not implemented.
pfLoadImageTile will cause the tile to be loaded either synchronously or
asynchronously depending on the imagetile's current read queue - see
pfImageTileReadQueue above. This routine will attempt to load the entire
image from the file specified via the imagetile's filename parameter.
pfLoadPartialImageTile specifies that ntexels texels should be read into
the imagetile and validated.
pfLoadImageTileFile effectively sets the filename of the imagetile and
causes it to be loaded.
pfLoadPartialImageTileFile sets the filename of the imagetile and causes
a partial load to take place.
pfFreeImageTileMem causes the memory used to hold the actual texture
image within the imagetile to be freed.
pfGetGlobalReadQueue will return a pointer to a preconfigured global read
queue with one service thread that can manage all loading of
pfImageTile's asynchronously.
pfDeleteGlobalReadQueue will delete the global read queue. The first time
Page 9
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
pfGetGlobalReadQueue is called after the read queue has been deleted, a
new one will be allocated and configured.
pfImageTileMemQueue sets the queue where image tiles will be place store
their pfMemory when they are reconfigured by an image cache. The memory
queue holds a list of pfMemorys. In practice, only the image tile used as
the proto tile needs to set a valid memqueue value. The use of the
MemQueue and be controlled via the pfImageTileUseMemQueue function
described below.
pfGetImageTileMemQueue returns the current value of the image tile's
memqueue pointer.
pfImageTileUseMemQueue is used to tell the ImageTile whether or not to
use the memory re-use queue described by pfImageTileMemQueue. The
default value is TRUE which will allow the queue to be used.
pfGetImageTileUseMemQueue returns TRUE if the imagetile is currently set
to use the memory reuse queue defined by pfImageTileMemQueue.
pfImageTilePriority set the priority of an image tile. The priority value
is used by sorting read queues when the PF_DTR_READSORT DTR mode is
enabled. The priority is used by the read queue's sort function when the
queue is in sorting mode. image tile elements are sorted by priority, so
the most important tiles are read first. The image cache that owns the
image tile sets the tiles' priority based on their distance from the
center of tex region. A tile's priority is more important if the priority
value is lower. pfGetImageTilePriority returns the current value of an
image tile's priority.
pfImageTileSortFunc is a static member function of the pfImageTile class.
It is used as the sorting function for the read queue of a pfImageCache.
It is not intended for general use by applications.
pfImageTileIsLoading indicates whether the image tile is currently being
processed by the read function. A value of non-zero means that the tile
represented by this image tile is being read from disk into a tile of the
image cache in system memory.
pfImageTileFileNameFunc sets the file name function that the read
function will call to dynamically evaluate the file name that should be
used to read tile data from disk to the image cache's mem region. The
default function, pfImageCache::autoConfigFileName(), takes an image tile
argument and computes the proper file name string using the parameter
values set in the pfImageCache object. This function pointer is
automatically set when the pfImageCache creates and configures its
pfImageTile objects.
pfGetImageTileFileNameFunc returns a function pointer showing the
pfImageTile object's file name function. This function is called by the
read function on the pfImageTile object to set the filename before
reading the file to download the texel data. An exmple function that uses
Page 10
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
this function is the ReadNormal and ReadDirect example read functions in
lib/libpfutil/pfdLoadImage.c
pfImageTileImageCache set the current pfImageCache pointer. The
pfImageCache object is used by the file name configuration function to
generate the image tile filename. This function is called by the read
function when the pfImageTile texel data is downloaded from disk the
pfImageCache object's mem region. This value is automatically set by the
pfImageCache object when it creates and configures its pfImageTile
objects.
pfGetImageTileImageCache returns a pointer to the current pfImageCache
object. If the pfImageTile object was created by the application, the
default value of the pointer is NULL. If created by a pfImageCache
object, the pointer will point to the creating pfImageCache.
pfImageTileTileIndex set the s, t, and r coordinates of the image tile
within the cliptexture level. This value positions the tile within the
complete virtual level. This value is set by the creating pfImageCache
object.
pfGetImageTileTileIndex return the current s, t, and r coordinates of the
image tile.
pfProcessOneReadImageTile this is the function that manages the global
read queue. The read queue calls this function with a pointer to the last
read element. The function casts the pointer to an pfImageTile pointer,
then calls the image tile's read function. The ProcessOneRead function
returns the number of bytes read.
pfReadDirectImageTile this is the default read function used by the
global read queue. It tries to use direct I/O for efficiency to read the
disk file containing the image cache data. The source code for the C
version of this function is defined in
/usr/share/Performer/src/lib/libpfdb/pfdLoadImage.c. If the disk file
can't be read using direct I/O, the function calls pfReadNormalImageTile.
pfReadNormalImageTile this is the fallback read function used by the
global read queue. It is called by pfReadDirectImageTile if it fails. It
tries to read the disk file using the FILE library. If it fails, it
prints a warning message. The source code for the C version of this
function is defined in
/usr/share/Performer/src/lib/libpfdb/pfdLoadImage.c.
SEE ALSO
pfImageCache, pfQueue, pfTexLoad, pfTexture
Page 11
