pfMaterial(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
NAME
pfNewMtl, pfGetMtlClassType, pfMtlSide, pfGetMtlSide, pfMtlAlpha,
pfGetMtlAlpha, pfMtlShininess, pfGetMtlShininess, pfMtlColor,
pfGetMtlColor, pfMtlColorMode, pfGetMtlColorMode, pfApplyMtl, pfGetCurMtl
- Create, modify and query a material.
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfMaterial * pfNewMtl(void *arena);
pfType * pfGetMtlClassType(void);
void pfMtlSide(pfMaterial *mtl, int side);
int pfGetMtlSide(pfMaterial *mtl);
void pfMtlAlpha(pfMaterial *mtl, float alpha);
float pfGetMtlAlpha(pfMaterial *mtl);
void pfMtlShininess(pfMaterial *mtl, float shininess);
float pfGetMtlShininess(pfMaterial *mtl);
void pfMtlColor(pfMaterial *mtl, int color, float r, float g,
float b);
void pfGetMtlColor(pfMaterial *mtl, int color, float *r,
float *g, float *b);
void pfMtlColorMode(pfMaterial *mtl, int side, int mode);
int pfGetMtlColorMode(pfMaterial *mtl, int side);
void pfApplyMtl(pfMaterial *mtl);
pfMaterial * pfGetCurMtl(int side);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfMaterial is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfMaterial. Casting an object of
class pfMaterial 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);
Page 1
pfMaterial(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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 pfMaterial 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);
PARAMETERS
mtl identifies a pfMaterial.
DESCRIPTION
In conjunction with other lighting parameters, a pfMaterial defines the
appearance of illuminated geometry. A pfMaterial defines the reflectance
characteristics of surfaces such as diffuse color and shininess. See the
OpenGL glMaterial(3g) man page for more details on materials parameters.
pfNewMtl creates and returns a handle to a pfMaterial. arena specifies a
malloc arena out of which the pfMaterial is allocated or NULL for
allocation off the process heap. A NULL pointer is returned to indicate
failure. pfMaterials can be deleted with pfDelete.
pfGetMtlClassType returns the pfType* for the class pfMaterial. The
pfType* returned by pfGetMtlClassType is the same as the pfType* returned
by invoking pfGetType on any instance of class pfMaterial. 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.
Page 2
pfMaterial(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
pfMtlSide receives a symbolic token, one of PFMTL_FRONT, PFMTL_BACK, or
PFMTL_BOTH indicating which side of a polygon the material should affect.
If lighting is to affect the back sides of polygons, two-sided lighting
must be enabled. Two-sided lighting requires a two-sided pfLightModel
(see pfLModelTwoSide) and that face culling be disabled (see pfCullFace)
so that backfacing polygons are not rejected.
pfGetMtlSide returns the side(s) affected by mtl.
pfMtlAlpha specifies the alpha of mtl in the range 0.0 through 1.0. If
transparency is enabled (see pfTransparency), a material whose alpha is <
1.0 and whose color mode is PFMTL_CMODE_OFF will be transparent with
alpha of 1.0 being completely opaque and 0.0 being completely
transparent. The default alpha value is 1.0 or completely opaque. For
non-homogeneous transparency, use a color mode other than PFMTL_CMODE_OFF
and transparency will be taken from geometry colors. In OpenGL,
pfMtlAlpha sets the alpha of the AMBIENT, DIFFUSE, EMISSIVE, and SPECULAR
colors. However, it is the DIFFUSE alpha that determines the resulting
alpha value from the lighting calculation.
pfGetMtlAlpha returns the alpha of mtl.
pfMtlShininess specifies the specular scattering exponent, or the
shininess, of the given material. It receives a floating point value in
the range 0.0 to 128.0. The default shininess value is 0.0, which
effectively disables specular reflection.
pfGetMtlShininess returns the shininess of mtl.
pfMtlColor sets a specific color of mtl. color indicates which color is
to be set by r, g, and b and is one of PFMTL_AMBIENT, PFMTL_DIFFUSE,
PFMTL_EMISSION, or PFMTL_SPECULAR. The default colors are:
Light Component Red Green Blue
____________________________________
PFMTL_AMBIENT 0.2 0.2 0.2
PFMTL_DIFFUSE 0.8 0.8 0.8
PFMTL_EMISSION 0.0 0.0 0.0
PFMTL_SPECULAR 0.0 0.0 0.0
|
pfGetMtlColor copies the color of mtl into r, g, and b. color may be one
of PFMTL_AMBIENT, PFMTL_DIFFUSE, PFMTL_EMISSION, or PFMTL_SPECULAR.
pfMtlColorMode specifies how pfGeoSet and Graphics Library color commands
affect mtl. side is the same symbolic token used for pfMtlSide and
indicates which side mode affects. mode is a symbolic token specifying
which color property of the material is replaced by color commands:
PFMTL_CMODE_AMBIENT_AND_DIFFUSE, RGB color commands will replace the
DIFFUSE and AMBIENT color property of the current material. This is
the default pfMaterial color mode.
Page 3
pfMaterial(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
PFMTL_CMODE_AMBIENT, RGB color commands will replace the AMBIENT
color property of the current material.
PFMTL_CMODE_DIFFUSE, RGB color commands will replace the DIFFUSE
color property of the current material.
PFMTL_CMODE_EMISSION, RGB color commands will replace the EMISSION
color property of the current material.
PFMTL_CMODE_SPECULAR, RGB color commands will replace the SPECULAR
color property of the current material.
PFMTL_CMODE_OFF, RGB color commands will be ignored, i.e.,
overridden by the material colors.
PFMTL_CMODE_COLOR, RGB color commands will replace the current
color. If lighting is enabled, lit material colors are always used.
PFMTL_CMODE_COLOR is not available in OpenGL and will be treated as
PFMTL_CMODE_OFF.
Materials do not have a single alpha; rather, the AMBIENT, DIFFUSE,
SPECULAR, and EMISSIVE colors have individual alphas which are replaced
along with red, green, and blue when the appropriate color mode is
enabled.
When enabled, pfMtlColorMode can offer substantial performance gains by
drastically reducing the number of different pfMaterials required by a
database. Instead of using a different pfMaterial for every unique
material color, pfMtlColorMode can take a color component from the
geometry, rather than from mtl. For example, if mode is
PFMTL_CMODE_DIFFUSE, then the diffuse color component of mtl is ignored.
Instead, the color specified by a pfGeoSet or the color specified through
the Graphics Library (e.g. glColor(3g) in OpenGL) becomes the new
diffuse color. However, pfGetMtlColor will still return the original
diffuse color.
The pfMtlColorMode of mtl must be enabled (other than PFMTL_CMODE_COLOR
or PFMTL_CMODE_OFF) for the colors (PFGS_COLOR4) of any pfGeoSets which
use mtl to have effect. Note that the only way to display per-vertex
colors on lit pfGeoSets is to enable pfMtlColorMode on the pfMaterial
used by the pfGeoSets; specifically, pfGeoSets do not support a different
pfMaterial for each vertex.
The default color mode is PFMTL_CMODE_AMBIENT_AND_DIFFUSE which causes
both diffuse and ambient material colors to be replaced by geometry color
commands. Specifically, this setting allows colors specified by
pfGeoSets to have effect. When lighting is disabled, the color mode is
set to PFMTL_CMODE_OFF.
pfGetMtlColorMode returns the color mode of mtl corresponding to side.
pfApplyMtl makes mtl the current pfMaterial. If lighting is enabled (see
Page 4
pfMaterial(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
below), mtl will be applied to all geometry drawn after pfApplyMtl is
called. Modifications to mtl, such as changing the diffuse color, will
not be applied until pfApplyMtl is called with mtl.
For geometry to be illuminated the following must be true:
1. Lighting must be enabled: pfEnable(PFEN_LIGHTING),
2. A pfLightModel must be applied: pfApplyLModel,
3. A pfMaterial must be applied: pfApplyMtl,
4. One or more pfLights must be on for diffuse and specular
effects: pfLightOn,
5. Illuminated geometry must have normals for diffuse and specular
effects: pfGSetAttr, PFGS_NORMAL3. Note that ambient and
emissive lighting does not require normals.
The front and back material state elements are identified by the
PFSTATE_FRONTMTL and PFSTATE_BACKMTL tokens. Use these tokens with
pfGStateAttr to set the materials of a pfGeoState and with pfOverride to
override subsequent material changes:
Example 1: Define a 50% transparent, shiny red plastic material
/* Make it red */
pfMtlColor(redMtl, PFMTL_DIFFUSE, 1.0f, 0.0f, 0.0f);
/* Disable color mode so the PFMTL_DIFFUSE color is not ignored */
pfMtlColorMode(redMtl, PFMTL_FRONT, PFMTL_CMODE_OFF);
/* Make it shiny */
pfMtlColor(redMtl, PFMTL_SPECULAR, 1.0f, 1.0f, 1.0f);
pfMtlShininess(redMtl, 16.0f);
/* Make it 50% transparent */
pfMtlAlpha(redMtl, 0.5f);
/* Set the front material of a pfGeoState */
pfGStateMode(gstate, PFSTATE_ENLIGHTING, PF_ON);
pfGStateMode(gstate, PFSTATE_TRANSPARENCY, PFTR_ON);
pfGStateAttr(gstate, PFSTATE_FRONTMTL, redMaterial);
/* Attach gstate to gset */
pfGSetGState(gset, gstate);
/* Set normal array. 'gset' is non-indexed */
pfGSetAttr(gset, PFGS_NORMAL3, PFGS_PER_VERTEX, norms, NULL);
/* Draw transparent, shiny red gset */
pfDrawGSet(gset);
Page 5
pfMaterial(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
Example 2:
pfMtlSide(mtl, PFMTL_FRONT);
pfApplyMtl(mtl);
/* Override so that all geometry uses 'mtl' as front material */
pfOverride(PFSTATE_FRONTMTL, PF_ON);
When setting the pfMaterial(s) of a pfGeoState using pfGStateAttr, the
side of the material is ignored. Instead, the PFSTATE token defines
which side the material should be applied to. For example,
pfGStateAttr(gstate, PFSTATE_FRONTMTL, mtl)
will ensure that mtl is always applied to the front side of polygons
after gstate is applied.
pfApplyMtl is a display-listable command. If a pfDispList has been
opened by pfOpenDList, pfApplyMtl will not have immediate effect but will
be captured by the pfDispList and will only have effect when that
pfDispList is later drawn with pfDrawDList.
pfGetCurMtl receives a symbolic token specifying the side of interest,
one of PFMTL_FRONT or PFMTL_BACK, and returns a pointer to the currently
active material for that side, or NULL if there is no active pfMaterial.
SEE ALSO
lmbind, lmcolor, lmdef, pfCullFace, pfDelete, pfDispList, pfEnable,
pfGSetAttr, pfGeoState, pfLight, pfLightModel, pfLightOn,
pfLModelTwoSide, pfObject, pfState, pfTransparency
Page 6
