HMaterialLibrary
Types
Fields
Functions
bool |
|
bool |
|
bool |
|
bool |
|
char const * |
|
char const * |
|
bool |
|
bool |
|
bool |
|
bool |
|
bool |
|
bool |
|
bool |
|
bool |
|
int |
|
bool |
|
bool |
|
bool |
|
char const * |
|
bool |
|
bool |
|
bool |
|
bool |
|
bool |
|
bool |
|
bool |
|
TK_Status |
|
char const * |
|
bool |
|
void |
|
void |
|
Detailed Description
-
class HMaterialLibrary
HMaterialLibrary is the main class for working with the material library.
Public Types
-
enum Read_Flags
see documentation on HMaterialLibrary::Read_Flags
options for file import
options for file export
Values:
-
enumerator Read_Flags_Default
use textures in the HMaterialLibrary in preference to any that are embedded in the data
-
enumerator Prefer_Embedded
keep the embedded material if there is a name conflict between existing and embedded one
-
enumerator Prefer_Highest_Resolution
keep the one with the highest resolution if there is a name conflict between existing and embedded one
-
enumerator Read_Flags_Default
Public Functions
-
HMaterialLibrary()
-
virtual ~HMaterialLibrary()
-
bool 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 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
-
inline bool IsValid() const
- Returns:
true if at least one material has been registered
-
bool 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 *GetContainerSegment() const
returns the name of the root segment under which resources are stored.
- Returns:
name of the container segment
-
char const *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 IsValidMaterial(char const *name) 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 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 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 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 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 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 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 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 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 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 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 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 *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 IsValidEnvironment(char const *name) 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 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 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 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 FindReferencedMaterials(HC_KEY segment_tree, char *list, int list_size)
-
bool InitWrite(char const *list, int *size)
-
bool InitRead(int version)
-
char const *GetCurrentEnvironment(char *buffer = 0, int buffer_length = -1)
-
bool 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.
-
inline void SetReadFlags(Read_Flags flags)
-
inline Read_Flags GetReadFlags()
see documentation on HMaterialLibrary::Read_Flags
-
inline void SetWriteFlags(Write_Flags flags)
-
inline Write_Flags GetWriteFlags()
see documentation on HMaterialLibrary::Write_Flags
-
enum Read_Flags