Difference between revisions of "Shader"

From GiderosMobile
(18 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
__NOTOC__
 
__NOTOC__
'''Supported platforms:''' <br/>
+
<!-- GIDEROSOBJ:Shader -->
 +
'''Supported platforms:''' [[File:Platform android.png]][[File:Platform ios.png]][[File:Platform mac.png]][[File:Platform pc.png]][[File:Platform html5.png]][[File:Platform winrt.png]][[File:Platform win32.png]]<br/>
 
'''Available since:''' Gideros 2015.06.30<br/>
 
'''Available since:''' Gideros 2015.06.30<br/>
 +
'''Inherits from:''' [[Object]]<br/>
 +
 
=== Description ===
 
=== Description ===
<translate>Gideros internally uses five distinct shaders:
+
Gideros internally uses five distinct shaders:
- the ‘Basic’ shader handle shapes with a constant color
+
*the ‘'''Basic'''’ shader handles shapes with a constant color
- the ‘Color’ shader handle shapes with per-vertex colors (mostly used by Mesh sprite)
+
*the ‘'''Color'''’ shader handles shapes with per-vertex colors (mostly used by Mesh sprite)
- the ‘Texture’ shader handle textured shapes (Bitmaps)
+
*the ‘'''Texture'''’ shader handles textured shapes (Bitmaps)
- the ‘TextureColor’ shader handle textured and per-vertex colored shapes
+
*the ‘'''TextureColor'''’ shader handles textured and per-vertex colored shapes
- and the ‘Particle’ shader deals with Box2D particle systems
+
*and the ‘'''Particle'''’ shader deals with Box2D particle systems
 +
 
 +
The shader API allows replacing the default shader used by Gideros with a custom one, on a sprite per sprite basis. As with most of Gideros API’s this one is [[Writing Shaders|straightforward]]: you create a Shader object and assign it to one or several sprites.
 +
 
 +
That said, since Gideros will use your shader as if it was the standard one, you will have to make sure that your custom shader is compatible with the standard one, which essentially means that it takes the same input parameters.
  
The new shader API allows to replace the default shader used by Gideros with a custom one, on a sprite per sprite basis. As with most of Gideros API’s this one is straight-forward: create a Shader object and assign it to one or several sprites.
+
You can also write your '''[[Lua Shaders|shader code in Lua]]''', it will then be automatically translated to the relevant shader language for the platform you are using, eg GLSL, HLSL or MTL. This is the recommended way.
  
That said, since Gideros will use your shader as if it was the standard one, you will have to make sure that your custom shader is compatible with the standard one, which essentially means that it takes the same input parameters.</translate>
+
=== Example ===
=== Examples ===
+
'''A blur shader'''
'''Shader example'''<br/>
+
<source lang="lua">
<source lang="lua">--Shaders are in vShader.glsl and fShader.glsl files
+
--Shaders are in vShader.glsl and fShader.glsl files
 +
local shader = Shader.new("vShader", "fShader", 0,
 +
{
 +
{name="vMatrix", type=Shader.CMATRIX, sys=Shader.SYS_WVP, vertex=true},
 +
{name="fColor", type=Shader.CFLOAT4, sys=Shader.SYS_COLOR, vertex=false},
 +
{name="fTexture", type=Shader.CTEXTURE, vertex=false},
 +
{name="fTexelSize", type=Shader.CFLOAT4, vertex=false},
 +
{name="fRad", type=Shader.CINT, vertex=false},
 +
},
 +
{
 +
{name="vVertex", type=Shader.DFLOAT, mult=3, slot=0, offset=0},
 +
{name="vColor", type=Shader.DUBYTE, mult=4, slot=1, offset=0},
 +
{name="vTexCoord", type=Shader.DFLOAT, mult=2, slot=2, offset=0},
 +
}
 +
);
  
local shader=Shader.new("vShader","fShader",0, {
+
shader:setConstant("fRad", Shader.CINT, 1, 0) -- initial blur level
{name="vMatrix",type=Shader.CMATRIX,sys=Shader.SYS_WVP,vertex=true},  
+
shader:setConstant("fTexelSize", Shader.CFLOAT4, 1, {1/texw, 1/texh, 0, 0}) -- initial texel size
{name="fColor",type=Shader.CFLOAT4,sys=Shader.SYS_COLOR,vertex=false},
 
{name="fTexture",type=Shader.CTEXTURE,vertex=false},
 
{name="fTexelSize",type=Shader.CFLOAT4,vertex=false},  
 
{name="fRad",type=Shader.CINT,vertex=false}, },
 
{ {name="vVertex",type=Shader.DFLOAT,mult=3,slot=0,offset=0},  
 
{name="vColor",type=Shader.DUBYTE,mult=4,slot=1,offset=0},  
 
{name="vTexCoord",type=Shader.DFLOAT,mult=2,slot=2,offset=0}, });
 
  
shader:setConstant("fRad",Shader.CINT,1,0) --Initial blur level
+
sprite:setShader(shader)
shader:setConstant("fTexelSize",Shader.CFLOAT4,1,{1/texw,1/texh,0,0}) --Initial texel size
+
</source>
  
sprite:setShader(shader)</source>
 
 
{|-
 
{|-
| style="width: 50%;"|
+
| style="width: 50%; vertical-align:top;"|
 
=== Methods ===
 
=== Methods ===
[[Shader.new]] - create new shader<br/>
+
[[Shader.new]] ''creates a new shader''<br/><!--GIDEROSMTD:Shader.new(vertex shader,fragment shader,flags,uniform descriptor,attribute descriptor) creates a new shader-->
[[Shader:getEngineVersion]] - get shader version<br/>
+
[[Shader.getEngineVersion]] ''gets the shader engine version''<br/><!--GIDEROSMTD:Shader.getEngineVersion() gets the shader engine version-->
[[Shader:getProperties]] - get graphics engine properties<br/>
+
[[Shader.getProperties]] ''gets the graphics engine properties''<br/><!--GIDEROSMTD:Shader.getProperties() gets the graphics engine properties-->
[[Shader:getShaderLanguage]] - Get shader language<br/>
+
[[Shader.getShaderLanguage]] ''gets the shader language''<br/><!--GIDEROSMTD:Shader.getShaderLanguage() gets the shader language-->
[[Shader:setConstant]] - change the value of a uniform<br/>
+
[[Shader:isValid]] ''check if this shader was compiled successfully''<br/><!--GIDEROSMTD:Shader:isValid() check if this shader was compiled successfully-->
| style="width: 50%;"|
+
[[Shader:setConstant]] ''changes the value of a uniform''<br/><!--GIDEROSMTD:Shader:setConstant(uniform name,data type,mult,data) changes the value of a uniform-->
 +
 
 +
| style="width: 50%; vertical-align:top;"|
 +
 
 
=== Events ===
 
=== Events ===
 
=== Constants ===
 
=== Constants ===
[[Shader.CFLOAT]]<br/>
+
[[Shader.CFLOAT]] ''a float value''<br/><!--GIDEROSCST:Shader.CFLOAT 1-->
[[Shader.CFLOAT4]]<br/>
+
[[Shader.CFLOAT2]] ''a vector of two floats''<br/><!--GIDEROSCST:Shader.CFLOAT2 2-->
[[Shader.CINT]]<br/>
+
[[Shader.CFLOAT3]] ''a vector of three floats''<br/><!--GIDEROSCST:Shader.CFLOAT3 3-->
[[Shader.CMATRIX]]<br/>
+
[[Shader.CFLOAT4]] ''a vector of four floats''<br/><!--GIDEROSCST:Shader.CFLOAT4 4-->
[[Shader.CTEXTURE]]<br/>
+
[[Shader.CINT]] ''an integer value''<br/><!--GIDEROSCST:Shader.CINT 0-->
[[Shader.DBYTE]]<br/>
+
[[Shader.CMATRIX]] ''a 4x4 float matrix''<br/><!--GIDEROSCST:Shader.CMATRIX 5-->
[[Shader.DFLOAT]]<br/>
+
[[Shader.CTEXTURE]] ''a texture''<br/><!--GIDEROSCST:Shader.CTEXTURE 6-->
[[Shader.DINT]]<br/>
+
[[Shader.DBYTE]]<br/><!--GIDEROSCST:Shader.DBYTE 0-->
[[Shader.DSHORT]]<br/>
+
[[Shader.DFLOAT]]<br/><!--GIDEROSCST:Shader.DFLOAT 5-->
[[Shader.DUBYTE]]<br/>
+
[[Shader.DINT]]<br/><!--GIDEROSCST:Shader.DINT 4-->
[[Shader.DUSHORT]]<br/>
+
[[Shader.DSHORT]]<br/><!--GIDEROSCST:Shader.DSHORT 2-->
[[Shader.FLAG_FROM_CODE]]<br/>
+
[[Shader.DUBYTE]]<br/><!--GIDEROSCST:Shader.DUBYTE 1-->
[[Shader.FLAG_NONE]]<br/>
+
[[Shader.DUSHORT]]<br/><!--GIDEROSCST:Shader.DUSHORT 3-->
[[Shader.FLAG_NO_DEFAULT_HEADER]]<br/>
+
[[Shader.FLAG_FROM_CODE]]<br/><!--GIDEROSCST:Shader.FLAG_FROM_CODE 4-->
[[Shader.SYS_COLOR]]<br/>
+
[[Shader.FLAG_NONE]]<br/><!--GIDEROSCST:Shader.FLAG_NONE 0-->
[[Shader.SYS_NONE]]<br/>
+
[[Shader.FLAG_NO_DEFAULT_HEADER]]<br/><!--GIDEROSCST:Shader.FLAG_NO_DEFAULT_HEADER 1-->
[[Shader.SYS_PARTICLESIZE]]<br/>
+
[[Shader.SHADER_PROGRAM_UNSPECIFIED]] ''Indeterminate program''<br/><!--GIDEROSCST:Shader.SHADER_PROGRAM_UNSPECIFIED 0-->
[[Shader.SYS_TEXTUREINFO]]<br/>
+
[[Shader.SHADER_PROGRAM_BASIC]] ''Render a plain color shape''<br/><!--GIDEROSCST:Shader.SHADER_PROGRAM_BASIC 1-->
[[Shader.SYS_WIT]]<br/>
+
[[Shader.SHADER_PROGRAM_COLOR]] ''Render a colored shape''<br/><!--GIDEROSCST:Shader.SHADER_PROGRAM_COLOR 2-->
[[Shader.SYS_WORLD]]<br/>
+
[[Shader.SHADER_PROGRAM_TEXTURE]] ''Render a textured shape''<br/><!--GIDEROSCST:Shader.SHADER_PROGRAM_TEXTURE 3-->
[[Shader.SYS_WVP]]<br/>
+
[[Shader.SHADER_PROGRAM_TEXTUREALPHA]] ''Render shape with an alpha texture''<br/><!--GIDEROSCST:Shader.SHADER_PROGRAM_TEXTUREALPHA 4-->
 +
[[Shader.SHADER_PROGRAM_TEXTURECOLOR]] ''Render a colored and textured shape''<br/><!--GIDEROSCST:Shader.SHADER_PROGRAM_TEXTURECOLOR 5-->
 +
[[Shader.SHADER_PROGRAM_TEXTUREALPHACOLOR]] ''Render a colored shape with an alpha texture''<br/><!--GIDEROSCST:Shader.SHADER_PROGRAM_TEXTUREALPHACOLOR 6-->
 +
[[Shader.SHADER_PROGRAM_PARTICLE]] ''Used by liquidfun particles''<br/><!--GIDEROSCST:Shader.SHADER_PROGRAM_PARTICLE 7-->
 +
[[Shader.SHADER_PROGRAM_PARTICLES]] ''Used by [[Particles]]''<br/><!--GIDEROSCST:Shader.SHADER_PROGRAM_PARTICLES 8-->
 +
[[Shader.SHADER_PROGRAM_PATHFILLCURVE]] ''Used by [[Path2D]] to fill a curve''<br/><!--GIDEROSCST:Shader.SHADER_PROGRAM_PATHFILLCURVE 9-->
 +
[[Shader.SHADER_PROGRAM_PATHSTROKECURVE]] ''Used by [[Path2D]] to draw a curve''<br/><!--GIDEROSCST:Shader.SHADER_PROGRAM_PATHSTROKECURVE 10-->
 +
[[Shader.SHADER_PROGRAM_PATHSTROKELINE]] ''Used by [[Path2D]] to draw a segment''<br/><!--GIDEROSCST:Shader.SHADER_PROGRAM_PATHSTROKELINE 11-->
 +
[[Shader.SHADER_VARIANT_TEXTURED]] ''A textured variant of a standard program''<br/><!--GIDEROSCST:Shader.SHADER_VARIANT_TEXTURED 1-->
 +
[[Shader.SHADER_VARIANT_3D]] ''A 3D variant of a standard program''<br/><!--GIDEROSCST:Shader.SHADER_VARIANT_3D 2-->
 +
[[Shader.SYS_COLOR]] ''The current color (CFLOAT4)''<br/><!--GIDEROSCST:Shader.SYS_COLOR 2-->
 +
[[Shader.SYS_NONE]] ''Not filled by Gideros''<br/><!--GIDEROSCST:Shader.SYS_NONE 0-->
 +
[[Shader.SYS_PARTICLESIZE]] ''The particle size''<br/><!--GIDEROSCST:Shader.SYS_PARTICLESIZE 6-->
 +
[[Shader.SYS_PROJECTION]] ''The projection matrix (CMATRIX)''<br/><!--GIDEROSCST:Shader.SYS_PROJECTION 10-->
 +
[[Shader.SYS_TEXTUREINFO]] ''Real extent and texel size of the texture (CFLOAT4)''<br/><!--GIDEROSCST:Shader.SYS_TEXTUREINFO 5-->
 +
[[Shader.SYS_TIMER]] ''Current time (CFLOAT)''<br/><!--GIDEROSCST:Shader.SYS_TIMER 9-->
 +
[[Shader.SYS_VIEW]] ''The view matrix (CMATRIX)''<br/><!--GIDEROSCST:Shader.SYS_VIEW 8-->
 +
[[Shader.SYS_VP]] ''Combined view/projection matrix (CMATRIX)''<br/><!--GIDEROSCST:Shader.SYS_VP 11-->
 +
[[Shader.SYS_WIT]] ''The World Inverse Transpose matrix (CMATRIX)''<br/><!--GIDEROSCST:Shader.SYS_WIT 7-->
 +
[[Shader.SYS_WIT3]] ''3x3 World Inverse Transpose matrix''<br/><!--GIDEROSCST:Shader.SYS_WIT3 3-->
 +
[[Shader.SYS_WORLD]] ''The world or matrix (CMATRIX)''<br/><!--GIDEROSCST:Shader.SYS_WORLD 4-->
 +
[[Shader.SYS_WVP]] ''The combined world/view/projection matrix (CMATRIX)''<br/><!--GIDEROSCST:Shader.SYS_WVP 1-->
 
|}
 
|}
 +
 +
{{GIDEROS IMPORTANT LINKS}}

Revision as of 08:42, 18 December 2020

Supported platforms: Platform android.pngPlatform ios.pngPlatform mac.pngPlatform pc.pngPlatform html5.pngPlatform winrt.pngPlatform win32.png
Available since: Gideros 2015.06.30
Inherits from: Object

Description

Gideros internally uses five distinct shaders:

  • the ‘Basic’ shader handles shapes with a constant color
  • the ‘Color’ shader handles shapes with per-vertex colors (mostly used by Mesh sprite)
  • the ‘Texture’ shader handles textured shapes (Bitmaps)
  • the ‘TextureColor’ shader handles textured and per-vertex colored shapes
  • and the ‘Particle’ shader deals with Box2D particle systems

The shader API allows replacing the default shader used by Gideros with a custom one, on a sprite per sprite basis. As with most of Gideros API’s this one is straightforward: you create a Shader object and assign it to one or several sprites.

That said, since Gideros will use your shader as if it was the standard one, you will have to make sure that your custom shader is compatible with the standard one, which essentially means that it takes the same input parameters.

You can also write your shader code in Lua, it will then be automatically translated to the relevant shader language for the platform you are using, eg GLSL, HLSL or MTL. This is the recommended way.

Example

A blur shader

--Shaders are in vShader.glsl and fShader.glsl files
local shader = Shader.new("vShader", "fShader", 0,
	{
		{name="vMatrix", type=Shader.CMATRIX, sys=Shader.SYS_WVP, vertex=true},
		{name="fColor", type=Shader.CFLOAT4, sys=Shader.SYS_COLOR, vertex=false},
		{name="fTexture", type=Shader.CTEXTURE, vertex=false},
		{name="fTexelSize", type=Shader.CFLOAT4, vertex=false},
		{name="fRad", type=Shader.CINT, vertex=false},
	},
	{
		{name="vVertex", type=Shader.DFLOAT, mult=3, slot=0, offset=0},
		{name="vColor", type=Shader.DUBYTE, mult=4, slot=1, offset=0},
		{name="vTexCoord", type=Shader.DFLOAT, mult=2, slot=2, offset=0},
	}
);

shader:setConstant("fRad", Shader.CINT, 1, 0) -- initial blur level
shader:setConstant("fTexelSize", Shader.CFLOAT4, 1, {1/texw, 1/texh, 0, 0}) -- initial texel size

sprite:setShader(shader)

Methods

Shader.new creates a new shader
Shader.getEngineVersion gets the shader engine version
Shader.getProperties gets the graphics engine properties
Shader.getShaderLanguage gets the shader language
Shader:isValid check if this shader was compiled successfully
Shader:setConstant changes the value of a uniform

Events

Constants

Shader.CFLOAT a float value
Shader.CFLOAT2 a vector of two floats
Shader.CFLOAT3 a vector of three floats
Shader.CFLOAT4 a vector of four floats
Shader.CINT an integer value
Shader.CMATRIX a 4x4 float matrix
Shader.CTEXTURE a texture
Shader.DBYTE
Shader.DFLOAT
Shader.DINT
Shader.DSHORT
Shader.DUBYTE
Shader.DUSHORT
Shader.FLAG_FROM_CODE
Shader.FLAG_NONE
Shader.FLAG_NO_DEFAULT_HEADER
Shader.SHADER_PROGRAM_UNSPECIFIED Indeterminate program
Shader.SHADER_PROGRAM_BASIC Render a plain color shape
Shader.SHADER_PROGRAM_COLOR Render a colored shape
Shader.SHADER_PROGRAM_TEXTURE Render a textured shape
Shader.SHADER_PROGRAM_TEXTUREALPHA Render shape with an alpha texture
Shader.SHADER_PROGRAM_TEXTURECOLOR Render a colored and textured shape
Shader.SHADER_PROGRAM_TEXTUREALPHACOLOR Render a colored shape with an alpha texture
Shader.SHADER_PROGRAM_PARTICLE Used by liquidfun particles
Shader.SHADER_PROGRAM_PARTICLES Used by Particles
Shader.SHADER_PROGRAM_PATHFILLCURVE Used by Path2D to fill a curve
Shader.SHADER_PROGRAM_PATHSTROKECURVE Used by Path2D to draw a curve
Shader.SHADER_PROGRAM_PATHSTROKELINE Used by Path2D to draw a segment
Shader.SHADER_VARIANT_TEXTURED A textured variant of a standard program
Shader.SHADER_VARIANT_3D A 3D variant of a standard program
Shader.SYS_COLOR The current color (CFLOAT4)
Shader.SYS_NONE Not filled by Gideros
Shader.SYS_PARTICLESIZE The particle size
Shader.SYS_PROJECTION The projection matrix (CMATRIX)
Shader.SYS_TEXTUREINFO Real extent and texel size of the texture (CFLOAT4)
Shader.SYS_TIMER Current time (CFLOAT)
Shader.SYS_VIEW The view matrix (CMATRIX)
Shader.SYS_VP Combined view/projection matrix (CMATRIX)
Shader.SYS_WIT The World Inverse Transpose matrix (CMATRIX)
Shader.SYS_WIT3 3x3 World Inverse Transpose matrix
Shader.SYS_WORLD The world or matrix (CMATRIX)
Shader.SYS_WVP The combined world/view/projection matrix (CMATRIX)