HMaterialLibrary

class HMaterialLibrary

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

Enumerations

Methods

HMaterialLibrary::HMaterialLibrary()
virtual HMaterialLibrary::~HMaterialLibrary()

virtual

bool HMaterialLibrary::RegisterMaterials(char const *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

directory: the location on disk of the materials

Returns

true on success, false if no materials were found at the given location
bool HMaterialLibrary::RegisterMaterials(wchar_t const *directory)

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

Parameters

directory: the location on disk of the materials

Returns

true on success, false if no materials were found at the given location
bool HMaterialLibrary::IsValid() const

const

Returns

true if at least one material has been registered
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
char const *HMaterialLibrary::GetContainerSegment() const

const

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

Returns

name of the container segment
char const *HMaterialLibrary::GetMaterialList(char *buffer = 0, int buffer_length = -1)

Parameters

buffer: The buffer to write the results into. If non-NULL, it will also be returned back to the user.

buffer_length: The 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.
bool HMaterialLibrary::IsValidMaterial(char const *name) const

const

Parameters

name: the 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.
bool HMaterialLibrary::ApplyMaterial(char const *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

name: UTF8-encoded name as passed back from GetMaterialList()

Returns

true on success
bool HMaterialLibrary::ReloadMaterial(char const *name)

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

Parameters

name: the 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.
bool HMaterialLibrary::CloneMaterial(char const *old_material_name, char *new_material_name)

creates a copy of a material with a new name.

Parameters

old_material_name: the material to be copied

new_material_name: the 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
bool HMaterialLibrary::RenameMaterial(char const *old_material_name, char const *new_material_name)

creates a copy of a material with a new name.

Parameters

old_material_name: the material to be copied

new_material_name: the 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.
bool HMaterialLibrary::GetTweakablesCount(char const *material_name, int *count)

Allows the user to show the number of tweakables.

Parameters

material_name: the material name

the: number of materials.

Returns

true on success (even if the count is 0)
bool HMaterialLibrary::GetTweakableByIndex(char const *material_name, int index, char *tweakable_name, char *type)

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

Parameters

material_name: the material name

index: the tweakable index (0-based offset from the start of the comma-delimited tweakables string in the material’s DAT file).

tweakable_name: the name of the tweakable, returned to user (e.g. for GUI labels)

type: the 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.
bool HMaterialLibrary::GetTweakableByName(char const *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_name: the material name

tweakable_name: the name of the tweakable

index: the tweakable index, returned to user.

type: the 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.
int HMaterialLibrary::CountFromType(char const *type)

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

Parameters

type: must be one of: “float”, “float2”, “float3”, “float4”

Returns

count, or -1 if type is not one of the expected types
bool HMaterialLibrary::GetTweakableDefaults(char const *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_name: the material name

the: tweakable index (0-based offset from the start of the comma-delimited tweakables string in the material’s DAT file).

vals: a 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.
bool HMaterialLibrary::Tweak(char const *material_name, int index, float const *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_name: the material name

the: tweakable index (0-based offset from the start of the comma-delimited tweakables string in the material’s DAT file).

vals: a 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.
bool HMaterialLibrary::Tweak(char const *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_name: the material name

the: tweakable index (0-based offset from the start of the comma-delimited tweakables string in the material’s DAT file).

val0: the first value injected into the hlsl code.

val1: the second value injected into the hlsl code (if applicable, depending on the tweakable’s type).

val2: the third value injected into the hlsl code (if applicable, depending on the tweakable’s type).

val3: the 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.
char const *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
bool HMaterialLibrary::IsValidEnvironment(char const *name) const

const

Parameters

name: the 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.
bool HMaterialLibrary::SetEnvironment(char const *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

name: the environment to set

Returns

true on success
bool HMaterialLibrary::EnsureMaterialInitialized(char const *name)

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

Parameters

name: the material name

Returns

true on success
bool HMaterialLibrary::EnsureEnvironmentInitialized(char const *name)

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

Parameters

name: the material name

Returns

true on success
bool HMaterialLibrary::FindReferencedMaterials(HC_KEY segment_tree, char *list, int list_size)
bool HMaterialLibrary::InitWrite(char const *list, int *size)
bool HMaterialLibrary::InitRead(int version)
TK_Status HMaterialLibrary::ParseBuffer(char const *buffer, int size)
char const *HMaterialLibrary::GetCurrentEnvironment(char *buffer = 0, int buffer_length = -1)
bool HMaterialLibrary::Compile(char const *name)

Parameters

name: the 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.
void HMaterialLibrary::SetReadFlags(Read_Flags flags)
Read_Flags HMaterialLibrary::GetReadFlags()

see documentation on HMaterialLibrary::Read_Flags

void HMaterialLibrary::SetWriteFlags(Write_Flags flags)
Write_Flags HMaterialLibrary::GetWriteFlags()

see documentation on HMaterialLibrary::Write_Flags

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

protected

Loads resources from disk to populate material attributes

Parameters

name: the material name

environment: indicates whether the data will be used as an environment (which should contain texture definitions but no color settings).

Returns

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

protected virtual

Reports an error.

Parameters

message: the string to be shown to the user

severity: warning = 1, error = 2, fatal error = 3

bool HMaterialLibrary::GetTweakablesString(char const *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_name: the material name

string: the list of tweakables, returned to the caller

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

protected

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

Parameters

material_name: the material name

shader_source: hlsl/glsl shader source code. returned to user.

options: defaults to NULL, but if specified, a buffer in which to put the options associated with a material’s shader definition.

char const *HMaterialLibrary::FindValidMaterial(char const *name) const

protected const

Parameters

name: the 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.
bool HMaterialLibrary::Compile(char const *name, void *bufferlist)

protected

Parameters

name: the name of the material be compiled.

bufferlist: a vlist of SerializationNode objects onto which the compile results should be appended

Returns

true on success
void HMaterialLibrary::Init()

private

void HMaterialLibrary::RecordHSFMaterial(wchar_t const *path, wchar_t const *filename)

private

void HMaterialLibrary::FindHSFMaterials(wchar_t const *path)

private

bool HMaterialLibrary::HasIndexFile(wchar_t const *path, wchar_t const *subpath, wchar_t const *subdir, wchar_t const *index_file)

private

void HMaterialLibrary::FindSubdirectories(wchar_t const *path, wchar_t const *subpath)

private

bool HMaterialLibrary::GenerateSerializationBufferList(char const *materials)

private

char const *HMaterialLibrary::HashToString(struct vhash_s *hash, char *buffer = 0, int buffer_size = -1) const

private const

ErrorCode HMaterialLibrary::slurp_dat_file(wchar_t const *index_file, wchar_t const *subdir, wchar_t const *path, void *datlist)

private

Variables

wchar_t const *HMaterialLibrary::m_MaterialDirectory

protected

wchar_t const

see documentation on HMaterialLibrary::Write_Flags

the path to the materials and environments on disk

struct vhash_s *HMaterialLibrary::m_MaterialHash

protected

struct vhash_s

maps material names to the compiled material hsf file from which it came

struct vhash_s *HMaterialLibrary::m_EnvironmentHash

protected

struct vhash_s

maps environment names to the compiled material hsf file from which it came

char const *HMaterialLibrary::m_MaterialList

protected

char const

the material list

char const *HMaterialLibrary::m_EnvironmentList

protected

char const

the environment list

char const *HMaterialLibrary::m_CurrentEnvironment

protected

char const

the name of the environment most recently set with SetEnvironment

HC_KEY HMaterialLibrary::m_MaterialSegmentKey

protected

HC_KEY

the segment containing the materials and environments

HC_KEY HMaterialLibrary::m_CurrentEnvironmentKey

protected

HC_KEY

the currently active environment

Read_Flags HMaterialLibrary::m_ReadFlags

protected

see documentation on HMaterialLibrary::Read_Flags

Write_Flags HMaterialLibrary::m_WriteFlags

protected

see documentation on HMaterialLibrary::Write_Flags

bool HMaterialLibrary::m_Valid

protected

bool

self-explanatory

struct vlist_s *HMaterialLibrary::m_SerializationBufferList

private

struct vlist_s
BStreamFileToolkit *HMaterialLibrary::m_tk

private

BStreamFileToolkit