Difference between revisions of "Shader:send"

m
 
(17 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
{{newin|[[0.9.0]]|090|type=function|text=It has been renamed from [[PixelEffect:send]]}}
 
{{newin|[[0.9.0]]|090|type=function|text=It has been renamed from [[PixelEffect:send]]}}
Sends one or more values to a special (''extern'') variable inside the shader. Extern variables have to be marked using the ''extern'' keyword, e.g.
+
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.
  
 
<source lang="glsl">
 
<source lang="glsl">
extern number time;
+
uniform float time;  // "float" is the typical number type used in GLSL shaders.
extern vec2 light_pos;
+
uniform float vars[2];
extern vec4 colors[4];
+
uniform vec2 light_pos;
 +
uniform vec4 colors[4];
 
</source>
 
</source>
  
Line 12: Line 13:
 
<source lang="lua">
 
<source lang="lua">
 
shader:send("time", t)
 
shader:send("time", t)
 +
shader:send("vars",a,b)
 
shader:send("light_pos", {light_x, light_y})
 
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})
 
shader:send("colors", {r1, g1, b1, a1},  {r2, g2, b2, a2},  {r3, g3, b3, a3},  {r4, g4, b4, a4})
Line 17: Line 19:
  
  
Extern variables can be accessed in both the Vertex and Pixel components of a shader, as long as the variable is declared in each.
+
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.
 +
 
 +
{{notice|There is a bug in version [[0.10.2]] which causes Shader:send to ignore the last argument when sending arrays. A simple workaround is to add an extra dummy argument when sending multiple values to a uniform array.}}
  
 
== Function ==
 
== Function ==
Line 26: Line 30:
 
=== Arguments ===
 
=== Arguments ===
 
{{param|string|name|Name of the number to send to the shader.}}
 
{{param|string|name|Name of the number to send to the shader.}}
{{param|number|number|Number to send to store in the extern.}}
+
{{param|number|number|Number to send to store in the uniform variable.}}
{{param|number|...|Additional numbers to send in case the extern is an array.}}
+
{{param|number|...|Additional numbers to send if the uniform variable is an array.}}
 
=== Returns ===
 
=== Returns ===
 
Nothing.
 
Nothing.
 +
=== Notes ===
 +
Because all numbers in Lua are floating point, in versions prior to [[0.10.2]] you must use the function [[Shader:sendInt]] to send values to <code>uniform int</code> variables in the shader's code.
  
 
== Function ==
 
== Function ==
Line 38: Line 44:
 
=== Arguments ===
 
=== Arguments ===
 
{{param|string|name|Name of the vector to send to the shader.}}
 
{{param|string|name|Name of the vector to send to the shader.}}
{{param|table|vector|Numbers to send to the extern as a vector. The number of elements in the table determines the type of the vector (e.g. two numbers -> vec2). At least two and at most four numbers can be used.}}
+
{{param|table|vector|Numbers to send to the uniform variable as a vector. The number of elements in the table determines the type of the vector (e.g. two numbers -> vec2). At least two and at most four numbers can be used.}}
{{param|table|...|Additional vectors to send in case the extern is an array. All vectors need to be of the same size (e.g. only vec3's)}}
+
{{param|table|...|Additional vectors to send if the uniform variable is an array. All vectors need to be of the same size (e.g. only vec3's).}}
 +
 
 
=== Returns ===
 
=== Returns ===
 
Nothing.
 
Nothing.
Line 50: Line 57:
 
=== Arguments ===
 
=== Arguments ===
 
{{param|string|name|Name of the matrix to send to the shader.}}
 
{{param|string|name|Name of the matrix to send to the shader.}}
{{param|table|matrix|2x2, 3x3, or 4x4 matrix to send to the extern. Using table form: <code><nowiki>{{a,b,c,d}, {e,f,g,h}, ... }</nowiki></code>}}
+
{{param|table|matrix|2x2, 3x3, or 4x4 matrix to send to the uniform variable. Using table form: <code><nowiki>{{a,b,c,d}, {e,f,g,h}, ... }</nowiki></code> or (since version [[0.10.2]]) <code>{a,b,c,d, e,f,g,h, ...}</code>. The order in 0.10.2 is column-major; starting in [[11.0]] it's row-major instead.}}
{{param|table|...|Additional matrices of the same type as ''matrix'' to store in the extern array.}}
+
{{param|table|...|Additional matrices of the same type as ''matrix'' to store in a uniform array.}}
 +
 
 
=== Returns ===
 
=== Returns ===
 
Nothing.
 
Nothing.
Line 58: Line 66:
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
Shader:send( name, image, ... )
+
Shader:send( name, texture )
 
</source>
 
</source>
 
=== Arguments ===
 
=== Arguments ===
{{param|string|name|Name of the Image to send to the shader.}}
+
{{param|string|name|Name of the [[Texture]] to send to the shader.}}
{{param|Image|image|Image to send to the extern.}}
+
{{param|Texture|texture|Texture ([[Image]] or [[Canvas]]) to send to the uniform variable.}}
{{param|Image|...|Additional images in case the extern is an array.}}
 
 
=== Returns ===
 
=== Returns ===
 
Nothing.
 
Nothing.
Line 70: Line 77:
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
Shader:send( name, canvas, ... )
+
Shader:send( name, boolean, ... )
 
</source>
 
</source>
 
=== Arguments ===
 
=== Arguments ===
{{param|string|name|Name of the Canvas to send to the shader.}}
+
{{param|string|name|Name of the boolean to send to the shader.}}
{{param|Canvas|canvas|Canvas to send to the extern. The shader extern type is ''Image''.}}
+
{{param|boolean|boolean|Boolean to send to store in the uniform variable.}}
{{param|Canvas|...|Additional canvases to send to the extern array.}}
+
{{param|boolean|...|Additional booleans to send if the uniform variable is an array.}}
 
=== Returns ===
 
=== Returns ===
 
Nothing.
 
Nothing.
  
 
== Function ==
 
== Function ==
 +
{{newin|[[11.0]]|110|type=variant}}
 +
=== Synopsis ===
 +
<source lang="lua">
 +
Shader:send( name, matrixlayout, matrix, ... )
 +
</source>
 +
=== Arguments ===
 +
{{param|string|name|Name of the matrix to send to the shader.}}
 +
{{param|MatrixLayout|matrixlayout|The layout (row- or column-major) of the matrix.}}
 +
{{param|table|matrix|2x2, 3x3, or 4x4 matrix to send to the uniform variable. Using table form: <code><nowiki>{{a,b,c,d}, {e,f,g,h}, ... }</nowiki></code> or <code>{a,b,c,d, e,f,g,h, ...}</code>.}}
 +
{{param|table|...|Additional matrices of the same type as ''matrix'' to store in a uniform array.}}
 +
 +
== Function ==
 +
{{newin|[[11.0]]|110|type=variant}}
 +
Sends uniform values to the Shader sourced from the contents of a [[Data]] object. This directly copies the bytes of the data.
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
Shader:send( name, boolean, ... )
+
Shader:send( name, data, offset, size )
 +
</source>
 +
=== Arguments ===
 +
{{param|string|name|Name of the uniform to send to the shader.}}
 +
{{param|Data|data|Data object containing the values to send.}}
 +
{{param|number|offset (0)|Offset in bytes from the start of the Data object.}}
 +
{{param|number|size (all)|Size in bytes of the data to send. If nil, as many bytes as the specified uniform uses will be copied.}}
 +
=== Returns ===
 +
Nothing.
 +
 
 +
== Function ==
 +
{{newin|[[11.0]]|110|type=variant}}
 +
Sends uniform matrices to the Shader sourced from the contents of a [[Data]] object. This directly copies the bytes of the data.
 +
=== Synopsis ===
 +
<source lang="lua">
 +
Shader:send( name, data, matrixlayout, offset, size )
 
</source>
 
</source>
 
=== Arguments ===
 
=== Arguments ===
{{param|string|name|Name of the boolean to send to the shader.}}
+
{{param|string|name|Name of the uniform matrix to send to the shader.}}
{{param|boolean|boolean|Boolean to send to store in the extern.}}
+
{{param|Data|data|Data object containing the values to send.}}
{{param|boolean|...|Additional booleans to send in case the extern is an array.}}
+
{{param|MatrixLayout|matrixlayout|The layout (row- or column-major) of the matrix in memory.}}
 +
{{param|number|offset (0)|Offset in bytes from the start of the Data object.}}
 +
{{param|number|size (all)|Size in bytes of the data to send. If nil, as many bytes as the specified uniform uses will be copied.}}
 
=== Returns ===
 
=== Returns ===
 
Nothing.
 
Nothing.
Line 95: Line 133:
 
[[Category:Functions]]
 
[[Category:Functions]]
 
{{#set:Description=Sends one or more values to the shader.}}
 
{{#set:Description=Sends one or more values to the shader.}}
 +
 
== Other Languages ==
 
== Other Languages ==
 
{{i18n|Shader:send}}
 
{{i18n|Shader:send}}

Latest revision as of 02:37, 5 April 2018

Available since LÖVE 0.9.0
It has been renamed from PixelEffect:send.

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 vars[2];
uniform vec2 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.

O.png There is a bug in version 0.10.2 which causes Shader:send to ignore the last argument when sending arrays. A simple workaround is to add an extra dummy argument when sending multiple values to a uniform array.  


Function

Synopsis

Shader:send( name, number, ... )

Arguments

string name
Name of the number to send to the shader.
number number
Number to send to store in the uniform variable.
number ...
Additional numbers to send if the uniform variable is an array.

Returns

Nothing.

Notes

Because all numbers in Lua are floating point, in versions prior to 0.10.2 you must use the function Shader:sendInt to send values to uniform int variables in the shader's code.

Function

Synopsis

Shader:send( name, vector, ... )

Arguments

string name
Name of the vector to send to the shader.
table vector
Numbers to send to the uniform variable as a vector. The number of elements in the table determines the type of the vector (e.g. two numbers -> vec2). At least two and at most four numbers can be used.
table ...
Additional vectors to send if the uniform variable is an array. All vectors need to be of the same size (e.g. only vec3's).

Returns

Nothing.

Function

Synopsis

Shader:send( name, matrix, ... )

Arguments

string name
Name of the matrix to send to the shader.
table matrix
2x2, 3x3, or 4x4 matrix to send to the uniform variable. Using table form: {{a,b,c,d}, {e,f,g,h}, ... } or (since version 0.10.2) {a,b,c,d, e,f,g,h, ...}. The order in 0.10.2 is column-major; starting in 11.0 it's row-major instead.
table ...
Additional matrices of the same type as matrix to store in a uniform array.

Returns

Nothing.

Function

Synopsis

Shader:send( name, texture )

Arguments

string name
Name of the Texture to send to the shader.
Texture texture
Texture (Image or Canvas) to send to the uniform variable.

Returns

Nothing.

Function

Synopsis

Shader:send( name, boolean, ... )

Arguments

string name
Name of the boolean to send to the shader.
boolean boolean
Boolean to send to store in the uniform variable.
boolean ...
Additional booleans to send if the uniform variable is an array.

Returns

Nothing.

Function

Available since LÖVE 11.0
This variant is not supported in earlier versions.

Synopsis

Shader:send( name, matrixlayout, matrix, ... )

Arguments

string name
Name of the matrix to send to the shader.
MatrixLayout matrixlayout
The layout (row- or column-major) of the matrix.
table matrix
2x2, 3x3, or 4x4 matrix to send to the uniform variable. Using table form: {{a,b,c,d}, {e,f,g,h}, ... } or {a,b,c,d, e,f,g,h, ...}.
table ...
Additional matrices of the same type as matrix to store in a uniform array.

Function

Available since LÖVE 11.0
This variant is not supported in earlier versions.

Sends uniform values to the Shader sourced from the contents of a Data object. This directly copies the bytes of the data.

Synopsis

Shader:send( name, data, offset, size )

Arguments

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

Returns

Nothing.

Function

Available since LÖVE 11.0
This variant is not supported in earlier versions.

Sends uniform matrices to the Shader sourced from the contents of a Data object. This directly copies the bytes of the data.

Synopsis

Shader:send( name, data, matrixlayout, offset, size )

Arguments

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

Returns

Nothing.

See Also


Other Languages