canvas_item_shader.rst 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289
  1. .. _doc_canvas_item_shader:
  2. CanvasItem shaders
  3. ==================
  4. CanvasItem shaders are used to draw all 2D elements in Godot. These include
  5. all nodes that inherit from CanvasItems, and all GUI elements.
  6. CanvasItem shaders contain less built-in variables and functionality than Spatial
  7. shaders, but they maintain the same basic structure with vertex, fragment, and
  8. light processor functions.
  9. Render modes
  10. ^^^^^^^^^^^^
  11. +---------------------------------+----------------------------------------------------------------------+
  12. | Render mode | Description |
  13. +=================================+======================================================================+
  14. | **blend_mix** | Mix blend mode (alpha is transparency), default. |
  15. +---------------------------------+----------------------------------------------------------------------+
  16. | **blend_add** | Additive blend mode. |
  17. +---------------------------------+----------------------------------------------------------------------+
  18. | **blend_sub** | Subtractive blend mode. |
  19. +---------------------------------+----------------------------------------------------------------------+
  20. | **blend_mul** | Multiplicative blend mode. |
  21. +---------------------------------+----------------------------------------------------------------------+
  22. | **blend_premul_alpha** | Pre-multiplied alpha blend mode. |
  23. +---------------------------------+----------------------------------------------------------------------+
  24. | **blend_disabled** | Disable blending, values (including alpha) are written as-is. |
  25. +---------------------------------+----------------------------------------------------------------------+
  26. | **unshaded** | Result is just albedo. No lighting/shading happens in material. |
  27. +---------------------------------+----------------------------------------------------------------------+
  28. | **light_only** | Only draw on light pass. |
  29. +---------------------------------+----------------------------------------------------------------------+
  30. | **skip_vertex_transform** | VERTEX/NORMAL/etc need to be transformed manually in vertex function.|
  31. +---------------------------------+----------------------------------------------------------------------+
  32. Built-ins
  33. ^^^^^^^^^
  34. Values marked as "in" are read-only. Values marked as "out" are for optional writing and will
  35. not necessarily contain sensible values. Values marked as "inout" provide a sensible default
  36. value, and can optionally be written to. Samplers are not subjects of writing and they are
  37. not marked.
  38. Global built-ins
  39. ^^^^^^^^^^^^^^^^
  40. Global built-ins are available everywhere, including custom functions.
  41. +-------------------+----------------------------------------------------------------------------------------+
  42. | Built-in | Description |
  43. +===================+========================================================================================+
  44. | in float **TIME** | Global time since the engine has started, in seconds (always positive). |
  45. | | It's subject to the rollover setting (which is 3,600 seconds by default). |
  46. | | It's not affected by :ref:`time_scale<class_Engine_property_time_scale>` |
  47. | | or pausing, but you can define a global shader uniform to add a "scaled" |
  48. | | ``TIME`` variable if desired. |
  49. +-------------------+----------------------------------------------------------------------------------------+
  50. | in float **PI** | A ``PI`` constant (``3.141592``). |
  51. | | A ration of circle's circumference to its diameter and amount of radians in half turn. |
  52. +-------------------+----------------------------------------------------------------------------------------+
  53. | in float **TAU** | A ``TAU`` constant (``6.283185``). |
  54. | | An equivalent of ``PI * 2`` and amount of radians in full turn. |
  55. +-------------------+----------------------------------------------------------------------------------------+
  56. | in float **E** | A ``E`` constant (``2.718281``). |
  57. | | Euler's number and a base of the natural logarithm. |
  58. +-------------------+----------------------------------------------------------------------------------------+
  59. Vertex built-ins
  60. ^^^^^^^^^^^^^^^^
  61. Vertex data (``VERTEX``) is presented in local space (pixel coordinates, relative to the Node2D's origin).
  62. If not written to, these values will not be modified and be passed through as they came.
  63. The user can disable the built-in model to world transform (world to screen and projection will still
  64. happen later) and do it manually with the following code:
  65. .. code-block:: glsl
  66. shader_type canvas_item;
  67. render_mode skip_vertex_transform;
  68. void vertex() {
  69. VERTEX = (MODEL_MATRIX * vec4(VERTEX, 0.0, 1.0)).xy;
  70. }
  71. Other built-ins, such as UV and COLOR, are also passed through to the fragment function if not modified.
  72. For instancing, the INSTANCE_CUSTOM variable contains the instance custom data. When using particles, this information
  73. is usually:
  74. * **x**: Rotation angle in radians.
  75. * **y**: Phase during lifetime (0 to 1).
  76. * **z**: Animation frame.
  77. +--------------------------------+----------------------------------------------------+
  78. | Built-in | Description |
  79. +================================+====================================================+
  80. | in mat4 **MODEL_MATRIX** | Local space to world space transform. World space |
  81. | | is the coordinates you normally use in the editor. |
  82. +--------------------------------+----------------------------------------------------+
  83. | in mat4 **CANVAS_MATRIX** | World space to canvas space transform. In canvas |
  84. | | space the origin is the upper-left corner of the |
  85. | | screen and coordinates ranging from (0, 0) to |
  86. | | viewport size. |
  87. +--------------------------------+----------------------------------------------------+
  88. | in mat4 **SCREEN_MATRIX** | Canvas space to clip space. In clip space |
  89. | | coordinates ranging from (-1, -1) to (1, 1). |
  90. +--------------------------------+----------------------------------------------------+
  91. | in vec4 **INSTANCE_CUSTOM** | Instance custom data. |
  92. +--------------------------------+----------------------------------------------------+
  93. | in bool **AT_LIGHT_PASS** | Always ``false``. |
  94. +--------------------------------+----------------------------------------------------+
  95. | in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of default 2D texture. |
  96. | | For a Sprite2D with a texture of size 64x32px, |
  97. | | **TEXTURE_PIXEL_SIZE** = :code:`vec2(1/64, 1/32)` |
  98. +--------------------------------+----------------------------------------------------+
  99. | inout vec2 **VERTEX** | Vertex, in image space. |
  100. +--------------------------------+----------------------------------------------------+
  101. | inout vec2 **UV** | Normalized texture coordinates. Range from 0 to 1. |
  102. +--------------------------------+----------------------------------------------------+
  103. | inout vec4 **COLOR** | Color from vertex primitive. |
  104. +--------------------------------+----------------------------------------------------+
  105. | inout float **POINT_SIZE** | Point size for point drawing. |
  106. +--------------------------------+----------------------------------------------------+
  107. Fragment built-ins
  108. ^^^^^^^^^^^^^^^^^^
  109. Certain Nodes (for example, :ref:`Sprite2Ds <class_Sprite2D>`) display a texture by default. However,
  110. when a custom fragment function is attached to these nodes, the texture lookup needs to be done
  111. manually. Godot does not provide the texture color in the ``COLOR`` built-in variable; to read
  112. the texture color for such nodes, use:
  113. .. code-block:: glsl
  114. COLOR = texture(TEXTURE, UV);
  115. This differs from the behavior of the built-in normal map. If a normal map is attached, Godot uses
  116. it by default and assigns its value to the built-in ``NORMAL`` variable. If you are using a normal
  117. map meant for use in 3D, it will appear inverted. In order to use it in your shader, you must assign
  118. it to the ``NORMALMAP`` property. Godot will handle converting it for use in 2D and overwriting ``NORMAL``.
  119. .. code-block:: glsl
  120. NORMALMAP = texture(NORMAL_TEXTURE, UV).rgb;
  121. +---------------------------------------------+---------------------------------------------------------------+
  122. | Built-in | Description |
  123. +=============================================+===============================================================+
  124. | in vec4 **FRAGCOORD** | Coordinate of pixel center. In screen space. ``xy`` specifies |
  125. | | position in window, ``z`` specifies fragment depth if |
  126. | | ``DEPTH`` is not used. Origin is lower-left. |
  127. +---------------------------------------------+---------------------------------------------------------------+
  128. | in vec2 **SCREEN_PIXEL_SIZE** | Size of individual pixels. Equal to inverse of resolution. |
  129. +---------------------------------------------+---------------------------------------------------------------+
  130. | in vec2 **POINT_COORD** | Coordinate for drawing points. |
  131. +---------------------------------------------+---------------------------------------------------------------+
  132. | sampler2D **TEXTURE** | Default 2D texture. |
  133. +---------------------------------------------+---------------------------------------------------------------+
  134. | in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of default 2D texture. |
  135. | | For a Sprite2D with a texture of size 64x32px, |
  136. | | **TEXTURE_PIXEL_SIZE** = :code:`vec2(1/64, 1/32)` |
  137. +---------------------------------------------+---------------------------------------------------------------+
  138. | in bool **AT_LIGHT_PASS** | Always ``false``. |
  139. +---------------------------------------------+---------------------------------------------------------------+
  140. | sampler2D **SPECULAR_SHININESS_TEXTURE** | Specular shininess texture of this object. |
  141. +---------------------------------------------+---------------------------------------------------------------+
  142. | in vec4 **SPECULAR_SHININESS** | Specular shininess color, as sampled from the texture. |
  143. +---------------------------------------------+---------------------------------------------------------------+
  144. | in vec2 **UV** | UV from vertex function. |
  145. +---------------------------------------------+---------------------------------------------------------------+
  146. | in vec2 **SCREEN_UV** | Screen UV coordinate for current pixel. |
  147. +---------------------------------------------+---------------------------------------------------------------+
  148. | sampler2D **SCREEN_TEXTURE** | Removed in Godot 4. Use a ``sampler2D`` with |
  149. | | ``hint_screen_texture`` instead. |
  150. +---------------------------------------------+---------------------------------------------------------------+
  151. | inout vec3 **NORMAL** | Normal read from **NORMAL_TEXTURE**. Writable. |
  152. +---------------------------------------------+---------------------------------------------------------------+
  153. | sampler2D **NORMAL_TEXTURE** | Default 2D normal texture. |
  154. +---------------------------------------------+---------------------------------------------------------------+
  155. | out vec3 **NORMAL_MAP** | Configures normal maps meant for 3D for use in 2D. If used, |
  156. | | overrides **NORMAL**. |
  157. +---------------------------------------------+---------------------------------------------------------------+
  158. | out float **NORMAL_MAP_DEPTH** | Normalmap depth for scaling. |
  159. +---------------------------------------------+---------------------------------------------------------------+
  160. | inout vec2 **VERTEX** | Pixel position in screen space. |
  161. +---------------------------------------------+---------------------------------------------------------------+
  162. | inout vec2 **SHADOW_VERTEX** | Same as ``VERTEX`` but can be written to alter shadows. |
  163. +---------------------------------------------+---------------------------------------------------------------+
  164. | inout vec3 **LIGHT_VERTEX** | Same as ``VERTEX`` but can be written to alter lighting. |
  165. | | Z component represents height. |
  166. +---------------------------------------------+---------------------------------------------------------------+
  167. | inout vec4 **COLOR** | Color from vertex function and output fragment color. If |
  168. | | unused, will be set to **TEXTURE** color. |
  169. +---------------------------------------------+---------------------------------------------------------------+
  170. Light built-ins
  171. ^^^^^^^^^^^^^^^
  172. Light processor functions work differently in Godot 4.x than they did in Godot
  173. 3.x. In Godot 4.x all lighting is done during the regular draw pass. In other
  174. words, Godot no longer draws the object again for each light.
  175. Use render_mode ``unshaded`` if you do not want the light processor function to
  176. run. Use render_mode ``light_only`` if you only want to see the impact of
  177. lighting on an object; this can be useful when you only want the object visible
  178. where it is covered by light.
  179. Below is an example of a light shader that takes a CanvasItem's normal map into account:
  180. .. code-block:: glsl
  181. void light() {
  182. float cNdotL = max(0.0, dot(NORMAL, LIGHT_DIRECTION));
  183. LIGHT = vec4(LIGHT_COLOR.rgb * COLOR.rgb * LIGHT_ENERGY * cNdotL, LIGHT_COLOR.a);
  184. }
  185. +----------------------------------+------------------------------------------------------------------------------+
  186. | Built-in | Description |
  187. +==================================+==============================================================================+
  188. | in vec4 **FRAGCOORD** | Coordinate of pixel center. In screen space. ``xy`` specifies |
  189. | | position in window, ``z`` specifies fragment depth if |
  190. | | ``DEPTH`` is not used. Origin is lower-left. |
  191. +----------------------------------+------------------------------------------------------------------------------+
  192. | in vec3 **NORMAL** | Input Normal. |
  193. +----------------------------------+------------------------------------------------------------------------------+
  194. | in vec4 **COLOR** | Input Color. |
  195. | | This is the output of the fragment function with final modulation applied. |
  196. +----------------------------------+------------------------------------------------------------------------------+
  197. | in vec2 **UV** | UV from vertex function, equivalent to the UV in the fragment function. |
  198. +----------------------------------+------------------------------------------------------------------------------+
  199. | sampler2D **TEXTURE** | Current texture in use for CanvasItem. |
  200. +----------------------------------+------------------------------------------------------------------------------+
  201. | in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of default 2D texture. |
  202. | | For a Sprite2D with a texture of size 64x32px, |
  203. | | **TEXTURE_PIXEL_SIZE** = :code:`vec2(1/64, 1/32)` |
  204. +----------------------------------+------------------------------------------------------------------------------+
  205. | in vec2 **SCREEN_UV** | Screen UV coordinate for current pixel. |
  206. +----------------------------------+------------------------------------------------------------------------------+
  207. | in vec2 **POINT_COORD** | UV for Point Sprite. |
  208. +----------------------------------+------------------------------------------------------------------------------+
  209. | in vec4 **LIGHT_COLOR** | Color of Light. |
  210. +----------------------------------+------------------------------------------------------------------------------+
  211. | in float **LIGHT_ENERGY** | Energy multiplier of Light. |
  212. +----------------------------------+------------------------------------------------------------------------------+
  213. | in vec3 **LIGHT_POSITION** | Position of Light in screen space. If using a ``DirectionalLight2D`` |
  214. | | this is always ``vec3(0,0,0)``. |
  215. +----------------------------------+------------------------------------------------------------------------------+
  216. | in vec3 **LIGHT_DIRECTION** | Direction of Light in screen space. |
  217. +----------------------------------+------------------------------------------------------------------------------+
  218. | in bool **LIGHT_IS_DIRECTIONAL** | ``true`` if this pass is a ``DirectionalLight2D``. |
  219. +----------------------------------+------------------------------------------------------------------------------+
  220. | in vec3 **LIGHT_VERTEX** | Pixel position, in screen space as modified in the fragment function. |
  221. +----------------------------------+------------------------------------------------------------------------------+
  222. | inout vec4 **LIGHT** | Value from the Light texture and output color. Can be modified. If not used, |
  223. | | the light function is ignored. |
  224. +----------------------------------+------------------------------------------------------------------------------+
  225. | in vec4 **SPECULAR_SHININESS** | Specular shininess, as set in the object's texture. |
  226. +----------------------------------+------------------------------------------------------------------------------+
  227. | out vec4 **SHADOW_MODULATE** | Multiply shadows cast at this point by this color. |
  228. +----------------------------------+------------------------------------------------------------------------------+
  229. SDF functions
  230. ^^^^^^^^^^^^^
  231. There are a few additional functions implemented to sample an automatically
  232. generated Signed Distance Field texture. These functions available for Fragment
  233. and Light functions of CanvasItem shaders.
  234. The signed distance field is generated from :ref:`class_LightOccluder2D` nodes
  235. present in the scene with the **SDF Collision** property enabled (which is the
  236. default). See the :ref:`2D lights and shadows <doc_2d_lights_and_shadows_setting_up_shadows>`
  237. documentation for more information.
  238. +-----------------------------------------------+----------------------------------------+
  239. | Function | Description |
  240. +===============================================+========================================+
  241. | float **texture_sdf** (vec2 sdf_pos) | Performs an SDF texture lookup. |
  242. +-----------------------------------------------+----------------------------------------+
  243. | vec2 **texture_sdf_normal** (vec2 sdf_pos) | Performs an SDF normal texture lookup. |
  244. +-----------------------------------------------+----------------------------------------+
  245. | vec2 **sdf_to_screen_uv** (vec2 sdf_pos) | Converts a SDF to screen UV. |
  246. +-----------------------------------------------+----------------------------------------+
  247. | vec2 **screen_uv_to_sdf** (vec2 uv) | Converts screen UV to a SDF. |
  248. +-----------------------------------------------+----------------------------------------+