pfuGridify(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages
NAME
pfuGridifySaveSize, pfuGridifyMem, pfuUnGridifyMem, pfuGridifyFileP,
pfuGridifyFile, pfuGridifyImageTile, pfuUnGridifyImageTile,
pfuGridifyImageCache, pfuUnGridifyImageCache, pfuGridifyClipTexture,
pfuUnGridifyClipTexture, pfuGridifyMPClipTexture,
pfuUnGridifyMPClipTexture, pfuGridifyAnyClipTexture,
pfuUnGridifyAnyClipTexture - Runtime clip texture gridification
FUNCTION SPECIFICATION
#include <Performer/pfutil.h>
int pfuGridifySaveSize(int width, int height, int pixeldepth,
int borderwidth);
void pfuGridifyMem(unsigned char *buf, int width, int height,
int pixeldepth, int borderwidth,
const unsigned char color[/* pixeldepth */],
unsigned char savecolors[/* pfuGridifySaveSize() */]);
void pfuUnGridifyMem(unsigned char *buf, int width, int height,
int pixeldepth, int borderwidth,
const unsigned char savedcolors[/* pfuGridifySaveSize() */]);
int pfuGridifyFileP(const char *infilename_for_errors, FILE *infp,
const char *outfilename_for_errors, FILE *outfp, int width,
int height, int pixeldepth, int borderwidth,
unsigned char color[/* pixeldepth */]);
int pfuGridifyFile(const char *filename, int width, int height,
int pixeldepth, int borderwidth,
unsigned char color[/* pixeldepth */]);
int pfuGridifyImageTile(pfImageTile *itile, int pixeldepth,
const unsigned char color[/* pixeldepth */], int isproto);
int pfuUnGridifyImageTile(pfImageTile *itile);
int pfuGridifyImageCache(pfImageCache *icache, int pixeldepth,
unsigned char color[/* pixeldepth */]);
int pfuUnGridifyImageCache(pfImageCache *icache);
int pfuGridifyClipTexture(pfClipTexture *cliptex);
int pfuUnGridifyClipTexture(pfClipTexture *cliptex);
int pfuGridifyMPClipTexture(pfMPClipTexture *mpcliptex);
int pfuUnGridifyMPClipTexture(pfMPClipTexture *mpcliptex);
Page 1
pfuGridify(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages
int pfuGridifyAnyClipTexture(pfNode *scene, int i);
int pfuUnGridifyAnyClipTexture(pfNode *scene, int i);
DESCRIPTION
The pfuGridify functions overlay color-coded grids on image tile data at
runtime, to facilitate visual verification of texel size, tile size, and
which mipmap levels of detail are being displayed. Functions are
provided to gridify image data that is represented in any of the
following forms: pfClipTexture, pfImageCache, pfImageTile, raw tile in
memory, or raw tile in file. For all but the last of these, the image
pixels clobbered by the grid is saved in a compact form so that the
corresponding pfuUnGridify function can retrieve them and restore the
original underlying image quickly. This allows an application to
efficiently toggle gridification at runtime. In the sample application
perfly, the 'g' key toggles clipmap gridification (if the scene contains
a clipmap).
If the image data is in an RGB format (PFTEX_RGBA_8 or PFTEX_RGB5_A1),
the grid color is chosen as follows, depending on the destination clipmap
level size:
cyan 1x1 64x64 4096x4096 262144x262144
blue 2x2 128x128 8192x8192 524288x524288
magenta 4x4 256x256 16384x16384 1048576x1048576
red 8x8 512x512 32767x32768 2097152x2097152
yellow 16x16 1024x1024 65535x65535 4194304x4194304
green 32x32 2048x2048 131072x131072 8388608x8388608
If the data is in luminance (PFTEX_I_8) format, the grid colors alternate
between black and white: black for 1x1, 4x4, 16x16, etc. and white for
2x2, 8x8, 32x32, etc.
The grid for a pfImageTile or raw memory or file tile consists of:
-- A 2-pixel border around the entire tile
-- A column of 4x8-pixel ticks, spaced 8 pixels apart, down the
center of the tile vertically, and a similar row of them across
the center horizontally
-- Two columns of 2x4-pixel ticks, spaced 16 pixels apart, at the
1/4 and 3/4 tile position, and similar rows of them.
Page 2
pfuGridify(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages
For example, this is the grid overlayed on a 128x128 tile (only the
upper-left quarter is shown):
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
::
::
:: ::::::::
:: ::::::::
::
::
:: .... ::::::::
:: """" ::::::::
::
::
:: ::::::::
:: ::::::::
::
::
:: :: .::. :: ::::::::
:: :: "::" :: ::::::::
::
::
:: ::::::::
:: ::::::::
::
::
:: .... ::::::::
:: """" ::::::::
::
::
:: ::::::::
:: ::::::::
::
:: :::: :::: :::: :::: :::: :::: :::: ::::
:: :::: :::: :::: :::: :::: :::: :::: ::::::::
:: :::: :::: :::: :::: :::: :::: :::: ::::::::
:: :::: :::: :::: :::: :::: :::: :::: ::::
::
:: ::::::::
Page 3
pfuGridify(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages
And this is the grid used for a 64x64 tile:
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
:: ::
:: ::
:: :::::::: ::
:: :::::::: ::
:: ::
:: ::
:: .::. :::::::: .::. ::
:: "::" :::::::: "::" ::
:: ::
:: ::
:: :::::::: ::
:: :::::::: ::
:: ::
:: :::: :::: :::: :::: :::: :::: :::: ::
:: :::: :::: :::: :::::::: :::: :::: :::: ::
:: :::: :::: :::: :::::::: :::: :::: :::: ::
:: :::: :::: :::: :::: :::: :::: :::: ::
:: ::
:: :::::::: ::
:: :::::::: ::
:: ::
:: ::
:: .::. :::::::: .::. ::
:: "::" :::::::: "::" ::
:: ::
:: ::
:: :::::::: ::
:: :::::::: ::
:: ::
:: ::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
Thus a user can look at geometry that is textured with a gridified
clipmap and deduce the following kinds of information:
Texel size and size of tiles and imagery in texels:
Use the known size of the ticks (4x8 texels and 2x4 texels),
the size of the tile border (2 texels wide around each tile, so
the boundary line between adjacent tiles is 4 texels wide), and
the spacing between ticks (little ticks are 16 texels apart,
big ticks are 8 texels apart) to measure sizes.
Which mipmap levels of detail are being displayed:
Look it up by color in the table above. For RGB data, the
colors repeat every 6 levels, so some deduction by other means
may be necessary (e.g. familiarity with the image data itself,
or fiddling with the minLOD or maxLOD slider). Usually it is
only necessary to think hard once in order to "get one's
bearings"; after that, it is easy see transitions between
levels and to figure out the size of a given level from
knowledge of adjacent levels.
Page 4
pfuGridify(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages
The pfuGridifySaveSize function takes the size (width,height) and
bytes-per-pixel (pixeldepth) of raw image tile in memory, and
returns the size in bytes of the buffer needed for saving and
restoring the image pixels that will get clobbered by pfuGridifyMem.
pfuGridifyMem takes a pointer buf to a tile of raw image data of
size width,height with pixeldepth bytes per pixel, and a given
borderwidth (2 is standard, but any number can be given; e.g. a
value larger than width/2 will change the tile to a solid color),
and gridifies it using the specified color for the grid. If
savecolors is not NULL, it must be a pointer to a buffer of size
previously returned by pfuGridifySaveSize to be used for saving the
image pixels that will get clobbered by the grid. pfuUnGridifyMem
undoes the effect of pfuGridifyMem.
pfuGridifyFile is just like pfuGridifyMem except that it operates on
a raw image tile in a file (specified by filename) rather than in
memory. There is no corresponding ungridify function, since it is
easy enough to simply save a copy of the original file. The
function return value is 1 indicating success, or 0 (and a pfNotify
message of level PFNFY_WARN) indicating failure to open, read from,
or write to the file.
pfuGridifyFileP is a lower-level interface to the functionality of
pfuGridifyFile. It takes file pointers (infp, outfp) and the input
file may be different from the output file. The parameters
infilename_for_errors and outfilename_for_errors are used for
printing in error messages, should an error occur. The function
return value is 1 indicating success, or 0 (and a pfNotify message
of level PFNFY_WARN) indicating failure to read from infp or write
to outfp.
pfuGridifyImageTile gridifies the pfImageTile itile using a border
width of 2 and pixeldepth bytes per pixel (which must be the actual
number of bytes per pixel in itile), with the given color. If
isproto is FALSE, this means waiting for the tile to become valid
and then gridifying the underlying memory. If isproto is true, it
means setting the readFunc so that all pfImageTiles cloned from
itile in the future will automatically get gridified as they are
read in from disk. pfuUnGridifyImageTile undoes the effect of
pfuGridifyImageTile. Both functions return 1 on success, or 0 (and
a pfNotify message of level PFNFY_WARN) if an error or unexpected
state is encountered (e.g. trying to gridify an already-gridified
image cache, or trying to ungridify one that has not been
gridified).
pfuGridifyImageCache gridifies the given image cache icache by
calling pfuGridifyImageTile with the given arguments on the
prototype tile and all tiles in the cache. pfuUnGridifyImageCache
undoes the effect of BpfuGridifyImageCache. Both function return 1
on success, or 0 (and a pfNotify message of level PFNFY_WARN) if an
error is encountered.
Page 5
pfuGridify(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages
pfuGridifyClipTexture gridifies the pfClipTexture cliptex by calling
pfuGridifyImageCache on each level (with grid colors assigned to
levels as described earlier), and then marking all destination
texture memory as invalid so that it will be reloaded.
pfuUnGridifyClipTexture undoes the effect of pfuGridifyClipTexture.
Both functions return 1 on success, or 0 (and a pfNotify message of
level PFNFY_WARN) if an error is encountered.
pfuGridifyAnyClipTexture is a convenience function that calls
pfuGridifyClipTexture on the i'th texture encountered during
traversal of the scene graph rooted at scene.
pfuUnGridifyAnyClipTexture undoes the effect of
pfuGridifyAnyClipTexture.
NOTES
In a multiprocess Performer application, these functions should only be
called from the DRAW process.
While a pfClipTexture, pfImageCache, or pfImageTile is in a gridified
state, its user data is used to store the saved pixels and callback
information, so applications cannot use the objects' user data for other
purposes.
The implementation of pfuGridifyImageCache (and thus also
pfuGridifyClipTexture which uses it) installs a wrapper readFunc on the
prototype tile. This wrapper calls the original readFunc and gridifies
the data before returning, allocating an array to store the saved pixels.
(The corresponding pfuUnGridify functions restore the saved pixels, free
the saved pixel array, and restore the original readFunc.) This
implementation has two important consequences: first, while an object is
in a gridified state, it can incur per-frame memory allocations and frees
(a practice that is frowned upon when trying to achieve consistent frame
rates). Second, applications that install a custom readFunc must take
care to do so *before* gridifying so that the gridification function will
wrap it properly.
pfuGridifyMPClipTexture and pfuUnGridifyMPClipTexture are not
implemented.
The libpfutil source code, object code and documentation are provided as
unsupported software. Routines are subject to change in future releases.
SEE ALSO
pfClipTexture, pfImageCache, pfImageTile, pfMultiprocess, pfNotify,
perfly
Page 6
