diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index 2569f114f3a..3321bdaf4e6 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -2247,6 +2247,7 @@ Texture functions | | |gvec4_type| | | :ref:`texture`\ (\ |gsampler3D| s, vec3 p [, float bias] ) | | | | vec4 | | :ref:`texture`\ (\ samplerCube s, vec3 p [, float bias] ) | | | | vec4 | | :ref:`texture`\ (\ samplerCubeArray s, vec4 p [, float bias] ) | | + | | vec4 | | :ref:`texture`\ (\ samplerExternalOES s, vec2 p [, float bias] ) | | +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ | | |gvec4_type| | | :ref:`textureProj`\ (\ |gsampler2D| s, vec3 p [, float bias] ) | Perform a texture read with projection. | | | |gvec4_type| | | :ref:`textureProj`\ (\ |gsampler2D| s, vec4 p [, float bias] ) | | @@ -2505,6 +2506,10 @@ vec4 **texture**\ (\ samplerCube s, vec3 p [, float bias] ) vec4 **texture**\ (\ samplerCubeArray s, vec4 p [, float bias] ) +.. rst-class:: classref-method + +vec4 **texture**\ (\ samplerExternalOES s, vec2 p [, float bias] ) + Retrieves texels from a texture. Samples texels from the texture bound to ``s`` at texture coordinate ``p``. An optional bias, specified in ``bias`` is diff --git a/tutorials/shaders/shader_reference/shading_language.rst b/tutorials/shaders/shader_reference/shading_language.rst index c48e26f2004..d2a9e44cc73 100644 --- a/tutorials/shaders/shader_reference/shading_language.rst +++ b/tutorials/shaders/shader_reference/shading_language.rst @@ -19,72 +19,75 @@ Data types Most GLSL ES 3.0 datatypes are supported: -+----------------------+---------------------------------------------------------------------------------+ -| Type | Description | -+======================+=================================================================================+ -| **void** | Void datatype, useful only for functions that return nothing. | -+----------------------+---------------------------------------------------------------------------------+ -| **bool** | Boolean datatype, can only contain ``true`` or ``false``. | -+----------------------+---------------------------------------------------------------------------------+ -| **bvec2** | Two-component vector of booleans. | -+----------------------+---------------------------------------------------------------------------------+ -| **bvec3** | Three-component vector of booleans. | -+----------------------+---------------------------------------------------------------------------------+ -| **bvec4** | Four-component vector of booleans. | -+----------------------+---------------------------------------------------------------------------------+ -| **int** | 32 bit signed scalar integer. | -+----------------------+---------------------------------------------------------------------------------+ -| **ivec2** | Two-component vector of signed integers. | -+----------------------+---------------------------------------------------------------------------------+ -| **ivec3** | Three-component vector of signed integers. | -+----------------------+---------------------------------------------------------------------------------+ -| **ivec4** | Four-component vector of signed integers. | -+----------------------+---------------------------------------------------------------------------------+ -| **uint** | Unsigned scalar integer; can't contain negative numbers. | -+----------------------+---------------------------------------------------------------------------------+ -| **uvec2** | Two-component vector of unsigned integers. | -+----------------------+---------------------------------------------------------------------------------+ -| **uvec3** | Three-component vector of unsigned integers. | -+----------------------+---------------------------------------------------------------------------------+ -| **uvec4** | Four-component vector of unsigned integers. | -+----------------------+---------------------------------------------------------------------------------+ -| **float** | 32 bit floating-point scalar. | -+----------------------+---------------------------------------------------------------------------------+ -| **vec2** | Two-component vector of floating-point values. | -+----------------------+---------------------------------------------------------------------------------+ -| **vec3** | Three-component vector of floating-point values. | -+----------------------+---------------------------------------------------------------------------------+ -| **vec4** | Four-component vector of floating-point values. | -+----------------------+---------------------------------------------------------------------------------+ -| **mat2** | 2x2 matrix, in column major order. | -+----------------------+---------------------------------------------------------------------------------+ -| **mat3** | 3x3 matrix, in column major order. | -+----------------------+---------------------------------------------------------------------------------+ -| **mat4** | 4x4 matrix, in column major order. | -+----------------------+---------------------------------------------------------------------------------+ -| **sampler2D** | Sampler type for binding 2D textures, which are read as float. | -+----------------------+---------------------------------------------------------------------------------+ -| **isampler2D** | Sampler type for binding 2D textures, which are read as signed integer. | -+----------------------+---------------------------------------------------------------------------------+ -| **usampler2D** | Sampler type for binding 2D textures, which are read as unsigned integer. | -+----------------------+---------------------------------------------------------------------------------+ -| **sampler2DArray** | Sampler type for binding 2D texture arrays, which are read as float. | -+----------------------+---------------------------------------------------------------------------------+ -| **isampler2DArray** | Sampler type for binding 2D texture arrays, which are read as signed integer. | -+----------------------+---------------------------------------------------------------------------------+ -| **usampler2DArray** | Sampler type for binding 2D texture arrays, which are read as unsigned integer. | -+----------------------+---------------------------------------------------------------------------------+ -| **sampler3D** | Sampler type for binding 3D textures, which are read as float. | -+----------------------+---------------------------------------------------------------------------------+ -| **isampler3D** | Sampler type for binding 3D textures, which are read as signed integer. | -+----------------------+---------------------------------------------------------------------------------+ -| **usampler3D** | Sampler type for binding 3D textures, which are read as unsigned integer. | -+----------------------+---------------------------------------------------------------------------------+ -| **samplerCube** | Sampler type for binding Cubemaps, which are read as float. | -+----------------------+---------------------------------------------------------------------------------+ -| **samplerCubeArray** | Sampler type for binding Cubemap arrays, which are read as float. | -| | Only supported in Forward+ and Mobile, not Compatibility. | -+----------------------+---------------------------------------------------------------------------------+ ++------------------------+---------------------------------------------------------------------------------+ +| Type | Description | ++========================+=================================================================================+ +| **void** | Void datatype, useful only for functions that return nothing. | ++------------------------+---------------------------------------------------------------------------------+ +| **bool** | Boolean datatype, can only contain ``true`` or ``false``. | ++------------------------+---------------------------------------------------------------------------------+ +| **bvec2** | Two-component vector of booleans. | ++------------------------+---------------------------------------------------------------------------------+ +| **bvec3** | Three-component vector of booleans. | ++------------------------+---------------------------------------------------------------------------------+ +| **bvec4** | Four-component vector of booleans. | ++------------------------+---------------------------------------------------------------------------------+ +| **int** | 32 bit signed scalar integer. | ++------------------------+---------------------------------------------------------------------------------+ +| **ivec2** | Two-component vector of signed integers. | ++------------------------+---------------------------------------------------------------------------------+ +| **ivec3** | Three-component vector of signed integers. | ++------------------------+---------------------------------------------------------------------------------+ +| **ivec4** | Four-component vector of signed integers. | ++------------------------+---------------------------------------------------------------------------------+ +| **uint** | Unsigned scalar integer; can't contain negative numbers. | ++------------------------+---------------------------------------------------------------------------------+ +| **uvec2** | Two-component vector of unsigned integers. | ++------------------------+---------------------------------------------------------------------------------+ +| **uvec3** | Three-component vector of unsigned integers. | ++------------------------+---------------------------------------------------------------------------------+ +| **uvec4** | Four-component vector of unsigned integers. | ++------------------------+---------------------------------------------------------------------------------+ +| **float** | 32 bit floating-point scalar. | ++------------------------+---------------------------------------------------------------------------------+ +| **vec2** | Two-component vector of floating-point values. | ++------------------------+---------------------------------------------------------------------------------+ +| **vec3** | Three-component vector of floating-point values. | ++------------------------+---------------------------------------------------------------------------------+ +| **vec4** | Four-component vector of floating-point values. | ++------------------------+---------------------------------------------------------------------------------+ +| **mat2** | 2x2 matrix, in column major order. | ++------------------------+---------------------------------------------------------------------------------+ +| **mat3** | 3x3 matrix, in column major order. | ++------------------------+---------------------------------------------------------------------------------+ +| **mat4** | 4x4 matrix, in column major order. | ++------------------------+---------------------------------------------------------------------------------+ +| **sampler2D** | Sampler type for binding 2D textures, which are read as float. | ++------------------------+---------------------------------------------------------------------------------+ +| **isampler2D** | Sampler type for binding 2D textures, which are read as signed integer. | ++------------------------+---------------------------------------------------------------------------------+ +| **usampler2D** | Sampler type for binding 2D textures, which are read as unsigned integer. | ++------------------------+---------------------------------------------------------------------------------+ +| **sampler2DArray** | Sampler type for binding 2D texture arrays, which are read as float. | ++------------------------+---------------------------------------------------------------------------------+ +| **isampler2DArray** | Sampler type for binding 2D texture arrays, which are read as signed integer. | ++------------------------+---------------------------------------------------------------------------------+ +| **usampler2DArray** | Sampler type for binding 2D texture arrays, which are read as unsigned integer. | ++------------------------+---------------------------------------------------------------------------------+ +| **sampler3D** | Sampler type for binding 3D textures, which are read as float. | ++------------------------+---------------------------------------------------------------------------------+ +| **isampler3D** | Sampler type for binding 3D textures, which are read as signed integer. | ++------------------------+---------------------------------------------------------------------------------+ +| **usampler3D** | Sampler type for binding 3D textures, which are read as unsigned integer. | ++------------------------+---------------------------------------------------------------------------------+ +| **samplerCube** | Sampler type for binding Cubemaps, which are read as float. | ++------------------------+---------------------------------------------------------------------------------+ +| **samplerCubeArray** | Sampler type for binding Cubemap arrays, which are read as float. | +| | Only supported in Forward+ and Mobile, not Compatibility. | ++------------------------+---------------------------------------------------------------------------------+ +| **samplerExternalOES** | External sampler type. | +| | Only supported in Compatibility/Android platform. | ++------------------------+---------------------------------------------------------------------------------+ .. warning:: @@ -943,88 +946,90 @@ GDScript uses different variable types than GLSL does, so when passing variables from GDScript to shaders, Godot converts the type automatically. Below is a table of the corresponding types: -+----------------------+-------------------------+------------------------------------------------------------+ -| GLSL type | GDScript type | Notes | -+======================+=========================+============================================================+ -| **bool** | **bool** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **bvec2** | **int** | Bitwise packed int where bit 0 (LSB) corresponds to x. | -| | | | -| | | For example, a bvec2 of (bx, by) could be created in | -| | | the following way: | -| | | | -| | | .. code-block:: gdscript | -| | | | -| | | bvec2_input: int = (int(bx)) | (int(by) << 1) | -| | | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **bvec3** | **int** | Bitwise packed int where bit 0 (LSB) corresponds to x. | -+----------------------+-------------------------+------------------------------------------------------------+ -| **bvec4** | **int** | Bitwise packed int where bit 0 (LSB) corresponds to x. | -+----------------------+-------------------------+------------------------------------------------------------+ -| **int** | **int** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **ivec2** | **Vector2i** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **ivec3** | **Vector3i** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **ivec4** | **Vector4i** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **uint** | **int** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **uvec2** | **Vector2i** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **uvec3** | **Vector3i** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **uvec4** | **Vector4i** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **float** | **float** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **vec2** | **Vector2** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **vec3** | **Vector3**, **Color** | When Color is used, it will be interpreted as (r, g, b). | -+----------------------+-------------------------+------------------------------------------------------------+ -| **vec4** | **Vector4**, **Color**, | When Color is used, it will be interpreted as (r, g, b, a).| -| | **Rect2**, **Plane**, | | -| | **Quaternion** | When Rect2 is used, it will be interpreted as | -| | | (position.x, position.y, size.x, size.y). | -| | | | -| | | When Plane is used it will be interpreted as | -| | | (normal.x, normal.y, normal.z, d). | -| | | | -| | | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **mat2** | **Transform2D** | | -| | | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **mat3** | **Basis** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **mat4** | **Projection**, | When a Transform3D is used, the w Vector is set to the | -| | **Transform3D** | identity. | -+----------------------+-------------------------+------------------------------------------------------------+ -| **sampler2D** | **Texture2D** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **isampler2D** | **Texture2D** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **usampler2D** | **Texture2D** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **sampler2DArray** | **Texture2DArray** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **isampler2DArray** | **Texture2DArray** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **usampler2DArray** | **Texture2DArray** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **sampler3D** | **Texture3D** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **isampler3D** | **Texture3D** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **usampler3D** | **Texture3D** | | -+----------------------+-------------------------+------------------------------------------------------------+ -| **samplerCube** | **Cubemap** | See :ref:`doc_importing_images_changing_import_type` for | -| | | instructions on importing cubemaps for use in Godot. | -+----------------------+-------------------------+------------------------------------------------------------+ -| **samplerCubeArray** | **CubemapArray** | Only supported in Forward+ and Mobile, not Compatibility. | -+----------------------+-------------------------+------------------------------------------------------------+ ++------------------------+-------------------------+------------------------------------------------------------+ +| GLSL type | GDScript type | Notes | ++========================+=========================+============================================================+ +| **bool** | **bool** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **bvec2** | **int** | Bitwise packed int where bit 0 (LSB) corresponds to x. | +| | | | +| | | For example, a bvec2 of (bx, by) could be created in | +| | | the following way: | +| | | | +| | | .. code-block:: gdscript | +| | | | +| | | bvec2_input: int = (int(bx)) | (int(by) << 1) | +| | | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **bvec3** | **int** | Bitwise packed int where bit 0 (LSB) corresponds to x. | ++------------------------+-------------------------+------------------------------------------------------------+ +| **bvec4** | **int** | Bitwise packed int where bit 0 (LSB) corresponds to x. | ++------------------------+-------------------------+------------------------------------------------------------+ +| **int** | **int** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **ivec2** | **Vector2i** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **ivec3** | **Vector3i** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **ivec4** | **Vector4i** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **uint** | **int** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **uvec2** | **Vector2i** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **uvec3** | **Vector3i** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **uvec4** | **Vector4i** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **float** | **float** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **vec2** | **Vector2** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **vec3** | **Vector3**, **Color** | When Color is used, it will be interpreted as (r, g, b). | ++------------------------+-------------------------+------------------------------------------------------------+ +| **vec4** | **Vector4**, **Color**, | When Color is used, it will be interpreted as (r, g, b, a).| +| | **Rect2**, **Plane**, | | +| | **Quaternion** | When Rect2 is used, it will be interpreted as | +| | | (position.x, position.y, size.x, size.y). | +| | | | +| | | When Plane is used it will be interpreted as | +| | | (normal.x, normal.y, normal.z, d). | +| | | | +| | | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **mat2** | **Transform2D** | | +| | | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **mat3** | **Basis** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **mat4** | **Projection**, | When a Transform3D is used, the w Vector is set to the | +| | **Transform3D** | identity. | ++------------------------+-------------------------+------------------------------------------------------------+ +| **sampler2D** | **Texture2D** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **isampler2D** | **Texture2D** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **usampler2D** | **Texture2D** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **sampler2DArray** | **Texture2DArray** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **isampler2DArray** | **Texture2DArray** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **usampler2DArray** | **Texture2DArray** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **sampler3D** | **Texture3D** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **isampler3D** | **Texture3D** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **usampler3D** | **Texture3D** | | ++------------------------+-------------------------+------------------------------------------------------------+ +| **samplerCube** | **Cubemap** | See :ref:`doc_importing_images_changing_import_type` for | +| | | instructions on importing cubemaps for use in Godot. | ++------------------------+-------------------------+------------------------------------------------------------+ +| **samplerCubeArray** | **CubemapArray** | Only supported in Forward+ and Mobile, not Compatibility. | ++------------------------+-------------------------+------------------------------------------------------------+ +| **samplerExternalOES** | **ExternalTexture** | Only supported in Compatibility/Android platform. | ++------------------------+-------------------------+------------------------------------------------------------+ .. note:: Be careful when setting shader uniforms from GDScript, no error will be thrown if the type does not match. Your shader will just exhibit