Material

IMaterial, number Material( string materialName, string pngParameters = nil )

Description

Either returns the material with the given name, or loads the material interpreting the first argument as the path.

.png, .jpg and other image formats

This function is capable to loading .png or .jpg images, generating a texture and material for them on the fly.

PNG, JPEG, GIF, and TGA files will work, but only if they have the .png or .jpg file extensions (even if the actual image format doesn't match the file extension)

Use AddonMaterial for image files with the .cache file extension. (from steamworks.Download)

While images are no longer scaled to Power of 2 (sizes of 8, 16, 32, 64, 128, etc.) sizes since February 2019, it is still a good practice for things like icons, etc.

Server-side, this function can consistently return an invalid material (with '__error') depending on the file type loaded.

This function is very expensive when used in rendering hooks or in operations requiring very frequent calls. It is a good idea to cache the material in a variable (like in the examples).

Arguments

1 string materialName

The material name or path relative to the materials/ folder.
Paths outside the materials/ folder like data/MyImage.jpg or maps/thumb/gm_construct.png will also work for when generating materials.

To retrieve a Lua material created with CreateMaterial, just prepend a ! to the material name.

2 string pngParameters = nil

A string containing space separated keywords which will be used to add material parameters.

See Material Parameters for more information.

This feature only works when importing .png or .jpg image files.

Returns

1 IMaterial

Generated material.

2 number

How long it took for the function to run.

Example

Creates a PNG material with noclamp and smooth parameters set and then draws on screen.

In this example the .png file is located in materials/vgui/wave.png.

local wave = Material( "vgui/wave.png", "noclamp smooth" ) hook.Add( "HUDPaint", "HUDPaint_DrawATexturedBox", function() surface.SetMaterial( wave ) surface.SetDrawColor( 255, 255, 255, 255 ) surface.DrawTexturedRect( 50, 50, 128, 128 ) end )

Example

Acquires and uses one of the Post-Processing Materials to make the screen darker and more saturated.

local mat_color = Material( "pp/colour" ) -- used outside of the hook for performance hook.Add("RenderScreenspaceEffects", "ColorExample", function() render.UpdateScreenEffectTexture() mat_color:SetTexture( "$fbtexture", render.GetScreenEffectTexture() ) mat_color:SetFloat( "$pp_colour_addr", 0 ) mat_color:SetFloat( "$pp_colour_addg", 0 ) mat_color:SetFloat( "$pp_colour_addb", 0 ) mat_color:SetFloat( "$pp_colour_mulr", 0 ) mat_color:SetFloat( "$pp_colour_mulg", 0 ) mat_color:SetFloat( "$pp_colour_mulb", 0 ) mat_color:SetFloat( "$pp_colour_brightness", 0 ) mat_color:SetFloat( "$pp_colour_contrast", 0.5 ) mat_color:SetFloat( "$pp_colour_colour", 5 ) render.SetMaterial( mat_color ) render.DrawScreenQuad() end )