HMaterialLibrary
-
class
HMaterialLibrary HMaterialLibraryis the main class for working with the material library.Index
Methods
ApplyMaterial()ApplyStyles()CloneMaterial()Compile()Compile()CountFromType()EnsureEnvironmentInitialized()EnsureMaterialInitialized()Error()FindHSFMaterials()FindReferencedMaterials()FindSubdirectories()FindValidMaterial()GenerateSerializationBufferList()GetContainerSegment()GetCurrentEnvironment()GetEnvironmentList()GetMaterialList()GetReadFlags()GetShaderSource()GetTweakableByIndex()GetTweakableByName()GetTweakableDefaults()GetTweakablesCount()GetTweakablesString()GetWriteFlags()HashToString()HasIndexFile()HMaterialLibrary()Init()Initialize()InitRead()InitWrite()IsValid()IsValidEnvironment()IsValidMaterial()ParseBuffer()RecordHSFMaterial()RegisterMaterials()RegisterMaterials()ReloadMaterial()RenameMaterial()SetEnvironment()SetReadFlags()SetWriteFlags()slurp_dat_file()Tweak()Tweak()~HMaterialLibrary()
Variables
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 materialsReturns
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 materialsReturns
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 afterRegisterMaterials()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 afterRegisterMaterials()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 fromGetMaterialList()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 nameReturns
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 afterRegisterMaterials()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 afterRegisterMaterials()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 setReturns
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 nameReturns
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 nameReturns
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 afterRegisterMaterials()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 constsee documentation on
HMaterialLibrary::Write_Flagsthe path to the materials and environments on disk
-
struct vhash_s *
HMaterialLibrary::m_MaterialHash protected
struct vhash_smaps material names to the compiled material hsf file from which it came
-
struct vhash_s *
HMaterialLibrary::m_EnvironmentHash protected
struct vhash_smaps environment names to the compiled material hsf file from which it came
-
char const *
HMaterialLibrary::m_MaterialList protected
char constthe material list
-
char const *
HMaterialLibrary::m_EnvironmentList protected
char constthe environment list
-
char const *
HMaterialLibrary::m_CurrentEnvironment protected
char constthe name of the environment most recently set with SetEnvironment
-
HC_KEY
HMaterialLibrary::m_MaterialSegmentKey protected
HC_KEYthe segment containing the materials and environments
-
HC_KEY
HMaterialLibrary::m_CurrentEnvironmentKey protected
HC_KEYthe 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
boolself-explanatory
-
struct vlist_s *
HMaterialLibrary::m_SerializationBufferList private
struct vlist_s
-
BStreamFileToolkit *
HMaterialLibrary::m_tk private
BStreamFileToolkit