pfMaterial(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
NAME
pfMaterial, pfGetCurMtl - Create, modify and query a material.
FUNCTION SPECIFICATION
#include <Performer/pr/pfMaterial.h>
pfMaterial::pfMaterial();
static pfType * pfMaterial::getClassType(void);
void pfMaterial::setSide(int side);
int pfMaterial::getSide(void);
void pfMaterial::setAlpha(float alpha);
float pfMaterial::getAlpha(void);
void pfMaterial::setShininess(float shininess);
float pfMaterial::getShininess(void);
void pfMaterial::setColor(int color, float r, float g,
float b);
void pfMaterial::getColor(int color, float *r, float *g,
float *b);
void pfMaterial::setColorMode(int side, int mode);
int pfMaterial::getColorMode(int side);
void pfMaterial::apply(void);
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. 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();
Page 1
pfMaterial(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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.
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
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.
new(arena) allocates a pfMaterial from the specified memory arena, or
from the process heap if arena is NULL. new allocates a pfMaterial from
the default memory arena (see pfGetSharedArena). Like other pfObjects,
pfMaterials cannot be created statically, automatically on the stack or
in arrays. pfMaterials should be deleted with pfDelete rather than the
delete operator.
pfMaterial::getClassType returns the pfType* for the class pfMaterial.
The pfType* returned by pfMaterial::getClassType is the same as the
pfType* returned by invoking the virtual function getType 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 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.
pfMaterial::setSide 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 pfLightModel::setTwoSide) and that face culling
Page 2
pfMaterial(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
be disabled (see pfCullFace) so that backfacing polygons are not
rejected.
pfMaterial::getSide returns the side(s) affected by the pfMaterial.
pfMaterial::setAlpha specifies the alpha of the pfMaterial 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, pfMaterial::setAlpha 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.
pfMaterial::getAlpha returns the alpha of the pfMaterial.
pfMaterial::setShininess 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.
pfMaterial::getShininess returns the shininess of the pfMaterial.
pfMaterial::setColor sets a specific color of the pfMaterial. 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
|
pfMaterial::getColor copies the color of the pfMaterial into r, g, and b.
color may be one of PFMTL_AMBIENT, PFMTL_DIFFUSE, PFMTL_EMISSION, or
PFMTL_SPECULAR.
pfMaterial::setColorMode specifies how pfGeoSet and Graphics Library
color commands affect the pfMaterial. side is the same symbolic token
used for pfMaterial::setSide 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.
PFMTL_CMODE_AMBIENT, RGB color commands will replace the AMBIENT
Page 3
pfMaterial(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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, pfMaterial::setColorMode 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, pfMaterial::setColorMode can take a color
component from the geometry, rather than from the pfMaterial. For
example, if mode is PFMTL_CMODE_DIFFUSE, then the diffuse color component
of the pfMaterial 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, pfMaterial::getColor
will still return the original diffuse color.
The the pfMaterial of mtl must be enabled (other than PFMTL_CMODE_COLOR
or PFMTL_CMODE_OFF) for the colors (PFGS_COLOR4) of any pfGeoSets which
use the pfMaterial to have effect. Note that the only way to display
per-vertex colors on lit pfGeoSets is to enable pfMaterial::setColorMode
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.
pfMaterial::getColorMode returns the color mode of the pfMaterial
corresponding to side.
pfMaterial::apply makes the pfMaterial the current pfMaterial. If
Page 4
pfMaterial(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
lighting is enabled (see below), the pfMaterial will be applied to all
geometry drawn after pfMaterial::apply is called. Modifications to the
pfMaterial, such as changing the diffuse color, will not be applied until
pfMaterial::apply is called with the pfMaterial.
For geometry to be illuminated the following must be true:
1. Lighting must be enabled: pfEnable(PFEN_LIGHTING),
2. A pfLightModel must be applied: pfLightModel::apply,
3. A pfMaterial must be applied: pfMaterial::apply,
4. One or more pfLights must be on for diffuse and specular
effects: pfLight::on,
5. Illuminated geometry must have normals for diffuse and specular
effects: pfGeoSet::setAttr, 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
pfGeoState::setAttr 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 */
redMtl->setColor(PFMTL_DIFFUSE, 1.0f, 0.0f, 0.0f);
/* Disable color mode so the PFMTL_DIFFUSE color is not ignored */
redMtl->setColorMode(PFMTL_FRONT, PFMTL_CMODE_OFF);
/* Make it shiny */
redMtl->setColor(PFMTL_SPECULAR, 1.0f, 1.0f, 1.0f);
redMtl->setShininess(16.0f);
/* Make it 50% transparent */
redMtl->setAlpha(0.5f);
/* Set the front material of a pfGeoState */
gstate->setMode(PFSTATE_ENLIGHTING, PF_ON);
gstate->setMode(PFSTATE_TRANSPARENCY, PFTR_ON);
gstate->setAttr(PFSTATE_FRONTMTL, redMaterial);
/* Attach gstate to gset */
gset->setGState(gstate);
/* Set normal array. 'gset' is non-indexed */
gset->setAttr(PFGS_NORMAL3, PFGS_PER_VERTEX, norms, NULL);
/* Draw transparent, shiny red gset */
Page 5
pfMaterial(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
gset->draw();
Example 2:
mtl->setSide(PFMTL_FRONT);
mtl->apply();
/* Override so that all geometry uses 'mtl' as front material */
pfOverride(PFSTATE_FRONTMTL, PF_ON);
When setting the pfMaterial(s) of a pfGeoState using pfGeoState::setAttr,
the side of the material is ignored. Instead, the PFSTATE token defines
which side the material should be applied to. For example,
gstate->setAttr(PFSTATE_FRONTMTL, mtl)
will ensure that mtl is always applied to the front side of polygons
after gstate is applied.
pfMaterial::apply is a display-listable command. If a pfDispList has
been opened by pfDispList::open, pfMaterial::apply will not have
immediate effect but will be captured by the pfDispList and will only
have effect when that pfDispList is later drawn with pfDispList::draw.
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
