#include <HMaterialLibrary.h>

Public Types

enum  Read_Flags { Read_Flags_Default = 0x0000, Prefer_Embedded = 0x0001, Prefer_Highest_Resolution = 0x0002 }
 see documentation on HMaterialLibrary::Read_Flags More...
 
enum  Write_Flags { Write_Flags_Default = 0x0000, Embedded = 0x0001 }
 

Public Member Functions

bool ApplyMaterial (const char *name)
 
bool ApplyStyles ()
 
bool CloneMaterial (const char *old_material_name, char *new_material_name)
 
bool Compile (const char *name)
 
int CountFromType (const char *type)
 
bool EnsureEnvironmentInitialized (const char *name)
 
bool EnsureMaterialInitialized (const char *name)
 
bool FindReferencedMaterials (HC_KEY segment_tree, char *list, int list_size)
 
const char * GetContainerSegment () const
 
const char * GetCurrentEnvironment (char *buffer=0, int buffer_length=-1)
 
const char * GetEnvironmentList (char *buffer=0, int buffer_length=-1)
 
const char * GetMaterialList (char *buffer=0, int buffer_length=-1)
 
Read_Flags GetReadFlags ()
 see documentation on HMaterialLibrary::Read_Flags
 
bool GetTweakableByIndex (const char *material_name, int index, char *tweakable_name, char *type)
 
bool GetTweakableByName (const char *material_name, char const *tweakable_name, int *index, char *type)
 
bool GetTweakableDefaults (const char *material_name, int index, float *vals)
 
bool GetTweakablesCount (const char *material_name, int *count)
 
Write_Flags GetWriteFlags ()
 see documentation on HMaterialLibrary::Write_Flags
 
bool InitRead (int version)
 
bool InitWrite (const char *list, int *size)
 
bool IsValid () const
 
bool IsValidEnvironment (const char *name) const
 
bool IsValidMaterial (const char *name) const
 
TK_Status ParseBuffer (char const *buffer, int size)
 
bool RegisterMaterials (const char *directory)
 
bool RegisterMaterials (const wchar_t *directory)
 
bool ReloadMaterial (const char *name)
 
bool RenameMaterial (const char *old_material_name, const char *new_material_name)
 
bool SetEnvironment (const char *name)
 
void SetReadFlags (Read_Flags flags)
 
void SetWriteFlags (Write_Flags flags)
 
bool Tweak (const char *material_name, int index, const float *vals)
 
bool Tweak (const char *material_name, int index, float val0, float val1=0, float val2=0, float val3=0)
 

Protected Member Functions

bool Compile (const char *name, void *bufferlist)
 
virtual void Error (const char *message, int severity=1)
 
const char * FindValidMaterial (const char *name) const
 
bool GetShaderSource (const char *material_name, char *shader_source, char *options=0)
 
bool GetTweakablesString (const char *material_name, char *string)
 
bool Initialize (const char *name, bool environment=false)
 

Protected Attributes

const char * m_CurrentEnvironment
 the name of the environment most recently set with SetEnvironment
 
HC_KEY m_CurrentEnvironmentKey
 the currently active environment
 
struct vhash_s * m_EnvironmentHash
 maps environment names to the compiled material hsf file from which it came
 
const char * m_EnvironmentList
 the environment list
 
const wchar_t * m_MaterialDirectory
 see documentation on HMaterialLibrary::Write_Flags More...
 
struct vhash_s * m_MaterialHash
 maps material names to the compiled material hsf file from which it came
 
const char * m_MaterialList
 the material list
 
HC_KEY m_MaterialSegmentKey
 the segment containing the materials and environments
 
Read_Flags m_ReadFlags
 see documentation on HMaterialLibrary::Read_Flags
 
bool m_Valid
 self-explanatory
 
Write_Flags m_WriteFlags
 see documentation on HMaterialLibrary::Write_Flags
 

Friends

class HTK_Material_Composite
 
class HTK_One_Material
 

Detailed Description

HMaterialLibrary is the main class for working with the material library.

Member Enumeration Documentation

◆ Read_Flags

see documentation on HMaterialLibrary::Read_Flags

options for file import

options for file export

Enumerator
Read_Flags_Default 

use textures in the HMaterialLibrary in preference to any that are embedded in the data

Prefer_Embedded 

keep the embedded material if there is a name conflict between existing and embedded one

Prefer_Highest_Resolution 

keep the one with the highest resolution if there is a name conflict between existing and embedded one

◆ Write_Flags

Enumerator
Write_Flags_Default 

write with no textures at all to keep file sizes compact

Embedded 

embed hsf versions of the materials into the data so that the receiving side

Member Function Documentation

◆ ApplyMaterial()

bool HMaterialLibrary::ApplyMaterial ( const char *  name)

Applies all of the attributes of the given material to the currently open segment. Initializes the material if necessary by pulling the resources (DAT, shader and images) from disk.

Parameters
nameUTF8-encoded name as passed back from GetMaterialList()
Returns
true on success

◆ ApplyStyles()

bool HMaterialLibrary::ApplyStyles ( )

After materials are registered, something in the model's ancestry needs to be styled by the materials segment, so that any and all name definitions are made available. We suggest the scene key, but really we can use anything from which the model inherits attributes provided it is in the same subwindow as the model. This function applies the library styles to the current segment.

Returns
true on success

◆ CloneMaterial()

bool HMaterialLibrary::CloneMaterial ( const char *  old_material_name,
char *  new_material_name 
)

creates a copy of a material with a new name.

Parameters
old_material_namethe material to be copied
new_material_namethe new material name. It will be the old material name plus a suffix guaranteed not to conflict with any materials yet defined, starting with "+1".
Returns
true on success

◆ Compile() [1/2]

bool HMaterialLibrary::Compile ( const char *  name)
Parameters
namethe material name to be compiled.
Returns
true on success. Outputs an hsf to the directory given to RegisterMaterials, which will fail if that directory is either not writeable or invalid. The output file will be of the same name as the material, except with '/' converted to '.' and a ".hsf" appended to the end.

◆ Compile() [2/2]

bool HMaterialLibrary::Compile ( const char *  name,
void *  bufferlist 
)
protected
Parameters
namethe name of the material be compiled.
bufferlista vlist of SerializationNode objects onto which the compile results should be appended
Returns
true on success

◆ CountFromType()

int HMaterialLibrary::CountFromType ( const char *  type)

A utility to determine the number of floating point values required to store the data for a given type.

Parameters
typemust be one of: "float", "float2", "float3", "float4"
Returns
count, or -1 if type is not one of the expected types

◆ EnsureEnvironmentInitialized()

bool HMaterialLibrary::EnsureEnvironmentInitialized ( const char *  name)

Checks whether the environment has already been initialized, and calls through to Initialize if it has not.

Parameters
namethe material name
Returns
true on success

◆ EnsureMaterialInitialized()

bool HMaterialLibrary::EnsureMaterialInitialized ( const char *  name)

Checks whether the material has already been initialized, and calls through to Initialize if it has not.

Parameters
namethe material name
Returns
true on success

◆ Error()

virtual void HMaterialLibrary::Error ( const char *  message,
int  severity = 1 
)
protectedvirtual

Reports an error.

Parameters
messagethe string to be shown to the user
severitywarning = 1, error = 2, fatal error = 3

◆ FindValidMaterial()

const char* HMaterialLibrary::FindValidMaterial ( const char *  name) const
protected
Parameters
namethe name of the material to search for.
Returns
if the given name is in the list, return a pointer to the location in the m_MaterialList where the requested material name starts. This function will always return NULL until after RegisterMaterials() is called.

◆ GetContainerSegment()

const char* HMaterialLibrary::GetContainerSegment ( ) const

returns the name of the root segment under which resources are stored.

Returns
name of the container segment

◆ GetEnvironmentList()

const char* HMaterialLibrary::GetEnvironmentList ( char *  buffer = 0,
int  buffer_length = -1 
)
Returns
a semicolon-separated list of legal values to be passed into SetEnvironment. Returns NULL until after RegisterMaterials() is called

◆ GetMaterialList()

const char* HMaterialLibrary::GetMaterialList ( char *  buffer = 0,
int  buffer_length = -1 
)
Parameters
bufferThe buffer to write the results into. If non-NULL, it will also be returned back to the user.
buffer_lengthThe maximum number of characters to write into buffer. If less than or equal to zero, the caller is assumed to have allocated sufficient space to hold all contents.
Returns
a semicolon-separated list of legal values to be passed into SetEnvironment. To allow for wide character material names, the names are encoded as UTF8, which is mostly the same as ASCII with minor exceptions. Convert to unicode before using these values to populate a GUI for proper support of wide characters (e.g. Asian languages) being used in material names. This function will return NULL until after RegisterMaterials() is called. If buffer is NULL (the default), the return value is a pointer to the internal array used to store the material list. That array will be invalidated (and reallocated) upon the next call to CloneMaterial or RenameMaterial, so the caller should take care not to hang on to a stale pointer.

◆ GetShaderSource()

bool HMaterialLibrary::GetShaderSource ( const char *  material_name,
char *  shader_source,
char *  options = 0 
)
protected

Pulls the shader source for a given material out of the material segment

Parameters
material_namethe material name
shader_sourcehlsl/glsl shader source code. returned to user.
optionsdefaults to NULL, but if specified, a buffer in which to put the options associated with a material's shader definition.

◆ GetTweakableByIndex()

bool HMaterialLibrary::GetTweakableByIndex ( const char *  material_name,
int  index,
char *  tweakable_name,
char *  type 
)

Tweakables can be identified by a combination of material name and index.

Parameters
material_namethe material name
indexthe tweakable index (0-based offset from the start of the comma-delimited tweakables string in the material's DAT file).
tweakable_namethe name of the tweakable, returned to user (e.g. for GUI labels)
typethe tweakable type. Possible values are float, float2, float3 and float4
Returns
true on success, false if material_name matches no material yet defined or if the index is out of range.

◆ GetTweakableByName()

bool HMaterialLibrary::GetTweakableByName ( const char *  material_name,
char const *  tweakable_name,
int *  index,
char *  type 
)

Tweakables can be identified by a combination of material name and tweakable name.

Parameters
material_namethe material name
tweakable_namethe name of the tweakable
indexthe tweakable index, returned to user.
typethe tweakable type. Possible values are float, float2, float3 and float4
Returns
true on success, false if material_name matches no material yet defined or if the index is out of range.

◆ GetTweakableDefaults()

bool HMaterialLibrary::GetTweakableDefaults ( const char *  material_name,
int  index,
float *  vals 
)

pulls the initializer for a tweakable (specified by material_name and index) and returns the values to the user.

Parameters
material_namethe material name
thetweakable index (0-based offset from the start of the comma-delimited tweakables string in the material's DAT file).
valsa pointer to up to 4 float values (depending on the type as returned by GetTweakable()) to be returned to the user currently specified in the hlsl code.
Returns
true on success, false if material_name matches no material yet defined or if the index is out of range.

◆ GetTweakablesCount()

bool HMaterialLibrary::GetTweakablesCount ( const char *  material_name,
int *  count 
)

Allows the user to show the number of tweakables.

Parameters
material_namethe material name
thenumber of materials.
Returns
true on success (even if the count is 0)

◆ GetTweakablesString()

bool HMaterialLibrary::GetTweakablesString ( const char *  material_name,
char *  string 
)
protected

Pulls the comma-separated list of tweakables for a given material out of the material segment's user data.

Parameters
material_namethe material name
stringthe list of tweakables, returned to the caller

◆ Initialize()

bool HMaterialLibrary::Initialize ( const char *  name,
bool  environment = false 
)
protected

Loads resources from disk to populate material attributes

Parameters
namethe material name
environmentindicates whether the data will be used as an environment (which should contain texture definitions but no color settings).
Returns
true on success

◆ IsValid()

bool HMaterialLibrary::IsValid ( ) const
inline
Returns
true if at least one material has been registered

◆ IsValidEnvironment()

bool HMaterialLibrary::IsValidEnvironment ( const char *  name) const
Parameters
namethe name of the environment to search for.
Returns
true if the given name is in the list. This function will always return false until after RegisterMaterials() is called.

◆ IsValidMaterial()

bool HMaterialLibrary::IsValidMaterial ( const char *  name) const
Parameters
namethe name of the material to search for.
Returns
true if the given name is in the list. This function will always return false until after RegisterMaterials() is called.

◆ RegisterMaterials() [1/2]

bool HMaterialLibrary::RegisterMaterials ( const char *  directory)

Scans the given directory path and records the names of materials it discovers. Also creates a style link from the materials segment to the segment that is currently open. This function should be called from somewhere above the model in the model's path, but materials_segment does not necessarily need to be in the models path.

Parameters
directorythe location on disk of the materials
Returns
true on success, false if no materials were found at the given location

◆ RegisterMaterials() [2/2]

bool HMaterialLibrary::RegisterMaterials ( const wchar_t *  directory)

Scans the given directory path and records the names of materials it discovers.

Parameters
directorythe location on disk of the materials
Returns
true on success, false if no materials were found at the given location

◆ ReloadMaterial()

bool HMaterialLibrary::ReloadMaterial ( const char *  name)

Refresh the material from disk.
Note that any new materials that were cloned will not be affected.

Parameters
namethe material name
Returns
true on success. This function will return false if called on a material that is created via CloneMaterial, since there is no corresponding data on disk.

◆ RenameMaterial()

bool HMaterialLibrary::RenameMaterial ( const char *  old_material_name,
const char *  new_material_name 
)

creates a copy of a material with a new name.

Parameters
old_material_namethe material to be copied
new_material_namethe new material name.
Returns
true on success. Fails if old_material_name is not a valid material or new_material_name is already in use.

◆ SetEnvironment()

bool HMaterialLibrary::SetEnvironment ( const char *  name)

An environment typically contains a cube map, and specifies the colors that are picked up by reflective materials and optionally the color of the window background

Parameters
namethe environment to set
Returns
true on success

◆ Tweak() [1/2]

bool HMaterialLibrary::Tweak ( const char *  material_name,
int  index,
const float *  vals 
)

pulls the initializer for a tweakable (specified by material_name and index) and replaces the values with values specified by the user.

Parameters
material_namethe material name
thetweakable index (0-based offset from the start of the comma-delimited tweakables string in the material's DAT file).
valsa pointer to up to 4 float values (depending on the type as returned by GetTweakable()) to be injected into the hlsl code.
Returns
true on success, false if material_name matches no material yet defined or if the index is out of range.

◆ Tweak() [2/2]

bool HMaterialLibrary::Tweak ( const char *  material_name,
int  index,
float  val0,
float  val1 = 0,
float  val2 = 0,
float  val3 = 0 
)

a convenience wrapper around Tweak (const char *, int, const float *)

Parameters
material_namethe material name
thetweakable index (0-based offset from the start of the comma-delimited tweakables string in the material's DAT file).
val0the first value injected into the hlsl code.
val1the second value injected into the hlsl code (if applicable, depending on the tweakable's type).
val2the third value injected into the hlsl code (if applicable, depending on the tweakable's type).
val3the fourth value injected into the hlsl code (if applicable, depending on the tweakable's type).
Returns
true on success, false if material_name matches no material yet defined or if the index is out of range.

Member Data Documentation

◆ m_MaterialDirectory

const wchar_t* HMaterialLibrary::m_MaterialDirectory
protected

see documentation on HMaterialLibrary::Write_Flags

the path to the materials and environments on disk


The documentation for this class was generated from the following file: