.. _stdlib_material_properties: ======================= Material Properties API ======================= .. line-block:: This module provides a simple way to define and manage material properties. Material properties are key-value pairs that can be used to define the appearance of a material or the values of per-instance properties. The values can be of the following types: ``float``, ``float4``, and ``int``. Defined in:: engine.render.material_properties To define a new material property, use the add function. For example:: var properties = MaterialProperties("color", GREEN_COLOR) // Adds a green color property To add more properties, use the add function:: var properties = MaterialProperties("color", GREEN_COLOR) add(properties, "uvRect", uvRect) Or construct the properties in a single call:: var properties = MaterialProperties("color", GREEN_COLOR, "uvRect", uvRect) To see the list of all available properties, refer to the corresponding :ref:`shader documentation `. +++++++++ Constants +++++++++ .. _global-material_properties-MAX_MATERIAL_PROPERTIES: .. das:attribute:: MAX_MATERIAL_PROPERTIES = 8 The maximum number of material properties that can be defined ++++++++++++ Enumerations ++++++++++++ .. _enum-material_property_enums-FaceCullMode: .. das:attribute:: FaceCullMode Represents a value for "faceCullMode" property. We treat faces as back if they're oriented counter-clockwise (CCW) after projection into screen space. We treat faces as front if they're oriented clockwise (CW) after projection into screen space. For back faces their normals will be mirrored along interpolated surface normal. :Values: * **None** = 0 - Neither of the sides will be culled. * **Back** = 1 - Back faces will be culled. This is the default mode. * **Front** = 2 - Front faces will be culled. .. _enum-material_property_enums-TransparencyMode: .. das:attribute:: TransparencyMode Represents a transparency value for "transparencyMode" property. :Values: * **Opaque** = 0 - No blending (``finalColor = srcColor``) * **Translucent** = 1 - Default blending (``finalColor = srcColor * srcAlpha + dstColor * (1 - srcAlpha)``) * **Additive** = 2 - Additive blending (``finalColor = srcColor * srcAlpha + dstColor``) ++++++++++ Structures ++++++++++ .. _struct-material_properties-MaterialProperties: .. das:attribute:: MaterialProperties Represents a collection of material properties. :Fields: * **names** : string[8] - The names of the material properties * **values** : :ref:`MaterialPropertyValue ` - The values of the material properties * **cursor** : int - The current cursor position in the material properties array +++++++++ Functions +++++++++ * :ref:`MaterialProperties () : MaterialProperties ` * :ref:`add (var properties: MaterialProperties; name: string; value: float) : MaterialProperties& ` * :ref:`add (var properties: MaterialProperties; name: string; value: float4) : MaterialProperties& ` * :ref:`add (var properties: MaterialProperties; name: string; value: int) : MaterialProperties& ` * :ref:`MaterialProperties (name1: string; value1: float|float4|int) : MaterialProperties ` * :ref:`MaterialProperties (name1: string; value1: float|float4|int; name2: string; value2: float|float4|int) : MaterialProperties ` * :ref:`MaterialProperties (name1: string; value1: float|float4|int; name2: string; value2: float|float4|int; name3: string; value3: float|float4|int) : MaterialProperties ` * :ref:`MaterialProperties (name1: string; value1: float|float4|int; name2: string; value2: float|float4|int; name3: string; value3: float|float4|int; name4: string; value4: float|float4|int) : MaterialProperties ` .. _function-material_properties_MaterialProperties: .. das:function:: MaterialProperties() : MaterialProperties Creates a new material properties collection. :Returns: * :ref:`MaterialProperties ` - the new material properties collection .. _function-material_properties_add_MaterialProperties_string_float: .. das:function:: add(properties: MaterialProperties; name: string; value: float) : MaterialProperties& Adds a float material property to the collection. :Arguments: * **properties** : :ref:`MaterialProperties ` - the material properties collection * **name** : string - the name of the property * **value** : float - the value of the property :Returns: * :ref:`MaterialProperties ` & - the updated material properties collection .. _function-material_properties_add_MaterialProperties_string_float4: .. das:function:: add(properties: MaterialProperties; name: string; value: float4) : MaterialProperties& Adds a float4 material property to the collection. :Arguments: * **properties** : :ref:`MaterialProperties ` - the material properties collection * **name** : string - the name of the property * **value** : float4 - the value of the property :Returns: * :ref:`MaterialProperties ` & - the updated material properties collection .. _function-material_properties_add_MaterialProperties_string_int: .. das:function:: add(properties: MaterialProperties; name: string; value: int) : MaterialProperties& Adds an int material property to the collection. :Arguments: * **properties** : :ref:`MaterialProperties ` - the material properties collection * **name** : string - the name of the property * **value** : int - the value of the property :Returns: * :ref:`MaterialProperties ` & - the updated material properties collection .. _function-material_properties_MaterialProperties_string_floatfloat4int: .. das:function:: MaterialProperties(name1: string; value1: float|float4|int) : MaterialProperties Creates a new material properties collection with a single float property. :Arguments: * **name1** : string - the name of the property * **value1** : option - the value of the property :Returns: * :ref:`MaterialProperties ` - the new material properties collection .. _function-material_properties_MaterialProperties_string_floatfloat4int_string_floatfloat4int: .. das:function:: MaterialProperties(name1: string; value1: float|float4|int; name2: string; value2: float|float4|int) : MaterialProperties Creates a new material properties collection with two float properties. :Arguments: * **name1** : string - the name of the first property * **value1** : option - the value of the first property * **name2** : string - the name of the second property * **value2** : option - the value of the second property :Returns: * :ref:`MaterialProperties ` - the new material properties collection .. _function-material_properties_MaterialProperties_string_floatfloat4int_string_floatfloat4int_string_floatfloat4int: .. das:function:: MaterialProperties(name1: string; value1: float|float4|int; name2: string; value2: float|float4|int; name3: string; value3: float|float4|int) : MaterialProperties Creates a new material properties collection with three float properties. :Arguments: * **name1** : string - the name of the first property * **value1** : option - the value of the first property * **name2** : string - the name of the second property * **value2** : option - the value of the second property * **name3** : string - the name of the third property * **value3** : option - the value of the third property :Returns: * :ref:`MaterialProperties ` - the new material properties collection .. _function-material_properties_MaterialProperties_string_floatfloat4int_string_floatfloat4int_string_floatfloat4int_string_floatfloat4int: .. das:function:: MaterialProperties(name1: string; value1: float|float4|int; name2: string; value2: float|float4|int; name3: string; value3: float|float4|int; name4: string; value4: float|float4|int) : MaterialProperties Creates a new material properties collection with four float properties. :Arguments: * **name1** : string - the name of the first property * **value1** : option - the value of the first property * **name2** : string - the name of the second property * **value2** : option - the value of the second property * **name3** : string - the name of the third property * **value3** : option - the value of the third property * **name4** : string - the name of the fourth property * **value4** : option - the value of the fourth property :Returns: * :ref:`MaterialProperties ` - the new material properties collection