Shader

Description:

  A Shader is used for advanced hardware-accelerated pixel or vertex manipulation. These effects are written in a language based on GLSL (OpenGL Shading Language) with a few things simplified for easier coding.

type

Type: Function.

Description:

  Gets the type of the object as a string.

Signature:

type: function(self: Shader): string

Returns:

Return Type	Description
string	The type as a string.

Of

Type: Function.

Description:

  Checks whether an object is of a certain type. If the object has the type with the specified name in its hierarchy, this function will return true.

Signature:

typeOf: function(self: Shader, type_name: string): boolean

Parameters:

Parameter	Type	Description
type_name	string	The name of the type to check for.

Returns:

Return Type	Description
boolean	True if the object is of the specified type, false otherwise.

release

Type: Function.

Description:

  Destroys the object's Lua reference. The object will be completely deleted if it's not referenced by any other LÖVE object or thread. This method can be used to immediately clean up resources without waiting for Lua's garbage collector.

Signature:

release: function(self: Shader): boolean

Returns:

Return Type	Description
boolean	True if the object was released by this call, false if it had been previously released.

getWarnings

Type: Function.

Description:

  Returns any warning and error messages from compiling the shader code. This can be used for debugging your shaders if there's anything the graphics hardware doesn't like.

Signature:

getWarnings: function(self: Shader): string

Returns:

Return Type	Description
string	Warning and error messages (if any).

getExternVariable

Type: Function.

Description:

  Gets whether an extern variable exists in the Shader. Deprecated compatibility alias for hasUniform used by LÖVE versions before 0.10.

Signature:

getExternVariable: function(self: Shader, name: string): boolean

Parameters:

Parameter	Type	Description
name	string	The name parameter.

hasUniform

Type: Function.

Description:

  Gets whether a uniform / extern variable exists in the Shader. If a graphics driver's shader compiler determines that a uniform / extern variable doesn't affect the final output of the shader, it may optimize the variable out. This function will return false in that case.

Signature:

hasUniform: function(self: Shader, name: string): boolean

Parameters:

Parameter	Type	Description
name	string	The name of the uniform variable.

Returns:

Return Type	Description
boolean	Whether the uniform exists in the shader and affects its final output.

send

Type: Function.

Description:

  Sends one or more values to a special (''uniform'') variable inside the shader. Uniform variables have to be marked using the ''uniform'' or ''extern'' keyword, e.g.

-- uniform float time; // 'float' is the typical number type used in GLSL shaders.

-- uniform float varsvec2 light_pos;

-- uniform vec4 colors[4;

-- The corresponding send calls would be

-- shader:send('time', t)

-- shader:send('vars',a,b)

-- shader:send('light_pos', {light_x, light_y})

-- shader:send('colors', {r1, g1, b1, a1}, {r2, g2, b2, a2}, {r3, g3, b3, a3}, {r4, g4, b4, a4})

-- Uniform / extern variables are read-only in the shader code and remain constant until modified by a Shader:send call. Uniform variables can be accessed in both the Vertex and Pixel components of a shader, as long as the variable is declared in each.

Signature:

send: function(self: Shader, name: string, texture: Image | Canvas, textures: Image | Canvas...)

Parameters:

Parameter	Type	Description
name	string	Name of the number to send to the shader.
texture	Image	Canvas
textures	Image	Canvas...

send

Type: Function.

Description:

  Sends one or more values to a special (''uniform'') variable inside the shader. Uniform variables have to be marked using the ''uniform'' or ''extern'' keyword, e.g.

-- uniform float time; // 'float' is the typical number type used in GLSL shaders.

-- uniform float varsvec2 light_pos;

-- uniform vec4 colors[4;

-- The corresponding send calls would be

-- shader:send('time', t)

-- shader:send('vars',a,b)

-- shader:send('light_pos', {light_x, light_y})

-- shader:send('colors', {r1, g1, b1, a1}, {r2, g2, b2, a2}, {r3, g3, b3, a3}, {r4, g4, b4, a4})

-- Uniform / extern variables are read-only in the shader code and remain constant until modified by a Shader:send call. Uniform variables can be accessed in both the Vertex and Pixel components of a shader, as long as the variable is declared in each.

Signature:

send: function(self: Shader, name: string, matrix_layout: MatrixLayout, matrices: {number} | {{number}}...)

Parameters:

Parameter	Type	Description
name	string	Name of the vector to send to the shader.
matrix_layout	MatrixLayout	The layout (row- or column-major) of the matrix in memory.
matrices	{number}	{{number}}...

send

Type: Function.

Description:

  Sends one or more values to a special (''uniform'') variable inside the shader. Uniform variables have to be marked using the ''uniform'' or ''extern'' keyword, e.g.

-- uniform float time; // 'float' is the typical number type used in GLSL shaders.

-- uniform float varsvec2 light_pos;

-- uniform vec4 colors[4;

-- The corresponding send calls would be

-- shader:send('time', t)

-- shader:send('vars',a,b)

-- shader:send('light_pos', {light_x, light_y})

-- shader:send('colors', {r1, g1, b1, a1}, {r2, g2, b2, a2}, {r3, g3, b3, a3}, {r4, g4, b4, a4})

-- Uniform / extern variables are read-only in the shader code and remain constant until modified by a Shader:send call. Uniform variables can be accessed in both the Vertex and Pixel components of a shader, as long as the variable is declared in each.

Signature:

send: function(self: Shader, name: string, data: Data, offset?: number, size?: number)

Parameters:

Parameter	Type	Description
name	string	Name of the matrix to send to the shader.
data	Data	Data object containing the values to send.
offset	number	Offset in bytes from the start of the Data object. (Default: 0.)
size	number	Size in bytes of the data to send. If nil, as many bytes as the specified uniform uses will be copied. (Default: all.)

send

Type: Function.

Description:

  Sends one or more values to a special (''uniform'') variable inside the shader. Uniform variables have to be marked using the ''uniform'' or ''extern'' keyword, e.g.

-- uniform float time; // 'float' is the typical number type used in GLSL shaders.

-- uniform float varsvec2 light_pos;

-- uniform vec4 colors[4;

-- The corresponding send calls would be

-- shader:send('time', t)

-- shader:send('vars',a,b)

-- shader:send('light_pos', {light_x, light_y})

-- shader:send('colors', {r1, g1, b1, a1}, {r2, g2, b2, a2}, {r3, g3, b3, a3}, {r4, g4, b4, a4})

-- Uniform / extern variables are read-only in the shader code and remain constant until modified by a Shader:send call. Uniform variables can be accessed in both the Vertex and Pixel components of a shader, as long as the variable is declared in each.

Signature:

send: function(self: Shader, name: string, matrix_layout: MatrixLayout, data: Data, offset?: number, size?: number)

Parameters:

Parameter	Type	Description
name	string	Name of the Texture to send to the shader.
matrix_layout	MatrixLayout	The layout (row- or column-major) of the matrix in memory.
data	Data	Data object containing the values to send.
offset	number	Offset in bytes from the start of the Data object. (Default: 0.)
size	number	Size in bytes of the data to send. If nil, as many bytes as the specified uniform uses will be copied. (Default: all.)

send

Type: Function.

Description:

  Sends one or more values to a special (''uniform'') variable inside the shader. Uniform variables have to be marked using the ''uniform'' or ''extern'' keyword, e.g.

-- uniform float time; // 'float' is the typical number type used in GLSL shaders.

-- uniform float varsvec2 light_pos;

-- uniform vec4 colors[4;

-- The corresponding send calls would be

-- shader:send('time', t)

-- shader:send('vars',a,b)

-- shader:send('light_pos', {light_x, light_y})

-- shader:send('colors', {r1, g1, b1, a1}, {r2, g2, b2, a2}, {r3, g3, b3, a3}, {r4, g4, b4, a4})

-- Uniform / extern variables are read-only in the shader code and remain constant until modified by a Shader:send call. Uniform variables can be accessed in both the Vertex and Pixel components of a shader, as long as the variable is declared in each.

Signature:

send: function(self: Shader, name: string, data: Data, matrix_layout: MatrixLayout, offset?: number, size?: number)

Parameters:

Parameter	Type	Description
name	string	Name of the boolean to send to the shader.
data	Data	Data object containing the values to send.
matrix_layout	MatrixLayout	The layout (row- or column-major) of the matrix in memory.
offset	number	Offset in bytes from the start of the Data object. (Default: 0.)
size	number	Size in bytes of the data to send. If nil, as many bytes as the specified uniform uses will be copied. (Default: all.)

send

Type: Function.

Description:

  Sends one or more values to a special (''uniform'') variable inside the shader. Uniform variables have to be marked using the ''uniform'' or ''extern'' keyword, e.g.

-- uniform float time; // 'float' is the typical number type used in GLSL shaders.

-- uniform float varsvec2 light_pos;

-- uniform vec4 colors[4;

-- The corresponding send calls would be

-- shader:send('time', t)

-- shader:send('vars',a,b)

-- shader:send('light_pos', {light_x, light_y})

-- shader:send('colors', {r1, g1, b1, a1}, {r2, g2, b2, a2}, {r3, g3, b3, a3}, {r4, g4, b4, a4})

-- Uniform / extern variables are read-only in the shader code and remain constant until modified by a Shader:send call. Uniform variables can be accessed in both the Vertex and Pixel components of a shader, as long as the variable is declared in each.

Signature:

send: function(self: Shader, name: string, values: ShaderValue...)

Parameters:

Parameter	Type	Description
name	string	Name of the uniform to send to the shader.
values	ShaderValue...	Texture (Image or Canvas) to send to the uniform variable.

sendColor

Type: Function.

Description:

  Sends one or more colors to a special (''extern'' / ''uniform'') vec3 or vec4 variable inside the shader. The color components must be in the range of 1. The colors are gamma-corrected if global gamma-correction is enabled.

-- Extern variables must be marked using the ''extern'' keyword, e.g.

-- extern vec4 Color;

-- The corresponding sendColor call would be

-- shader:sendColor('Color', {r, g, b, a})

-- Extern variables can be accessed in both the Vertex and Pixel stages of a shader, as long as the variable is declared in each.

-- In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

Signature:

sendColor: function(self: Shader, name: string, data: Data, offset?: number, size?: number)

Parameters:

Parameter	Type	Description
name	string	The name of the color extern variable to send to in the shader.
data	Data	A table with red, green, blue, and optional alpha color components in the range of 1 to send to the extern as a vector.
offset	number	Additional colors to send in case the extern is a table. All colors need to be of the same size (e.g. only vec3's).
size	number	The number of bytes to read from the Data object.

sendColor

Type: Function.

Description:

  Sends one or more colors to a special (''extern'' / ''uniform'') vec3 or vec4 variable inside the shader. The color components must be in the range of 1. The colors are gamma-corrected if global gamma-correction is enabled.

-- Extern variables must be marked using the ''extern'' keyword, e.g.

-- extern vec4 Color;

-- The corresponding sendColor call would be

-- shader:sendColor('Color', {r, g, b, a})

-- Extern variables can be accessed in both the Vertex and Pixel stages of a shader, as long as the variable is declared in each.

-- In versions prior to 11.0, color component values were within the range of 0 to 255 instead of 0 to 1.

Signature:

sendColor: function(self: Shader, name: string, values: ShaderValue...)

Parameters:

Parameter	Type	Description
name	string	The name of the color extern variable to send to in the shader.
values	ShaderValue...	A table with red, green, blue, and optional alpha color components in the range of 1 to send to the extern as a vector.