pfString(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfString(3pf)NAMEpfString - String facility using pfFont
FUNCTION SPECIFICATION
#include <Performer/pr/pfString.h>
pfString::pfString();
pfType* pfString::getClassType(void);
void pfString::setMat(const pfMatrix *mat);
void pfString::getMat(pfMatrix &at);
void pfString::setMode(int mode, int val);
int pfString::getMode(int mode);
void pfString::setFont(pfFont* font);
pfFont* pfString::getFont(void);
void pfString::setString(const char* cstr);
const char* pfString::getString(void);
void pfString::setBBox(pfBox *newBBox);
const pfBox* pfString::getBBox(void);
void pfString::setSpacingScale(float horiz, float vert,
float depth);
void pfString::getSpacingScale(float *horiz, float *vert,
float *depth);
void pfString::setColor(float r, float g, float b, float a);
void pfString::getColor(float *r, float *g, float *b,
float *a);
const pfGeoSet* pfString::getCharGSet(void);
const pfVec3* pfString::getCharPos(void);
size_t pfString::getStringLength(void);
void pfString::setGState(pfGeoState* gstate);
pfGeoState* pfString::getGState(void);
Page 1
pfString(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfString(3pf)
void pfString::draw(void);
void pfString::flatten(void);
void pfString::setIsectMask(uint mask, int setMode,
int bitOp);
uint pfString::getIsectMask(void);
int pfString::isect(pfSegSet *segSet, pfHit **hits[]);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfString is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfString. 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 pfString 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();
Page 2
pfString(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfString(3pf)
int pfMemory::getSize();
PARAMETERS
string identifies a pointer to a pfString
font identifies a pointer to a pfFont
DESCRIPTIONnew(arena) allocates a pfString from the specified memory arena, or from
the process heap if arena is NULL. new allocates a pfString from the
default memory arena (see pfGetSharedArena). Like other pfObjects,
pfStrings cannot be created statically, automatically on the stack or in
arrays. pfStrings should be deleted with pfDelete rather than the delete
operator.
pfString::getClassType returns the pfType* for the class pfString. The
pfType* returned by pfString::getClassType is the same as the pfType*
returned by invoking the virtual function getType on any instance of
class pfString. 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.
pfString::setMat sets the transformation matrix for the pfString to mat
or to the identity matrix if mat is NULL. Call pfString::getMat to
retrieve the matrix.
Use pfString::setMode and pfString::getMode to set and get modes of the
pfString. Use the PFSTR_JUSTIFY mode to set the justification of the
string to one of the following:
PFSTR_FIRST or PFSTR_LEFT
Set the string to be left-justified; the first character will
be immediately to the right of the origin.
PFSTR_MIDDLE or PFSTR_CENTER
Set the string to be center-justified; the string will be
centered at the origin.
PFSTR_LAST or PFSTR_RIGHT
Set the string to be right-justified; the last character will
be immediately to the left of the origin.
Use the PFSTR_CHAR_SIZE to specify the size, in bytes, of each character
in the string. val is one of PFSTR_CHAR, PFSTR_SHORT, PFSTR_INT
indicating that character sizes are sizeof(char), sizeof(short), and
sizeof(int) respectively.
Call pfString::getBBox to retrieve the bounding box around the pfString
as if it were drawn using the assigned justification, drawing style,
Page 3
pfString(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfString(3pf)
font, and character string. Call pfString::setBBox to set this bounding
box explicitly.
pfString::setSpacingScale and pfString::getSpacingScale set and get the
spacing scales of the pfString. Normally after rendering a character,
the rendering position is translated in x, y, and z by the character's
spacing which is supplied by the pfFont associated with the pfString.
This spacing is scaled by the supplied scale factors enabling
greater/lesser distances between characters. Also, when the
PFSTR_AUTO_SPACING mode is enabled, the spacing scales can be used to
change the direction of the rendered string, for example, spacing scales
of (0, -1, 0) will render the string vertically, suitable for labeling
the vertical axis of a 2D graph.
The default spacing scales are all 1.0 An interesting example is
horizontal scale 0 and vertical scale -1, in which case the string is
drawn downward like a neon sign outside a downtown bar and grill.
pfString::setGState and pfString::getGState set and get the pfGeoState
attached to the pfString. If no pfGeoState is attached, then the
pfString will be drawn with whatever graphics state is active at draw
time.
Call pfString::setFont and pfString::getFont to set or get the pfFont
used by the pfString. Call pfString::setString and pfString::getString
to set or get the character string for the pfString.
pfString::getStringLength will return the length of a pfString's current
character string. pfString::setColor and pfString::getColor get and set
string's color.
pfString::getCharGSet returns a pointer to the GeoSet currently being
used to draw the character at place index in the pfString's string.
pfString::getCharPos likewise returns a pointer to a pfVec3 that
specifies the exact location relative to the current transform where the
character in position index in the string array will be drawn. Both of
the above functions will return NULL if index is greater than or equal to
the pfString's length - which may be obtained through
pfString::getStringLength.
Call pfString::draw to draw the string, including applying the pfGeoState
if available, the color, and the texture if this is a PFSTR_TEXTURED
string.
A pfString is normally composed of a pfGeoSet per character in the
string. Call pfString::flatten to flatten the character spacings into
the individual GeoSets. A flattened primitive is faster, but flattening
has overhead which should be avoided if the string will be changing
quickly, e.g. in every frame. pfString::flatten Must be called every
time you change the contents of the string geometry; e.g. after calling
pfString::setString.
pfString::setIsectMask enables intersections and sets the intersection
Page 4
pfString(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfString(3pf)
mask for the pfString. mask is a 32-bit mask used to determine whether a
particular pfString should be examined during a particular intersection
request. A non-zero bit-wise AND of the pfString's mask with the mask of
the intersection request (pfString::isect) indicates that the pfString
should be tested. The default mask is all 1's, i.e. 0xffffffff.
pfString::getIsectMask returns the intersection mask of the specified
pfString.
pfString::isect tests for intersection between the pfString the pfString
and the group of line segments specified in string. This is done by
testing against each of the pfGeoSets in the pfString. The resulting
intersections (if any) are returned in hits. The return value of
pfString::isect is the number of segments that intersected the pfString.
See pfGSetIsectSegs for intersection information returned from tests
against the geometric primitives inside pfGeoSets.
NOTES
See pfText for sample code demonstrating pfString.
SEE ALSO
pfFont, pfDelete, pfGeoSet, pfText
Page 5
