IFXMaterialResource

IFXMaterialResource is the interface used to get and set material properties for a shared resource. Material Resources can be shared among many objects. Material Resources are managed by the scenegraph, and contained in the Material Resource Palette. IFXMaterialResource inherits the IFXMarker and IFXUnknown interfaces. It is supported by the CIFXMaterialResource component.

When to Use

IFXMaterialResource will be used whenever the parameters of a material resource need to be set or queried.

Interface Methods

Description

GetAttributes

Retrieves the attributes of the material resource. The attributes are a 32-bit field of flags, where each indicate whether or not the material resource has that attribute

SetAttributes

Assigns the specified bitfield as the attributes for the material resource

GetAmbient

Retrieves the ambient color property of the material, in the form of a 3 component vector

SetAmbient

Assigns an ambient color property to the material

GetDiffuse

Retrieves the diffuse color property of the material, in the form of a 3-component vector

SetDiffuse

Assigns a diffuse color property to the material

GetSpecular

Retrieves the specular color property of the material, in the form of a 3-component vector

SetSpecular

Assigns a specular color property to the material

GetEmission

Retrieves the emissive color property of the material, in the form of a 3 component vector

SetEmission

Assigns an emissive color property to the material

GetOpacity

Retrieves the opacity property of the material, in the form of a single floating point value

SetOpacity

Assigns an opacity property to the material

GetReflectivity

Retrieves the reflective property of the material, in the form of a single floating point value

SetReflectivity

Assigns a reflective property to the material

GetTransparent

Retrieves the appropriate transparent property of the material

SetTransparent

Assigns the appropriate transparent property to the material

GetElasticity

Retrieves the elasticity property of the material, in the form of a single floating point value

SetElasticity

Assigns an elasticity property to the material


IFXMaterialResource::GetAttributes()

This method retrieves the attributes of the material resource. The attributes are a 32-bit field of flags, where each flag indicates whether or not the material resource has that attribute. There are eight distinct flags, defined in the following order:

AMBIENT = 1,

DIFFUSE = 1<<1,

SPECULAR = 1<<2,

EMISSIVE = 1<<3,

REFLECTIVITY = 1<<4,

OPACITY = 1<<5,

DENSITY = 1<<6,

ELASTICITY = 1<<7,

There is an additional defined value, ALL = 0xFFFF, which is used to indicate that all defined attributes are used by the material resource.

Parameters:

None

Return Values:

U32 - The bitfield containing the flags for each attributes. If a bit in the value is set (1), then the corresponding attribute is used by the material resource.

Comments:

For example, if 0x0023 is returned, then the material resource uses AMBIENT and DIFFUSE colors, but no SPECULAR. It has an opacity value, but none of the other properties are relevant.


IFXMaterialResource::SetAttributes(U32 uInAttributes)

This method assigns an attributes field to the material resource. The attributes are a 32-bit field of flags, where each flag indicates whether or not the material resource has that attribute. There are only eight distinct flags, defined in the following order:

AMBIENT = 1,

DIFFUSE = 1<<1,

SPECULAR = 1<<2,

EMISSIVE = 1<<3,

REFLECTIVITY = 1<<4,

OPACITY = 1<<5,

DENSITY = 1<<6,

ELASTICITY = 1<<7,

There is an additional defined value, ALL = 0xFFFF, which is used to indicate that all defined attributes are used by the material resource.

Parameters:

uInAttributes

The bitfield that represents the attributes being assigned to the material resource

Return Values:

None

Comments:

If you want to assign AMBIENT, DIFFUSE, and OPACITY attributes to a resource, create the attributes value in this manner:

U32 value = AMBIENT | DIFFUSE | OPACITY ;

Where '|' is the bitwise OR operator.


IFXMaterialResource::GetAmbient(IFXSGVector* pvOutAmbient)

This method retrieves the ambient color property of the material resource. The attribute is contained in an IFXSGVector, which is a 4-component vector, although only the R,G,B components are used for the ambient attribute.

Parameters:

pvOutAmbient

Pointer to an IFXSGVector which will receive the ambient color property of the material resource

Return Values

Comments:

Ambient material properties are used with ambient light properties. The ambient color is not used if there is not an ambient light.


IFXMaterialResource::SetAmbient(IFXSGVector vInAmbient)

This method assigns an ambient color property to the material resource. The attribute is contained in an IFXSGVector, which is a 4-component vector, although only the R,G,B components (values range from 0.0f to 1.0f) are used for the ambient attribute.

Parameters:

vInAmbient

The IFXSGVector that contains the ambient material property being assigned to the resource

Return Values

Comments:

The ambient color is not used if there is not an ambient light.


IFXMaterialResource::GetDiffuse(IFXSGVector* pvOutDiffuse)

This method retrieves the diffuse color property of the material resource. The attribute is contained in an IFXSGVector, which is a 4-component vector, although only the R,G,B components are used for the attribute.

Parameters:

pvOutDiffuse

Pointer to an IFXSGVector which will receive the diffuse color property of the material resource

Return Values

Comments:

Diffuse material properties are used with diffuse light properties.


IFXMaterialResource::SetDiffuse(IFXSGVector vInDiffuse)

This method assigns a diffuse color property to the material resource. The attribute is contained in an IFXSGVector, which is a 4-component vector, although only the R,G,B components (values range from 0.0f to 1.0f) are used for the attribute.

Parameters:

vInDiffuse

The IFXSGVector that contains the diffuse material property being assigned to the resource

Return Values


IFXMaterialResource::GetSpecular(IFXSGVector* pvOutSpecular)

This method retrieves the specular color property of the material resource. The attribute is contained in an IFXSGVector, which is a 4-component vector, although only the R,G,B components are used for the attribute.

Parameters:

pvOutSpecular

Pointer to an IFXSGVector which will receive the specular color property of the material resource

Return Values

Comments:

Specular material properties are used with specular light properties.


IFXMaterialResource::SetSpecular(FXSGVector vInSpecular)

This method assigns a specular color property to the material resource. The attribute is contained in an IFXSGVector, which is a 4-component vector, although only the R,G,B components (values range from 0.0f to 1.0f) are used for the attribute.

Parameters:

vInSpecular

The IFXSGVector that contains the specular material property being assigned to the resource

Return Values


IFXMaterialResource::GetEmission(IFXSGVector* pvOutEmission)

This method retrieves the emissive color property of the material resource. The attribute is contained in an IFXSGVector, which is a 4-component vector, although only the R,G,B components are used for the attribute.

Parameters:

pvOutEmission

Pointer to an IFXSGVector which will receive the emissive color property of the material resource

Return Values

Comments:

Emissive material properties are used with Emissive light properties.


IFXMaterialResource::SetEmission(IFXSGVector vInEmission)

This method assigns an emissive color property to the material resource. The attribute is contained in an IFXSGVector, which is a 4 component vector, although only the R,G,B components (values range from 0.0f to 1.0f) are used for the attribute.

Parameters:

vInEmission

The IFXSGVector that contains the emissive material property being assigned to the resource

Return Values


IFXMaterialResource::GetOpacity(F32* pfOutOpacity)

This method retrieves the opacity value of the material. This is a single floating-point value. It has a range of 0.0f - 1.0f, where 0.0 represents no opacity (is fully transparent) and 1.0 represents full opacity (no transparency).

Parameters:

pfOutOpacity

Pointer to a floating point value that will be assigned the opacity of the material resource

Return Values


IFXMaterialResource::SetOpacity(F32 fInOpacity)

This method assigns an opacity value to the material. This is a single floating-point value. It has a range of 0.0f - 1.0f, where 0.0 represents no opacity (is fully transparent) and 1.0 represents full opacity (no transparency).

Parameters:

fInOpacity

The floating point value that is the opacity being assigned to the material resource

Return Values


IFXMaterialResource::GetReflectivity(F32* pfOutReflectivity)

This method retrieves the reflectivity value of the material. This is a single floating-point value. It has a range of 0.0f - 1.0f, where 0.0 represents extremely low reflectivity and 1.0 represents high reflectivity. Reflectivity is best thought of as the material's 'shininess' that interacts with specular light properties. A low reflectivity value will produce a very concentrated specular region on the object. A high reflectivity value will produce a more muted, but larger specular region on the object.

Parameters:

pfOutReflectivity

Pointer to a floating point value that will be assigned the reflectivity of the material resource

Return Values


IFXMaterialResource::SetReflectivity(F32 fInReflectivity)

This method assigns a reflectivity value to the material. This is a single floating-point value. It has a range of 0.0f - 1.0f, where 0.0 represents extremely low reflectivity and 1.0 represents high reflectivity. Reflectivity is best thought of as the material's 'shininess', which interacts with specular light properties. A low reflectivity value will produce a very concentrated specular region on the object. A high reflectivity value will produce a more muted, but larger specular region on the object.

Parameters:

fInReflectivity

The floating point value being assigned as the reflectivity of the material resource

Return Values


IFXMaterialResource::GetTransparent(BOOL * pbOutTransparent)

This method retrieves the transparent value (yes or no) of the material.

Parameters:

pbOutTransparent

A pointer to the transparent value that will be assigned to the material resource

Return Values


IFXMaterialResource::SetTransparent(BOOL bInTransparent)

This method assigns the transparent value (yes or no) of the material.

Parameters:

bInTransparent

The transparent value assigned to the material resource

Return Values


IFXMaterialResource::GetElasticity(F32* pfOutElasticity)

This method retrieves the elasticity value of the material. This is a single floating-point value. It has a range of 0.0f - 1.0f, where 0.0 represents extremely low elasticity and 1.0 represents high elasticity. Elasticity is a physics property that will apply to any object which uses this material. A low elasticity value will cause the object to dissipate energy during collisions with other objects. A high elasticity value will cause the object to preserve energy during collisions with other objects. A good analogy would be to compare a clay ball (low elasticity) to a billiard ball (high elasticity).

Parameters:

pfOutElasticity

Pointer to a floating point value that will be assigned the elasticity of the material resource

Return Values


IFXMaterialResource::SetElasticity(F32 fInElasticity)

This method assigns an elasticity value to the material. This is a single floating-point value. It has a range of 0.0f - 1.0f, where 0.0 represents extremely low elasticity and 1.0 represents high elasticity. Elasticity is a physics property that will apply to any object which uses this material. A low elasticity value will cause the object to dissipate energy during collisions with other objects. A high elasticity value will cause the object to preserve energy during collisions with other objects. A good analogy would be to compare a clay ball (low elasticity) to a billiard ball (high elasticity).

Parameters:

fInElasticity

The floating point value being assigned as the elasticity of the material resource

Return Values

 

§See asterisked (*) statement at Legal Information © 2001 Intel Corporation.