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

TYPES
material.constant_info_value Material constant result value
material.constant_value Material constant value
material.vertex_attribute_value Material vertex attribute value
RECORDS
material.constant_info Shader constant information
material.constant_options Shader constant update
material.named_vertex_attribute_options Named material vertex attribute update
material.sampler_info Texture sampler information
material.sampler_options Texture sampler update
material.texture_info Texture information
material.vertex_attribute_info Material vertex attribute information
material.vertex_attribute_options Material vertex attribute update
ENUMS
material.CONSTANT_TYPE Material constant types
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

Types

material.constant_info_value

material.constant_info_value = vector4 | matrix4 | vector4[] | matrix4[]

The value of a user constant returned in a material.constant_info entry by material.get_constants. A scalar constant is returned as a vector4 or matrix4; a shader constant array is returned as an array of those values. Non-user constants do not include a value field.

EXAMPLES

for _, constant in ipairs(material.get_constants(self.material)) do
    if constant.value then
        pprint(constant.name, constant.value)
    end
end

material.constant_value

material.constant_value = number | vector3 | vector4 | matrix4 | (number|vector3|vector4|matrix4)[]

A value accepted by material.set_constants when updating a shader constant. Use a number or vector for user vector constants, a matrix4 for matrix constants, and an array to update a shader constant array.

EXAMPLES

material.set_constants(self.material, {
    tint = { value = vmath.vector4(1, 0.5, 0.5, 1) },
    weights = { value = { 0.25, 0.5, 0.75, 1 } }
})

material.vertex_attribute_value

material.vertex_attribute_value = number | vector3 | vector4 | matrix4 | number[]

A vertex attribute value accepted by material.set_vertex_attributes and returned by material.get_vertex_attributes. Use a number or vector for scalar and vector attributes, matrix4 for a 4x4 matrix, and a flat array of numbers for matrix shapes that do not map to matrix4.

EXAMPLES

material.set_vertex_attributes(self.material, {
    tint = { value = vmath.vector4(1, 0, 0, 1) },
    transform_2d = { value = { 1, 0, 0, 0, 1, 0, 0, 0, 1 } }
})

Records

material.constant_info

Shader constant information

FIELDS

name hash Constant name.
type material.CONSTANT_TYPE Constant type.
[value] material.constant_info_value Constant value or values. Present for user constants.

material.constant_options

Shader constant update

FIELDS

[type] material.CONSTANT_TYPE Constant type.
[value] material.constant_value Constant value or values.

material.named_vertex_attribute_options

Named material vertex attribute update

FIELDS

name string|hash Attribute name.
[value] material.vertex_attribute_value Attribute value.
[normalize] boolean Whether integer data is normalized.
[data_type] graphics.DATA_TYPE Attribute data type.
[coordinate_space] graphics.COORDINATE_SPACE Attribute coordinate space.
[semantic_type] graphics.SEMANTIC_TYPE Attribute semantic.

material.sampler_info

Texture sampler information

FIELDS

name hash Sampler name.
type graphics.TEXTURE_TYPE Sampler texture type.
u_wrap graphics.TEXTURE_WRAP Horizontal wrap mode.
v_wrap graphics.TEXTURE_WRAP Vertical wrap mode.
min_filter graphics.TEXTURE_FILTER Minification filter.
mag_filter graphics.TEXTURE_FILTER Magnification filter.
max_anisotropy number Maximum anisotropy.

material.sampler_options

Texture sampler update

FIELDS

[u_wrap] graphics.TEXTURE_WRAP Horizontal wrap mode.
[v_wrap] graphics.TEXTURE_WRAP Vertical wrap mode.
[min_filter] graphics.TEXTURE_FILTER Minification filter.
[mag_filter] graphics.TEXTURE_FILTER Magnification filter.
[max_anisotropy] number Maximum anisotropy.

material.texture_info

Texture information

FIELDS

[path] hash Texture resource path, if backed by a resource.
handle texture Runtime texture handle.
width integer Texture width.
height integer Texture height.
depth integer Texture depth or layer count.
page_count integer Texture page count.
mipmaps integer Mipmap count.
type graphics.TEXTURE_TYPE Texture type.
flags graphics.TEXTURE_USAGE_FLAG Texture usage flags.

material.vertex_attribute_info

Material vertex attribute information

FIELDS

name hash Attribute name.
value material.vertex_attribute_value Attribute value.
normalize boolean Whether integer data is normalized.
data_type graphics.DATA_TYPE Attribute data type.
coordinate_space graphics.COORDINATE_SPACE Attribute coordinate space.
semantic_type graphics.SEMANTIC_TYPE Attribute semantic.

material.vertex_attribute_options

Material vertex attribute update

FIELDS

[value] material.vertex_attribute_value Attribute value.
[normalize] boolean Whether integer data is normalized.
[data_type] graphics.DATA_TYPE Attribute data type.
[coordinate_space] graphics.COORDINATE_SPACE Attribute coordinate space.
[semantic_type] graphics.SEMANTIC_TYPE Attribute semantic.

Enums

material.CONSTANT_TYPE

material.CONSTANT_TYPE: integer

Material constant types

VALUES

material.CONSTANT_TYPE_USER User vector constant.
material.CONSTANT_TYPE_USER_COLOR User color constant.
material.CONSTANT_TYPE_USER_MATRIX4 User matrix constant.
material.CONSTANT_TYPE_VIEWPROJ View-projection matrix constant.
material.CONSTANT_TYPE_WORLD World matrix constant.
material.CONSTANT_TYPE_TEXTURE Texture matrix constant.
material.CONSTANT_TYPE_VIEW View matrix constant.
material.CONSTANT_TYPE_PROJECTION Projection matrix constant.
material.CONSTANT_TYPE_NORMAL Normal matrix constant.
material.CONSTANT_TYPE_WORLDVIEW World-view matrix constant.
material.CONSTANT_TYPE_WORLDVIEWPROJ World-view-projection matrix constant.
material.CONSTANT_TYPE_TIME Time constant.
material.CONSTANT_TYPE_WORLD_INVERSE Inverse world matrix constant.
material.CONSTANT_TYPE_VIEW_INVERSE Inverse view matrix constant.
material.CONSTANT_TYPE_PROJECTION_INVERSE Inverse projection matrix constant.
material.CONSTANT_TYPE_VIEWPROJ_INVERSE Inverse view-projection matrix constant.
material.CONSTANT_TYPE_WORLDVIEW_INVERSE Inverse world-view matrix constant.
material.CONSTANT_TYPE_WORLDVIEWPROJ_INVERSE Inverse world-view-projection matrix constant.

Functions

material.get_constants()

material.get_constants(path:hash|string)→constants:material.constant_info[]

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

constants material.constant_info[]
 Shader constant information.

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:hash|string)→samplers:material.sampler_info[]

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

samplers material.sampler_info[]
 texture sampler information

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:hash|string)→textures:material.texture_info[]

Returns a table of all the textures from the material.

PARAMETERS

path hash
string
 The path to the resource

RETURNS

textures material.texture_info[]
 material texture information

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:hash|string)→attributes:material.vertex_attribute_info[]

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

attributes material.vertex_attribute_info[]
 vertex attribute information

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:hash|string, constants:table<string|hash, material.constant_options>)

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

PARAMETERS

path hash
string
 The path to the resource
constants table<string|hash, material.constant_options>
 Shader constant updates keyed by constant name. Partial updates are supported.

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:hash|string, samplers:table<string|hash, material.sampler_options>)

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<string|hash, material.sampler_options>
 Sampler updates keyed by sampler name. Partial updates are supported.

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:hash|string, textures:table<string|hash, string|hash>)

Sets textures in a material, if the samplers exist.

PARAMETERS

path hash
string
 The path to the resource
textures table<string|hash, string|hash>
 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:hash|string, attributes:table<string|hash, material.vertex_attribute_options>|material.named_vertex_attribute_options[])

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

PARAMETERS

path hash
string
 The path to the resource
attributes table<string|hash, material.vertex_attribute_options>
material.named_vertex_attribute_options[]
 Vertex attributes keyed by name, or an array with explicit name fields. Partial updates are supported.

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