| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| en:orx:config:settings_structure:orxshader [2013/05/02 17:14 (12 years ago)] – [Details] sergeig | en:orx:config:settings_structure:orxshader [2023/09/20 00:22 (19 months ago)] (current) – sausage |
|---|
| ===== orxSHADER structure ===== | ===== orxSHADER structure ===== |
| | |
| | Shader module. Allows the definition of shader information (code + parameters). |
| |
| ==== Summary ==== | ==== Summary ==== |
| // Do stuff | // Do stuff |
| }" | }" |
| KeepInCache = <bool> | CodeList = CodeKey1 # ... # CodeKeyN |
| ParamList = ParamFloat # ParamTexture # ParamVector | ParamList = Param1 # ... # ParamN |
| ParamFloat = <float> | ParamFloat = <float> |
| ParamVector = <vector> | ParamVector = <vector> |
| ParamTexture = path/to/TextureFile|screen | ParamTexture = path/to/texture |
| UseCustomParam = <bool></code> | UseCustomParam = <bool> |
| | KeepInCache = <bool> |
| | </code> |
| |
| |
| |
| Here's a list of the available properties for an ''orxSHADER'' structure: | Here's a list of the available properties for an ''orxSHADER'' structure: |
| * ''Code'': This block ((delimited by double quotes (") as seen in the [[en:orx:config:syntax|syntax page]])) contains the code that will be executed. It needs to be provided and be valid [[wp>glsl|GLSL]] fragment shader code. | * ''Code'': Used to declare a monolithic shader. Will be ignored if CodeList is defined. This block ((delimited by double quotes (") as seen in the [[en:orx:config:syntax|syntax page]])) contains the code that will be executed. It needs to be provided and be valid [[wp>glsl|GLSL]] fragment shader code. |
| | * ''CodeList'': The values of this list will be used as config keys from this section to reconstruct, in the given order, a multi-part shader. If not defined, Code will be used instead. |
| * ''KeepInCache'': Defines if the shader code should be kept in memory even if no shader of this type is currently in use. This saves time (reading from disk + compiling) but costs memory. Its default value is ''false''. | * ''KeepInCache'': Defines if the shader code should be kept in memory even if no shader of this type is currently in use. This saves time (reading from disk + compiling) but costs memory. Its default value is ''false''. |
| * ParamList: This defines the list of parameters needed and used by the shader's code. Every defined parameter must have a default value that will help orx guess their type. If none is provided, then its type will be assumed to be a texture. Available types are <float>, <vector> and texture (if a path to a texture file or the keyword ''screen'' is provided). If an invalid path is provided for a parameter, or the parameter isn't defined at all, the owner's texture will be used ((if the owner is a viewport, it will be its associated texture; if it's an object, it's current graphic/animation key's texture will be used)). **If an explicit list is provided for any parameter, the shader variable will be an array of this parameter type (instead of a regular variable) and its size will be the number of items in the list.** | * ParamList: Define all the parameters your shader code needs. Defined params then must have a default value to guess their type: textures, vectors and floats are supported. If none is provided, type defaults to texture and will use shader's owner texture as value. If an invalid path is provided for a parameter, or the parameter isn't defined at all, the owner's texture will be used ((if the owner is a viewport, it will be its associated texture; if it's an object, it's current graphic/animation key's texture will be used)). **If an explicit list is provided for any parameter, the shader variable will be an array of this parameter type (instead of a regular variable) and its size will be the number of items in the list.** |
| * ''UseCustomParam'': Defines if parameters can have their value overridden at runtime (ie. interactive). Its default value is ''false'' which means only the default values will be used. | * ''UseCustomParam'': When set to true, an event will be sent to override params values at runtime as well as the automated "time" value. Defaults to false, ie. no runtime override unless "time" is used for a float param. |
| |
| Here's a simple example of a non-interactive shader as seen in the [[en:orx:tutorials:spawner|spawner/shader tutorial]]. | Here's a simple example of a non-interactive shader as seen in the [[en:tutorials:spawners:spawner|spawner/shader tutorial]]. |
| |
| <code ini>[Decompose] | <code ini>[Decompose] |
| offset = (-0.05, -0.05, 0.0) ~ (0.05, 0.05, 0.0); <= Let's take some random offset</code> | offset = (-0.05, -0.05, 0.0) ~ (0.05, 0.05, 0.0); <= Let's take some random offset</code> |
| |
| Please see the [[en:orx:tutorials:spawner|spawner/shader tutorial]] for more information. | Please see the [[en:tutorials:main#spawners|Shader Tutorials]] and [[en:examples:shaders:main|Shader Examples]] for more information. |
| |
| === Overriding Parameters at Runtime with UseCustomParam === | === Overriding Parameters at Runtime with UseCustomParam === |
| is set in your shader. An event of type ''orxEVENT_TYPE_SHADER'' and ID ''orxSHADER_EVENT_SET_PARAM'' will be fired for all parameters and its payload will contain the name of the param and its default value. Event handler can then modify that value if need be, and it'll get used by the shader. | is set in your shader. An event of type ''orxEVENT_TYPE_SHADER'' and ID ''orxSHADER_EVENT_SET_PARAM'' will be fired for all parameters and its payload will contain the name of the param and its default value. Event handler can then modify that value if need be, and it'll get used by the shader. |
| |
| However, when UseCustomParam is defined, those objects can't be batched at rendering. So it might be a bit more expensive. The severity of the processing penalty depends on how many objects are in the scene. See test playgroung code, orxBounce, for an example on how to set those shader parameters on the fly. | However, when UseCustomParam is defined to true, those objects can't be batched at rendering, making the rendering phase more expensive. |
| | The severity of the processing penalty depends on how many affected objects are displayed. |
| | See the test/playground code, orxBounce, for an example on how to set those shader parameters on the fly. |
| |
| ==== Shader Execution Environment ==== | ==== Shader Execution Environment ==== |
| |
| === Specifying an Empty Texture === | === Using built-in 'time' keyword as parameter argument === |
| |
| There is an internal texture called ''pixel''. It can be used to specify an image of arbitrary size when used with the Scale key of the object: | "time" is a keyword recognized by orx: the parameter value will be the object's "age", in seconds. Example: |
| |
| <code> | <code ini> |
| [Object] | ParamList = fTime |
| Graphic = MyTexture | fTime = time |
| Scale = (16, 16, 1) | </code> |
| | |
| | === Using the internal 'pixel' texture === |
| | |
| | There is an internal texture called ''pixel''. It can be used to specify an image of arbitrary size when used with the Scale property of the object: |
| | |
| | <code ini> |
| | [Object] |
| | Graphic = MyTexture |
| | Scale = (16, 16, 1) |
| | |
| [MyTexture] | [MyTexture] |
| Texture = pixel | Texture = pixel |
| </code> | </code> |
| |
| In the example above an empty 16x16 pixels texture is created. | In the example above, an Object has a Graphic that will span over 16x16 pixels. |
| |
| This technique can be useful in some types of shaders. | |
| |
| === Coordinate System === | === Coordinate System === |
| |
| Shader receives original owner's texture coordinates. For example: | Shaders contain implicit parameters containing owner's texture coordinates. For example: |
| |
| <code ini> | <code ini> |
| [GameObject] | [GameObject] |
| Graphic = @ | Graphic = @ |
| Texture = ObjectTexture.png | Texture = ObjectTexture.png |
| TextureCorner = (16, 16, 0) | TextureOrigin = (16, 16, 0) |
| TextureSize = (8, 8, 0) | TextureSize = (8, 8, 0) |
| ShaderList = Shader | ShaderList = Shader |
| |
| [Shader] | [Shader] |
| ParamList = myTexture # ... | ParamList = MyTexture # ... |
| Code = ... | Code = ... |
| </code> | </code> |
| |
| Then orx will generate extra parameters behind the scene for the texture. The names follow the pattern: | Then orx will generate extra parameters behind the scene regarding the texture MyTexture. The names follow the pattern: |
| <code> | <code> |
| <NameOfYourTexture>_top, <NameOfYourTexture>_right, | <NameOfTexture>_top, <NameOfTexture>_left, |
| <NameOfYourTexture>_bottom, <NameOfYourTexture>_left | <NameOfTexture>_bottom, <NameOfTexture>_right |
| </code> | </code> |
| |
| In the example above the names will be: | In the above example, the names will then be: |
| <code> | <code> |
| myTexture_top, myTexture_right, myTexture_bottom, myTexture_left | MyTexture_top, MyTexture_left, MyTexture_bottom, MyTexture_right |
| </code> | </code> |
| |
| Let's say myTexture is 32x32, we'd then get: | If MyTexture's dimensions are 32x32, we'd then get: |
| <code> | <code> |
| myTexture_left = 16 out of 32 => 0.5 | MyTexture_top = 16 / 32 => 0.5 |
| myTexture_top = 32 - 16 out of 32 => 0.5 | MyTexture_left = 16 / 32 => 0.5 |
| myTexture_right = 16 + 8 out of 32 => 0.75 | MyTexture_bottom = (16 + 8) / 32 => 0.75 |
| myTexture_bottom = 32 - (16 + 8) out of 32 => 0.25 (it has been inverted for you as you can see, same for _top, but in this example it doesn't show) | MyTexture_right = (16 + 8) / 32 => 0.75 |
| </code> | </code> |
| | |
| | |
| | ==== Latest config settings for the Development Version ==== |
| | {{section>en:orx:config:developmentversion#&noheader&nofooter&noeditbutton}} |
| | |
