pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
NAME
pfImageTile, pfGetGlobalReadQueue, pfDeleteGlobalReadQueue - Memory
representation for rectangular (sub)section of texture image.
FUNCTION SPECIFICATION
#include <Performer/pr/pfImageTile.h>
void pfImageTile::pfImageTile();
void pfImageTile::setSize(int w, int h, int d);
void pfImageTile::getSize(int *w, int *h, int *d);
void pfImageTile::setOrigin(int s, int t, int r);
void pfImageTile::getOrigin(int *s, int *t, int *r);
void pfImageTile::setMem(unsigned char *img, int nBytes);
unsigned char * pfImageTile::getMem(void);
unsigned char * pfImageTile::getUnalignedMem(void);
int pfImageTile::getNumImageComponents(void);
void pfImageTile::setMemImageFormat(int format);
int pfImageTile::getMemImageFormat(void);
void pfImageTile::setMemImageType(int type);
int pfImageTile::getMemImageType(void);
int pfImageTile::getMemImageTexelSize(void);
void pfImageTile::setMemInfo(int psize, int lock);
void pfImageTile::getMemInfo(int *psize, int *lock);
void pfImageTile::setName(const char *fname);
const char * pfImageTile::getName(void);
void pfImageTile::setFileName(const char *fname);
const char * pfImageTile::getFileName(void);
int pfImageTile::getFileImageTexelSize(void);
void pfImageTile::setFileTile(int tileS, int tileT,
int tileR);
Page 1
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
void pfImageTile::getFileTile(int *tileS, int *tileT,
int *tileR);
void pfImageTile::setNumFileTiles(int nTilesS, int nTilesT,
int nTilesR);
void pfImageTile::getNumFileTiles(int *nTielsS,
int *nTilesT, int *nTilesR);
void pfImageTile::setFileImageFormat(int fileFmt);
int pfImageTile::getFileImageFormat(void);
void pfImageTile::setFileImageType(int fileType);
int pfImageTile::getFileImageType(void);
void pfImageTile::setHeaderOffset(int offset);
int pfImageTile::getHeaderOffset(void);
unsigned char * pfImageTile::getSubTile(int s, int t, int r);
unsigned char * pfImageTile::getValidSubTile(int s, int t, int r);
void pfImageTile::setReadQueue(pfQueue *q);
pfQueue * pfImageTile::getReadQueue(void);
int pfImageTile::getTotalBytes(void);
int pfImageTile::getValidBytes(void);
int pfImageTile::getValidTexels(void);
void pfImageTile::setValidTexels(int nTexels);
int pfImageTile::isValid(void);
int pfImageTile::isDirty(void);
void pfImageTile::setReadFunc(pfReadImageTileFuncType func);
pfReadImageTileFuncType
pfImageTile::getReadFunc(void);
void pfImageTile::setDefaultTile(pfImageTile *default);
pfImageTile * pfImageTile::getDefaultTile(void);
Page 2
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
void pfImageTile::setDefaultTileMode(int useDefault);
int pfImageTile::getDefaultTileMode(void);
int pfImageTile::load(void);
int pfImageTile::load(int nTexels);
int pfImageTile::load(const char *fname);
int pfImageTile::load(const char *fname, int nTexels);
void pfImageTile::freeMem(void);
void pfImageTile::setMemQueue(pfQueue *q);
pfQueue * pfImageTile::getMemQueue(void);
void pfImageTile::setPriority(int priority);
int pfImageTile::getPriority(void);
void pfImageTile::sortFunc(pfQueueSortFuncData *data);
int pfImageTile::isLoading(void);
void pfImageTile::setUseMemQueue(short useMemQueue);
short pfImageTile::getUseMemQueue(void);
void -
pfImageTile::setFileNameFunc(pfTileFileNameFuncType fnptr);
pfTileFileNameFuncType
pfImageTile::getFileNameFunc(void);
void pfImageTile::setImageCache(pfImageCache *icache);
pfImageCache * pfImageTile::getImageCache(void)
void pfImageTile::setTileIndex(int s, int t, int r);
void pfImageTile::getTileIndex(int *s, int *t, int *r);
int pfImageTile::ProcessOneRead(void *data);
int pfImageTile::ReadDirect(pfImageTile *itile,
int ntexels);
int pfImageTile::ReadNormal(pfImageTile *itile,
int ntexels);
Page 3
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfQueue* pfGetGlobalReadQueue(void);
void pfDeleteGlobalReadQueue(void);
typedef int (*pfReadImageTileFuncType)(pfImageTile *itile,
int nTexels);
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. 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 pfImageTile 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();
int pfMemory::unrefDelete();
int pfMemory::unrefGetRef();
int pfMemory::getRef();
int pfMemory::checkDelete();
int pfMemory::isFluxed();
void * pfMemory::getArena();
int pfMemory::getSize();
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
Page 4
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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.
The default constructor pfImageTile creates a pfImageTile. new(arena)
allocates a pfImageTile from the specified memory arena, or from the
process heap if arena is NULL. new allocates a pfImageTile from the
default memory arena (see pfGetSharedArena). Like other pfObjects,
pfImageTiles cannot be created statically, automatically on the stack or
in arrays. pfImageTiles should be deleted with pfDelete rather than with
the delete operator.
pfImageTile::setSize sets the size of this tile in each of the three
supported image dimensions. pfImageTile::getSize 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.
pfImageTile::setOrigin sets the origin of the subregion of the imagetile
with respect to the possibly larger whole image. pfImageTile::getOrigin
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.
pfImageTile::getMem 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 pfImageTile::setMem.
pfImageTile::getUnalignedMem 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 pfImageTile::getMem.
This routine is useful for directly getting the memory pointer set on the
imagetile via pfImageTile::setMem.
pfImageTile::setMem 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.
pfImageTile::setMemImageFormat 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
Page 5
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
glTexImage2D. pfImageTile::getMemImageFormat 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.
pfImageTile::setMemImageType 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. pfImageTile::getMemImageType returns the
memory type used to represent each image texel within the imagetile.
pfImageTile::getMemImageTexelSize 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.
pfImageTile::getNumImageComponents returns the number of color components
in each image texel, based on the imagetile's memory format and memory
type.
pfImageTile::setMemInfo 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. pfImageTile::getMemInfo 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.
pfImageTile::setName and pfImageTile::getName 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.
pfImageTile::setFileName and pfImageTile::getFileName set and get the
filename associated with a particular image tile. This filename is used
when the imagetile is loaded via pfImageTile::load.
Page 6
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfImageTile::setFileImageFormat 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. pfImageTile::getFileImageFormat 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.
pfImageTile::setFileImageType 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.
See pfTexture and glTexImage2D. pfImageTile::getFileImageType returns
the data type used to represent each image texel within the imagetile as
stored externally to the tile.
pfImageTile::getFileImageTexelSize 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.
pfImageTile::setFileTile sets the subtile of the file in which the
imagetile exists. pfImageTile::getFileTile returns the file subtile for
this imagetile. Any of the arguments tileS,tileT,tileR may be NULL, in
which case it will be ignored. pfImageTile::setNumFileTiles sets the
number of tiles in each dimension within the file containing the
pfImageTile. pfImageTile::getNumFileTiles 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.
pfImageTile::setHeaderOffset and pfImageTile::getHeaderOffset sets and
gets the header offset to be ignored at the beginning of reading
pfImageTile's from disk.
pfImageTile::setDefaultTile sets an alternate pfImageTile to use when
data is requested from this tile and is not available.
pfImageTile::getDefaultTile returns the alternate pfImageTile that was
specified to be used when image data is requested and is not available.
pfImageTile::setDefaultTileMode and pfImageTile::getDefaultTileMode 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.
pfImageTile::getSubTile returns a pointer to the texel corresponding to
s,t,r.
pfImageTile::getValidSubTile also returns a pointer to the texel
corresponding to s,t,r; however, this function will spin waiting for that
Page 7
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
texel data to be validated before it returns. This is useful for
synchronizing texel data being loaded asynchronously.
pfImageTile::setValidTexels 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.
pfImageTile::getValidTexels returns the number of currently valid texels.
This number is determined by either the number of texels marked valid
through a pfImageTile::load or explicitly set via
pfImageTile::setValidTexels.
pfImageTile::getTotalBytes 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
of each texel.
pfImageTile::getValidBytes 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.
pfImageTile::isValid returns whether the entire texture image stored
within the imagetile has been loaded.
pfImageTile::isDirty returns whether something about the imagetile has
changed that could cause it have to be loaded.
pfImageTile::setReadFunc 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. pfImageTile::getReadFunc returns the current function
used to read data into an imagetile when pfImageTile::load is called.
pfImageTile::setReadQueue 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.
pfImageTile::halve 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.
pfImageTile::load will cause the tile to be loaded either synchronously
or asynchronously depending on the imagetile's current read queue - see
pfImageTile::setReadQueue above. This routine will attempt to load the
entire image from the file specified via the imagetile's filename
parameter.
Page 8
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfImageTile::load(int ntexels) specifies that ntexels texels should be
read into the imagetile and validated.
pfImageTile::load(const char *fname) effectively sets the filename of the
imagetile and causes it to be loaded.
pfImageTile::load(const char *fname, int ntexels) sets the filename of
the imagetile and causes a partial load to take place.
pfImageTile::freeMem 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
pfGetGlobalReadQueue is called after the read queue has been deleted, a
new one will be allocated and configured.
pfImageTile::setMemQueue 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 pfImageTile::setUseMemQueue
function described below.
pfImageTile::getMemQueue returns the current value of the image tile's
memqueue pointer.
pfImageTile::setUseMemQueue is used to tell the ImageTile whether or not
to use the memory re-use queue described by pfImageTile::setMemQueue.
The default value is TRUE which will allow the queue to be used.
pfImageTile::getUseMemQueue returns TRUE if the imagetile is currently
set to use the memory reuse queue defined by pfImageTile::setMemQueue.
pfImageTile::setPriority 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. pfImageTile::getPriority returns the current value of an
image tile's priority.
pfImageTile::sortFunc 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.
pfImageTile::isLoading indicates whether the image tile is currently
Page 9
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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.
pfImageTile::setFileNameFunc 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.
pfImageTile::getFileNameFunc 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
this function is the ReadNormal and ReadDirect example read functions in
lib/libpfutil/pfdLoadImage.c
pfImageTile::setImageCache 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.
pfImageTile::getImageCache 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.
pfImageTile::setTileIndex 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.
pfImageTile::getTileIndex return the current s, t, and r coordinates of
the image tile.
pfImageTile::ProcessOneRead 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.
pfImageTile::ReadDirect 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
Page 10
pfImageTile(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
can't be read using direct I/O, the function calls
pfImageTile::ReadNormal.
pfImageTile::ReadNormal this is the fallback read function used by the
global read queue. It is called by pfImageTile::ReadDirect 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
