pfString(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfString(3pf)NAME
pfNewString, pfGetStringClassType, pfStringMat, pfGetStringMat,
pfStringMode, pfGetStringMode, pfStringFont, pfGetStringFont,
pfStringString, pfGetStringString, pfStringBBox, pfGetStringBBox,
pfStringSpacingScale, pfGetStringSpacingScale, pfStringColor,
pfGetStringColor, pfGetStringCharGSet, pfGetStringCharPos,
pfGetStringStringLength, pfStringGState, pfGetStringGState, pfDrawString,
pfFlattenString, pfStringIsectMask, pfGetStringIsectMask,
pfStringIsectSegs - String facility using pfFont
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfString* pfNewString(void *arena);
pfType* pfGetStringClassType(void);
void pfStringMat(pfString *string, const pfMatrix mat);
void pfGetStringMat(const pfString *string, pfMatrix mat);
void pfStringMode(pfString *string, int mode, int val);
int pfGetStringMode(const pfString *string, int mode);
void pfStringFont(pfString *string, pfFont* font);
pfFont* pfGetStringFont(const pfString *string);
void pfStringString(pfString *string, const char* cstr);
const char* pfGetStringString(const pfString *string);
void pfStringBBox(pfString *string, const pfBox *newBBox);
const pfBox* pfGetStringBBox(pfString *string);
void pfStringSpacingScale(pfString *string, float horiz,
float vert, float depth);
void pfGetStringSpacingScale(const pfString *string,
float *horiz, float *vert, float *depth);
void pfStringColor(pfString *string, float r, float g,
float b, float a);
void pfGetStringColor(const pfString *string, float *r,
float *g, float *b, float *a);
const pfGeoSet* pfGetStringCharGSet(pfString *string, int index);
Page 1
pfString(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfString(3pf)
const pfVec3* pfGetStringCharPos(pfString *string, int index);
size_t pfGetStringStringLength(pfString *string);
void pfStringGState(pfString *string, pfGeoState* gstate);
pfGeoState* pfGetStringGState(const pfString *string);
void pfDrawString(pfString *string);
void pfFlattenString(pfString *string);
void pfStringIsectMask(pfString *string, uint mask,
int setMode, int bitOp);
uint pfGetStringIsectMask(pfString *string);
int pfStringIsectSegs(pfString *string, 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. Casting an object of
class pfString 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 pfString 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);
Page 2
pfString(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfString(3pf)
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);
PARAMETERS
string identifies a pointer to a pfString
font identifies a pointer to a pfFont
DESCRIPTION
pfNewString creates and returns a handle to a pfString. arena specifies
a malloc arena out of which the pfString is allocated or NULL for
allocation off the process heap. pfStrings can be deleted with pfDelete.
pfGetStringClassType returns the pfType* for the class pfString. The
pfType* returned by pfGetStringClassType is the same as the pfType*
returned by invoking pfGetType 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 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.
pfStringMat sets the transformation matrix for string to mat or to the
identity matrix if mat is NULL. Call pfGetStringMat to retrieve the
matrix.
Use pfStringMode and pfGetStringMode to set and get modes of the string.
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
Page 3
pfString(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfString(3pf)
indicating that character sizes are sizeof(char), sizeof(short), and
sizeof(int) respectively.
Call pfGetStringBBox to retrieve the bounding box around string as if it
were drawn using the assigned justification, drawing style, font, and
character string. Call pfStringBBox to set this bounding box explicitly.
pfStringSpacingScale and pfGetStringSpacingScale set and get the spacing
scales of string. 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.
pfStringGState and pfGetStringGState set and get the pfGeoState attached
to string. If no pfGeoState is attached, then string will be drawn with
whatever graphics state is active at draw time.
Call pfStringFont and pfGetStringFont to set or get the pfFont used by
string. Call pfStringString and pfGetStringString to set or get the
character string for string. pfGetStringStringLength will return the
length of a pfString's current character string. pfStringColor and
pfGetStringColor get and set string's color.
pfGetStringCharGSet returns a pointer to the GeoSet currently being used
to draw the character at place index in the pfString's string.
pfGetStringCharPos 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
pfGetStringStringLength.
Call pfDrawString 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 pfFlattenString 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. pfFlattenString Must be called every time you
change the contents of the string geometry; e.g. after calling
pfStringString.
Page 4
pfString(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfString(3pf)
pfStringIsectMask enables intersections and sets the intersection mask
for string. 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 (pfStringIsectSegs) indicates that the pfString
should be tested. The default mask is all 1's, i.e. 0xffffffff.
pfGetStringIsectMask returns the intersection mask of the specified
pfString.
pfStringIsectSegs tests for intersection between the pfString string 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
pfStringIsectSegs 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
