Material is a re-usable Asset that provides a structure that will tell the GPU how to draw triangles. It combines two key components that will be passed down to the rendering pipeline. First, a Shader that is the program that the GPU will be execution. Second are the sampler slots; in other words, textures or cube maps that will be set and send along so the GPU can use their content within the Shader program.

The Shader program can also feed to the Material uniform Variable that can be preset manually offline or dynamically modified at runtime.

Materials are the main component to use when you want the GPU to draw or execute (compute shader). They can be used to draw a single primitive (triangle list), post-processing effects or simply to run general computing programs on your graphics processor.

Static Variables

Name	Description
`asset`	Reference to the global Navigation associated to your project where the active Material is stored.
Declaration Asset *asset
`handler`	Manage scripting functionalities of the active Material.
Declaration Handler handler
`shader`	GPU programs that dictates how the Material should draw.
Declaration Shader *shader
`slot_count`	Current amount of sampler slots the Material contains.
Declaration unsigned char slot_count
`shader`	Total amount of uniforms Variable that are currently maintained by the Material.
Declaration unsigned char variable_count Note Variables are automatically extracted from the Shader uniforms definitions. Please refer to the Shader help page to learn more about exposing and handling uniforms variables.

Variables

Name Description

redraw Specify that the Material should execute another pass.

Declaration

bool redraw

Note: This variable is usually used within the OnDraw callback of the Material. If set to true it the system will analyze that another Material pass has to be performed; and will reset back the value to false after each pass. As a system limit, a Material is not allowed to draw more than 255 passes.

Functions

Name	Description
`SetShader`	Assign a Shader to the active Material.
Declaration void SetShader( Shader shader ) Parameters* `shader`: A valid Shader reference or `nil` to disconnect the current Shader connected to the Material.
`AddSamplerSlot`	Add a new sampler slot to handle either a Texture or Cubemap.
Declaration int AddSamplerSlot( void ) Return Value The new sampler slot index; or `-1` if the Material run out of slots. Note The maximum number of slots is determined by the capability of the current graphics driver found on your system; if more slots than the max. amount has been declared on a prior driver the system will simply ignore them.
`EnableSamplerSlot`	Enable or disable an existing sampler slot.
Declaration bool EnableSamplerSlot( const unsigned char slot_index, bool enabled ) Parameters `slot_index`: A valid sampler slot index. `enabled`: Enable the slot (`true`) or disable it (`false`). Return Value `true` if the operation is successful; else `false` if the `slot_index` is invalid.
`SetTexture`	Connect an existing Texture to a specific sampler slot.
Declaration bool SetTexture( const unsigned char slot_index, Texture texture ) Parameters* `slot_index`: A valid sampler slot index. `texture`: An existing Texture reference or `nil` to disconnect the current connection. Return Value `true` if the operation is successful; else `false` if the `slot_index` is invalid.
`SetCubemap`	Connect an existing Cubemap to a specific sampler slot.
Declaration bool SetCubemap( const unsigned char slot_index, Cubemap cubemap ) Parameters* `slot_index`: A valid sampler slot index. `cubemap`: An existing Texture reference or `nil` to disconnect the current connection. Return Value `true` if the operation is successful; else `false` if the `slot_index` is invalid.
`GetSampler`	Retrieve the active Sampler of a specific slot.
Declaration Sampler GetSampler( const unsigned char slot_index ) Parameters* `slot_index`: A valid sampler slot index. Return Value `nil` if the slot is not connected to anything; else the function will return the Sampler of the Asset associated with the slot.
`GetSamplerSlotIndex`	Retrieve the slot index used by a specific Sampler.
Declaration int GetSamplerSlotIndex( const Sampler sampler ) Parameters* `sampler`: A valid sampler reference. Return Value `-1` upon failure caused by an invalid Sampler reference received by the function; else return a valid Sampler reference pointer.
`SetSamplerSlotIndex`	Move a specific Sampler to another slot index.
Declaration bool SetSamplerSlotIndex( Sampler sampler, const unsigned char slot_index ) Parameters* `sampler`: Reference to a Sampler handled by the Material. `slot_index`: The new slot index to move the Sampler to. Return Value `true` if both the Sampler is connected to the Material and the slot index is not out of bounds; else return `false`.
`RemoveSamplerSlot`	Remove a specific slot using its index as key.
Declaration bool RemoveSamplerSlot( const int slot_index ) Parameters `slot_index`: The slot index to remove. Return Value `true` on success; else return `false`.
`SwapSamplerSlots`	Swap the location of two sampler slots.
Declaration bool SwapSamplerSlots( const unsigned char slot_index0, const unsigned char slot_index1 ) Parameters `slot_index0`: The first index slot index to swap. `slot_index1`: The destination index of the slot. Return Value `true` if both indexes are valid and the swap have occurred; else return `false`.
`GetVariable`	Retrieve an existing Variable connected to the Material using its name as key.
Declaration Variable GetVariable( const char name ) Parameters `name`: Name of the Variable to retrieve. Return Value On success, a valid Variable reference; else return `nil` if the name received in parameter does not correspond on any Variable maintained by the Material.
`GetVariableAt`	Retrieve a Variable using its index as key.
Declaration Variable GetVariableAt( const unsigned char index ) Parameters* `index`: Index of the Variable to retrieve. Return Value A Variable reference; else return `nil` if the index is out of bounds. <tr class="outline_row"> <td><a class="el" id="Material.GetVariableIndex" href="javascript:onclick=show_hide('GetVariableIndex');">`GetVariableIndex`</a></td> <td>Return the index of an existing \ref Variable.</td> </tr> <tr style="display: none;" class="display_open" id="GetVariableIndex"> <td colspan="2"> <b>Declaration</b> int GetVariableIndex( const Variable variable ) Parameters* `variable`: A valid Variable reference. Return Value `-1` if the variable reference received in parameter is not maintained by the Material; else return the variable index.
`GetVariableBool`	Retrieve the value of an existing boolean Variable.
Declaration bool GetVariableBool( const char name ) Parameters* `name`: The name of the boolean variable to retrieve the value from. Return Value `false` if the Variable does not exist or if its value is actually set to `false`; else return `true`. Note This function is simply a helper function. Always verify that the Variable actually exists using the `GetVariable` function.
`SetVariableBool`	Set the value of an existing boolean Variable.
Declaration bool SetVariableBool( const char name, const bool value ) Parameters* `name`: The name of the Variable to update. `value`: The value to update. Return Value `true` if the variable have been successfully updated; return `false` if the variable does not exists or if its not a boolean.
`GetVariableInt`	Retrieve the value of an existing integer Variable.
Declaration int GetVariableInt( const char name ) Parameters* `name`: The name of the integer variable to retrieve the value from. Return Value `0` if the Variable does not exist or if its value is actually set to `0`; else returns the variable actual value. Note This function is simply a helper function. Always verify that the Variable actually exists using the `GetVariable` function.
`SetVariableInt`	Set the value of an existing integer Variable.
Declaration bool SetVariableInt( const char name, const int value ) Parameters* `name`: The name of the Variable to update. `value`: The value to update. Return Value `true` if the variable have been successfully updated; return `false` if the variable does not exists or if its not an integer.
`GetVariableFloat`	Retrieve the value of an existing float Variable.
Declaration float GetVariableFloat( const char name ) Parameters* `name`: The name of the float variable to retrieve the value from. Return Value `0.0` if the Variable does not exist or if its value is actually set to `0.0`; else returns the variable actual value. Note This function is simply a helper function. Always verify that the Variable actually exists using the `GetVariable` function.
`SetVariableFloat`	Set the value of an existing float Variable.
Declaration bool SetVariableFloat( const char name, const float value ) Parameters* `name`: The name of the Variable to update. `value`: The value to update. Return Value `true` if the variable have been successfully updated; return `false` if the variable does not exists or if its not a floating point.
`GetVariableVec2`	Retrieve the value of an existing vec2 Variable.
Declaration vec2 GetVariableVec2( const char name ) Parameters* `name`: The name of the vec2 variable to retrieve the value from. Return Value A zeroed vector if the Variable does not exist or if its values are actually set to `0.0`; else returns the variable actual value. Note This function is simply a helper function. Always verify that the Variable actually exists using the `GetVariable` function.
`SetVariableVec2`	Set the value of an existing vec2 Variable.
Declaration bool SetVariableVec2( const char name, const vec2 value ) Parameters* `name`: The name of the Variable to update. `value`: The vector value to update to. Return Value `true` if the variable have been successfully updated; return `false` if the variable does not exists or if its not a 2d vector.
`GetVariableVec3`	Retrieve the value of an existing vec3 Variable.
Declaration vec3 GetVariableVec3( const char name ) Parameters* `name`: The name of the vec3 variable to retrieve the value from. Return Value A zeroed vector if the Variable does not exist or if its values are actually set to `0.0`; else returns the variable actual value. Note This function is simply a helper function. Always verify that the Variable actually exists using the `GetVariable` function.
`SetVariableVec3`	Set the value of an existing vec3 Variable.
Declaration bool SetVariableVec3( const char name, const vec3 value ) Parameters* `name`: The name of the Variable to update. `value`: The vector value to update to. Return Value `true` if the variable have been successfully updated; return `false` if the variable does not exists or if its not a 3d vector.
`GetVariableVec4`	Retrieve the value of an existing vec4 Variable.
Declaration vec4 GetVariableVec4( const char name ) Parameters* `name`: The name of the vec4 variable to retrieve the value from. Return Value A zeroed vector if the Variable does not exist or if its values are actually set to `0.0`; else returns the variable actual value. Note This function is simply a helper function. Always verify that the Variable actually exists using the `GetVariable` function.
`SetVariableVec4`	Set the value of an existing vec4 Variable.
Declaration bool SetVariableVec4( const char name, const vec4 value ) Parameters* `name`: The name of the Variable to update. `value`: The vector value to update to. Return Value `true` if the variable have been successfully updated; return `false` if the variable does not exists or if its not a 4d vector.
`SyncVariables`	Re-synchronize the active Material Variable.
Declaration void SyncVariables( void )

Events

Callbacks	Description
`OnDraw`	Triggered before the Material is about to send data to the GPU.
Declaration function OnDraw()
`OnDisplay`	Happen right after the Material have sent data to the GPU.
Declaration function OnDisplay()