DEFOLD
Home Features Showcase Learn Asset Portal Community Support API Free Download Donate  

Defold Learn logo

Defold Learn logo

Material API documentation

Functions for interacting with materials.

Version: alpha

FUNCTIONS
material.get_constants() gets shader constants from a material
material.get_samplers() gets texture samplers from a material
material.get_textures() gets textures associated with a material
material.get_vertex_attributes() gets vertex attributes from a material
material.set_constants() sets shader constants in a material
material.set_samplers() sets texture samplers in a material
material.set_textures() sets textures in a material
material.set_vertex_attributes() sets vertex attributes in a material

Functions

material.get_constants()

material.get_constants(path)

Returns a table of all the shader constants in the material. This function will return all the shader constants that are used in both the vertex and the fragment shaders.

PARAMETERS

path hash
string
 The path to the resource

RETURNS

table table
 A table of tables, where each entry contains info about the shader constants:
name
hash the hashed name of the constant
type
number the type of the constant. Supported values:
  • material.CONSTANT_TYPE_USER
  • material.CONSTANT_TYPE_USER_MATRIX4
  • material.CONSTANT_TYPE_VIEWPROJ
  • material.CONSTANT_TYPE_WORLD
  • material.CONSTANT_TYPE_TEXTURE
  • material.CONSTANT_TYPE_VIEW
  • material.CONSTANT_TYPE_PROJECTION
  • material.CONSTANT_TYPE_NORMAL
  • material.CONSTANT_TYPE_WORLDVIEW
  • material.CONSTANT_TYPE_WORLDVIEWPROJ
  • material.CONSTANT_TYPE_TIME
  • material.CONSTANT_TYPE_WORLD_INVERSE
  • material.CONSTANT_TYPE_VIEW_INVERSE
  • material.CONSTANT_TYPE_PROJECTION_INVERSE
  • material.CONSTANT_TYPE_VIEWPROJ_INVERSE
  • material.CONSTANT_TYPE_WORLDVIEW_INVERSE
  • material.CONSTANT_TYPE_WORLDVIEWPROJ_INVERSE
value
vmath.vector4 | vmath.matrix4 the value(s) of the constant. If the constant is an array, the value will be a table of vmath.vector4 or vmath.matrix4 if the type is material.CONSTANT_TYPE_USER_MATRIX4.

EXAMPLES

Get the shader constants from a material specified as a resource property 
go.property("my_material", resource.material())

function init(self)
    local constants = material.get_constants(self.my_material)
end

material.get_samplers()

material.get_samplers(path)

Returns a table of all the texture samplers in the material. This function will return all the texture samplers that are used in both the vertex and the fragment shaders.

PARAMETERS

path hash
string
 The path to the resource

RETURNS

table table
 A table of tables, where each entry contains info about the texture samplers:
name
hash the hashed name of the texture sampler
u_wrap
number the u wrap mode of the texture sampler. Supported values:
  • graphics.TEXTURE_WRAP_CLAMP_TO_BORDER
  • graphics.TEXTURE_WRAP_CLAMP_TO_EDGE
  • graphics.TEXTURE_WRAP_MIRRORED_REPEAT
  • graphics.TEXTURE_WRAP_REPEAT
v_wrap
number the v wrap mode of the texture sampler. Supported values:
  • graphics.TEXTURE_WRAP_CLAMP_TO_BORDER
  • graphics.TEXTURE_WRAP_CLAMP_TO_EDGE
  • graphics.TEXTURE_WRAP_MIRRORED_REPEAT
  • graphics.TEXTURE_WRAP_REPEAT
min_filter
number the min filter mode of the texture sampler. Supported values:
  • graphics.TEXTURE_FILTER_DEFAULT
  • graphics.TEXTURE_FILTER_NEAREST
  • graphics.TEXTURE_FILTER_LINEAR
  • graphics.TEXTURE_FILTER_NEAREST_MIPMAP_NEAREST
  • graphics.TEXTURE_FILTER_NEAREST_MIPMAP_LINEAR
  • graphics.TEXTURE_FILTER_LINEAR_MIPMAP_NEAREST
  • graphics.TEXTURE_FILTER_LINEAR_MIPMAP_LINEAR
mag_filter
number the mag filter mode of the texture sampler
  • graphics.TEXTURE_FILTER_DEFAULT
  • graphics.TEXTURE_FILTER_NEAREST
  • graphics.TEXTURE_FILTER_LINEAR
max_anisotropy
number the max anisotropy of the texture sampler

EXAMPLES

Get the texture samplers from a material specified as a resource property 
go.property("my_material", resource.material())

function init(self)
    local samplers = material.get_samplers(self.my_material)
end

material.get_textures()

material.get_textures(path)

Returns a table of all the textures from the material.

PARAMETERS

path hash
string
 The path to the resource

RETURNS

table table
 A table of tables, where each entry contains info about the material textures:
path
hash the resource path of the texture. Only available if the texture is a resource.
handle
hash the runtime handle of the texture.
width
number the width of the texture
height
number the height of the texture
depth
number the depth of the texture. Corresponds to the number of layers in an array texture.
mipmaps
number the number of mipmaps in the texture
type
number the type of the texture. Supported values:
  • graphics.TEXTURE_TYPE_2D
  • graphics.TEXTURE_TYPE_2D_ARRAY
  • graphics.TEXTURE_TYPE_CUBE_MAP
  • graphics.TEXTURE_TYPE_IMAGE_2D
  • graphics.TEXTURE_TYPE_3D
  • graphics.TEXTURE_TYPE_IMAGE_3D
flags
number the flags of the texture. This field is a bit mask of these supported flags:
  • graphics.TEXTURE_USAGE_FLAG_SAMPLE
  • graphics.TEXTURE_USAGE_FLAG_MEMORYLESS
  • graphics.TEXTURE_USAGE_FLAG_STORAGE
  • graphics.TEXTURE_USAGE_FLAG_INPUT
  • graphics.TEXTURE_USAGE_FLAG_COLOR

EXAMPLES

Get the textures from a material specified as a resource property 
go.property("my_material", resource.material())

function init(self)
    local textures = material.get_textures(self.my_material)
end

material.get_vertex_attributes()

material.get_vertex_attributes(path)

Returns a table of all the vertex attributes in the material. This function will return all the vertex attributes that are used in the vertex shader of the material.

PARAMETERS

path hash
string
 The path to the resource

RETURNS

table table
 A table of tables, where each entry contains info about the vertex attributes:
name
hash the hashed name of the vertex attribute
value
vmath.vector4 | vmath.vector3 | vmath.matrix4 | number | table the value of the vertex attribute. Matrix attributes that do not map to vmath.matrix4 are returned as a table of numbers.
normalize
boolean whether the value is normalized when passed into the shader
data_type
number the data type of the vertex attribute. Supported values:
  • graphics.DATA_TYPE_BYTE
  • graphics.DATA_TYPE_UNSIGNED_BYTE
  • graphics.DATA_TYPE_SHORT
  • graphics.DATA_TYPE_UNSIGNED_SHORT
  • graphics.DATA_TYPE_INT
  • graphics.DATA_TYPE_UNSIGNED_INT
  • graphics.DATA_TYPE_FLOAT
coordinate_space
number the coordinate space of the vertex attribute. Supported values:
  • graphics.COORDINATE_SPACE_WORLD
  • graphics.COORDINATE_SPACE_LOCAL
semantic_type
number the semantic type of the vertex attribute. Supported values:
  • graphics.SEMANTIC_TYPE_NONE
  • graphics.SEMANTIC_TYPE_POSITION
  • graphics.SEMANTIC_TYPE_TEXCOORD
  • graphics.SEMANTIC_TYPE_PAGE_INDEX
  • graphics.SEMANTIC_TYPE_COLOR
  • graphics.SEMANTIC_TYPE_NORMAL
  • graphics.SEMANTIC_TYPE_TANGENT
  • graphics.SEMANTIC_TYPE_WORLD_MATRIX
  • graphics.SEMANTIC_TYPE_NORMAL_MATRIX
  • graphics.SEMANTIC_TYPE_BONE_WEIGHTS
  • graphics.SEMANTIC_TYPE_BONE_INDICES
  • graphics.SEMANTIC_TYPE_TEXTURE_TRANSFORM_2D

EXAMPLES

Get the vertex attributes from a material specified as a resource property 
go.property("my_material", resource.material())

function init(self)
    local vertex_attributes = material.get_vertex_attributes(self.my_material)
end

material.set_constants()

material.set_constants(path,constants)

Sets shader constants in a material, if the constants exist.

PARAMETERS

path hash
string
 The path to the resource
constants table
 A table keyed by constant name with args tables as values. Constants can be partially updated. Supported entries:
type
number the type of the constant. Supported values:
  • material.CONSTANT_TYPE_USER
  • material.CONSTANT_TYPE_USER_MATRIX4
  • material.CONSTANT_TYPE_VIEWPROJ
  • material.CONSTANT_TYPE_WORLD
  • material.CONSTANT_TYPE_TEXTURE
  • material.CONSTANT_TYPE_VIEW
  • material.CONSTANT_TYPE_PROJECTION
  • material.CONSTANT_TYPE_NORMAL
  • material.CONSTANT_TYPE_WORLDVIEW
  • material.CONSTANT_TYPE_WORLDVIEWPROJ
  • material.CONSTANT_TYPE_TIME
  • material.CONSTANT_TYPE_WORLD_INVERSE
  • material.CONSTANT_TYPE_VIEW_INVERSE
  • material.CONSTANT_TYPE_PROJECTION_INVERSE
  • material.CONSTANT_TYPE_VIEWPROJ_INVERSE
  • material.CONSTANT_TYPE_WORLDVIEW_INVERSE
  • material.CONSTANT_TYPE_WORLDVIEWPROJ_INVERSE
value
vmath.vector4 | vmath.vector3 | vmath.matrix4 | number | table the value(s) of the constant. If the shader constant is an array, the amount of values to update depends on how many values that are passed in the 'value' field.

EXAMPLES

Set a shader constant in a material specified as a resource property 
go.property("my_material", resource.material())

function update(self)
    -- update the 'tint' constant
    material.set_constants(self.my_material, {
        tint = { value = vmath.vector4(1, 0, 0, 1) }
    })
    -- change the type of the 'view_proj' constant to CONSTANT_TYPE_USER_MATRIX4 so the renderer can set our custom data
    material.set_constants(self.my_material, {
        view_proj = { value = self.my_view_proj, type = material.CONSTANT_TYPE_USER_MATRIX4 }
    })
end

material.set_samplers()

material.set_samplers(path,samplers)

Sets texture samplers in a material, if the samplers exist. Use this function to change the settings of texture samplers. To set actual textures that should be bound to the samplers, use the material.set_textures function instead.

PARAMETERS

path hash
string
 The path to the resource
samplers table
 A table keyed by sampler name with args tables as values. Partial updates are supported. Supported entries:
u_wrap
number the u wrap mode of the texture sampler. Supported values:
  • graphics.TEXTURE_WRAP_CLAMP_TO_BORDER
  • graphics.TEXTURE_WRAP_CLAMP_TO_EDGE
  • graphics.TEXTURE_WRAP_MIRRORED_REPEAT
  • graphics.TEXTURE_WRAP_REPEAT
v_wrap
number the v wrap mode of the texture sampler. Supported values:
  • graphics.TEXTURE_WRAP_CLAMP_TO_BORDER
  • graphics.TEXTURE_WRAP_CLAMP_TO_EDGE
  • graphics.TEXTURE_WRAP_MIRRORED_REPEAT
  • graphics.TEXTURE_WRAP_REPEAT
min_filter
number the min filter mode of the texture sampler. Supported values:
  • graphics.TEXTURE_FILTER_DEFAULT
  • graphics.TEXTURE_FILTER_NEAREST
  • graphics.TEXTURE_FILTER_LINEAR
  • graphics.TEXTURE_FILTER_NEAREST_MIPMAP_NEAREST
  • graphics.TEXTURE_FILTER_NEAREST_MIPMAP_LINEAR
  • graphics.TEXTURE_FILTER_LINEAR_MIPMAP_NEAREST
  • graphics.TEXTURE_FILTER_LINEAR_MIPMAP_LINEAR
mag_filter
number the mag filter mode of the texture sampler
  • graphics.TEXTURE_FILTER_DEFAULT
  • graphics.TEXTURE_FILTER_NEAREST
  • graphics.TEXTURE_FILTER_LINEAR
max_anisotropy
number the max anisotropy of the texture sampler

EXAMPLES

Configures a sampler in a material specified as a resource property 
go.property("my_material", resource.material())

function init(self)
    material.set_samplers(self.my_material, {
        texture_sampler = { u_wrap = graphics.TEXTURE_WRAP_REPEAT, v_wrap = graphics.TEXTURE_WRAP_MIRRORED_REPEAT }
    })
end

material.set_textures()

material.set_textures(path,textures)

Sets textures in a material, if the samplers exist.

PARAMETERS

path hash
string
 The path to the resource
textures table
 A table keyed by sampler name with texture resources as values.

EXAMPLES

Set a texture in a material from a resource 
go.property("my_material", resource.material())
go.property("my_texture", resource.texture())

function init(self)
    material.set_textures(self.my_material, {
        my_texture = self.my_texture
    })
end

material.set_vertex_attributes()

material.set_vertex_attributes(path,attributes)

Sets vertex attributes in a material, if the vertex attributes exist.

PARAMETERS

path hash
string
 The path to the resource
attributes table
 A table keyed by vertex attribute name with args tables as values. Partial updates are supported. Supported entries:
value
vmath.vector4 | vmath.vector3 | vmath.matrix4 | number | table the value of the vertex attribute. Use a table of numbers for matrix attributes that do not map to vmath.matrix4.
normalize
boolean whether the value is normalized when passed into the shader
data_type
number the data type of the vertex attribute. Supported values:
  • graphics.DATA_TYPE_BYTE
  • graphics.DATA_TYPE_UNSIGNED_BYTE
  • graphics.DATA_TYPE_SHORT
  • graphics.DATA_TYPE_UNSIGNED_SHORT
  • graphics.DATA_TYPE_INT
  • graphics.DATA_TYPE_UNSIGNED_INT
  • graphics.DATA_TYPE_FLOAT
coordinate_space
number the coordinate space of the vertex attribute. Supported values:
  • graphics.COORDINATE_SPACE_DEFAULT
  • graphics.COORDINATE_SPACE_WORLD
  • graphics.COORDINATE_SPACE_LOCAL
semantic_type
number the semantic type of the vertex attribute. Supported values:
  • graphics.SEMANTIC_TYPE_NONE
  • graphics.SEMANTIC_TYPE_POSITION
  • graphics.SEMANTIC_TYPE_TEXCOORD
  • graphics.SEMANTIC_TYPE_PAGE_INDEX
  • graphics.SEMANTIC_TYPE_COLOR
  • graphics.SEMANTIC_TYPE_NORMAL
  • graphics.SEMANTIC_TYPE_TANGENT
  • graphics.SEMANTIC_TYPE_WORLD_MATRIX
  • graphics.SEMANTIC_TYPE_NORMAL_MATRIX
  • graphics.SEMANTIC_TYPE_BONE_WEIGHTS
  • graphics.SEMANTIC_TYPE_BONE_INDICES
  • graphics.SEMANTIC_TYPE_TEXTURE_TRANSFORM_2D

EXAMPLES

Configures a vertex attribute in a material specified as a resource property 
go.property("my_material", resource.material())

function init(self)
    material.set_vertex_attributes(self.my_material, {
        tint_attribute = { value = vmath.vec4(1, 0, 0, 1), semantic_type = graphics.SEMANTIC_TYPE_COLOR },
        weights        = { value = vmath.vec4(0, 1, 0, 0), semantic_type = graphics.SEMANTIC_TYPE_NONE }
    })
end