lovr.graphics.newMaterial

Creates a new Material from a table of properties and textures. All fields are optional. Once a Material is created, its properties can not be changed. Instead, a new Material should be created with the updated properties.

material = lovr.graphics.newMaterial(properties)

Arguments

NameTypeDefaultDescription
propertiestable Material properties.
.colorVec4{ 1, 1, 1, 1 } The base color of the surface. Can be a Vec3, Vec4, table of numbers, or hexcode. Can be toggled in shaders using the materialColor flag, which defaults to true.
.glowVec4{ 0, 0, 0, 0 } The glow color of the surface, sometimes called "emissive". The glow is not affected by lighting, so it's a good fit for e.g. headlights on a car or LED lights on a panel. The alpha of the glow color is used as the glow strength. Can be a Vec3, Vec4, table of numbers, or hexcode. Can be toggled in shaders using the glow flag, which defaults to false.
.uvShiftVec2{ 0, 0 } An offset to apply to the UV coordinates used to sample textures. The offset is not affected by uvScale. This can be used to map UV coordinates to a sub-rectangle of a texture atlas. Can be a Vec2, table of numbers, or a single number which gets assigned to both axes. Can be toggled in shaders using the uvTransform flag, which defaults to true.
.uvScaleVec2{ 1, 1 } A scale factor to apply to the UV coordinates used to sample textures. The scale is not affected by uvOffset. This can be used to map UV coordinates to a sub-rectangle of a texture atlas, or repeat a texture multiple times across a surface. Can be a Vec2, table of numbers, or a single number which gets assigned to both axes. Can be toggled in shaders using the uvTransform flag, which defaults to true.
.metalnessnumber0 The metalness the surface, used for physically-based rendering. 1.0 means the surface is metallic (conductor), and 0.0 means the surface is non-metallic (dielectric). Values in between are seldom used and are only used in textures to transition between a metallic and non-metallic surface. Metals reflect light differently than non-metals. Used by the lighting helper functions initSurface and getLighting.
.roughnessnumber0 The roughness of the surface, used for physically-based rendering. 1.0 means the surface is rough (blurry reflections), and 0.0 means the surface is smooth (sharp reflections). Used by the lighting helper functions initSurface and getLighting.
.clearcoatnumber0 The clearcoat factor. Not currently used by LÖVR.
.clearcoatRoughnessnumber0 The roughness of the clearcoat layer. Not currently used by LÖVR.
.occlusionStrengthnumber1 The strength of the ambient occlusion effect. Ambient occlusion only affects indirect lighting. Used by the lighting helper functions initSurface and getIndirectLighting. Can be toggled in shaders using the ambientOcclusion flag, which defaults to true.
.normalScalenumber1 The strength of the normal map. Used by the initSurface function to bend the surface normal. Can be toggled in shaders using the normalMap flag, which defaults to false.
.alphaCutoffnumber0 The alpha cutoff. At the end of the fragment shader, if the alpha of the final color is below the alpha cutoff, then the pixel will be "discarded" which means that it won't write a depth value. Often used for transparent textures, especially with the "alpha to coverage" state set by Pass:setAlphaToCoverage. Can be toggled in shaders using the alphaCutoff flag, which defaults to false.
.textureTexture The base color texture. In shaders this gets multiplied with the color property to get the base color of the pixel. Can be toggled in shaders using the colorTexture flag, which defaults to true.
.glowTextureTexture The glow color texture. In shaders, samples from this texture get multiplied with the glow property to get the glow color of the pixel. Can be toggled in shaders using the glowTexture flag, which defaults to true (also requires the glow flag to be enabled).
.metalnessTextureTexture The metalness texture. In shaders, samples from the blue channel of this texture get multiplied with the metalness property to get the metalness value of the pixel. Can be toggled in shaders using the metalnessTexture flag, which defaults to true.
.roughnessTextureTexture The roughness texture. In shaders, samples from the green channel of this texture get multiplied with the roughness property to get the roughness value of the pixel. Can be toggled in shaders using the roughnessTexture flag, which defaults to true.
.clearcoatTextureTexture Not currently used by LÖVR.
.occlusionTextureTexture The ambient occlusion texture. In shaders, samples from the red channel of this texture get multiplied with the occlusionStrength property to get the ambient occlusion value of the pixel. Used by the lighting helper functions initSurface and getIndirectLighting. Can be toggled in shaders using the ambientOcclusion flag, which defaults to true.
.normalTextureTexture The normal map, used to apply details to a surface without adding mesh geometry. The normalScale property can be used to control how strong the effect is. Can be toggled in shaders using the normalMap flag, which defaults to false.

Returns

NameTypeDescription
materialMaterial The new material.

Notes

The non-texture material properties can be accessed in shaders using Material.<property>, where the property is the same as the Lua table key. The textures use capitalized names in shader code, e.g. ColorTexture.

See also