From 5cf349d535dee2887a9bba52cbb1ab9876dd1433 Mon Sep 17 00:00:00 2001 From: clayjohn Date: Sun, 3 Apr 2022 22:04:07 -0700 Subject: [PATCH 01/25] Initial test of new shader function style --- .../shader_reference/shading_language.rst | 1208 +++++++++++++---- 1 file changed, 909 insertions(+), 299 deletions(-) diff --git a/tutorials/shaders/shader_reference/shading_language.rst b/tutorials/shaders/shader_reference/shading_language.rst index c32e5ee0c6a..ef6f23fc5be 100644 --- a/tutorials/shaders/shader_reference/shading_language.rst +++ b/tutorials/shaders/shader_reference/shading_language.rst @@ -818,314 +818,924 @@ Uniforms can also be assigned default values: Built-in variables ------------------ -A large number of built-in variables are available, like ``UV``, ``COLOR`` and ``VERTEX``. What variables are available depends on the type of shader (``spatial``, ``canvas_item`` or ``particle``) and the function used (``vertex``, ``fragment`` or ``light``). -For a list of the built-in variables that are available, please see the corresponding pages: +A large number of built-in variables are available, like ``UV``, ``COLOR`` and +``VERTEX``. What variables are available depends on the type of shader +(``spatial``, ``canvas_item``, ``particle``, ``sky``, or ``fog``) and the +function used (``vertex``, ``fragment``, ``light``, ``start``, ``process, +``sky``, or ``fog``). For a list of the built-in variables that are available, +please see the corresponding pages: - :ref:`Spatial shaders ` - :ref:`Canvas item shaders ` - :ref:`Particle shaders ` +- :ref:`Sky shaders ` +- :ref:`Fog shaders ` Built-in functions ------------------ -A large number of built-in functions are supported, conforming to GLSL ES 3.0. -When vec_type (float), vec_int_type, vec_uint_type, vec_bool_type nomenclature -is used, it can be scalar or vector. +Godot supports a large number of built-in functions, conforming roughly to the +GLSL 4.00 specification. -.. note:: For a list of the functions that are not available in the GLES2 +When vec_type, ivec_type, uvec_type, or bvec_type nomenclature is used, the type +can be scalar or vector. For example vec_type can be float, vec2, vec3, or vec4. + +.. note:: For a list of the functions that are not available in the OpenGL backend, please see the :ref:`Differences between GLES2 and GLES3 doc `. -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| Function | Description / Return value | -+===========================================================================+=====================================================================+ -| vec_type **radians** (vec_type degrees) | Convert degrees to radians. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **degrees** (vec_type radians) | Convert radians to degrees. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **sin** (vec_type x) | Sine. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **cos** (vec_type x) | Cosine. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **tan** (vec_type x) | Tangent. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **asin** (vec_type x) | Arcsine. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **acos** (vec_type x) | Arccosine. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **atan** (vec_type y_over_x) | Arctangent. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **atan** (vec_type y, vec_type x) | Arctangent. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **sinh** (vec_type x) | Hyperbolic sine. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **cosh** (vec_type x) | Hyperbolic cosine. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **tanh** (vec_type x) | Hyperbolic tangent. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **asinh** (vec_type x) | Inverse hyperbolic sine. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **acosh** (vec_type x) | Inverse hyperbolic cosine. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **atanh** (vec_type x) | Inverse hyperbolic tangent. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **pow** (vec_type x, vec_type y) | Power (undefined if ``x`` < 0 or if ``x`` == 0 and ``y`` <= 0). | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **exp** (vec_type x) | Base-e exponential. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **exp2** (vec_type x) | Base-2 exponential. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **log** (vec_type x) | Natural logarithm. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **log2** (vec_type x) | Base-2 logarithm. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **sqrt** (vec_type x) | Square root. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **inversesqrt** (vec_type x) | Inverse square root. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **abs** (vec_type x) | Absolute value (returns positive value if negative). | -| | | -| ivec_type **abs** (ivec_type x) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **sign** (vec_type x) | Sign (returns ``1.0`` if positive, ``-1.0`` if negative, | -| | ``0.0`` if zero). | -| ivec_type **sign** (ivec_type x) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **floor** (vec_type x) | Round to the integer below. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **round** (vec_type x) | Round to the nearest integer. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **roundEven** (vec_type x) | Round to the nearest even integer. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **trunc** (vec_type x) | Truncation. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **ceil** (vec_type x) | Round to the integer above. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **fract** (vec_type x) | Fractional (returns ``x - floor(x)``). | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **mod** (vec_type x, vec_type y) | Modulo (division remainder). | -| | | -| vec_type **mod** (vec_type x, float y) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **modf** (vec_type x, out vec_type i) | Fractional of ``x``, with ``i`` as integer part. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **min** (vec_type a, vec_type b) | Lowest value between ``a`` and ``b``. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **max** (vec_type a, vec_type b) | Highest value between ``a`` and ``b``. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **clamp** (vec_type x, vec_type min, vec_type max) | Clamp ``x`` between ``min`` and ``max`` (inclusive). | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| float **mix** (float a, float b, float c) | Linear interpolate between ``a`` and ``b`` by ``c``. | -| | | -| vec_type **mix** (vec_type a, vec_type b, float c) | | -| | | -| vec_type **mix** (vec_type a, vec_type b, bvec_type c) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **fma** (vec_type a, vec_type b, vec_type c) | Performs a fused multiply-add operation: ``(a * b + c)`` | -| | (faster than doing it manually). | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **step** (vec_type a, vec_type b) | ``b[i] < a[i] ? 0.0 : 1.0``. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **step** (float a, vec_type b) | ``b[i] < a ? 0.0 : 1.0``. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **smoothstep** (vec_type a, vec_type b, vec_type c) | Hermite interpolate between ``a`` and ``b`` by ``c``. | -| | | -| vec_type **smoothstep** (float a, float b, vec_type c) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bvec_type **isnan** (vec_type x) | Returns ``true`` if scalar or vector component is ``NaN``. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bvec_type **isinf** (vec_type x) | Returns ``true`` if scalar or vector component is ``INF``. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec_type **floatBitsToInt** (vec_type x) | Float->Int bit copying, no conversion. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| uvec_type **floatBitsToUint** (vec_type x) | Float->UInt bit copying, no conversion. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **intBitsToFloat** (ivec_type x) | Int->Float bit copying, no conversion. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **uintBitsToFloat** (uvec_type x) | UInt->Float bit copying, no conversion. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| float **length** (vec_type x) | Vector length. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| float **distance** (vec_type a, vec_type b) | Distance between vectors i.e ``length(a - b)``. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| float **dot** (vec_type a, vec_type b) | Dot product. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec3 **cross** (vec3 a, vec3 b) | Cross product. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **normalize** (vec_type x) | Normalize to unit length. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec3 **reflect** (vec3 I, vec3 N) | Reflect. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec3 **refract** (vec3 I, vec3 N, float eta) | Refract. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **faceforward** (vec_type N, vec_type I, vec_type Nref) | If ``dot(Nref, I)`` < 0, return N, otherwise –N. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| mat_type **matrixCompMult** (mat_type x, mat_type y) | Matrix component multiplication. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| mat_type **outerProduct** (vec_type column, vec_type row) | Matrix outer product. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| mat_type **transpose** (mat_type m) | Transpose matrix. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| float **determinant** (mat_type m) | Matrix determinant. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| mat_type **inverse** (mat_type m) | Inverse matrix. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bvec_type **lessThan** (vec_type x, vec_type y) | Bool vector comparison on < int/uint/float vectors. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bvec_type **greaterThan** (vec_type x, vec_type y) | Bool vector comparison on > int/uint/float vectors. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bvec_type **lessThanEqual** (vec_type x, vec_type y) | Bool vector comparison on <= int/uint/float vectors. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bvec_type **greaterThanEqual** (vec_type x, vec_type y) | Bool vector comparison on >= int/uint/float vectors. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bvec_type **equal** (vec_type x, vec_type y) | Bool vector comparison on == int/uint/float vectors. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bvec_type **notEqual** (vec_type x, vec_type y) | Bool vector comparison on != int/uint/float vectors. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bool **any** (bvec_type x) | ``true`` if any component is ``true``, ``false`` otherwise. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bool **all** (bvec_type x) | ``true`` if all components are ``true``, ``false`` otherwise. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bvec_type **not** (bvec_type x) | Invert boolean vector. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec2 **textureSize** (gsampler2D s, int lod) | Get the size of a texture. | -| | | -| ivec3 **textureSize** (gsampler2DArray s, int lod) | | -| | | -| ivec3 **textureSize** (gsampler3D s, int lod) | | -| | | -| ivec2 **textureSize** (samplerCube s, int lod) | | -| | | -| ivec2 **textureSize** (samplerCubeArray s, int lod) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| gvec4_type **texture** (gsampler2D s, vec2 p [, float bias]) | Perform a texture read. | -| | | -| gvec4_type **texture** (gsampler2DArray s, vec3 p [, float bias]) | | -| | | -| gvec4_type **texture** (gsampler3D s, vec3 p [, float bias]) | | -| | | -| vec4 **texture** (samplerCube s, vec3 p [, float bias]) | | -| | | -| vec4 **texture** (samplerCubeArray s, vec4 p [, float bias]) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| gvec4_type **textureProj** (gsampler2D s, vec3 p [, float bias]) | Perform a texture read with projection. | -| | | -| gvec4_type **textureProj** (gsampler2D s, vec4 p [, float bias]) | | -| | | -| gvec4_type **textureProj** (gsampler3D s, vec4 p [, float bias]) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| gvec4_type **textureLod** (gsampler2D s, vec2 p, float lod) | Perform a texture read at custom mipmap. | -| | | -| gvec4_type **textureLod** (gsampler2DArray s, vec3 p, float lod) | | -| | | -| gvec4_type **textureLod** (gsampler3D s, vec3 p, float lod) | | -| | | -| vec4 **textureLod** (samplerCube s, vec3 p, float lod) | | -| | | -| vec4 **textureLod** (samplerCubeArray s, vec4 p, float lod) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| gvec4_type **textureProjLod** (gsampler2D s, vec3 p, float lod) | Performs a texture read with projection/LOD. | -| | | -| gvec4_type **textureProjLod** (gsampler2D s, vec4 p, float lod) | | -| | | -| gvec4_type **textureProjLod** (gsampler3D s, vec4 p, float lod) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| gvec4_type **textureGrad** (gsampler2D s, vec2 p, vec2 dPdx, | Performs a texture read with explicit gradients. | -| vec2 dPdy) | | -| | | -| gvec4_type **textureGrad** (gsampler2DArray s, vec3 p, vec2 dPdx, | | -| vec2 dPdy) | | -| | | -| gvec4_type **textureGrad** (gsampler3D s, vec3 p, vec2 dPdx, | | -| vec2 dPdy) | | -| | | -| vec4 **textureGrad** (samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy) | | -| | | -| vec4 **textureGrad** (samplerCubeArray s, vec3 p, vec3 dPdx, | | -| vec3 dPdy) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| gvec4_type **texelFetch** (gsampler2D s, ivec2 p, int lod) | Fetches a single texel using integer coordinates. | -| | | -| gvec4_type **texelFetch** (gsampler2DArray s, ivec3 p, int lod) | | -| | | -| gvec4_type **texelFetch** (gsampler3D s, ivec3 p, int lod) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| gvec4_type **textureGather** (gsampler2D s, vec2 p [, int comps]) | Gathers four texels from a texture. | -| | Use ``comps`` within range of 0..3 to | -| gvec4_type **textureGather** (gsampler2DArray s, vec3 p [, int comps]) | define which component (x, y, z, w) is returned. | -| | If ``comps`` is not provided: 0 (or x-component) is used. | -| vec4 **textureGather** (samplerCube s, vec3 p [, int comps]) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **dFdx** (vec_type p) | Derivative in ``x`` using local differencing. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **dFdy** (vec_type p) | Derivative in ``y`` using local differencing. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **fwidth** (vec_type p) | Sum of absolute derivative in ``x`` and ``y``. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| uint **packHalf2x16** (vec2 v) | Convert two 32-bit floating-point numbers into 16-bit | -| | and pack them into a 32-bit unsigned integer and vice-versa. | -| vec2 **unpackHalf2x16** (uint v) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| uint **packUnorm2x16** (vec2 v) | Convert two 32-bit floating-point numbers (clamped | -| | within 0..1 range) into 16-bit and pack them | -| vec2 **unpackUnorm2x16** (uint v) | into a 32-bit unsigned integer and vice-versa. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| uint **packSnorm2x16** (vec2 v) | Convert two 32-bit floating-point numbers (clamped | -| | within -1..1 range) into 16-bit and pack them | -| vec2 **unpackSnorm2x16** (uint v) | into a 32-bit unsigned integer and vice-versa. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| uint **packUnorm4x8** (vec4 v) | Convert four 32-bit floating-point numbers (clamped | -| | within 0..1 range) into 8-bit and pack them | -| vec4 **unpackUnorm4x8** (uint v) | into a 32-bit unsigned integer and vice-versa. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| uint **packSnorm4x8** (vec4 v) | Convert four 32-bit floating-point numbers (clamped | -| | within -1..1 range) into 8-bit and pack them | -| vec4 **unpackSnorm4x8** (uint v) | into a 32-bit unsigned integer and vice-versa. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec_type **bitfieldExtract** (ivec_type value, int offset, int bits) | Extracts a range of bits from an integer. | -| | | -| uvec_type **bitfieldExtract** (uvec_type value, int offset, int bits) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec_type **bitfieldInsert** (ivec_type base, ivec_type insert, | Insert a range of bits into an integer. | -| int offset, int bits) | | -| | | -| uvec_type **bitfieldInsert** (uvec_type base, uvec_type insert, | | -| int offset, int bits) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec_type **bitfieldReverse** (ivec_type value) | Reverse the order of bits in an integer. | -| | | -| uvec_type **bitfieldReverse** (uvec_type value) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec_type **bitCount** (ivec_type value) | Counts the number of 1 bits in an integer. | -| | | -| uvec_type **bitCount** (uvec_type value) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec_type **findLSB** (ivec_type value) | Find the index of the least significant bit set to 1 in an integer. | -| | | -| uvec_type **findLSB** (uvec_type value) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec_type **findMSB** (ivec_type value) | Find the index of the most significant bit set to 1 in an integer. | -| | | -| uvec_type **findMSB** (uvec_type value) | | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| void **imulExtended** (ivec_type x, ivec_type y, out ivec_type msb, | Adds two 32-bit numbers and produce a 64-bit result. | -| out ivec_type lsb) | ``x`` - the first number. | -| | ``y`` - the second number. | -| void **umulExtended** (uvec_type x, uvec_type y, out uvec_type msb, | ``msb`` - will contain the most significant bits. | -| out uvec_type lsb) | ``lsb`` - will contain the least significant bits. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| uvec_type **uaddCarry** (uvec_type x, uvec_type y, out uvec_type carry) | Adds two unsigned integers and generates carry. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| uvec_type **usubBorrow** (uvec_type x, uvec_type y, out uvec_type borrow) | Subtracts two unsigned integers and generates borrow. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **ldexp** (vec_type x, out ivec_type exp) | Assemble a floating-point number from a value and exponent. | -| | | -| | If this product is too large to be represented in the | -| | floating-point type the result is undefined. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type **frexp** (vec_type x, out ivec_type exp) | Splits a floating-point number(``x``) into significand | -| | (in the range of [0.5, 1.0]) and an integral exponent. | -| | | -| | For ``x`` equals zero the significand and exponent are both zero. | -| | For ``x`` of infinity or NaN, the results are undefined. | -+---------------------------------------------------------------------------+---------------------------------------------------------------------+ ++-------------+---------------------------------------------------------------------------------------------------------+ +| Return Type | Function | ++=============+=========================================================================================================+ +| vec_type | :js:attr:`radians ` (vec_type degrees) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`degrees ` (vec_type radians) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`sin ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`cos ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`tan ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`asin ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`acos ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`atan ` (vec_type y_over_x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`atan ` (vec_type y, vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`sinh ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`cosh ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`tanh ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`asinh ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`acosh ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`atanh ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`pow ` (vec_type x, vec_type y) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`exp ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`exp2 ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`log ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`log2 ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`sqrt ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`inversesqrt ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`abs ` (vec_type x) | +| | | +| ivec_type | :js:attr:`abs ` (ivec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`sign ` (vec_type x) | +| | | +| ivec_type | :js:attr:`sign ` (ivec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`floor ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`round ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`roundEven ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`trunc ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`ceil ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`fract ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`mod ` (vec_type x, vec_type y) | +| | | +| vec_type | :js:attr:`mod ` (vec_type x, float y) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`modf ` (vec_type x, out vec_type i) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`min ` (vec_type a, vec_type b) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`max ` (vec_type a, vec_type b) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`clamp ` (vec_type x, vec_type min, vec_type max) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| float | :js:attr:`mix ` (float a, float b, float c) | +| | | +| vec_type | :js:attr:`mix ` (vec_type a, vec_type b, float c) | +| | | +| vec_type | :js:attr:`mix ` (vec_type a, vec_type b, bvec_type c) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`fma ` (vec_type a, vec_type b, vec_type c) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`step ` (vec_type a, vec_type b) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`step ` (float a, vec_type b) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`smoothstep ` (vec_type a, vec_type b, vec_type c) | +| | | +| vec_type | :js:attr:`smoothstep ` (float a, float b, vec_type c) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| bvec_type | :js:attr:`isnan ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| bvec_type | :js:attr:`isinf ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| ivec_type | :js:attr:`floatBitsToInt ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| uvec_type | :js:attr:`floatBitsToUint ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`intBitsToFloat ` (ivec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`uintBitsToFloat ` (uvec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| float | :js:attr:`length ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| float | :js:attr:`distance ` (vec_type a, vec_type b) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| float | :js:attr:`dot ` (vec_type a, vec_type b) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec3 | :js:attr:`cross ` (vec3 a, vec3 b) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`normalize ` (vec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec3 | :js:attr:`reflect ` (vec3 I, vec3 N) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec3 | :js:attr:`refract ` (vec3 I, vec3 N, float eta) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`faceforward ` (vec_type N, vec_type I, vec_type Nref) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| mat_type | :js:attr:`matrixCompMult ` (mat_type x, mat_type y) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| mat_type | :js:attr:`outerProduct ` (vec_type column, vec_type row) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| mat_type | :js:attr:`transpose ` (mat_type m) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| float | :js:attr:`determinant ` (mat_type m) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| mat_type | :js:attr:`inverse ` (mat_type m) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| bvec_type | :js:attr:`lessThan ` (vec_type x, vec_type y) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| bvec_type | :js:attr:`greaterThan ` (vec_type x, vec_type y) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| bvec_type | :js:attr:`lessThanEqual ` (vec_type x, vec_type y) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| bvec_type | :js:attr:`greaterThanEqual ` (vec_type x, vec_type y) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| bvec_type | :js:attr:`equal ` (vec_type x, vec_type y) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| bvec_type | :js:attr:`notEqual ` (vec_type x, vec_type y) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| bool | :js:attr:`any ` (bvec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| bool | :js:attr:`all ` (bvec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| bvec_type | :js:attr:`not ` (bvec_type x) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| ivec2 | :js:attr:`textureSize ` (gsampler2D s, int lod) | +| | | +| ivec3 | :js:attr:`textureSize ` (gsampler2DArray s, int lod) | +| | | +| ivec3 | :js:attr:`textureSize ` (gsampler3D s, int lod) | +| | | +| ivec2 | :js:attr:`textureSize ` (samplerCube s, int lod) | +| | | +| ivec2 | :js:attr:`textureSize ` (samplerCubeArray s, int lod) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| gvec4_type | :js:attr:`texture ` (gsampler2D s, vec2 p [, float bias]) | +| | | +| gvec4_type | :js:attr:`texture ` (gsampler2DArray s, vec3 p [, float bias]) | +| | | +| gvec4_type | :js:attr:`texture ` (gsampler3D s, vec3 p [, float bias]) | +| | | +| vec4 | :js:attr:`texture ` (samplerCube s, vec3 p [, float bias]) | +| | | +| vec4 | :js:attr:`texture ` (samplerCubeArray s, vec4 p [, float bias]) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| gvec4_type | :js:attr:`textureProj ` (gsampler2D s, vec3 p [, float bias]) | +| | | +| gvec4_type | :js:attr:`textureProj ` (gsampler2D s, vec4 p [, float bias]) | +| | | +| gvec4_type | :js:attr:`textureProj ` (gsampler3D s, vec4 p [, float bias]) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| gvec4_type | :js:attr:`textureLod ` (gsampler2D s, vec2 p, float lod) | +| | | +| gvec4_type | :js:attr:`textureLod ` (gsampler2DArray s, vec3 p, float lod) | +| | | +| gvec4_type | :js:attr:`textureLod ` (gsampler3D s, vec3 p, float lod) | +| | | +| vec4 | :js:attr:`textureLod ` (samplerCube s, vec3 p, float lod) | +| | | +| vec4 | :js:attr:`textureLod ` (samplerCubeArray s, vec4 p, float lod) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| gvec4_type | :js:attr:`textureProjLod ` (gsampler2D s, vec3 p, float lod) | +| | | +| gvec4_type | :js:attr:`textureProjLod ` (gsampler2D s, vec4 p, float lod) | +| | | +| gvec4_type | :js:attr:`textureProjLod ` (gsampler3D s, vec4 p, float lod) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| gvec4_type | :js:attr:`textureGrad ` (gsampler2D s, vec2 p, vec2 dPdx, vec2 dPdy) | +| | | +| gvec4_type | :js:attr:`textureGrad ` (gsampler2DArray s, vec3 p, vec2 dPdx, vec2 dPdy) | +| | | +| gvec4_type | :js:attr:`textureGrad ` (gsampler3D s, vec3 p, vec2 dPdx, vec2 dPdy) | +| | | +| vec4 | :js:attr:`textureGrad ` (samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy) | +| | | +| vec4 | :js:attr:`textureGrad ` (samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| gvec4_type | :js:attr:`texelFetch ` (gsampler2D s, ivec2 p, int lod) | +| | | +| gvec4_type | :js:attr:`texelFetch ` (gsampler2DArray s, ivec3 p, int lod) | +| | | +| gvec4_type | :js:attr:`texelFetch ` (gsampler3D s, ivec3 p, int lod) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| gvec4_type | :js:attr:`textureGather ` (gsampler2D s, vec2 p [, int comps]) | +| | | +| gvec4_type | :js:attr:`textureGather ` (gsampler2DArray s, vec3 p [, int comps]) | +| | | +| vec4 | :js:attr:`textureGather ` (samplerCube s, vec3 p [, int comps]) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`dFdx ` (vec_type p) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`dFdy ` (vec_type p) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`fwidth ` (vec_type p) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| uint | :js:attr:`packHalf2x16 ` (vec2 v) | +| | | +| vec2 | :js:attr:`unpackHalf2x16 ` (uint v) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| uint | :js:attr:`packUnorm2x16 ` (vec2 v) | +| | | +| vec2 | :js:attr:`unpackUnorm2x16 ` (uint v) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| uint | :js:attr:`packSnorm2x16 ` (vec2 v) | +| | | +| vec2 | :js:attr:`unpackSnorm2x16 ` (uint v) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| uint | :js:attr:`packUnorm4x8 ` (vec4 v) | +| | | +| vec4 | :js:attr:`unpackUnorm4x8 ` (uint v) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| uint | :js:attr:`packSnorm4x8 ` (vec4 v) | +| | | +| vec4 | :js:attr:`unpackSnorm4x8 ` (uint v) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| ivec_type | :js:attr:`bitfieldExtract ` (ivec_type value, int offset, int bits) | +| | | +| uvec_type | :js:attr:`bitfieldExtract ` (uvec_type value, int offset, int bits) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| ivec_type | :js:attr:`bitfieldInsert ` (ivec_type base, ivec_type insert, int offset, int bits) | +| | | +| uvec_type | :js:attr:`bitfieldInsert ` (uvec_type base, uvec_type insert, int offset, int bits) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| ivec_type | :js:attr:`bitfieldReverse ` (ivec_type value) | +| | | +| uvec_type | :js:attr:`bitfieldReverse ` (uvec_type value) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| ivec_type | :js:attr:`bitCount ` (ivec_type value) | +| | | +| uvec_type | :js:attr:`bitCount ` (uvec_type value) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| ivec_type | :js:attr:`findLSB ` (ivec_type value) | +| | | +| uvec_type | :js:attr:`findLSB ` (uvec_type value) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| ivec_type | :js:attr:`findMSB ` (ivec_type value) | +| | | +| uvec_type | :js:attr:`findMSB ` (uvec_type value) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| void | :js:attr:`imulExtended ` (ivec_type x, ivec_type y, out ivec_type msb, out ivec_type lsb) | +| | | +| void | :js:attr:`umulExtended ` (uvec_type x, uvec_type y, out uvec_type msb, out uvec_type lsb) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| uvec_type | :js:attr:`uaddCarry ` (uvec_type x, uvec_type y, out uvec_type carry) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| uvec_type | :js:attr:`usubBorrow ` (uvec_type x, uvec_type y, out uvec_type borrow) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`ldexp ` (vec_type x, out ivec_type exp) | ++-------------+---------------------------------------------------------------------------------------------------------+ +| vec_type | :js:attr:`frexp ` (vec_type x, out ivec_type exp) | ++-------------+---------------------------------------------------------------------------------------------------------+ + +.. js:function:: radians( vec_type degrees ) + + ``radians`` converts a quantity specified in degrees into radians. + + `GLSL documentation `_ + + :param vec_type degrees: + Specify the quantity, in degrees, to be converted to radians. + + :return: + The return value is ``(π * degrees) / 180``. + + :rtype: vec_type + +.. js:function:: degrees (vec_type radians) + + ``degrees`` converts a quantity specified in radians into degrees. + + `GLSL documentation `_. + + :param vec_type radians: + Specify the quantity, in radians, to be converted to degrees. + + :return: + The return value is ``(radians * 180) / π``. + + :rtype: vec_type + +.. js:function:: sin (vec_type angle) + + `GLSL documentation `_. + + :param vec_type angle: + The quantity, in radians, of which to return the sine + + :return: + The return value is the trigonometric sine of ``angle``. + + :rtype: vec_type + +.. js:function:: cos (vec_type angle) + + `GLSL documentation `_. + + :param vec_type angle: + The quantity, in radians, of which to return the cosine. + + :return: + The return value is the trigonometric cosine of ``angle``. + + :rtype: vec_type + +.. js:function:: tan (vec_type angle) + + `GLSL documentation `_. + + :param vec_type angle: + The quantity, in radians, of which to return the tangent. + + :return: + The return value is the trigonometric tangent of ``angle``. + + :rtype: vec_type + +.. js:function:: asin (vec_type x) + + Calculates the angle whose sine is ``x``. + The result is undefined if ``x < -1`` or ``x > 1``. + + `GLSL documentation `_. + + :param vec_type x: + The value whose arccosine to return. + :return: + The return value is the angle whose trigonometric sine is ``x`` and is + in the range ``[-π/2, π/2]``. + + :rtype: vec_type + +.. js:function:: acos (vec_type x) + + Calculates the angle whose cosine is ``x``. + The result is undefined if ``x < -1`` or ``x > 1``. + + `GLSL documentation `_. + + :param vec_type x: + The value whose arccosine to return. + + :return: + The return value is the angle whose trigonometric cosine is ``x`` and + is in the range ``[0, π]``. + + :rtype: vec_type + +.. js:function:: atan (vec_type y_over_x) + + Calculate the arctangent given a tangent value of ``y/x``. Note: becuase of + the sign ambiguity, the function cannot determine with certainty in which + quadrant the angle falls only by its tangent value. If you need to know the + quadrant, use the other overload of ``atan``. + + `GLSL documentation `_. + + :param vec_type y_over_x: + The fraction whose arctangent to return. + + :return: + The return value is the trigonometric arc-tangent of ``y_over_x`` and is + in the range ``[−π/2, π/2]``. + + :rtype: vec_type + +.. js:function:: atan (vec_type y, vec_type x) + + Calculate the arctangent given a numerator and denominator. The signs of + ``y`` and ``x`` are used to determine the quadrant that the angle lies in. + The result is undefined if ``x == 0``. + + `GLSL documentation `_. + + :param vec_type y: + The numerator of the fraction whose arctangent to return. + + :param vec_type x: + The denominator of the fraction whose arctangent to return. + + :return: + The return value is the trigonometric arc-tangent of ``y/x`` and is in + the range ``[−π, π]``. + + :rtype: vec_type + +.. js:function:: sinh (vec_type x) + + Calculates the hyperbolic sine using ``(e^x - e^-x)/2``. + `GLSL documentation `_. + + :param vec_type x: + The value whose hyperbolic sine to return. + + :return: + The return value is the hyperbolic sine of ``x``. + + :rtype: vec_type + +.. js:function:: cosh (vec_type x) + + Calculates the hyperbolic cosine using ``(e^x + e^-x)/2``. + `GLSL documentation `_. + + :param vec_type x: + The value whose hyperbolic cosine to return. + + :return: + The return value is the hyperbolic cosine of ``x``. + + :rtype: vec_type + +.. js:function:: tanh (vec_type x) + + Calculates the hyperbolic tangent using ``sinh(x)/cosh(x)``. + `GLSL documentation `_. + + :param vec_type x: + The value whose hyperbolic tangent to return. + + :return: + The return value is the hyperbolic tangent of ``x``. + + :rtype: vec_type + +.. js:function:: asinh (vec_type x) + + Calculates the arc hyperbolic sine of a value. + + `GLSL documentation `_. + + :param vec_type x: + The value whose arc hyperbolic sine to return. + + :return: + The return value is the arc hyperbolic sine of ``x`` which is the + inverse of sinh. + + :rtype: vec_type + +.. js:function:: acosh (vec_type x) + + Calculates the arc hyperbolic cosine of a value. + The result is undefined if ``x < 1``. + + `GLSL documentation `_. + + :param vec_type x: + The value whose arc hyperbolic cosine to return. + + :return: + The return value is the arc hyperbolic cosine of ``x`` which is the + inverse of cosh. + + :rtype: vec_type + +.. js:function:: atanh (vec_type x) + + Calculate the arctangent given a tangent value of ``y/x``. Note: becuase of + the sign ambiguity, the function cannot determine with certainty in which + quadrant the angle falls only by its tangent value. If you need to know the + quadrant, use the other overload of ``atan``. + + The result is undefined if ``x < -1`` or ``x > 1``. + + `GLSL documentation `_. + + :param vec_type y_over_x: + The fraction whose arc hyperbolic tangent to return. + + :return: + The return value is the arc hyperbolic tangent of ``x`` which is the + inverse of tanh. + + :rtype: vec_type + +.. js:function:: pow (vec_type x, vec_type y) + + Raises ``x`` to the power of ``y``. + + The result is undefined if ``x < 0`` or if ``x == 0`` and ``y <= 0``. + + `GLSL documentation `_. + + :param vec_type x: + The value to be raised to the power ``y``. + + :param vec_type y: + The power to which ``x`` will be raised. + + :return: + Returns the value of ``x`` raised to the ``y`` power. + + :rtype: vec_type + +.. js:function:: exp (vec_type x) + + + `GLSL documentation <>`_. + + :param vec_type radians: + + :return: +The return value is + + :rtype: vec_type + +.. js:function:: exp2 (vec_type x) + + `GLSL documentation <>`_. + + :param vec_type radians: + + :return: +The return value is + + :rtype: vec_type + +.. js:function:: log (vec_type x) + + `GLSL documentation <>`_. + + :param vec_type radians: + + :return: +The return value is + + :rtype: vec_type + +.. js:function:: log2 (vec_type x) + + `GLSL documentation <>`_. + + :param vec_type radians: + + :return: +The return value is + + :rtype: vec_type + +.. js:function:: sqrt (vec_type x) + + `GLSL documentation <>`_. + + :param vec_type radians: + + :return: +The return value is + + :rtype: vec_type + +.. js:function:: inversesqrt (vec_type x) + + `GLSL documentation <>`_. + + :param vec_type radians: + + :return: +The return value is + + :rtype: vec_type + +.. js:function:: abs (vec_type x) + + `GLSL documentation <>`_. + + :param vec_type radians: + + :return: +The return value is + + :rtype: vec_type + +.. js:function:: abs (ivec_type x) + + `GLSL documentation <>`_. + + :param ivec_type x: + + :return: +The return value is + + :rtype: ivec_type + +.. js:function:: sign (vec_type x) + + `GLSL documentation <>`_. + + :param vec_type radians: + + :return: +The return value is + + :rtype: vec_type + +.. js:function:: sign (ivec_type x) + + `GLSL documentation <>`_. + + :param ivec_type x: + + :return: +The return value is + + :rtype: ivec_type + +.. js:function:: floor (vec_type x) + + `GLSL documentation <>`_. + + :param vec_type radians: + + :return: +The return value is + + :rtype: vec_type + +.. js:function:: round (vec_type x) + + `GLSL documentation <>`_. + + :param vec_type radians: + + :return: +The return value is + + :rtype: vec_type + +.. js:function:: roundEven (vec_type x) + + `GLSL documentation <>`_. + + :param vec_type radians: + + :return: +The return value is + + :rtype: vec_type + +.. js:function:: trunc (vec_type x) + + `GLSL documentation <>`_. + + :param vec_type radians: + + :return: +The return value is + + :rtype: vec_type + +.. js:function:: ceil (vec_type x) + + `GLSL documentation <>`_. + + :param vec_type radians: + + :return: +The return value is + + :rtype: vec_type + +.. js:function:: fract (vec_type x) + + `GLSL documentation <>`_. + + :param vec_type radians: + + :return: +The return value is + + :rtype: vec_type + +.. js:function:: mod (vec_type x, vec_type y) + +.. js:function:: mod (vec_type x, float y) + +.. js:function:: modf (vec_type x, out vec_type i) + +.. js:function:: min (vec_type a, vec_type b) + +.. js:function:: max (vec_type a, vec_type b) + +.. js:function:: clamp (vec_type x, vec_type min, vec_type max) + +.. js:function:: mix (float a, float b, float c) + +.. js:function:: mix (vec_type a, vec_type b, float c) + +.. js:function:: mix (vec_type a, vec_type b, bvec_type c) + +.. js:function:: fma (vec_type a, vec_type b, vec_type c) + +.. js:function:: step (vec_type a, vec_type b) + +.. js:function:: step (float a, vec_type b) + +.. js:function:: smoothstep (vec_type a, vec_type b, vec_type c) + +.. js:function:: smoothstep (float a, float b, vec_type c) + +.. js:function:: isnan (vec_type x) + +.. js:function:: isinf (vec_type x) + +.. js:function:: floatBitsToInt (vec_type x) + +.. js:function:: floatBitsToUint (vec_type x) + +.. js:function:: intBitsToFloat (ivec_type x) + +.. js:function:: uintBitsToFloat (uvec_type x) + +.. js:function:: length (vec_type x) + +.. js:function:: distance (vec_type a, vec_type b) + +.. js:function:: dot (vec_type a, vec_type b) + +.. js:function:: cross (vec3 a, vec3 b) + +.. js:function:: normalize (vec_type x) + +.. js:function:: reflect (vec3 I, vec3 N) + +.. js:function:: refract (vec3 I, vec3 N, float eta) + +.. js:function:: faceforward (vec_type N, vec_type I, vec_type Nref) + +.. js:function:: matrixCompMult (mat_type x, mat_type y) + +.. js:function:: outerProduct (vec_type column, vec_type row) + +.. js:function:: transpose (mat_type m) + +.. js:function:: determinant (mat_type m) + +.. js:function:: inverse (mat_type m) + +.. js:function:: lessThan (vec_type x, vec_type y) + +.. js:function:: greaterThan (vec_type x, vec_type y) + +.. js:function:: lessThanEqual (vec_type x, vec_type y) + +.. js:function:: greaterThanEqual (vec_type x, vec_type y) + +.. js:function:: equal (vec_type x, vec_type y) + +.. js:function:: notEqual (vec_type x, vec_type y) + +.. js:function:: any (bvec_type x) + +.. js:function:: all (bvec_type x) + +.. js:function:: not (bvec_type x) + + ``degrees`` converts a quantity specified in radians into degrees. + `GLSL documentation `_ + + :param bvec_type x: +Specify the quantity, in radians, to be converted to degrees. + + :return: +The return value is ``(radians * 180) / π``. + + :rtype: bool + +.. js:function:: textureSize (gsampler2D s, int lod) +.. js:function:: textureSize (gsampler2DArray s, int lod) +.. js:function:: textureSize (gsampler3D s, int lod) +.. js:function:: textureSize (samplerCube s, int lod) +.. js:function:: textureSize (samplerCubeArray s, int lod) + + ``degrees`` converts a quantity specified in radians into degrees. + `GLSL documentation `_ + + :param sampler_type s: +Specify the quantity, in radians, to be converted to degrees. + + :param int lod: +Specify the quantity, in radians, to be converted to degrees. + + :return: +The return value is ``(radians * 180) / π``. + + :rtype: vec_type + +.. js:function:: texture (gsampler2D s, vec2 p [, float bias]) +.. js:function:: texture (gsampler2DArray s, vec3 p [, float bias]) +.. js:function:: texture (gsampler3D s, vec3 p [, float bias]) +.. js:function:: texture (samplerCube s, vec3 p [, float bias]) +.. js:function:: texture (samplerCubeArray s, vec4 p [, float bias]) + +.. js:function:: textureProj (gsampler2D s, vec3 p [, float bias]) +.. js:function:: textureProj (gsampler2D s, vec4 p [, float bias]) +.. js:function:: textureProj (gsampler3D s, vec4 p [, float bias]) + +.. js:function:: textureLod (gsampler2D s, vec2 p, float lod) +.. js:function:: textureLod (gsampler2DArray s, vec3 p, float lod) +.. js:function:: textureLod (gsampler3D s, vec3 p, float lod) +.. js:function:: textureLod (samplerCube s, vec3 p, float lod) +.. js:function:: textureLod (samplerCubeArray s, vec4 p, float lod) + +.. js:function:: textureProjLod (gsampler2D s, vec3 p, float lod) +.. js:function:: textureProjLod (gsampler2D s, vec4 p, float lod) +.. js:function:: textureProjLod (gsampler3D s, vec4 p, float lod) + +.. js:function:: textureGrad (gsampler2D s, vec2 p, vec2 dPdx, vec2 dPdy) +.. js:function:: textureGrad (gsampler2DArray s, vec3 p, vec2 dPdx, vec2 dPdy) +.. js:function:: textureGrad (gsampler3D s, vec3 p, vec2 dPdx, vec2 dPdy) +.. js:function:: textureGrad ` (samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy) +.. js:function:: textureGrad ` (samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy) + +.. js:function:: texelFetch ` (gsampler2D s, ivec2 p, int lod) +.. js:function:: texelFetch ` (gsampler2DArray s, ivec3 p, int lod) +.. js:function:: texelFetch ` (gsampler3D s, ivec3 p, int lod) + +.. js:function:: textureGather ` (gsampler2D s, vec2 p [, int comps]) +.. js:function:: textureGather ` (gsampler2DArray s, vec3 p [, int comps]) +.. js:function:: textureGather ` (samplerCube s, vec3 p [, int comps]) + +.. js:function:: dFdx (vec_type p) + +.. js:function:: dFdy (vec_type p) + +.. js:function:: fwidth (vec_type p) + +.. js:function:: packHalf2x16 (vec2 v) +.. js:function:: unpackHalf2x16 (uint v) + +.. js:function:: packUnorm2x16 (vec2 v) +.. js:function:: unpackUnorm2x16 (uint v) + +.. js:function:: packSnorm2x16 (vec2 v) +.. js:function:: unpackSnorm2x16 (uint v) + +.. js:function:: packUnorm4x8 (vec4 v) +.. js:function:: unpackUnorm4x8 (uint v) + +.. js:function:: packSnorm4x8 (vec4 v) +.. js:function:: unpackSnorm4x8 (uint v) + +.. js:function:: bitfieldExtract (ivec_type value, int offset, int bits) +.. js:function:: bitfieldExtract (uvec_type value, int offset, int bits) + +.. js:function:: bitfieldInsert (ivec_type base, ivec_type insert, int offset, int bits) +.. js:function:: bitfieldInsert (uvec_type base, uvec_type insert, int offset, int bits) + +.. js:function:: bitfieldReverse (ivec_type value) +.. js:function:: bitfieldReverse (uvec_type value) + +.. js:function:: bitCount (ivec_type value) +.. js:function:: bitCount (uvec_type value) + +.. js:function:: findLSB (ivec_type value) +.. js:function:: findLSB (uvec_type value) + +.. js:function:: findMSB (ivec_type value) +.. js:function:: findMSB (uvec_type value) + +.. js:function:: imulExtended (ivec_type x, ivec_type y, out ivec_type msb, out ivec_type lsb) +.. js:function:: umulExtended (uvec_type x, uvec_type y, out uvec_type msb, out uvec_type lsb) + +.. js:function:: uaddCarry (uvec_type x, uvec_type y, out uvec_type carry) + +.. js:function:: usubBorrow (uvec_type x, uvec_type y, out uvec_type borrow) + +.. js:function:: ldexp (vec_type x, out ivec_type exp) + +.. js:function:: frexp (vec_type x, out ivec_type exp) \ No newline at end of file From 44e4170372dd162c2112703bfba4b6be320b7417 Mon Sep 17 00:00:00 2001 From: ashbygeek Date: Fri, 3 May 2024 18:00:58 -0400 Subject: [PATCH 02/25] Shader Functions are in separate file, table is split into categories --- tutorials/shaders/shader_reference/index.rst | 1 + .../shader_reference/shader_functions.rst | 883 ++++++++++++++++ .../shader_reference/shading_language.rst | 970 ------------------ 3 files changed, 884 insertions(+), 970 deletions(-) create mode 100644 tutorials/shaders/shader_reference/shader_functions.rst diff --git a/tutorials/shaders/shader_reference/index.rst b/tutorials/shaders/shader_reference/index.rst index e6822c55b34..b286a4a5d16 100644 --- a/tutorials/shaders/shader_reference/index.rst +++ b/tutorials/shaders/shader_reference/index.rst @@ -8,6 +8,7 @@ Shading reference :name: toc-shading-reference shading_language + shader_functions shader_preprocessor spatial_shader canvas_item_shader diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst new file mode 100644 index 00000000000..addea286c8f --- /dev/null +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -0,0 +1,883 @@ +.. _doc_shader_functions: + +Built-in functions +------------------------------------------ + +Godot supports a large number of built-in functions, conforming roughly to the +GLSL 4.00 specification. + +.. note:: + The following type aliases only used in documentation to reduce repetitive function declarations. + They can each refer to any of several actual types. + + +-----------------+--------------------------------------------------+--------------------------+ + | alias | actual types | glsl documentation alias | + +=================+==================================================+==========================+ + | vec_type | float, vec2, vec3, or vec4 | genType | + +-----------------+--------------------------------------------------+--------------------------+ + | vec_int_type | int, ivec2, ivec3, or ivec4 | genIType | + +-----------------+--------------------------------------------------+--------------------------+ + | vec_uint_type | uint, uvec2, uvec3, or uvec4 | genUType | + +-----------------+--------------------------------------------------+--------------------------+ + | mat_type | mat2, mat3, or mat4 | mat | + +-----------------+--------------------------------------------------+--------------------------+ + | gsampler2D | sampler2D, isampler2D, uSampler2D | | + +-----------------+--------------------------------------------------+--------------------------+ + | gsampler2DArray | sampler2DArray, isampler2DArray, uSampler2DArray | | + +-----------------+--------------------------------------------------+--------------------------+ + | gsampler3D | sampler3D, isampler3D, uSampler3D | | + +-----------------+--------------------------------------------------+--------------------------+ + + + If any of these are specified for multiple parameters, they must all be the same type unless otherwise noted. + + +.. rst-class:: classref-reftable-group + +Trigonometric Functions +------------------------------------------ + ++-----------------+-------------------------------------------------------------+-----------------------------+ +| Return Type | Function | Description / Return value | ++=================+=============================================================+=============================+ +| |vec_type| | :ref:`radians` ( |vec_type| degrees) | Convert degrees to radians. | ++-----------------+-------------------------------------------------------------+-----------------------------+ +| |vec_type| | :ref:`degrees` ( |vec_type| radians) | Convert radians to degrees. | ++-----------------+-------------------------------------------------------------+-----------------------------+ +| |vec_type| | :ref:`sin` ( |vec_type| x) | Sine. | ++-----------------+-------------------------------------------------------------+-----------------------------+ +| |vec_type| | :ref:`cos` ( |vec_type| x) | Cosine. | ++-----------------+-------------------------------------------------------------+-----------------------------+ +| |vec_type| | :ref:`tan` ( |vec_type| x) | Tangent. | ++-----------------+-------------------------------------------------------------+-----------------------------+ +| |vec_type| | :ref:`asin` ( |vec_type| x) | Arcsine. | ++-----------------+-------------------------------------------------------------+-----------------------------+ +| |vec_type| | :ref:`acos` ( |vec_type| x) | Arccosine. | ++-----------------+-------------------------------------------------------------+-----------------------------+ +| |vec_type| | :ref:`atan` ( |vec_type| y_over_x) | Arctangent. | ++-----------------+-------------------------------------------------------------+ | +| |vec_type| | :ref:`atan` ( |vec_type| y, |vec_type| x) | | ++-----------------+-------------------------------------------------------------+-----------------------------+ +| |vec_type| | :ref:`sinh` ( |vec_type| x) | Hyperbolic sine. | ++-----------------+-------------------------------------------------------------+-----------------------------+ +| |vec_type| | :ref:`cosh` ( |vec_type| x) | Hyperbolic cosine. | ++-----------------+-------------------------------------------------------------+-----------------------------+ +| |vec_type| | :ref:`tanh` ( |vec_type| x) | Hyperbolic tangent. | ++-----------------+-------------------------------------------------------------+-----------------------------+ +| |vec_type| | :ref:`asinh` ( |vec_type| x) | Inverse hyperbolic sine. | ++-----------------+-------------------------------------------------------------+-----------------------------+ +| |vec_type| | :ref:`acosh` ( |vec_type| x) | Inverse hyperbolic cosine. | ++-----------------+-------------------------------------------------------------+-----------------------------+ +| |vec_type| | :ref:`atanh` ( |vec_type| x) | Inverse hyperbolic tangent. | ++-----------------+-------------------------------------------------------------+-----------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +.. _shader_func_radians: + +.. rst-class:: classref-method + +|vec_type| **radians** ( |vec_type| degrees ) + + Converts a quantity specified in degrees into radians. + + :param degrees: + Specify the quantity, in degrees, to be converted to radians. + + :return: + The return value is ``(π * degrees) / 180``. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/radians.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. _shader_func_degrees: + +.. rst-class:: classref-method + +|vec_type| degrees( |vec_type| radians) + + Converts a quantity specified in radians into degrees. + + :param radians: + Specify the quantity, in radians, to be converted to degrees. + + :return: + The return value is ``(radians * 180) / π``. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/degrees.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. _shader_func_sin: + +.. rst-class:: classref-method + +vec_type sin( |vec_type| angle) + + Return the sine of the parameter. + + :param angle: + The quantity, in radians, of which to return the sine + + :return: + The return value is the trigonometric sine of ``angle``. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/sin.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. _shader_func_cos: + +.. rst-class:: classref-method + +vec_type cos( |vec_type| angle) + + Return the cosine of the parameter. + + :param angle: + The quantity, in radians, of which to return the cosine. + + :return: + The return value is the trigonometric cosine of ``angle``. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/cos.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. _shader_func_tan: + +.. rst-class:: classref-method + +vec_type tan( |vec_type| angle) + + Return the tangent of the parameter. + + :param angle: + The quantity, in radians, of which to return the tangent. + + :return: + The return value is the trigonometric tangent of ``angle``. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/tan.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. _shader_func_asin: + +.. rst-class:: classref-method + +vec_type asin( |vec_type| x) + + Calculates the angle whose sine is ``x``. + The result is undefined if ``x < -1`` or ``x > 1``. + + :param x: + The value whose arccosine to return. + :return: + The return value is the angle whose trigonometric sine is ``x`` and is + in the range ``[-π/2, π/2]``. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/asin.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. _shader_func_acos: + +.. rst-class:: classref-method + +vec_type acos( |vec_type| x) + + Calculates the angle whose cosine is ``x``. + The result is undefined if ``x < -1`` or ``x > 1``. + + :param x: + The value whose arccosine to return. + + :return: + The return value is the angle whose trigonometric cosine is ``x`` and + is in the range ``[0, π]``. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/acos.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. _shader_func_atan: + +.. rst-class:: classref-method + +vec_type atan( |vec_type| y_over_x) + + Calculate the arctangent given a tangent value of ``y/x``. Note: becuase of + the sign ambiguity, the function cannot determine with certainty in which + quadrant the angle falls only by its tangent value. If you need to know the + quadrant, use ``atan( |vec_type| y, |vec_type| x )``. + + :param y_over_x: + The fraction whose arctangent to return. + + :return: + The return value is the trigonometric arc-tangent of ``y_over_x`` and is + in the range ``[-π/2, π/2]``. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/atan.xhtml + + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +vec_type atan( |vec_type| y, |vec_type| x) + + Calculate the arctangent given a numerator and denominator. The signs of + ``y`` and ``x`` are used to determine the quadrant that the angle lies in. + The result is undefined if ``x == 0``. + + :param y: + The numerator of the fraction whose arctangent to return. + + :param x: + The denominator of the fraction whose arctangent to return. + + :return: + The return value is the trigonometric arc-tangent of ``y/x`` and is in + the range ``[-π, π]``. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/atan.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. _shader_func_sinh: + +.. rst-class:: classref-method + +vec_type sinh( |vec_type| x) + + Calculates the hyperbolic sine using ``(e^x - e^-x)/2``. + + :param x: + The value whose hyperbolic sine to return. + + :return: + The return value is the hyperbolic sine of ``x``. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/sinh.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. _shader_func_cosh: + +.. rst-class:: classref-method + +vec_type cosh( |vec_type| x) + + Calculates the hyperbolic cosine using ``(e^x + e^-x)/2``. + + :param x: + The value whose hyperbolic cosine to return. + + :return: + The return value is the hyperbolic cosine of ``x``. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/cosh.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. _shader_func_tanh: + +.. rst-class:: classref-method + +vec_type tanh( |vec_type| x) + + Calculates the hyperbolic tangent using ``sinh(x)/cosh(x)``. + + :param x: + The value whose hyperbolic tangent to return. + + :return: + The return value is the hyperbolic tangent of ``x``. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/tanh.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. _shader_func_asinh: + +.. rst-class:: classref-method + +vec_type asinh( |vec_type| x) + + Calculates the arc hyperbolic sine of a value. + + :param x: + The value whose arc hyperbolic sine to return. + + :return: + The return value is the arc hyperbolic sine of ``x`` which is the + inverse of sinh. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/asinh.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. _shader_func_acosh: + +.. rst-class:: classref-method + +vec_type acosh( |vec_type| x) + + Calculates the arc hyperbolic cosine of a value. + The result is undefined if ``x < 1``. + + :param x: + The value whose arc hyperbolic cosine to return. + + :return: + The return value is the arc hyperbolic cosine of ``x`` which is the + inverse of cosh. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/acos.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. _shader_func_atanh: + +.. rst-class:: classref-method + +vec_type atanh( |vec_type| x) + + Calculate the arctangent given a tangent value of ``y/x``. Note: becuase of + the sign ambiguity, the function cannot determine with certainty in which + quadrant the angle falls only by its tangent value. If you need to know the + quadrant, use the other overload of ``atan``. + + The result is undefined if ``x < -1`` or ``x > 1``. + + :param y_over_x: + The fraction whose arc hyperbolic tangent to return. + + :return: + The return value is the arc hyperbolic tangent of ``x`` which is the + inverse of tanh. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/atan.xhtml + +.. rst-class:: classref-item-separator + +---- + + + +Exponential and Common Math Functions +------------------------------------------ + ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`pow` ( |vec_type| x, |vec_type| y) | Power (undefined if ``x`` < 0 or if ``x`` == 0 and ``y`` <= 0). | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`exp` ( |vec_type| x) | Base-e exponential. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`exp2` ( |vec_type| x) | Base-2 exponential. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`log` ( |vec_type| x) | Natural logarithm. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`log2` ( |vec_type| x) | Base-2 logarithm. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`sqrt` ( |vec_type| x) | Square root. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`inversesqrt` ( |vec_type| x) | Inverse square root. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`abs` ( |vec_type| x) | Absolute value (returns positive value if negative). | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_int_type| | :ref:`abs` ( |vec_int_type| x) | | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`sign` ( |vec_type| x) | Sign (returns ``1.0`` if positive, ``-1.0`` if negative, | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_int_type| | :ref:`sign` ( |vec_int_type| x) | Sign (returns ``1`` if positive, ``-1`` if negative, | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`floor` ( |vec_type| x) | Round to the integer below. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`round` ( |vec_type| x) | Round to the nearest integer. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`roundEven` ( |vec_type| x) | Round to the nearest even integer. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`trunc` ( |vec_type| x) | Truncation. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`ceil` ( |vec_type| x) | Round to the integer above. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`fract` ( |vec_type| x) | Fractional (returns ``x - floor(x)``). | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`mod` ( |vec_type| x, |vec_type| y) | Modulo (division remainder). | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_type| | :ref:`mod` ( |vec_type| x, float y) | | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`modf` (vecType x, out |vec_type| i) | Fractional of ``x``, with ``i`` as integer part. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`min` ( |vec_type| a, |vec_type| b) | Lowest value between ``a`` and ``b``. | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_type| | :ref:`min` ( |vec_type| a, float b) | | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_int_type| | :ref:`min` ( |vec_int_type| a, |vec_int_type| b) | Lowest value between ``a`` and ``b``. | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_int_type| | :ref:`min` ( |vec_int_type| a, int b) | | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_uint_type| | :ref:`min` ( |vec_uint_type| a, |vec_uint_type| b) | Lowest value between ``a`` and ``b``. | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_uint_type| | :ref:`min` ( |vec_uint_type| a, uint b) | | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`max` ( |vec_type| a, |vec_type| b) | Highest value between ``a`` and ``b``. | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_type| | :ref:`max` ( |vec_type| a, float b) | | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_uint_type| | :ref:`max` ( |vec_uint_type| a, |vec_uint_type| b) | Highest value between ``a`` and ``b``. | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_uint_type| | :ref:`max` ( |vec_uint_type| a, uint b) | | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_int_type| | :ref:`max` ( |vec_int_type| a, |vec_int_type| b) | Highest value between ``a`` and ``b``. | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_int_type| | :ref:`max` ( |vec_int_type| a, int b) | | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`clamp` (vecType x, |vec_type| min, |vec_type| max) | Clamp ``x`` between ``min`` and ``max`` (inclusive). | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_type| | :ref:`clamp` ( |vec_type| x, float min, float max) | | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_uint_type| | :ref:`clamp` ( |vec_int_type| x, |vec_int_type| min, |vec_int_type| max) | Clamp ``x`` between ``min`` and ``max`` (inclusive). | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_uint_type| | ref:`clamp` ( |vec_int_type| x, float min, float max) | | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_int_type| | :ref:`clamp` (vecType x, |vec_type| min, |vec_type| max) | Clamp ``x`` between ``min`` and ``max`` (inclusive). | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_int_type| | :ref:`clamp` ( |vec_type| x, float min, float max) | | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| float | :ref:`mix` (float a, float b, float c) | Linear interpolate between ``a`` and ``b`` by ``c``. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`mix` (vecType a, |vec_type| b, float c) | Linear interpolate between ``a`` and ``b`` by ``c``. | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_type| | :ref:`mix` (vecType a, |vec_type| b, |vec_type| c) | | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_type| | :ref:`mix` (vecType a, |vec_type| b, |vec_bool_type| c) | | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`fma` (vecType a, |vec_type| b, |vec_type| c) | Fused multiply-add operation: ``(a * b + c)`` | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`step` ( |vec_type| a, |vec_type| b) | ``b[i] < a[i] ? 0.0 : 1.0``. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`step` (float a, |vec_type| b) | ``b[i] < a ? 0.0 : 1.0``. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`smoothstep` (vecType a, |vec_type| b, |vec_type| c) | Hermite interpolate between ``a`` and ``b`` by ``c``. | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_type| | :ref:`smoothstep` (float a, float b, |vec_type| c) | | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_bool_type| | :ref:`isnan` ( |vec_type| x) | Returns ``true`` if scalar or vector component is ``NaN``. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_bool_type| | :ref:`isinf` ( |vec_type| x) | Returns ``true`` if scalar or vector component is ``INF``. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_int_type| | :ref:`floatBitsToInt` ( |vec_type| x) | Float->Int bit copying, no conversion. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_uint_type| | :ref:`floatBitsToUint` ( |vec_type| x) | Float->UInt bit copying, no conversion. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`intBitsToFloat` ( |vec_int_type| x) | Int->Float bit copying, no conversion. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| |vec_type| | :ref:`uintBitsToFloat` ( |vec_uint_type| x) | UInt->Float bit copying, no conversion. | ++-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + + + + + +Geometric Functions +------------------------------------------ + ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| float | :ref:`length` ( |vec_type| x) | Vector length. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| float | :ref:`distance` ( |vec_type| a, |vec_type| b) | Distance between vectors i.e ``length(a - b)``. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| float | :ref:`dot` ( |vec_type| a, |vec_type| b) | Dot product. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| vec3 | :ref:`cross` (vec3 a, vec3 b) | Cross product. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |vec_type| | :ref:`normalize` ( |vec_type| x) | Normalize to unit length. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| vec3 | :ref:`reflect` (vec3 I, vec3 N) | Reflect. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| vec3 | :ref:`refract` (vec3 I, vec3 N, float eta) | Refract. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |vec_type| | :ref:`faceforward` (vecType N, |vec_type| I, |vec_type| Nref) | If ``dot(Nref, I)`` < 0, return ``N``, otherwise ``-N``. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |mat_type| | :ref:`matrixCompMult` (|mat_type| x, |mat_type| y) | Matrix component multiplication. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |mat_type| | :ref:`outerProduct` ( |vec_type| column, |vec_type| row) | Matrix outer product. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |mat_type| | :ref:`transpose` (|mat_type| m) | Transpose matrix. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| float | :ref:`determinant` (|mat_type| m) | Matrix determinant. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |mat_type| | :ref:`inverse` (|mat_type| m) | Inverse matrix. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---------- + + +Comparison Functions +------------------------- + ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`lessThan` ( |vec_type| x, |vec_type| y) | Bool vector comparison on < int/uint/float vectors. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`greaterThan` ( |vec_type| x, |vec_type| y) | Bool vector comparison on > int/uint/float vectors. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`lessThanEqual` ( |vec_type| x, |vec_type| y) | Bool vector comparison on <= int/uint/float vectors. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`greaterThanEqual` ( |vec_type| x, |vec_type| y) | Bool vector comparison on >= int/uint/float vectors. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`equal` ( |vec_type| x, |vec_type| y) | Bool vector comparison on == int/uint/float vectors. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`notEqual` ( |vec_type| x, |vec_type| y) | Bool vector comparison on != int/uint/float vectors. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| bool | :ref:`any` ( |vec_bool_type| x) | ``true`` if any component is ``true``, ``false`` otherwise. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| bool | :ref:`all` ( |vec_bool_type| x) | ``true`` if all components are ``true``, ``false`` otherwise. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`not` ( |vec_bool_type| x) | Invert boolean vector. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + + + +Texture Functions +------------------------------------------ + ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| ivec2 | :ref:`textureSize` ( |gsampler2D| s, int lod) | Get the size of a texture. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| ivec2 | :ref:`textureSize` (samplerCube s, int lod) | The LOD defines which mipmap level is used. An LOD value of ``0`` | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| ivec2 | :ref:`textureSize` (samplerCubeArray s, int lod) | will use the full resolution texture. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| ivec3 | :ref:`textureSize` ( |gsampler2DArray| s, int lod) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| ivec3 | :ref:`textureSize` ( |gsampler3D| s, int lod) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| vec2 | :ref:`textureQueryLod` ( |gsampler2D| s, vec2 p) | Compute the level-of-detail that would be used to sample from a | ++--------------+-----------------------------------------------------------------------------------------------------+ texture. The ``x`` component of the resulted value is the mipmap | +| vec3 | :ref:`textureQueryLod` ( |gsampler2DArray| s, vec2 p) | array that would be accessed. The ``y`` component is computed | ++--------------+-----------------------------------------------------------------------------------------------------+ level-of-detail relative to the base level (regardless of the | +| vec2 | :ref:`textureQueryLod` ( |gsampler3D| s, vec3 p) | mipmap levels of the texture). | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec2 | :ref:`textureQueryLod` (samplerCube s, vec3 p) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| int | :ref:`textureQueryLevels` ( |gsampler2D| s) | Get the number of accessible mipmap levels of a texture. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| int | :ref:`textureQueryLevels` ( |gsampler2DArray| s) | If the texture is unassigned to a sampler, ``1`` is returned (Godot | ++--------------+-----------------------------------------------------------------------------------------------------+ always internally assigns a texture even to an empty sampler). | +| int | :ref:`textureQueryLevels` ( |gsampler3D| s) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| int | :ref:`textureQueryLevels` (samplerCube s) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`texture` ( |gsampler2D| s, vec2 p [, float bias]) | Perform a texture read. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`texture` ( |gsampler2DArray| s, vec3 p [, float bias]) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |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]) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |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]) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureProj` ( |gsampler3D| s, vec4 p [, float bias]) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`textureLod` ( |gsampler2D| s, vec2 p, float lod) | Perform a texture read at custom mipmap. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureLod` ( |gsampler2DArray| s, vec3 p, float lod) | The LOD defines which mipmap level is used. An LOD value of ``0.0`` | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| | | will use the full resolution texture. If the texture lacks mipmaps, | +| |gvec4_type| | :ref:`textureLod` ( |gsampler3D| s, vec3 p, float lod) | all LOD values will act like ``0.0``. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec4 | :ref:`textureLod` (samplerCube s, vec3 p, float lod) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec4 | :ref:`textureLod` (samplerCubeArray s, vec4 p, float lod) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec3 p, float lod) | Performs a texture read with projection/LOD. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec4 p, float lod) | The LOD defines which mipmap level is used. An LOD value of ``0.0`` | +| | | will use the full resolution texture. If the texture lacks mipmaps, | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureProjLod` ( |gsampler3D| s, vec4 p, float lod) | all LOD values will act like ``0.0``. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`textureGrad` ( |gsampler2D| s, vec2 p, vec2 dPdx, vec2 dPdy) | Performs a texture read with explicit gradients. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureGrad` ( |gsampler2DArray| s, vec3 p, vec2 dPdx, vec2 dPdy) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureGrad` ( |gsampler3D| s, vec3 p, vec2 dPdx, vec2 dPdy) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec4 | :ref:`textureGrad` (samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec4 | :ref:`textureGrad` (samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy) | Performs a texture read with projection/LOD and with explicit | +| | | gradients. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`texelFetch` ( |gsampler2D| s, ivec2 p, int lod) | Fetches a single texel using integer coordinates. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`texelFetch` ( |gsampler2DArray| s, ivec3 p, int lod) | The LOD defines which mipmap level is used. An LOD value of ``0`` | +| | | will use the full resolution texture. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`texelFetch` ( |gsampler3D| s, ivec3 p, int lod) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`textureGather` ( |gsampler2D| s, vec2 p [, int comps]) | Gathers four texels from a texture. | +| | | Use ``comps`` within range of 0..3 to | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureGather` ( |gsampler2DArray| s, vec3 p [, int comps]) | define which component (x, y, z, w) is returned. | +| | | If ``comps`` is not provided: 0 (or x-component) is used. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec4 | :ref:`textureGather` (samplerCube s, vec3 p [, int comps]) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`dFdx` ( |vec_type| p) | Derivative in ``x`` using local differencing. | +| | | Internally, can use either ``dFdxCoarse`` or ``dFdxFine``, but the | +| | | decision for which to use is made by the GPU driver. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`dFdxCoarse` ( |vec_type| p) | Calculates derivative with respect to ``x`` window coordinate using | +| | | local differencing based on the value of ``p`` for the current | +| | | fragment neighbour(s), and will possibly, but not necessarily, | +| | | include the value for the current fragment. | +| | | Not available on ``gl_compatibility`` profile. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`dFdxFine` ( |vec_type| p) | Calculates derivative with respect to ``x`` window coordinate using | +| | | local differencing based on the value of ``p`` for the current | +| | | fragment and its immediate neighbour(s). | +| | | Not available on ``gl_compatibility`` profile. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`dFdy` ( |vec_type| p) | Derivative in ``y`` using local differencing. | +| | | Internally, can use either ``dFdyCoarse`` or ``dFdyFine``, but the | +| | | decision for which to use is made by the GPU driver. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`dFdyCoarse` ( |vec_type| p) | Calculates derivative with respect to ``y`` window coordinate using | +| | | local differencing based on the value of ``p`` for the current | +| | | fragment neighbour(s), and will possibly, but not necessarily, | +| | | include the value for the current fragment. | +| | | Not available on ``gl_compatibility`` profile. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`dFdyFine` ( |vec_type| p) | Calculates derivative with respect to ``y`` window coordinate using | +| | | local differencing based on the value of ``p`` for the current | +| | | fragment and its immediate neighbour(s). | +| | | Not available on ``gl_compatibility`` profile. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`fwidth` ( |vec_type| p) | Sum of absolute derivative in ``x`` and ``y``. | +| | | This is the equivalent of using ``abs(dFdx(p)) + abs(dFdy(p))``. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`fwidthCoarse` ( |vec_type| p) | Sum of absolute derivative in ``x`` and ``y``. | +| | | Not available on ``gl_compatibility`` profile. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`fwidthFine` ( |vec_type| p) | Sum of absolute derivative in ``x`` and ``y``. | +| | | Not available on ``gl_compatibility`` profile. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + + + + +Packing/Unpacking Functions +------------------------------------------ + ++------+--------------------------------------------------------------+--------------------------------------------------------------+ +| uint | :ref:`packHalf2x16` (vec2 v) | Convert two 32-bit floating-point numbers into 16-bit | +| | | and pack them into a 32-bit unsigned integer and vice-versa. | +| vec2 | :ref:`unpackHalf2x16` (uint v) | | ++------+--------------------------------------------------------------+--------------------------------------------------------------+ +| uint | :ref:`packUnorm2x16` (vec2 v) | Convert two 32-bit floating-point numbers (clamped | +| | | within 0..1 range) into 16-bit and pack them | +| vec2 | :ref:`unpackUnorm2x16` (uint v) | into a 32-bit unsigned integer and vice-versa. | ++------+--------------------------------------------------------------+--------------------------------------------------------------+ +| uint | :ref:`packSnorm2x16` (vec2 v) | Convert two 32-bit floating-point numbers (clamped | +| | | within -1..1 range) into 16-bit and pack them | +| vec2 | :ref:`unpackSnorm2x16` (uint v) | into a 32-bit unsigned integer and vice-versa. | ++------+--------------------------------------------------------------+--------------------------------------------------------------+ +| uint | :ref:`packUnorm4x8` (vec4 v) | Convert four 32-bit floating-point numbers (clamped | +| | | within 0..1 range) into 8-bit and pack them | +| vec4 | :ref:`unpackUnorm4x8` (uint v) | into a 32-bit unsigned integer and vice-versa. | ++------+--------------------------------------------------------------+--------------------------------------------------------------+ +| uint | :ref:`packSnorm4x8` (vec4 v) | Convert four 32-bit floating-point numbers (clamped | +| | | within -1..1 range) into 8-bit and pack them | +| vec4 | :ref:`unpackSnorm4x8` (uint v) | into a 32-bit unsigned integer and vice-versa. | ++------+--------------------------------------------------------------+--------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + + + + +Bitwise operations +------------------------------------------ + ++-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_int_type| | :ref:`bitfieldExtract` ( |vec_int_type| value, int offset, int bits) | Extracts a range of bits from an integer. | +| | | | +| |vec_uint_type| | :ref:`bitfieldExtract` ( |vec_uint_type| value, int offset, int bits) | | ++-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_int_type| | :ref:`bitfieldInsert` ( |vec_int_type| base, |vec_int_type| insert, | Insert a range of bits into an integer. | +| | int offset, int bits) | | ++-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | +| |vec_uint_type| | :ref:`bitfieldInsert` (|vec_uint_type| base, |vec_uint_type| insert, int offset, | | +| | int bits) | | ++-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_int_type| | :ref:`bitfieldReverse` ( |vec_int_type| value) | Reverse the order of bits in an integer. | +| | | | +| |vec_uint_type| | :ref:`bitfieldReverse` ( |vec_uint_type| value) | | ++-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_int_type| | :ref:`bitCount` ( |vec_int_type| value) | Counts the number of 1 bits in an integer. | +| | | | +| |vec_uint_type| | :ref:`bitCount` ( |vec_uint_type| value) | | ++-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_int_type| | :ref:`findLSB` ( |vec_int_type| value) | Find the index of the least significant bit set to 1 in an integer. | +| | | | +| |vec_uint_type| | :ref:`findLSB` ( |vec_uint_type| value) | | ++-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_int_type| | :ref:`findMSB` ( |vec_int_type| value) | Find the index of the most significant bit set to 1 in an integer. | +| | | | +| |vec_uint_type| | :ref:`findMSB` ( |vec_uint_type| value) | | ++-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |void| | :ref:`imulExtended` ( |vec_int_type| x, |vec_int_type| y,out |vec_int_type| msb, out |vec_int_type| lsb) | Multiplies two 32-bit numbers and produce a 64-bit result. | ++-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | +| |void| | :ref:`umulExtended` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| msb, out |vec_uint_type| lsb) | | ++-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_uint_type| | :ref:`uaddCarry` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| carry) | Adds two unsigned integers and generates carry. | ++-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_uint_type| | :ref:`usubBorrow` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| borrow) | Subtracts two unsigned integers and generates borrow. | ++-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`ldexp` (vecType x, out |vec_int_type| exp) | Assemble a floating-point number from a value and exponent. | ++-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`frexp` (vecType x, out |vec_int_type| exp) | Splits a floating-point number (``x``) into significand integral | +| | | components | ++-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + + +.. rst-class:: classref-section-separator + +---- + + +vec_type pow( |vec_type| x, |vec_type| y) + + Raises ``x`` to the power of ``y``. + + The result is undefined if ``x < 0`` or if ``x == 0`` and ``y <= 0``. + + :param x: + The value to be raised to the power ``y``. + + :param y: + The power to which ``x`` will be raised. + + :return: + Returns the value of ``x`` raised to the ``y`` power. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/pow.xhtml + +.. |void| replace:: :abbr:`void (No return value.)` +.. |vec_type| replace:: :abbr:`vec_type (Any of: float, vec2, vec3, vec4)` +.. |vec_int_type| replace:: :abbr:`vec_int_type (Any of: int, ivec2, ivec3, ivec4)` +.. |vec_uint_type| replace:: :abbr:`vec_uint_type (Any of: float, uvec2, uvec3, uvec4)` +.. |vec_bool_type| replace:: :abbr:`vec_bool_type (Any of: bool, bvec2, bvec3, bvec4)` +.. |gsampler2D| replace:: :abbr:`gsampler2D (Any of: sampler2D, isampler2D, uSampler2D)` +.. |gsampler2DArray| replace:: :abbr:`gsampler2DArray (Any of: sampler2DArray, isampler2DArray, uSampler2DArray)` +.. |gsampler3D| replace:: :abbr:`gsampler3D (Any of: sampler3D, isampler3D, uSampler3D)` +.. |mat_type| replace:: :abbr:`mat_type (Any of: mat2, mat3, mat4)` diff --git a/tutorials/shaders/shader_reference/shading_language.rst b/tutorials/shaders/shader_reference/shading_language.rst index 350d1be7d7e..20a453c8285 100644 --- a/tutorials/shaders/shader_reference/shading_language.rst +++ b/tutorials/shaders/shader_reference/shading_language.rst @@ -1134,973 +1134,3 @@ please see the corresponding pages: - :ref:`Particle shaders ` - :ref:`Sky shaders ` - :ref:`Fog shaders ` - -Built-in functions ------------------- - -Godot supports a large number of built-in functions, conforming roughly to the -GLSL 4.00 specification. - -When vec_type, ivec_type, uvec_type, or bvec_type nomenclature is used, the type -can be scalar or vector. For example vec_type can be float, vec2, vec3, or vec4. - -.. note:: For a list of the functions that are not available in the OpenGL - backend, please see the :ref:`Differences between GLES2 and GLES3 doc - `. - -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| Return Type | Function | Description / Return value | -+=============+=========================================================================================================+=====================================================================+ -| vec_type | :js:attr:`radians ` (vec_type degrees) | Convert degrees to radians. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`degrees ` (vec_type radians) | Convert radians to degrees. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`sin ` (vec_type x) | Sine. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`cos ` (vec_type x) | Cosine. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`tan ` (vec_type x) | Tangent. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`asin ` (vec_type x) | Arcsine. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`acos ` (vec_type x) | Arccosine. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`atan ` (vec_type y_over_x) | Arctangent. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`atan ` (vec_type y, vec_type x) | Arctangent. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`sinh ` (vec_type x) | Hyperbolic sine. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`cosh ` (vec_type x) | Hyperbolic cosine. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`tanh ` (vec_type x) | Hyperbolic tangent. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`asinh ` (vec_type x) | Inverse hyperbolic sine. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`acosh ` (vec_type x) | Inverse hyperbolic cosine. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`atanh ` (vec_type x) | Inverse hyperbolic tangent. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`pow ` (vec_type x, vec_type y) | Power (undefined if ``x`` < 0 or if ``x`` == 0 and ``y`` <= 0). | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`exp ` (vec_type x) | Base-e exponential. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`exp2 ` (vec_type x) | Base-2 exponential. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`log ` (vec_type x) | Natural logarithm. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`log2 ` (vec_type x) | Base-2 logarithm. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`sqrt ` (vec_type x) | Square root. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`inversesqrt ` (vec_type x) | Inverse square root. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`abs ` (vec_type x) | Absolute value (returns positive value if negative). | -| | | | -| ivec_type | :js:attr:`abs ` (ivec_type x) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`sign ` (vec_type x) | Sign (returns ``1.0`` if positive, ``-1.0`` if negative, | -| | | ``0.0`` if zero). | -| ivec_type | :js:attr:`sign ` (ivec_type x) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`floor ` (vec_type x) | Round to the integer below. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`round ` (vec_type x) | Round to the nearest integer. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`roundEven ` (vec_type x) | Round to the nearest even integer. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`trunc ` (vec_type x) | Truncation. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`ceil ` (vec_type x) | Round to the integer above. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`fract ` (vec_type x) | Fractional (returns ``x - floor(x)``). | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`mod ` (vec_type x, vec_type y) | Modulo (division remainder). | -| | | | -| vec_type | :js:attr:`mod ` (vec_type x, float y) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`modf ` (vec_type x, out vec_type i) | Fractional of ``x``, with ``i`` as integer part. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`min ` (vec_type a, vec_type b) | Lowest value between ``a`` and ``b``. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`max ` (vec_type a, vec_type b) | Highest value between ``a`` and ``b``. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`clamp ` (vec_type x, vec_type min, vec_type max) | Clamp ``x`` between ``min`` and ``max`` (inclusive). | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| float | :js:attr:`mix ` (float a, float b, float c) | Linear interpolate between ``a`` and ``b`` by ``c``. | -| | | | -| vec_type | :js:attr:`mix ` (vec_type a, vec_type b, float c) | | -| | | | -| vec_type | :js:attr:`mix ` (vec_type a, vec_type b, bvec_type c) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`fma ` (vec_type a, vec_type b, vec_type c) | Fused multiply-add operation: ``(a * b + c)`` | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`step ` (vec_type a, vec_type b) | ``b[i] < a[i] ? 0.0 : 1.0``. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`step ` (float a, vec_type b) | ``b[i] < a ? 0.0 : 1.0``. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`smoothstep ` (vec_type a, vec_type b, vec_type c) | Hermite interpolate between ``a`` and ``b`` by ``c``. | -| | | | -| vec_type | :js:attr:`smoothstep ` (float a, float b, vec_type c) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bvec_type | :js:attr:`isnan ` (vec_type x) | Returns ``true`` if scalar or vector component is ``NaN``. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bvec_type | :js:attr:`isinf ` (vec_type x) | Returns ``true`` if scalar or vector component is ``INF``. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec_type | :js:attr:`floatBitsToInt ` (vec_type x) | Float->Int bit copying, no conversion. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| uvec_type | :js:attr:`floatBitsToUint ` (vec_type x) | Float->UInt bit copying, no conversion. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`intBitsToFloat ` (ivec_type x) | Int->Float bit copying, no conversion. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`uintBitsToFloat ` (uvec_type x) | UInt->Float bit copying, no conversion. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| float | :js:attr:`length ` (vec_type x) | Vector length. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| float | :js:attr:`distance ` (vec_type a, vec_type b) | Distance between vectors i.e ``length(a - b)``. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| float | :js:attr:`dot ` (vec_type a, vec_type b) | Dot product. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec3 | :js:attr:`cross ` (vec3 a, vec3 b) | Cross product. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`normalize ` (vec_type x) | Normalize to unit length. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec3 | :js:attr:`reflect ` (vec3 I, vec3 N) | Reflect. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec3 | :js:attr:`refract ` (vec3 I, vec3 N, float eta) | Refract. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`faceforward ` (vec_type N, vec_type I, vec_type Nref) | If ``dot(Nref, I)`` < 0, return ``N``, otherwise ``-N``. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| mat_type | :js:attr:`matrixCompMult ` (mat_type x, mat_type y) | Matrix component multiplication. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| mat_type | :js:attr:`outerProduct ` (vec_type column, vec_type row) | Matrix outer product. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| mat_type | :js:attr:`transpose ` (mat_type m) | Transpose matrix. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| float | :js:attr:`determinant ` (mat_type m) | Matrix determinant. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| mat_type | :js:attr:`inverse ` (mat_type m) | Inverse matrix. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bvec_type | :js:attr:`lessThan ` (vec_type x, vec_type y) | Bool vector comparison on < int/uint/float vectors. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bvec_type | :js:attr:`greaterThan ` (vec_type x, vec_type y) | Bool vector comparison on > int/uint/float vectors. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bvec_type | :js:attr:`lessThanEqual ` (vec_type x, vec_type y) | Bool vector comparison on <= int/uint/float vectors. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bvec_type | :js:attr:`greaterThanEqual ` (vec_type x, vec_type y) | Bool vector comparison on >= int/uint/float vectors. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bvec_type | :js:attr:`equal ` (vec_type x, vec_type y) | Bool vector comparison on == int/uint/float vectors. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bvec_type | :js:attr:`notEqual ` (vec_type x, vec_type y) | Bool vector comparison on != int/uint/float vectors. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bool | :js:attr:`any ` (bvec_type x) | ``true`` if any component is ``true``, ``false`` otherwise. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bool | :js:attr:`all ` (bvec_type x) | ``true`` if all components are ``true``, ``false`` otherwise. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| bvec_type | :js:attr:`not ` (bvec_type x) | Invert boolean vector. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec2 | :js:attr:`textureSize ` (gsampler2D s, int lod) | Get the size of a texture. | -| | | | -| ivec3 | :js:attr:`textureSize ` (gsampler2DArray s, int lod) | The LOD defines which mipmap level is used. An LOD value of ``0`` | -| | | will use the full resolution texture. | -| ivec3 | :js:attr:`textureSize ` (gsampler3D s, int lod) | | -| | | | -| ivec2 | :js:attr:`textureSize ` (samplerCube s, int lod) | | -| | | | -| ivec2 | :js:attr:`textureSize ` (samplerCubeArray s, int lod) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec2 | :js:attr:`textureQueryLod ` (gsampler2D s, vec2 p) | Compute the level-of-detail that would be used to sample from a | -| | | texture. The ``x`` component of the resulted value is the mipmap | -| vec3 | :js:attr:`textureQueryLod ` (gsampler2DArray s, vec2 p) | array that would be accessed. The ``y`` component is computed | -| | | level-of-detail relative to the base level (regardless of the | -| vec2 | :js:attr:`textureQueryLod ` (gsampler3D s, vec3 p) | mipmap levels of the texture). | -| | | | -| vec2 | :js:attr:`textureQueryLod ` (samplerCube s, vec3 p) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| int | :js:attr:`textureQueryLevels ` (gsampler2D s) | Get the number of accessible mipmap levels of a texture. | -| | | | -| int | :js:attr:`textureQueryLevels ` (gsampler2DArray s) | If the texture is unassigned to a sampler, ``1`` is returned (Godot | -| | | always internally assigns a texture even to an empty sampler). | -| int | :js:attr:`textureQueryLevels ` (gsampler3D s) | | -| | | | -| int | :js:attr:`textureQueryLevels ` (samplerCube s) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| gvec4_type | :js:attr:`texture ` (gsampler2D s, vec2 p [, float bias]) | Perform a texture read. | -| | | | -| gvec4_type | :js:attr:`texture ` (gsampler2DArray s, vec3 p [, float bias]) | | -| | | | -| gvec4_type | :js:attr:`texture ` (gsampler3D s, vec3 p [, float bias]) | | -| | | | -| vec4 | :js:attr:`texture ` (samplerCube s, vec3 p [, float bias]) | | -| | | | -| vec4 | :js:attr:`texture ` (samplerCubeArray s, vec4 p [, float bias]) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| gvec4_type | :js:attr:`textureProj ` (gsampler2D s, vec3 p [, float bias]) | Perform a texture read with projection. | -| | | | -| gvec4_type | :js:attr:`textureProj ` (gsampler2D s, vec4 p [, float bias]) | | -| | | | -| gvec4_type | :js:attr:`textureProj ` (gsampler3D s, vec4 p [, float bias]) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| gvec4_type | :js:attr:`textureLod ` (gsampler2D s, vec2 p, float lod) | Perform a texture read at custom mipmap. | -| | | | -| gvec4_type | :js:attr:`textureLod ` (gsampler2DArray s, vec3 p, float lod) | The LOD defines which mipmap level is used. An LOD value of ``0.0`` | -| | | will use the full resolution texture. If the texture lacks mipmaps, | -| gvec4_type | :js:attr:`textureLod ` (gsampler3D s, vec3 p, float lod) | all LOD values will act like ``0.0``. | -| | | | -| vec4 | :js:attr:`textureLod ` (samplerCube s, vec3 p, float lod) | | -| | | | -| vec4 | :js:attr:`textureLod ` (samplerCubeArray s, vec4 p, float lod) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| gvec4_type | :js:attr:`textureProjLod ` (gsampler2D s, vec3 p, float lod) | Performs a texture read with projection/LOD. | -| | | | -| gvec4_type | :js:attr:`textureProjLod ` (gsampler2D s, vec4 p, float lod) | The LOD defines which mipmap level is used. An LOD value of ``0.0`` | -| | | will use the full resolution texture. If the texture lacks mipmaps, | -| gvec4_type | :js:attr:`textureProjLod ` (gsampler3D s, vec4 p, float lod) | all LOD values will act like ``0.0``. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| gvec4_type | :js:attr:`textureGrad ` (gsampler2D s, vec2 p, vec2 dPdx, vec2 dPdy) | Performs a texture read with explicit gradients. | -| | | | -| gvec4_type | :js:attr:`textureGrad ` (gsampler2DArray s, vec3 p, vec2 dPdx, vec2 dPdy) | | -| | | | -| gvec4_type | :js:attr:`textureGrad ` (gsampler3D s, vec3 p, vec2 dPdx, vec2 dPdy) | | -| | | | -| vec4 | :js:attr:`textureGrad ` (samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy) | | -| | | | -| vec4 | :js:attr:`textureGrad ` (samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ | -| gvec4_type | :js:attr:`textureProjGrad ` (gsampler2D s, vec3 p, vec2 dPdx, vec2 dPdy) | Performs a texture read with projection/LOD and with explicit | -| | | gradients. | -| gvec4_type | :js:attr:`textureProjGrad ` (gsampler2D s, vec4 p, vec2 dPdx, vec2 dPdy) | | -| | | | -| gvec4_type | :js:attr:`textureProjGrad ` (gsampler3D s, vec4 p, vec3 dPdx, vec3 dPdy) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| gvec4_type | :js:attr:`texelFetch ` (gsampler2D s, ivec2 p, int lod) |Fetches a single texel using integer coordinates. | -| | | | | -| gvec4_type | :js:attr:`texelFetch ` (gsampler2DArray s, ivec3 p, int lod) |The LOD defines which mipmap level is used. An LOD value of ``0`` | | -| | |will use the full resolution texture. | -| gvec4_type | :js:attr:`texelFetch ` (gsampler3D s, ivec3 p, int lod) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| gvec4_type | :js:attr:`textureGather ` (gsampler2D s, vec2 p [, int comps]) |Gathers four texels from a texture. | -| | |Use ``comps`` within range of 0..3 to | -| gvec4_type | :js:attr:`textureGather ` (gsampler2DArray s, vec3 p [, int comps]) |define which component (x, y, z, w) is returned. | -| | |If ``comps`` is not provided: 0 (or x-component) is used. | -| vec4 | :js:attr:`textureGather ` (samplerCube s, vec3 p [, int comps]) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`dFdx ` (vec_type p) | Derivative in ``x`` using local differencing. | -| | | Internally, can use either ``dFdxCoarse`` or ``dFdxFine``, but the | -| | | decision for which to use is made by the GPU driver. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`dFdxCoarse ` (vec_type p) | Calculates derivative with respect to ``x`` window coordinate using | -| | | local differencing based on the value of ``p`` for the current | -| | | fragment neighbour(s), and will possibly, but not necessarily, | -| | | include the value for the current fragment. | -| | | This function is not available on ``gl_compatibility`` profile. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`dFdxFine ` (vec_type p) | Calculates derivative with respect to ``x`` window coordinate using | -| | | local differencing based on the value of ``p`` for the current | -| | | fragment and its immediate neighbour(s). | -| | | This function is not available on ``gl_compatibility`` profile. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`dFdy ` (vec_type p) | Derivative in ``y`` using local differencing. | -| | | Internally, can use either ``dFdyCoarse`` or ``dFdyFine``, but the | -| | | decision for which to use is made by the GPU driver. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`dFdyCoarse ` (vec_type p) | Calculates derivative with respect to ``y`` window coordinate using | -| | | local differencing based on the value of ``p`` for the current | -| | | fragment neighbour(s), and will possibly, but not necessarily, | -| | | include the value for the current fragment. | -| | | This function is not available on ``gl_compatibility`` profile. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`dFdyFine ` (vec_type p) | Calculates derivative with respect to ``y`` window coordinate using | -| | | local differencing based on the value of ``p`` for the current | -| | | fragment and its immediate neighbour(s). | -| | | This function is not available on ``gl_compatibility`` profile. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`fwidth ` (vec_type p) | Sum of absolute derivative in ``x`` and ``y``. | -| | | This is the equivalent of using ``abs(dFdx(p)) + abs(dFdy(p))``. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`fwidthCoarse ` (vec_type p) | Sum of absolute derivative in ``x`` and ``y``. | -| | | This is the equivalent of using | -| | | ``abs(dFdxCoarse(p)) + abs(dFdyCoarse(p))``. | -| | | This function is not available on ``gl_compatibility`` profile. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`fwidthFine ` (vec_type p) | Sum of absolute derivative in ``x`` and ``y``. | -| | | This is the equivalent of using | -| | | ``abs(dFdxFine(p)) + abs(dFdyFine(p))``. | -| | | This function is not available on ``gl_compatibility`` profile. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| uint | :js:attr:`packHalf2x16 ` (vec2 v) | Convert two 32-bit floating-point numbers into 16-bit | -| | | and pack them into a 32-bit unsigned integer and vice-versa. | -| vec2 | :js:attr:`unpackHalf2x16 ` (uint v) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| uint | :js:attr:`packUnorm2x16 ` (vec2 v) | Convert two 32-bit floating-point numbers (clamped | -| | | within 0..1 range) into 16-bit and pack them | -| vec2 | :js:attr:`unpackUnorm2x16 ` (uint v) | into a 32-bit unsigned integer and vice-versa. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| uint | :js:attr:`packSnorm2x16 ` (vec2 v) | Convert two 32-bit floating-point numbers (clamped | -| | | within -1..1 range) into 16-bit and pack them | -| vec2 | :js:attr:`unpackSnorm2x16 ` (uint v) | into a 32-bit unsigned integer and vice-versa. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| uint | :js:attr:`packUnorm4x8 ` (vec4 v) | Convert four 32-bit floating-point numbers (clamped | -| | | within 0..1 range) into 8-bit and pack them | -| vec4 | :js:attr:`unpackUnorm4x8 ` (uint v) | into a 32-bit unsigned integer and vice-versa. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| uint | :js:attr:`packSnorm4x8 ` (vec4 v) | Convert four 32-bit floating-point numbers (clamped | -| | | within -1..1 range) into 8-bit and pack them | -| vec4 | :js:attr:`unpackSnorm4x8 ` (uint v) | into a 32-bit unsigned integer and vice-versa. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec_type | :js:attr:`bitfieldExtract ` (ivec_type value, int offset, int bits) | Extracts a range of bits from an integer. | -| | | | -| uvec_type | :js:attr:`bitfieldExtract ` (uvec_type value, int offset, int bits) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec_type | :js:attr:`bitfieldInsert ` (ivec_type base, ivec_type insert, int offset, int bits) | Insert a range of bits into an integer. | -| | | | -| uvec_type | :js:attr:`bitfieldInsert ` (uvec_type base, uvec_type insert, int offset, int bits) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec_type | :js:attr:`bitfieldReverse ` (ivec_type value) | Reverse the order of bits in an integer. | -| | | | -| uvec_type | :js:attr:`bitfieldReverse ` (uvec_type value) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec_type | :js:attr:`bitCount ` (ivec_type value) | Counts the number of 1 bits in an integer. | -| | | | -| uvec_type | :js:attr:`bitCount ` (uvec_type value) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec_type | :js:attr:`findLSB ` (ivec_type value) | Find the index of the least significant bit set to 1 in an integer. | -| | | | -| uvec_type | :js:attr:`findLSB ` (uvec_type value) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec_type | :js:attr:`findMSB ` (ivec_type value) | Find the index of the most significant bit set to 1 in an integer. | -| | | | -| uvec_type | :js:attr:`findMSB ` (uvec_type value) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| void | :js:attr:`imulExtended ` (ivec_type x, ivec_type y, out ivec_type msb, out ivec_type lsb) |Multiplies two 32-bit numbers and produce a 64-bit result. | -| | | | -| void | :js:attr:`umulExtended ` (uvec_type x, uvec_type y, out uvec_type msb, out uvec_type lsb) | | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| uvec_type | :js:attr:`uaddCarry ` (uvec_type x, uvec_type y, out uvec_type carry) | Adds two unsigned integers and generates carry. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| uvec_type | :js:attr:`usubBorrow ` (uvec_type x, uvec_type y, out uvec_type borrow) | Subtracts two unsigned integers and generates borrow. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`ldexp ` (vec_type x, out ivec_type exp) | Assemble a floating-point number from a value and exponent. | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec_type | :js:attr:`frexp ` (vec_type x, out ivec_type exp) | Splits a floating-point number (``x``) into significand integral | -| | | components | -+-------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ - - -.. js:function:: radians( vec_type degrees ) - - ``radians`` converts a quantity specified in degrees into radians. - - `GLSL documentation `_ - - :param vec_type degrees: - Specify the quantity, in degrees, to be converted to radians. - - :return: - The return value is ``(Ï€ * degrees) / 180``. - - :rtype: vec_type - -.. js:function:: degrees (vec_type radians) - - ``degrees`` converts a quantity specified in radians into degrees. - - `GLSL documentation `_. - - :param vec_type radians: - Specify the quantity, in radians, to be converted to degrees. - - :return: - The return value is ``(radians * 180) / Ï€``. - - :rtype: vec_type - -.. js:function:: sin (vec_type angle) - - `GLSL documentation `_. - - :param vec_type angle: - The quantity, in radians, of which to return the sine - - :return: - The return value is the trigonometric sine of ``angle``. - - :rtype: vec_type - -.. js:function:: cos (vec_type angle) - - `GLSL documentation `_. - - :param vec_type angle: - The quantity, in radians, of which to return the cosine. - - :return: - The return value is the trigonometric cosine of ``angle``. - - :rtype: vec_type - -.. js:function:: tan (vec_type angle) - - `GLSL documentation `_. - - :param vec_type angle: - The quantity, in radians, of which to return the tangent. - - :return: - The return value is the trigonometric tangent of ``angle``. - - :rtype: vec_type - -.. js:function:: asin (vec_type x) - - Calculates the angle whose sine is ``x``. - The result is undefined if ``x < -1`` or ``x > 1``. - - `GLSL documentation `_. - - :param vec_type x: - The value whose arccosine to return. - :return: - The return value is the angle whose trigonometric sine is ``x`` and is - in the range ``[-Ï€/2, Ï€/2]``. - - :rtype: vec_type - -.. js:function:: acos (vec_type x) - - Calculates the angle whose cosine is ``x``. - The result is undefined if ``x < -1`` or ``x > 1``. - - `GLSL documentation `_. - - :param vec_type x: - The value whose arccosine to return. - - :return: - The return value is the angle whose trigonometric cosine is ``x`` and - is in the range ``[0, Ï€]``. - - :rtype: vec_type - -.. js:function:: atan (vec_type y_over_x) - - Calculate the arctangent given a tangent value of ``y/x``. Note: becuase of - the sign ambiguity, the function cannot determine with certainty in which - quadrant the angle falls only by its tangent value. If you need to know the - quadrant, use the other overload of ``atan``. - - `GLSL documentation `_. - - :param vec_type y_over_x: - The fraction whose arctangent to return. - - :return: - The return value is the trigonometric arc-tangent of ``y_over_x`` and is - in the range ``[−π/2, Ï€/2]``. - - :rtype: vec_type - -.. js:function:: atan (vec_type y, vec_type x) - - Calculate the arctangent given a numerator and denominator. The signs of - ``y`` and ``x`` are used to determine the quadrant that the angle lies in. - The result is undefined if ``x == 0``. - - `GLSL documentation `_. - - :param vec_type y: - The numerator of the fraction whose arctangent to return. - - :param vec_type x: - The denominator of the fraction whose arctangent to return. - - :return: - The return value is the trigonometric arc-tangent of ``y/x`` and is in - the range ``[−π, Ï€]``. - - :rtype: vec_type - -.. js:function:: sinh (vec_type x) - - Calculates the hyperbolic sine using ``(e^x - e^-x)/2``. - `GLSL documentation `_. - - :param vec_type x: - The value whose hyperbolic sine to return. - - :return: - The return value is the hyperbolic sine of ``x``. - - :rtype: vec_type - -.. js:function:: cosh (vec_type x) - - Calculates the hyperbolic cosine using ``(e^x + e^-x)/2``. - `GLSL documentation `_. - - :param vec_type x: - The value whose hyperbolic cosine to return. - - :return: - The return value is the hyperbolic cosine of ``x``. - - :rtype: vec_type - -.. js:function:: tanh (vec_type x) - - Calculates the hyperbolic tangent using ``sinh(x)/cosh(x)``. - `GLSL documentation `_. - - :param vec_type x: - The value whose hyperbolic tangent to return. - - :return: - The return value is the hyperbolic tangent of ``x``. - - :rtype: vec_type - -.. js:function:: asinh (vec_type x) - - Calculates the arc hyperbolic sine of a value. - - `GLSL documentation `_. - - :param vec_type x: - The value whose arc hyperbolic sine to return. - - :return: - The return value is the arc hyperbolic sine of ``x`` which is the - inverse of sinh. - - :rtype: vec_type - -.. js:function:: acosh (vec_type x) - - Calculates the arc hyperbolic cosine of a value. - The result is undefined if ``x < 1``. - - `GLSL documentation `_. - - :param vec_type x: - The value whose arc hyperbolic cosine to return. - - :return: - The return value is the arc hyperbolic cosine of ``x`` which is the - inverse of cosh. - - :rtype: vec_type - -.. js:function:: atanh (vec_type x) - - Calculate the arctangent given a tangent value of ``y/x``. Note: becuase of - the sign ambiguity, the function cannot determine with certainty in which - quadrant the angle falls only by its tangent value. If you need to know the - quadrant, use the other overload of ``atan``. - - The result is undefined if ``x < -1`` or ``x > 1``. - - `GLSL documentation `_. - - :param vec_type y_over_x: - The fraction whose arc hyperbolic tangent to return. - - :return: - The return value is the arc hyperbolic tangent of ``x`` which is the - inverse of tanh. - - :rtype: vec_type - -.. js:function:: pow (vec_type x, vec_type y) - - Raises ``x`` to the power of ``y``. - - The result is undefined if ``x < 0`` or if ``x == 0`` and ``y <= 0``. - - `GLSL documentation `_. - - :param vec_type x: - The value to be raised to the power ``y``. - - :param vec_type y: - The power to which ``x`` will be raised. - - :return: - Returns the value of ``x`` raised to the ``y`` power. - - :rtype: vec_type - -.. js:function:: exp (vec_type x) - - - `GLSL documentation <>`_. - - :param vec_type radians: - - :return: -The return value is - - :rtype: vec_type - -.. js:function:: exp2 (vec_type x) - - `GLSL documentation <>`_. - - :param vec_type radians: - - :return: -The return value is - - :rtype: vec_type - -.. js:function:: log (vec_type x) - - `GLSL documentation <>`_. - - :param vec_type radians: - - :return: -The return value is - - :rtype: vec_type - -.. js:function:: log2 (vec_type x) - - `GLSL documentation <>`_. - - :param vec_type radians: - - :return: -The return value is - - :rtype: vec_type - -.. js:function:: sqrt (vec_type x) - - `GLSL documentation <>`_. - - :param vec_type radians: - - :return: -The return value is - - :rtype: vec_type - -.. js:function:: inversesqrt (vec_type x) - - `GLSL documentation <>`_. - - :param vec_type radians: - - :return: -The return value is - - :rtype: vec_type - -.. js:function:: abs (vec_type x) - - `GLSL documentation <>`_. - - :param vec_type radians: - - :return: -The return value is - - :rtype: vec_type - -.. js:function:: abs (ivec_type x) - - `GLSL documentation <>`_. - - :param ivec_type x: - - :return: -The return value is - - :rtype: ivec_type - -.. js:function:: sign (vec_type x) - - `GLSL documentation <>`_. - - :param vec_type radians: - - :return: -The return value is - - :rtype: vec_type - -.. js:function:: sign (ivec_type x) - - `GLSL documentation <>`_. - - :param ivec_type x: - - :return: -The return value is - - :rtype: ivec_type - -.. js:function:: floor (vec_type x) - - `GLSL documentation <>`_. - - :param vec_type radians: - - :return: -The return value is - - :rtype: vec_type - -.. js:function:: round (vec_type x) - - `GLSL documentation <>`_. - - :param vec_type radians: - - :return: -The return value is - - :rtype: vec_type - -.. js:function:: roundEven (vec_type x) - - `GLSL documentation <>`_. - - :param vec_type radians: - - :return: -The return value is - - :rtype: vec_type - -.. js:function:: trunc (vec_type x) - - `GLSL documentation <>`_. - - :param vec_type radians: - - :return: -The return value is - - :rtype: vec_type - -.. js:function:: ceil (vec_type x) - - `GLSL documentation <>`_. - - :param vec_type radians: - - :return: -The return value is - - :rtype: vec_type - -.. js:function:: fract (vec_type x) - - `GLSL documentation <>`_. - - :param vec_type radians: - - :return: -The return value is - - :rtype: vec_type - -.. js:function:: mod (vec_type x, vec_type y) - -.. js:function:: mod (vec_type x, float y) - -.. js:function:: modf (vec_type x, out vec_type i) - -.. js:function:: min (vec_type a, vec_type b) - -.. js:function:: max (vec_type a, vec_type b) - -.. js:function:: clamp (vec_type x, vec_type min, vec_type max) - -.. js:function:: mix (float a, float b, float c) - -.. js:function:: mix (vec_type a, vec_type b, float c) - -.. js:function:: mix (vec_type a, vec_type b, bvec_type c) - -.. js:function:: fma (vec_type a, vec_type b, vec_type c) - -.. js:function:: step (vec_type a, vec_type b) - -.. js:function:: step (float a, vec_type b) - -.. js:function:: smoothstep (vec_type a, vec_type b, vec_type c) - -.. js:function:: smoothstep (float a, float b, vec_type c) - -.. js:function:: isnan (vec_type x) - -.. js:function:: isinf (vec_type x) - -.. js:function:: floatBitsToInt (vec_type x) - -.. js:function:: floatBitsToUint (vec_type x) - -.. js:function:: intBitsToFloat (ivec_type x) - -.. js:function:: uintBitsToFloat (uvec_type x) - -.. js:function:: length (vec_type x) - -.. js:function:: distance (vec_type a, vec_type b) - -.. js:function:: dot (vec_type a, vec_type b) - -.. js:function:: cross (vec3 a, vec3 b) - -.. js:function:: normalize (vec_type x) - -.. js:function:: reflect (vec3 I, vec3 N) - -.. js:function:: refract (vec3 I, vec3 N, float eta) - -.. js:function:: faceforward (vec_type N, vec_type I, vec_type Nref) - -.. js:function:: matrixCompMult (mat_type x, mat_type y) - -.. js:function:: outerProduct (vec_type column, vec_type row) - -.. js:function:: transpose (mat_type m) - -.. js:function:: determinant (mat_type m) - -.. js:function:: inverse (mat_type m) - -.. js:function:: lessThan (vec_type x, vec_type y) - -.. js:function:: greaterThan (vec_type x, vec_type y) - -.. js:function:: lessThanEqual (vec_type x, vec_type y) - -.. js:function:: greaterThanEqual (vec_type x, vec_type y) - -.. js:function:: equal (vec_type x, vec_type y) - -.. js:function:: notEqual (vec_type x, vec_type y) - -.. js:function:: any (bvec_type x) - -.. js:function:: all (bvec_type x) - -.. js:function:: not (bvec_type x) - - ``degrees`` converts a quantity specified in radians into degrees. - `GLSL documentation `_ - - :param bvec_type x: -Specify the quantity, in radians, to be converted to degrees. - - :return: -The return value is ``(radians * 180) / Ï€``. - - :rtype: bool - -.. js:function:: textureSize (gsampler2D s, int lod) -.. js:function:: textureSize (gsampler2DArray s, int lod) -.. js:function:: textureSize (gsampler3D s, int lod) -.. js:function:: textureSize (samplerCube s, int lod) -.. js:function:: textureSize (samplerCubeArray s, int lod) - - ``degrees`` converts a quantity specified in radians into degrees. - `GLSL documentation `_ - - :param sampler_type s: -Specify the quantity, in radians, to be converted to degrees. - - :param int lod: -Specify the quantity, in radians, to be converted to degrees. - - :return: -The return value is ``(radians * 180) / Ï€``. - - :rtype: vec_type - -.. js:function:: texture (gsampler2D s, vec2 p [, float bias]) -.. js:function:: texture (gsampler2DArray s, vec3 p [, float bias]) -.. js:function:: texture (gsampler3D s, vec3 p [, float bias]) -.. js:function:: texture (samplerCube s, vec3 p [, float bias]) -.. js:function:: texture (samplerCubeArray s, vec4 p [, float bias]) - -.. js:function:: textureProj (gsampler2D s, vec3 p [, float bias]) -.. js:function:: textureProj (gsampler2D s, vec4 p [, float bias]) -.. js:function:: textureProj (gsampler3D s, vec4 p [, float bias]) - -.. js:function:: textureLod (gsampler2D s, vec2 p, float lod) -.. js:function:: textureLod (gsampler2DArray s, vec3 p, float lod) -.. js:function:: textureLod (gsampler3D s, vec3 p, float lod) -.. js:function:: textureLod (samplerCube s, vec3 p, float lod) -.. js:function:: textureLod (samplerCubeArray s, vec4 p, float lod) - -.. js:function:: textureProjLod (gsampler2D s, vec3 p, float lod) -.. js:function:: textureProjLod (gsampler2D s, vec4 p, float lod) -.. js:function:: textureProjLod (gsampler3D s, vec4 p, float lod) - -.. js:function:: textureGrad (gsampler2D s, vec2 p, vec2 dPdx, vec2 dPdy) -.. js:function:: textureGrad (gsampler2DArray s, vec3 p, vec2 dPdx, vec2 dPdy) -.. js:function:: textureGrad (gsampler3D s, vec3 p, vec2 dPdx, vec2 dPdy) -.. js:function:: textureGrad ` (samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy) -.. js:function:: textureGrad ` (samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy) - -.. js:function:: texelFetch ` (gsampler2D s, ivec2 p, int lod) -.. js:function:: texelFetch ` (gsampler2DArray s, ivec3 p, int lod) -.. js:function:: texelFetch ` (gsampler3D s, ivec3 p, int lod) - -.. js:function:: textureGather ` (gsampler2D s, vec2 p [, int comps]) -.. js:function:: textureGather ` (gsampler2DArray s, vec3 p [, int comps]) -.. js:function:: textureGather ` (samplerCube s, vec3 p [, int comps]) - -.. js:function:: dFdx (vec_type p) - -.. js:function:: dFdy (vec_type p) - -.. js:function:: fwidth (vec_type p) - -.. js:function:: packHalf2x16 (vec2 v) -.. js:function:: unpackHalf2x16 (uint v) - -.. js:function:: packUnorm2x16 (vec2 v) -.. js:function:: unpackUnorm2x16 (uint v) - -.. js:function:: packSnorm2x16 (vec2 v) -.. js:function:: unpackSnorm2x16 (uint v) - -.. js:function:: packUnorm4x8 (vec4 v) -.. js:function:: unpackUnorm4x8 (uint v) - -.. js:function:: packSnorm4x8 (vec4 v) -.. js:function:: unpackSnorm4x8 (uint v) - -.. js:function:: bitfieldExtract (ivec_type value, int offset, int bits) -.. js:function:: bitfieldExtract (uvec_type value, int offset, int bits) - -.. js:function:: bitfieldInsert (ivec_type base, ivec_type insert, int offset, int bits) -.. js:function:: bitfieldInsert (uvec_type base, uvec_type insert, int offset, int bits) - -.. js:function:: bitfieldReverse (ivec_type value) -.. js:function:: bitfieldReverse (uvec_type value) - -.. js:function:: bitCount (ivec_type value) -.. js:function:: bitCount (uvec_type value) - -.. js:function:: findLSB (ivec_type value) -.. js:function:: findLSB (uvec_type value) - -.. js:function:: findMSB (ivec_type value) -.. js:function:: findMSB (uvec_type value) - -.. js:function:: imulExtended (ivec_type x, ivec_type y, out ivec_type msb, out ivec_type lsb) -.. js:function:: umulExtended (uvec_type x, uvec_type y, out uvec_type msb, out uvec_type lsb) - -.. js:function:: uaddCarry (uvec_type x, uvec_type y, out uvec_type carry) - -.. js:function:: usubBorrow (uvec_type x, uvec_type y, out uvec_type borrow) - -.. js:function:: ldexp (vec_type x, out ivec_type exp) - -.. js:function:: frexp (vec_type x, out ivec_type exp) \ No newline at end of file From 15f5c413842d1c8cc1bf97c62c464648d2930d1a Mon Sep 17 00:00:00 2001 From: ashbygeek Date: Fri, 3 May 2024 22:29:09 -0400 Subject: [PATCH 03/25] Copy-Paste more shader functions --- .../shader_reference/shader_functions.rst | 2036 ++++++++++++++--- 1 file changed, 1748 insertions(+), 288 deletions(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index addea286c8f..14eebdd4224 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -21,6 +21,8 @@ GLSL 4.00 specification. +-----------------+--------------------------------------------------+--------------------------+ | mat_type | mat2, mat3, or mat4 | mat | +-----------------+--------------------------------------------------+--------------------------+ + | gvec4_type | vec4, ivec4, or uvec4 | | + +-----------------+--------------------------------------------------+--------------------------+ | gsampler2D | sampler2D, isampler2D, uSampler2D | | +-----------------+--------------------------------------------------+--------------------------+ | gsampler2DArray | sampler2DArray, isampler2DArray, uSampler2DArray | | @@ -28,14 +30,25 @@ GLSL 4.00 specification. | gsampler3D | sampler3D, isampler3D, uSampler3D | | +-----------------+--------------------------------------------------+--------------------------+ - If any of these are specified for multiple parameters, they must all be the same type unless otherwise noted. +.. note:: + Most operations on vectors (multiplication, division, etc) are performed component-wise. + For example, the operation ``vec2(3,4) * vec2(10,20)`` would result in ``vec2(3 * 10, 4 * 20)``. + As another exmple, the operation ``min(vec2(3,4), vec2(1,8))`` would result in ``vec2(min(3,1),min(4,8))``. + + The `GLSL Language Specification ` says under section 5.10 Vector and Matrix Operations: + + With a few exceptions, operations are component-wise. Usually, when an operator operates on a + vector or matrix, it is operating independently on each component of the vector or matrix, + in a component-wise fashion. [...] The exceptions are matrix multiplied by vector, + vector multiplied by matrix, and matrix multiplied by matrix. These do not operate component-wise, + but rather perform the correct linear algebraic multiply. .. rst-class:: classref-reftable-group Trigonometric Functions ------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^ +-----------------+-------------------------------------------------------------+-----------------------------+ | Return Type | Function | Description / Return value | @@ -402,8 +415,7 @@ vec_type acosh( |vec_type| x) The value whose arc hyperbolic cosine to return. :return: - The return value is the arc hyperbolic cosine of ``x`` which is the - inverse of cosh. + :rtype: |vec_type| @@ -445,10 +457,10 @@ vec_type atanh( |vec_type| x) Exponential and Common Math Functions ------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`pow` ( |vec_type| x, |vec_type| y) | Power (undefined if ``x`` < 0 or if ``x`` == 0 and ``y`` <= 0). | +| |vec_type| | :ref:`pow` ( |vec_type| x, |vec_type| y) | Power (undefined if ``x < 0`` or if ``x == 0`` and ``y <= 0``). | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ | |vec_type| | :ref:`exp` ( |vec_type| x) | Base-e exponential. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ @@ -466,9 +478,9 @@ Exponential and Common Math Functions +-----------------+---------------------------------------------------------------------------------------------+ | | |vec_int_type| | :ref:`abs` ( |vec_int_type| x) | | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`sign` ( |vec_type| x) | Sign (returns ``1.0`` if positive, ``-1.0`` if negative, | +| |vec_type| | :ref:`sign` ( |vec_type| x) | returns ``1.0`` if positive, ``-1.0`` if negative, | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_int_type| | :ref:`sign` ( |vec_int_type| x) | Sign (returns ``1`` if positive, ``-1`` if negative, | +| |vec_int_type| | :ref:`sign` ( |vec_int_type| x) | returns ``1`` if positive, ``-1`` if negative, | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ | |vec_type| | :ref:`floor` ( |vec_type| x) | Round to the integer below. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ @@ -491,46 +503,46 @@ Exponential and Common Math Functions | |vec_type| | :ref:`min` ( |vec_type| a, |vec_type| b) | Lowest value between ``a`` and ``b``. | +-----------------+---------------------------------------------------------------------------------------------+ | | |vec_type| | :ref:`min` ( |vec_type| a, float b) | | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_int_type| | :ref:`min` ( |vec_int_type| a, |vec_int_type| b) | Lowest value between ``a`` and ``b``. | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_int_type| | :ref:`min` ( |vec_int_type| a, |vec_int_type| b) | | +-----------------+---------------------------------------------------------------------------------------------+ | | |vec_int_type| | :ref:`min` ( |vec_int_type| a, int b) | | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_uint_type| | :ref:`min` ( |vec_uint_type| a, |vec_uint_type| b) | Lowest value between ``a`` and ``b``. | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_uint_type| | :ref:`min` ( |vec_uint_type| a, |vec_uint_type| b) | | +-----------------+---------------------------------------------------------------------------------------------+ | | |vec_uint_type| | :ref:`min` ( |vec_uint_type| a, uint b) | | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ | |vec_type| | :ref:`max` ( |vec_type| a, |vec_type| b) | Highest value between ``a`` and ``b``. | +-----------------+---------------------------------------------------------------------------------------------+ | | |vec_type| | :ref:`max` ( |vec_type| a, float b) | | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_uint_type| | :ref:`max` ( |vec_uint_type| a, |vec_uint_type| b) | Highest value between ``a`` and ``b``. | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_uint_type| | :ref:`max` ( |vec_uint_type| a, |vec_uint_type| b) | | +-----------------+---------------------------------------------------------------------------------------------+ | | |vec_uint_type| | :ref:`max` ( |vec_uint_type| a, uint b) | | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_int_type| | :ref:`max` ( |vec_int_type| a, |vec_int_type| b) | Highest value between ``a`` and ``b``. | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_int_type| | :ref:`max` ( |vec_int_type| a, |vec_int_type| b) | | +-----------------+---------------------------------------------------------------------------------------------+ | | |vec_int_type| | :ref:`max` ( |vec_int_type| a, int b) | | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ | |vec_type| | :ref:`clamp` (vecType x, |vec_type| min, |vec_type| max) | Clamp ``x`` between ``min`` and ``max`` (inclusive). | +-----------------+---------------------------------------------------------------------------------------------+ | | |vec_type| | :ref:`clamp` ( |vec_type| x, float min, float max) | | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_uint_type| | :ref:`clamp` ( |vec_int_type| x, |vec_int_type| min, |vec_int_type| max) | Clamp ``x`` between ``min`` and ``max`` (inclusive). | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | ref:`clamp` ( |vec_int_type| x, float min, float max) | | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_int_type| | :ref:`clamp` (vecType x, |vec_type| min, |vec_type| max) | Clamp ``x`` between ``min`` and ``max`` (inclusive). | +| |vec_uint_type| | :ref:`clamp` ( |vec_int_type| x, |vec_int_type| min, |vec_int_type| max) | | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_uint_type| | :ref:`clamp` ( |vec_int_type| x, float min, float max) | | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_int_type| | :ref:`clamp` (vecType x, |vec_type| min, |vec_type| max) | | +-----------------+---------------------------------------------------------------------------------------------+ | | |vec_int_type| | :ref:`clamp` ( |vec_type| x, float min, float max) | | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ | float | :ref:`mix` (float a, float b, float c) | Linear interpolate between ``a`` and ``b`` by ``c``. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`mix` (vecType a, |vec_type| b, float c) | Linear interpolate between ``a`` and ``b`` by ``c``. | ++-----------------+---------------------------------------------------------------------------------------------+ | +| |vec_type| | :ref:`mix` (vecType a, |vec_type| b, float c) | | +-----------------+---------------------------------------------------------------------------------------------+ | | |vec_type| | :ref:`mix` (vecType a, |vec_type| b, |vec_type| c) | | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_type| | :ref:`mix` (vecType a, |vec_type| b, |vec_bool_type| c) | | +| |vec_type| | :ref:`mix` (vecType a, |vec_type| b, |vec_bool_type| c) | | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ | |vec_type| | :ref:`fma` (vecType a, |vec_type| b, |vec_type| c) | Fused multiply-add operation: ``(a * b + c)`` | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ @@ -560,317 +572,1764 @@ Exponential and Common Math Functions ---- +.. _shader_func_pow: +.. rst-class:: classref-method -Geometric Functions ------------------------------------------- +vec_type pow( |vec_type| x, |vec_type| y) -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`length` ( |vec_type| x) | Vector length. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`distance` ( |vec_type| a, |vec_type| b) | Distance between vectors i.e ``length(a - b)``. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`dot` ( |vec_type| a, |vec_type| b) | Dot product. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| vec3 | :ref:`cross` (vec3 a, vec3 b) | Cross product. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |vec_type| | :ref:`normalize` ( |vec_type| x) | Normalize to unit length. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| vec3 | :ref:`reflect` (vec3 I, vec3 N) | Reflect. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| vec3 | :ref:`refract` (vec3 I, vec3 N, float eta) | Refract. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |vec_type| | :ref:`faceforward` (vecType N, |vec_type| I, |vec_type| Nref) | If ``dot(Nref, I)`` < 0, return ``N``, otherwise ``-N``. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`matrixCompMult` (|mat_type| x, |mat_type| y) | Matrix component multiplication. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`outerProduct` ( |vec_type| column, |vec_type| row) | Matrix outer product. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`transpose` (|mat_type| m) | Transpose matrix. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`determinant` (|mat_type| m) | Matrix determinant. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`inverse` (|mat_type| m) | Inverse matrix. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ + Raises ``x`` to the power of ``y``. -.. rst-class:: classref-section-separator + The result is undefined if ``x < 0`` or if ``x == 0`` and ``y <= 0``. ----------- + :param x: + The value to be raised to the power ``y``. + :param y: + The power to which ``x`` will be raised. -Comparison Functions -------------------------- + :return: + Returns the value of ``x`` raised to the ``y`` power. -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`lessThan` ( |vec_type| x, |vec_type| y) | Bool vector comparison on < int/uint/float vectors. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`greaterThan` ( |vec_type| x, |vec_type| y) | Bool vector comparison on > int/uint/float vectors. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`lessThanEqual` ( |vec_type| x, |vec_type| y) | Bool vector comparison on <= int/uint/float vectors. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`greaterThanEqual` ( |vec_type| x, |vec_type| y) | Bool vector comparison on >= int/uint/float vectors. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`equal` ( |vec_type| x, |vec_type| y) | Bool vector comparison on == int/uint/float vectors. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`notEqual` ( |vec_type| x, |vec_type| y) | Bool vector comparison on != int/uint/float vectors. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| bool | :ref:`any` ( |vec_bool_type| x) | ``true`` if any component is ``true``, ``false`` otherwise. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| bool | :ref:`all` ( |vec_bool_type| x) | ``true`` if all components are ``true``, ``false`` otherwise. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`not` ( |vec_bool_type| x) | Invert boolean vector. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ + :rtype: |vec_type| -.. rst-class:: classref-section-separator + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/pow.xhtml + +.. rst-class:: classref-item-separator ---- -Texture Functions ------------------------------------------- +.. _shader_func_exp: -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec2 | :ref:`textureSize` ( |gsampler2D| s, int lod) | Get the size of a texture. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| ivec2 | :ref:`textureSize` (samplerCube s, int lod) | The LOD defines which mipmap level is used. An LOD value of ``0`` | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| ivec2 | :ref:`textureSize` (samplerCubeArray s, int lod) | will use the full resolution texture. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| ivec3 | :ref:`textureSize` ( |gsampler2DArray| s, int lod) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| ivec3 | :ref:`textureSize` ( |gsampler3D| s, int lod) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec2 | :ref:`textureQueryLod` ( |gsampler2D| s, vec2 p) | Compute the level-of-detail that would be used to sample from a | -+--------------+-----------------------------------------------------------------------------------------------------+ texture. The ``x`` component of the resulted value is the mipmap | -| vec3 | :ref:`textureQueryLod` ( |gsampler2DArray| s, vec2 p) | array that would be accessed. The ``y`` component is computed | -+--------------+-----------------------------------------------------------------------------------------------------+ level-of-detail relative to the base level (regardless of the | -| vec2 | :ref:`textureQueryLod` ( |gsampler3D| s, vec3 p) | mipmap levels of the texture). | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec2 | :ref:`textureQueryLod` (samplerCube s, vec3 p) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| int | :ref:`textureQueryLevels` ( |gsampler2D| s) | Get the number of accessible mipmap levels of a texture. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| int | :ref:`textureQueryLevels` ( |gsampler2DArray| s) | If the texture is unassigned to a sampler, ``1`` is returned (Godot | -+--------------+-----------------------------------------------------------------------------------------------------+ always internally assigns a texture even to an empty sampler). | -| int | :ref:`textureQueryLevels` ( |gsampler3D| s) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| int | :ref:`textureQueryLevels` (samplerCube s) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`texture` ( |gsampler2D| s, vec2 p [, float bias]) | Perform a texture read. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`texture` ( |gsampler2DArray| s, vec3 p [, float bias]) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |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]) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |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]) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureProj` ( |gsampler3D| s, vec4 p [, float bias]) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureLod` ( |gsampler2D| s, vec2 p, float lod) | Perform a texture read at custom mipmap. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureLod` ( |gsampler2DArray| s, vec3 p, float lod) | The LOD defines which mipmap level is used. An LOD value of ``0.0`` | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| | | will use the full resolution texture. If the texture lacks mipmaps, | -| |gvec4_type| | :ref:`textureLod` ( |gsampler3D| s, vec3 p, float lod) | all LOD values will act like ``0.0``. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureLod` (samplerCube s, vec3 p, float lod) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureLod` (samplerCubeArray s, vec4 p, float lod) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec3 p, float lod) | Performs a texture read with projection/LOD. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec4 p, float lod) | The LOD defines which mipmap level is used. An LOD value of ``0.0`` | -| | | will use the full resolution texture. If the texture lacks mipmaps, | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureProjLod` ( |gsampler3D| s, vec4 p, float lod) | all LOD values will act like ``0.0``. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureGrad` ( |gsampler2D| s, vec2 p, vec2 dPdx, vec2 dPdy) | Performs a texture read with explicit gradients. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureGrad` ( |gsampler2DArray| s, vec3 p, vec2 dPdx, vec2 dPdy) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureGrad` ( |gsampler3D| s, vec3 p, vec2 dPdx, vec2 dPdy) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureGrad` (samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureGrad` (samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy) | Performs a texture read with projection/LOD and with explicit | -| | | gradients. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`texelFetch` ( |gsampler2D| s, ivec2 p, int lod) | Fetches a single texel using integer coordinates. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`texelFetch` ( |gsampler2DArray| s, ivec3 p, int lod) | The LOD defines which mipmap level is used. An LOD value of ``0`` | -| | | will use the full resolution texture. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`texelFetch` ( |gsampler3D| s, ivec3 p, int lod) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureGather` ( |gsampler2D| s, vec2 p [, int comps]) | Gathers four texels from a texture. | -| | | Use ``comps`` within range of 0..3 to | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureGather` ( |gsampler2DArray| s, vec3 p [, int comps]) | define which component (x, y, z, w) is returned. | -| | | If ``comps`` is not provided: 0 (or x-component) is used. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureGather` (samplerCube s, vec3 p [, int comps]) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdx` ( |vec_type| p) | Derivative in ``x`` using local differencing. | -| | | Internally, can use either ``dFdxCoarse`` or ``dFdxFine``, but the | -| | | decision for which to use is made by the GPU driver. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdxCoarse` ( |vec_type| p) | Calculates derivative with respect to ``x`` window coordinate using | -| | | local differencing based on the value of ``p`` for the current | -| | | fragment neighbour(s), and will possibly, but not necessarily, | -| | | include the value for the current fragment. | -| | | Not available on ``gl_compatibility`` profile. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdxFine` ( |vec_type| p) | Calculates derivative with respect to ``x`` window coordinate using | -| | | local differencing based on the value of ``p`` for the current | -| | | fragment and its immediate neighbour(s). | -| | | Not available on ``gl_compatibility`` profile. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdy` ( |vec_type| p) | Derivative in ``y`` using local differencing. | -| | | Internally, can use either ``dFdyCoarse`` or ``dFdyFine``, but the | -| | | decision for which to use is made by the GPU driver. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdyCoarse` ( |vec_type| p) | Calculates derivative with respect to ``y`` window coordinate using | -| | | local differencing based on the value of ``p`` for the current | -| | | fragment neighbour(s), and will possibly, but not necessarily, | -| | | include the value for the current fragment. | -| | | Not available on ``gl_compatibility`` profile. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdyFine` ( |vec_type| p) | Calculates derivative with respect to ``y`` window coordinate using | -| | | local differencing based on the value of ``p`` for the current | -| | | fragment and its immediate neighbour(s). | -| | | Not available on ``gl_compatibility`` profile. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`fwidth` ( |vec_type| p) | Sum of absolute derivative in ``x`` and ``y``. | -| | | This is the equivalent of using ``abs(dFdx(p)) + abs(dFdy(p))``. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`fwidthCoarse` ( |vec_type| p) | Sum of absolute derivative in ``x`` and ``y``. | -| | | Not available on ``gl_compatibility`` profile. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`fwidthFine` ( |vec_type| p) | Sum of absolute derivative in ``x`` and ``y``. | -| | | Not available on ``gl_compatibility`` profile. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +.. rst-class:: classref-method -.. rst-class:: classref-section-separator +|vec_type| **exp** ( |vec_type| x ) ----- + Return the natural exponentiation of the parameter. + :param x: + The value to exponentiate. + :return: + The natural exponentiation of x. i.e., e\ :sup:`x` -Packing/Unpacking Functions ------------------------------------------- + :rtype: |vec_type| -+------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packHalf2x16` (vec2 v) | Convert two 32-bit floating-point numbers into 16-bit | -| | | and pack them into a 32-bit unsigned integer and vice-versa. | -| vec2 | :ref:`unpackHalf2x16` (uint v) | | -+------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packUnorm2x16` (vec2 v) | Convert two 32-bit floating-point numbers (clamped | -| | | within 0..1 range) into 16-bit and pack them | -| vec2 | :ref:`unpackUnorm2x16` (uint v) | into a 32-bit unsigned integer and vice-versa. | -+------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packSnorm2x16` (vec2 v) | Convert two 32-bit floating-point numbers (clamped | -| | | within -1..1 range) into 16-bit and pack them | -| vec2 | :ref:`unpackSnorm2x16` (uint v) | into a 32-bit unsigned integer and vice-versa. | -+------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packUnorm4x8` (vec4 v) | Convert four 32-bit floating-point numbers (clamped | -| | | within 0..1 range) into 8-bit and pack them | -| vec4 | :ref:`unpackUnorm4x8` (uint v) | into a 32-bit unsigned integer and vice-versa. | -+------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packSnorm4x8` (vec4 v) | Convert four 32-bit floating-point numbers (clamped | -| | | within -1..1 range) into 8-bit and pack them | -| vec4 | :ref:`unpackSnorm4x8` (uint v) | into a 32-bit unsigned integer and vice-versa. | -+------+--------------------------------------------------------------+--------------------------------------------------------------+ + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/exp.xhtml -.. rst-class:: classref-section-separator +.. rst-class:: classref-item-separator ---- -Bitwise operations ------------------------------------------- +.. _shader_func_exp2: -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`bitfieldExtract` ( |vec_int_type| value, int offset, int bits) | Extracts a range of bits from an integer. | -| | | | -| |vec_uint_type| | :ref:`bitfieldExtract` ( |vec_uint_type| value, int offset, int bits) | | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`bitfieldInsert` ( |vec_int_type| base, |vec_int_type| insert, | Insert a range of bits into an integer. | -| | int offset, int bits) | | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`bitfieldInsert` (|vec_uint_type| base, |vec_uint_type| insert, int offset, | | -| | int bits) | | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`bitfieldReverse` ( |vec_int_type| value) | Reverse the order of bits in an integer. | -| | | | -| |vec_uint_type| | :ref:`bitfieldReverse` ( |vec_uint_type| value) | | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`bitCount` ( |vec_int_type| value) | Counts the number of 1 bits in an integer. | -| | | | -| |vec_uint_type| | :ref:`bitCount` ( |vec_uint_type| value) | | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`findLSB` ( |vec_int_type| value) | Find the index of the least significant bit set to 1 in an integer. | -| | | | -| |vec_uint_type| | :ref:`findLSB` ( |vec_uint_type| value) | | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`findMSB` ( |vec_int_type| value) | Find the index of the most significant bit set to 1 in an integer. | -| | | | -| |vec_uint_type| | :ref:`findMSB` ( |vec_uint_type| value) | | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |void| | :ref:`imulExtended` ( |vec_int_type| x, |vec_int_type| y,out |vec_int_type| msb, out |vec_int_type| lsb) | Multiplies two 32-bit numbers and produce a 64-bit result. | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | -| |void| | :ref:`umulExtended` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| msb, out |vec_uint_type| lsb) | | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_uint_type| | :ref:`uaddCarry` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| carry) | Adds two unsigned integers and generates carry. | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_uint_type| | :ref:`usubBorrow` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| borrow) | Subtracts two unsigned integers and generates borrow. | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`ldexp` (vecType x, out |vec_int_type| exp) | Assemble a floating-point number from a value and exponent. | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`frexp` (vecType x, out |vec_int_type| exp) | Splits a floating-point number (``x``) into significand integral | -| | | components | -+-----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +.. rst-class:: classref-method +|vec_type| **exp2** ( |vec_type| x ) -.. rst-class:: classref-section-separator + Return 2 raised to the power of the parameter. + + :param x: + The value of the power to which 2 will be raised. + + :return: + 2 raised to the power of x. i.e., 2\ :sup:`x` + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/exp2.xhtml + +.. rst-class:: classref-item-separator ---- -vec_type pow( |vec_type| x, |vec_type| y) - Raises ``x`` to the power of ``y``. - The result is undefined if ``x < 0`` or if ``x == 0`` and ``y <= 0``. +.. _shader_func_log: + +.. rst-class:: classref-method + +|vec_type| **log** ( |vec_type| x ) + + Return the natural logarithm of the parameter, i.e. the value y which satisfies x=e\ :sup:`y`. + The result is undefined if x ≤ 0. :param x: - The value to be raised to the power ``y``. + The value of which to take the natural logarithm. - :param y: - The power to which ``x`` will be raised. + :return: + the natural logarithm of x, + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/log.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_log2: + +.. rst-class:: classref-method + +|vec_type| **log2** ( |vec_type| x ) + + Return the base 2 logarithm of the parameter. + The result is undefined if x ≤ 0. + + :param x: + the value of which to take the base 2 logarithm. :return: - Returns the value of ``x`` raised to the ``y`` power. + the base 2 logarithm of x, i.e. the value y which satisfies x=2\ :sup:`y` + :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/pow.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/log2.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_sqrt: + +.. rst-class:: classref-method + +|vec_type| **sqrt** ( |vec_type| x ) + + Returns the square root of x. + The result is undefined if x < 0. + + :param x: + the value of which to take the square root. + + :return: + + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/sqrt.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_inversesqrt: + +.. rst-class:: classref-method + +|vec_type| **inversesqrt** ( |vec_type| x ) + + Returns the inverse of the square root of x. + The result is undefined if x ≤ 0. + + + :param x: + The value of which to take the inverse of the square root. + + :return: + The inverse of the square root of the parameter. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/inversesqrt.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_abs: + +.. rst-class:: classref-method + +|vec_type| **abs** ( |vec_type| x ) + + Returns the absolute value of x. Returns X if X is positive or X * -1 if X is negative. + + :param x: + the value of which to return the absolute. + + :return: + the absolute value of x + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/abs.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_int_type| **abs** ( |vec_int_type| x ) + + Returns the absolute value of x. Returns X if X is positive or X * -1 if X is negative. + + :param x: + the value of which to return the absolute. + + :return: + the absolute value of x + + :rtype: |vec_int_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/abs.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_sign: + +.. rst-class:: classref-method + +|vec_type| **sign** ( |vec_type| x ) + + Returns -1.0 if x is less than 0.0, 0.0 if x is equal to 0.0, and +1.0 if x is greater than 0.0. + + :param x: + the value from which to extract the sign. + + :return: + 1, -1 or 0. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/sign.xhtml + +.. rst-class:: classref-item-separator + +---- + + + +.. rst-class:: classref-method + +|vec_int_type| **sign** ( |vec_int_type| x ) + + Returns -1.0 if x is less than 0.0, 0.0 if x is equal to 0.0, and +1.0 if x is greater than 0.0. + + :param x: + the value from which to extract the sign. + + :return: + 1, -1 or 0. + + :rtype: |vec_int_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/sign.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_floor: + +.. rst-class:: classref-method + +|vec_type| **floor** ( |vec_type| x ) + + Returns a value equal to the nearest integer that is less than or equal to x. + + :param x: + the value to evaluate. + + :return: + the nearest integer that is less than or equal to x. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/floor.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_round: + +.. rst-class:: classref-method + +|vec_type| **round** ( |vec_type| x ) + + Returns a value equal to the nearest integer to x. + + The fraction 0.5 will round in a direction chosen by the implementation, presumably the direction + that is fastest. This includes the possibility that round(x) returns the same value as roundEven(x) + for all values of x. + + :param x: + the value to evaluate. + + :return: + the rounded value. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/round.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_roundEven: + +.. rst-class:: classref-method + +|vec_type| **roundEven** ( |vec_type| x ) + + returns a value equal to the nearest integer to x. + + The fractional part of 0.5 will round toward the nearest even integer. + For example, both 3.5 and 4.5 will round to 4.0. + + :param x: + the value to evaluate. + + :return: + the rounded value. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/roundEven.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_trunc: + +.. rst-class:: classref-method + +|vec_type| **trunc** ( |vec_type| x ) + + Returns a value equal to the nearest integer to x whose absolute value is not larger than the absolute value of x. + + :param x: + the value to evaluate. + + :return: + the truncated value. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/trunc.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_ceil: + +.. rst-class:: classref-method + +|vec_type| **ceil** ( |vec_type| x ) + + Returns a value equal to the nearest integer that is greater than or equal to x. + + :param x: + the value to evaluate. + + :return: + the ceiling-ed value. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/ceil.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_fract: + +.. rst-class:: classref-method + +|vec_type| **fract** ( |vec_type| x ) + + Returns the fractional part of x. + + This is calculated as x - floor(x). + + :param x: + the value to evaluate. + + :return: + the fraction part of x. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/fract.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_mod: + +.. rst-class:: classref-method + +|vec_type| **mod** ( |vec_type| x, |vec_type| y ) + + Returns the value of ``x modulo y``. + This is also sometimes called the remainder. + + This is computed as ``x - y * floor(x/y)``. + + :param x: + the value to evaluate. + + :return: + the value of ``x modulo y``. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/mod.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_type| **mod** ( |vec_type| x, float y ) + + Returns the value of ``x modulo y``. + This is also sometimes called the remainder. + + This is computed as ``x - y * floor(x/y)``. + + :param x: + the value to evaluate. + + :return: + the value of ``x modulo y``. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/mod.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_modf: + +.. rst-class:: classref-method + +|vec_type| **modf** ( vecType x, out |vec_type| i ) + + Separates a floating point value x into its integer and fractional parts. + + The fractional part of the number is returned from the function. + The integer part (as a floating point quantity) is returned in the output parameter i. + + :param x: + the value to separate. + + :param out i: + a variable that receives the integer part of the argument. + + :return: + the fractional part of the number. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/modf.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_min: + +.. rst-class:: classref-method + +|vec_type| **min** ( |vec_type| a, |vec_type| b ) + + Returns the minimum of the two parameters. + + It returns y if y is less than x, otherwise it returns x. + + :param a: + the first value to compare. + + :param b: + the second value to compare. + + :return: + the minimum of the two parameters. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/min.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_type| **min** ( |vec_type| a, float b ) + + Returns the minimum of the two parameters. + + It returns y if y is less than x, otherwise it returns x. + + :param a: + the first value to compare. + + :param b: + the second value to compare. + + :return: + the minimum of the two parameters. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/min.xhtml + +.. rst-class:: classref-item-separator + +---- + + + +.. rst-class:: classref-method + +|vec_int_type| **min** ( |vec_int_type| a, |vec_int_type| b ) + + Returns the minimum of the two parameters. + + It returns y if y is less than x, otherwise it returns x. + + :param a: + the first value to compare. + + :param b: + the second value to compare. + + :return: + the minimum of the two parameters. + + :rtype: |vec_int_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/min.xhtml + +.. rst-class:: classref-item-separator + +---- + + + +.. rst-class:: classref-method + +|vec_int_type| **min** ( |vec_int_type| a, int b ) + + Returns the minimum of the two parameters. + + It returns y if y is less than x, otherwise it returns x. + + :param a: + the first value to compare. + + :param b: + the second value to compare. + + :return: + the minimum of the two parameters. + + :rtype: |vec_int_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/min.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_uint_type| **min** ( |vec_uint_type| a, |vec_uint_type| b ) + + Returns the minimum of the two parameters. + + It returns y if y is less than x, otherwise it returns x. + + :param a: + the first value to compare. + + :param b: + the second value to compare. + + :return: + the minimum of the two parameters. + + :rtype: |vec_uint_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/min.xhtml + +.. rst-class:: classref-item-separator + +---- + + + +.. rst-class:: classref-method + +|vec_uint_type| **min** ( |vec_uint_type| a, uint b ) + + Returns the minimum of the two parameters. + + It returns y if y is less than x, otherwise it returns x. + + :param a: + the first value to compare. + + :param b: + the second value to compare. + + :return: + the minimum of the two parameters. + + :rtype: |vec_uint_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/min.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_max: + +.. rst-class:: classref-method + +|vec_type| **max** ( |vec_type| a, |vec_type| b ) + + Returns the maximum of the two parameters. + + It returns y if y is greater than x, otherwise it returns x. + + :param a: + the first value to compare. + + :param b: + the second value to compare. + + :return: + the maximum value. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml + +.. rst-class:: classref-item-separator + +---- + + + +.. rst-class:: classref-method + +|vec_type| **max** ( |vec_type| a, float b ) + + Returns the maximum of the two parameters. + + It returns y if y is greater than x, otherwise it returns x. + + :param a: + the first value to compare. + + :param b: + the second value to compare. + + :return: + the maximum value. + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml + +.. rst-class:: classref-item-separator + +---- + + + +.. rst-class:: classref-method + +|vec_uint_type| **max** ( |vec_uint_type| a, |vec_uint_type| b ) + + Returns the maximum of the two parameters. + + It returns y if y is greater than x, otherwise it returns x. + + :param a: + the first value to compare. + + :param b: + the second value to compare. + + :return: + the maximum value. + + :rtype: |vec_uint_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml + +.. rst-class:: classref-item-separator + +---- + + + +.. rst-class:: classref-method + +|vec_uint_type| **max** ( |vec_uint_type| a, uint b ) + + Returns the maximum of the two parameters. + + It returns y if y is greater than x, otherwise it returns x. + + :param a: + the first value to compare. + + :param b: + the second value to compare. + + :return: + the maximum value. + + :rtype: |vec_uint_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml + +.. rst-class:: classref-item-separator + +---- + + + +.. rst-class:: classref-method + +|vec_int_type| **max** ( |vec_int_type| a, |vec_int_type| b ) + + Returns the maximum of the two parameters. + + It returns y if y is greater than x, otherwise it returns x. + + :param a: + the first value to compare. + + :param b: + the second value to compare. + + :return: + the maximum value. + + :rtype: |vec_int_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_int_type| **max** ( |vec_int_type| a, int b ) + + Returns the maximum of the two parameters. + + It returns y if y is greater than x, otherwise it returns x. + + :param a: + the first value to compare. + + :param b: + the second value to compare. + + :return: + the maximum value. + + :rtype: |vec_int_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_clamp: + +.. rst-class:: classref-method + +|vec_type| **clamp** ( vecType x, |vec_type| min, |vec_type| max ) + + + + :param x: + + + :param min: + + + :param max: + + + :return: + + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_type| **clamp** ( |vec_type| x, float min, float max ) + + + + :param x: + + + :param min: + + + :param max: + + + :return: + + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_uint_type| **clamp** ( |vec_int_type| x, |vec_int_type| min, |vec_int_type| max ) + + + + :param x: + + + :param min: + + + :param max: + + + :return: + + + :rtype: |vec_uint_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_uint_type| **clamp** ( |vec_int_type| x, float min, float max ) + + + + :param x: + + + :param min: + + + :param max: + + + :return: + + + :rtype: |vec_uint_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_int_type| **clamp** ( vecType x, |vec_type| min, |vec_type| max ) + + + + :param x: + + + :param min: + + + :param max: + + + :return: + + + :rtype: |vec_int_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_int_type| **clamp** ( |vec_type| x, float min, float max ) + + + + :param x: + + + :param min: + + + :param max: + + + :return: + + + :rtype: |vec_int_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_mix: + +.. rst-class:: classref-method + +float **mix** ( float a, float b, float c ) + + + + :param a: + + + :param b: + + + :param c: + + + :return: + + + :rtype: float + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/mix.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_type| **mix** ( vecType a, |vec_type| b, float c ) + + + + :param a: + + + :param b: + + + :param c: + + + :return: + + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/mix.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_type| **mix** ( vecType a, |vec_type| b, |vec_type| c ) + + + + :param a: + + + :param b: + + + :param c: + + + :return: + + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/mix.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_type| **mix** ( vecType a, |vec_type| b, |vec_bool_type| c ) + + + + :param a: + + + :param b: + + + :param c: + + + :return: + + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/mix.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_fma: + +.. rst-class:: classref-method + +|vec_type| **fma** ( vecType a, |vec_type| b, |vec_type| c ) + + + + :param a: + + + :param b: + + + :param c: + + + :return: + + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/fma.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_step: + +.. rst-class:: classref-method + +|vec_type| **step** ( |vec_type| a, |vec_type| b ) + + + + :param a: + + + :param b: + + + :param : + + + :return: + + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/step.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_type| **step** ( float a, |vec_type| b ) + + + + :param a: + + + :param b: + + + :param : + + + :return: + + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/step.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_smoothstep: + +.. rst-class:: classref-method + +|vec_type| **smoothstep** ( vecType a, |vec_type| b, |vec_type| c ) + + + + :param a: + + + :param b: + + + :param c: + + + :return: + + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/smoothstep.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_type| **smoothstep** ( float a, float b, |vec_type| c ) + + + + :param a: + + + :param b: + + + :param c: + + + :return: + + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/smoothstep.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_isnan: + +.. rst-class:: classref-method + +|vec_bool_type| **isnan** ( |vec_type| x ) + + + + :param x: + + + :param : + + + :param : + + + :return: + + + :rtype: |vec_bool_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/isnan.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_isinf: + +.. rst-class:: classref-method + +|vec_bool_type| **isinf** ( |vec_type| x ) + + + + :param x: + + + :param : + + + :param : + + + :return: + + + :rtype: |vec_bool_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/isinf.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_floatBitsToInt: + +.. rst-class:: classref-method + +|vec_int_type| **floatBitsToInt** ( |vec_type| x ) + + + + :param x: + + + :param : + + + :param : + + + :return: + + + :rtype: |vec_int_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/floatBitsToInt.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_floatBitsToUint: + +.. rst-class:: classref-method + +|vec_uint_type| **floatBitsToUint** ( |vec_type| x ) + + + + :param x: + + + :param : + + + :param : + + + :return: + + + :rtype: |vec_uint_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/floatBitsToUint.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_intBitsToFloat: + +.. rst-class:: classref-method + +|vec_type| **intBitsToFloat** ( |vec_int_type| x ) + + + + :param x: + + + :param : + + + :param : + + + :return: + + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/intBitsToFloat.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_uintBitsToFloat: + +.. rst-class:: classref-method + +|vec_type| **uintBitsToFloat** ( |vec_uint_type| x ) + + + + :param x: + + + :param : + + + :param : + + + :return: + + + :rtype: |vec_type| + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/uintBitsToFloat.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + + + + +Geometric Functions +^^^^^^^^^^^^^^^^^^^ + ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| float | :ref:`length` ( |vec_type| x) | Vector length. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| float | :ref:`distance` ( |vec_type| a, |vec_type| b) | Distance between vectors i.e ``length(a - b)``. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| float | :ref:`dot` ( |vec_type| a, |vec_type| b) | Dot product. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| vec3 | :ref:`cross` (vec3 a, vec3 b) | Cross product. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |vec_type| | :ref:`normalize` ( |vec_type| x) | Normalize to unit length. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| vec3 | :ref:`reflect` (vec3 I, vec3 N) | Reflect. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| vec3 | :ref:`refract` (vec3 I, vec3 N, float eta) | Refract. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |vec_type| | :ref:`faceforward` (vecType N, |vec_type| I, |vec_type| Nref) | If ``dot(Nref, I)`` < 0, return ``N``, otherwise ``-N``. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |mat_type| | :ref:`matrixCompMult` (|mat_type| x, |mat_type| y) | Matrix component multiplication. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |mat_type| | :ref:`outerProduct` ( |vec_type| column, |vec_type| row) | Matrix outer product. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |mat_type| | :ref:`transpose` (|mat_type| m) | Transpose matrix. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| float | :ref:`determinant` (|mat_type| m) | Matrix determinant. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |mat_type| | :ref:`inverse` (|mat_type| m) | Inverse matrix. | ++------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---------- + + +Comparison Functions +^^^^^^^^^^^^^^^^^^^^ + ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`lessThan` ( |vec_type| x, |vec_type| y) | Bool vector comparison on < int/uint/float vectors. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`greaterThan` ( |vec_type| x, |vec_type| y) | Bool vector comparison on > int/uint/float vectors. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`lessThanEqual` ( |vec_type| x, |vec_type| y) | Bool vector comparison on <= int/uint/float vectors. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`greaterThanEqual` ( |vec_type| x, |vec_type| y) | Bool vector comparison on >= int/uint/float vectors. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`equal` ( |vec_type| x, |vec_type| y) | Bool vector comparison on == int/uint/float vectors. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`notEqual` ( |vec_type| x, |vec_type| y) | Bool vector comparison on != int/uint/float vectors. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| bool | :ref:`any` ( |vec_bool_type| x) | ``true`` if any component is ``true``, ``false`` otherwise. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| bool | :ref:`all` ( |vec_bool_type| x) | ``true`` if all components are ``true``, ``false`` otherwise. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`not` ( |vec_bool_type| x) | Invert boolean vector. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + + + +Texture Functions +^^^^^^^^^^^^^^^^^ + ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| ivec2 | :ref:`textureSize` ( |gsampler2D| s, int lod) | Get the size of a texture. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| ivec2 | :ref:`textureSize` (samplerCube s, int lod) | The LOD defines which mipmap level is used. An LOD value of ``0`` | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| ivec2 | :ref:`textureSize` (samplerCubeArray s, int lod) | will use the full resolution texture. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| ivec3 | :ref:`textureSize` ( |gsampler2DArray| s, int lod) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| ivec3 | :ref:`textureSize` ( |gsampler3D| s, int lod) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| vec2 | :ref:`textureQueryLod` ( |gsampler2D| s, vec2 p) | Compute the level-of-detail that would be used to sample from a | ++--------------+-----------------------------------------------------------------------------------------------------+ texture. The ``x`` component of the resulted value is the mipmap | +| vec3 | :ref:`textureQueryLod` ( |gsampler2DArray| s, vec2 p) | array that would be accessed. The ``y`` component is computed | ++--------------+-----------------------------------------------------------------------------------------------------+ level-of-detail relative to the base level (regardless of the | +| vec2 | :ref:`textureQueryLod` ( |gsampler3D| s, vec3 p) | mipmap levels of the texture). | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec2 | :ref:`textureQueryLod` (samplerCube s, vec3 p) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| int | :ref:`textureQueryLevels` ( |gsampler2D| s) | Get the number of accessible mipmap levels of a texture. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| int | :ref:`textureQueryLevels` ( |gsampler2DArray| s) | If the texture is unassigned to a sampler, ``1`` is returned (Godot | ++--------------+-----------------------------------------------------------------------------------------------------+ always internally assigns a texture even to an empty sampler). | +| int | :ref:`textureQueryLevels` ( |gsampler3D| s) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| int | :ref:`textureQueryLevels` (samplerCube s) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`texture` ( |gsampler2D| s, vec2 p [, float bias]) | Perform a texture read. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`texture` ( |gsampler2DArray| s, vec3 p [, float bias]) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |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]) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |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]) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureProj` ( |gsampler3D| s, vec4 p [, float bias]) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`textureLod` ( |gsampler2D| s, vec2 p, float lod) | Perform a texture read at custom mipmap. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureLod` ( |gsampler2DArray| s, vec3 p, float lod) | The LOD defines which mipmap level is used. An LOD value of ``0.0`` | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| | | will use the full resolution texture. If the texture lacks mipmaps, | +| |gvec4_type| | :ref:`textureLod` ( |gsampler3D| s, vec3 p, float lod) | all LOD values will act like ``0.0``. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec4 | :ref:`textureLod` (samplerCube s, vec3 p, float lod) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec4 | :ref:`textureLod` (samplerCubeArray s, vec4 p, float lod) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec3 p, float lod) | Performs a texture read with projection/LOD. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec4 p, float lod) | The LOD defines which mipmap level is used. An LOD value of ``0.0`` | +| | | will use the full resolution texture. If the texture lacks mipmaps, | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureProjLod` ( |gsampler3D| s, vec4 p, float lod) | all LOD values will act like ``0.0``. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`textureGrad` ( |gsampler2D| s, vec2 p, vec2 dPdx, vec2 dPdy) | Performs a texture read with explicit gradients. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureGrad` ( |gsampler2DArray| s, vec3 p, vec2 dPdx, vec2 dPdy) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureGrad` ( |gsampler3D| s, vec3 p, vec2 dPdx, vec2 dPdy) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec4 | :ref:`textureGrad` (samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec4 | :ref:`textureGrad` (samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy) | Performs a texture read with projection/LOD and with explicit | +| | | gradients. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`texelFetch` ( |gsampler2D| s, ivec2 p, int lod) | Fetches a single texel using integer coordinates. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`texelFetch` ( |gsampler2DArray| s, ivec3 p, int lod) | The LOD defines which mipmap level is used. An LOD value of ``0`` | +| | | will use the full resolution texture. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`texelFetch` ( |gsampler3D| s, ivec3 p, int lod) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`textureGather` ( |gsampler2D| s, vec2 p [, int comps]) | Gathers four texels from a texture. | +| | | Use ``comps`` within range of 0..3 to | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureGather` ( |gsampler2DArray| s, vec3 p [, int comps]) | define which component (x, y, z, w) is returned. | +| | | If ``comps`` is not provided: 0 (or x-component) is used. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec4 | :ref:`textureGather` (samplerCube s, vec3 p [, int comps]) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`dFdx` ( |vec_type| p) | Derivative in ``x`` using local differencing. | +| | | Internally, can use either ``dFdxCoarse`` or ``dFdxFine``, but the | +| | | decision for which to use is made by the GPU driver. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`dFdxCoarse` ( |vec_type| p) | Calculates derivative with respect to ``x`` window coordinate using | +| | | local differencing based on the value of ``p`` for the current | +| | | fragment neighbour(s), and will possibly, but not necessarily, | +| | | include the value for the current fragment. | +| | | Not available on ``gl_compatibility`` profile. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`dFdxFine` ( |vec_type| p) | Calculates derivative with respect to ``x`` window coordinate using | +| | | local differencing based on the value of ``p`` for the current | +| | | fragment and its immediate neighbour(s). | +| | | Not available on ``gl_compatibility`` profile. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`dFdy` ( |vec_type| p) | Derivative in ``y`` using local differencing. | +| | | Internally, can use either ``dFdyCoarse`` or ``dFdyFine``, but the | +| | | decision for which to use is made by the GPU driver. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`dFdyCoarse` ( |vec_type| p) | Calculates derivative with respect to ``y`` window coordinate using | +| | | local differencing based on the value of ``p`` for the current | +| | | fragment neighbour(s), and will possibly, but not necessarily, | +| | | include the value for the current fragment. | +| | | Not available on ``gl_compatibility`` profile. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`dFdyFine` ( |vec_type| p) | Calculates derivative with respect to ``y`` window coordinate using | +| | | local differencing based on the value of ``p`` for the current | +| | | fragment and its immediate neighbour(s). | +| | | Not available on ``gl_compatibility`` profile. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`fwidth` ( |vec_type| p) | Sum of absolute derivative in ``x`` and ``y``. | +| | | This is the equivalent of using ``abs(dFdx(p)) + abs(dFdy(p))``. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`fwidthCoarse` ( |vec_type| p) | Sum of absolute derivative in ``x`` and ``y``. | +| | | Not available on ``gl_compatibility`` profile. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`fwidthFine` ( |vec_type| p) | Sum of absolute derivative in ``x`` and ``y``. | +| | | Not available on ``gl_compatibility`` profile. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + + + + +Packing/Unpacking Functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ++------+--------------------------------------------------------------+--------------------------------------------------------------+ +| uint | :ref:`packHalf2x16` (vec2 v) | Convert two 32-bit floating-point numbers into 16-bit | +| | | and pack them into a 32-bit unsigned integer and vice-versa. | ++------+--------------------------------------------------------------+ + +| vec2 | :ref:`unpackHalf2x16` (uint v) | | ++------+--------------------------------------------------------------+--------------------------------------------------------------+ +| uint | :ref:`packUnorm2x16` (vec2 v) | Convert two 32-bit floating-point numbers (clamped | +| | | within 0..1 range) into 16-bit and pack them | ++------+--------------------------------------------------------------+ + +| vec2 | :ref:`unpackUnorm2x16` (uint v) | into a 32-bit unsigned integer and vice-versa. | ++------+--------------------------------------------------------------+--------------------------------------------------------------+ +| uint | :ref:`packSnorm2x16` (vec2 v) | Convert two 32-bit floating-point numbers (clamped | +| | | within -1..1 range) into 16-bit and pack them | ++------+--------------------------------------------------------------+ + +| vec2 | :ref:`unpackSnorm2x16` (uint v) | into a 32-bit unsigned integer and vice-versa. | ++------+--------------------------------------------------------------+--------------------------------------------------------------+ +| uint | :ref:`packUnorm4x8` (vec4 v) | Convert four 32-bit floating-point numbers (clamped | +| | | within 0..1 range) into 8-bit and pack them | ++------+--------------------------------------------------------------+ + +| vec4 | :ref:`unpackUnorm4x8` (uint v) | into a 32-bit unsigned integer and vice-versa. | ++------+--------------------------------------------------------------+--------------------------------------------------------------+ +| uint | :ref:`packSnorm4x8` (vec4 v) | Convert four 32-bit floating-point numbers (clamped | +| | | within -1..1 range) into 8-bit and pack them | ++------+--------------------------------------------------------------+ + +| vec4 | :ref:`unpackSnorm4x8` (uint v) | into a 32-bit unsigned integer and vice-versa. | ++------+--------------------------------------------------------------+--------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + + + + +Bitwise operations +^^^^^^^^^^^^^^^^^^ + ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_int_type| | :ref:`bitfieldExtract` ( |vec_int_type| value, int offset, int bits) | Extracts a range of bits from an integer. | +| | | | +| |vec_uint_type| | :ref:`bitfieldExtract` ( |vec_uint_type| value, int offset, int bits) | | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_int_type| | :ref:`bitfieldInsert` ( |vec_int_type| base, |vec_int_type| insert, | Insert a range of bits into an integer. | +| | int offset, int bits) | | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | +| |vec_uint_type| | :ref:`bitfieldInsert` (|vec_uint_type| base, |vec_uint_type| insert, int offset, | | +| | int bits) | | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_int_type| | :ref:`bitfieldReverse` ( |vec_int_type| value) | Reverse the order of bits in an integer. | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | +| |vec_uint_type| | :ref:`bitfieldReverse` ( |vec_uint_type| value) | | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_int_type| | :ref:`bitCount` ( |vec_int_type| value) | Counts the number of 1 bits in an integer. | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | +| |vec_uint_type| | :ref:`bitCount` ( |vec_uint_type| value) | | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_int_type| | :ref:`findLSB` ( |vec_int_type| value) | Find the index of the least significant bit set to 1 in an integer. | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | +| |vec_uint_type| | :ref:`findLSB` ( |vec_uint_type| value) | | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_int_type| | :ref:`findMSB` ( |vec_int_type| value) | Find the index of the most significant bit set to 1 in an integer. | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | +| |vec_uint_type| | :ref:`findMSB` ( |vec_uint_type| value) | | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |void| | :ref:`imulExtended` ( |vec_int_type| x, |vec_int_type| y,out |vec_int_type| msb, out |vec_int_type| lsb) | Multiplies two 32-bit numbers and produce a 64-bit result. | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | +| |void| | :ref:`umulExtended` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| msb, out |vec_uint_type| lsb) | | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_uint_type| | :ref:`uaddCarry` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| carry) | Adds two unsigned integers and generates carry. | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_uint_type| | :ref:`usubBorrow` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| borrow) | Subtracts two unsigned integers and generates borrow. | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`ldexp` (vecType x, out |vec_int_type| exp) | Assemble a floating-point number from a value and exponent. | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`frexp` (vecType x, out |vec_int_type| exp) | Splits a floating-point number (``x``) into significand integral | +| | | components | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + + +.. rst-class:: classref-section-separator + +---- + + .. |void| replace:: :abbr:`void (No return value.)` .. |vec_type| replace:: :abbr:`vec_type (Any of: float, vec2, vec3, vec4)` @@ -881,3 +2340,4 @@ vec_type pow( |vec_type| x, |vec_type| y) .. |gsampler2DArray| replace:: :abbr:`gsampler2DArray (Any of: sampler2DArray, isampler2DArray, uSampler2DArray)` .. |gsampler3D| replace:: :abbr:`gsampler3D (Any of: sampler3D, isampler3D, uSampler3D)` .. |mat_type| replace:: :abbr:`mat_type (Any of: mat2, mat3, mat4)` +.. |gvec4_type| replace:: :abbr:`gvec4_type (Any of: vec4, ivec4, uvec4)` From 0d6f7033b643da504aad28266225686eb71410f8 Mon Sep 17 00:00:00 2001 From: ashbygeek Date: Sat, 4 May 2024 23:08:32 -0400 Subject: [PATCH 04/25] finished exponential/common math category --- .../shader_reference/shader_functions.rst | 576 +++++++----------- 1 file changed, 225 insertions(+), 351 deletions(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index 14eebdd4224..324d5fe4d54 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -19,6 +19,8 @@ GLSL 4.00 specification. +-----------------+--------------------------------------------------+--------------------------+ | vec_uint_type | uint, uvec2, uvec3, or uvec4 | genUType | +-----------------+--------------------------------------------------+--------------------------+ + | vec_bool_type | bool, bvec2, bvec3, or bvec4 | genUType | + +-----------------+--------------------------------------------------+--------------------------+ | mat_type | mat2, mat3, or mat4 | mat | +-----------------+--------------------------------------------------+--------------------------+ | gvec4_type | vec4, ivec4, or uvec4 | | @@ -35,7 +37,7 @@ GLSL 4.00 specification. .. note:: Most operations on vectors (multiplication, division, etc) are performed component-wise. For example, the operation ``vec2(3,4) * vec2(10,20)`` would result in ``vec2(3 * 10, 4 * 20)``. - As another exmple, the operation ``min(vec2(3,4), vec2(1,8))`` would result in ``vec2(min(3,1),min(4,8))``. + or the operation ``min(vec2(3,4), vec2(1,8))`` would result in ``vec2(min(3,1),min(4,8))``. The `GLSL Language Specification ` says under section 5.10 Vector and Matrix Operations: @@ -102,9 +104,7 @@ Trigonometric Functions Specify the quantity, in degrees, to be converted to radians. :return: - The return value is ``(π * degrees) / 180``. - - :rtype: |vec_type| + ``(π * degrees) / 180``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/radians.xhtml @@ -125,9 +125,7 @@ Trigonometric Functions Specify the quantity, in radians, to be converted to degrees. :return: - The return value is ``(radians * 180) / π``. - - :rtype: |vec_type| + ``(radians * 180) / π``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/degrees.xhtml @@ -145,12 +143,10 @@ vec_type sin( |vec_type| angle) Return the sine of the parameter. :param angle: - The quantity, in radians, of which to return the sine + takehe quantity, in radians, of which to return the sine :return: - The return value is the trigonometric sine of ``angle``. - - :rtype: |vec_type| + the trigonometric sine of ``angle``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/sin.xhtml @@ -168,12 +164,10 @@ vec_type cos( |vec_type| angle) Return the cosine of the parameter. :param angle: - The quantity, in radians, of which to return the cosine. + the quantity, in radians, of which to return the cosine. :return: - The return value is the trigonometric cosine of ``angle``. - - :rtype: |vec_type| + the trigonometric cosine of ``angle``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/cos.xhtml @@ -194,9 +188,7 @@ vec_type tan( |vec_type| angle) The quantity, in radians, of which to return the tangent. :return: - The return value is the trigonometric tangent of ``angle``. - - :rtype: |vec_type| + the trigonometric tangent of ``angle``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/tan.xhtml @@ -217,11 +209,9 @@ vec_type asin( |vec_type| x) :param x: The value whose arccosine to return. :return: - The return value is the angle whose trigonometric sine is ``x`` and is + the angle whose trigonometric sine is ``x`` and is in the range ``[-π/2, π/2]``. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/asin.xhtml .. rst-class:: classref-item-separator @@ -242,11 +232,9 @@ vec_type acos( |vec_type| x) The value whose arccosine to return. :return: - The return value is the angle whose trigonometric cosine is ``x`` and + the angle whose trigonometric cosine is ``x`` and is in the range ``[0, π]``. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/acos.xhtml .. rst-class:: classref-item-separator @@ -269,11 +257,9 @@ vec_type atan( |vec_type| y_over_x) The fraction whose arctangent to return. :return: - The return value is the trigonometric arc-tangent of ``y_over_x`` and is + the trigonometric arc-tangent of ``y_over_x`` and is in the range ``[-π/2, π/2]``. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/atan.xhtml @@ -297,11 +283,9 @@ vec_type atan( |vec_type| y, |vec_type| x) The denominator of the fraction whose arctangent to return. :return: - The return value is the trigonometric arc-tangent of ``y/x`` and is in + the trigonometric arc-tangent of ``y/x`` and is in the range ``[-π, π]``. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/atan.xhtml .. rst-class:: classref-item-separator @@ -321,9 +305,7 @@ vec_type sinh( |vec_type| x) The value whose hyperbolic sine to return. :return: - The return value is the hyperbolic sine of ``x``. - - :rtype: |vec_type| + the hyperbolic sine of ``x``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/sinh.xhtml @@ -344,9 +326,7 @@ vec_type cosh( |vec_type| x) The value whose hyperbolic cosine to return. :return: - The return value is the hyperbolic cosine of ``x``. - - :rtype: |vec_type| + the hyperbolic cosine of ``x``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/cosh.xhtml @@ -367,9 +347,7 @@ vec_type tanh( |vec_type| x) The value whose hyperbolic tangent to return. :return: - The return value is the hyperbolic tangent of ``x``. - - :rtype: |vec_type| + the hyperbolic tangent of ``x``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/tanh.xhtml @@ -390,11 +368,9 @@ vec_type asinh( |vec_type| x) The value whose arc hyperbolic sine to return. :return: - The return value is the arc hyperbolic sine of ``x`` which is the + the arc hyperbolic sine of ``x`` which is the inverse of sinh. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/asinh.xhtml .. rst-class:: classref-item-separator @@ -417,8 +393,6 @@ vec_type acosh( |vec_type| x) :return: - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/acos.xhtml .. rst-class:: classref-item-separator @@ -443,11 +417,9 @@ vec_type atanh( |vec_type| x) The fraction whose arc hyperbolic tangent to return. :return: - The return value is the arc hyperbolic tangent of ``x`` which is the + the arc hyperbolic tangent of ``x`` which is the inverse of tanh. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/atan.xhtml .. rst-class:: classref-item-separator @@ -498,7 +470,7 @@ Exponential and Common Math Functions +-----------------+---------------------------------------------------------------------------------------------+ | | |vec_type| | :ref:`mod` ( |vec_type| x, float y) | | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`modf` (vecType x, out |vec_type| i) | Fractional of ``x``, with ``i`` as integer part. | +| |vec_type| | :ref:`modf` (|vec_type| x, out |vec_type| i) | Fractional of ``x``, with ``i`` as integer part. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ | |vec_type| | :ref:`min` ( |vec_type| a, |vec_type| b) | Lowest value between ``a`` and ``b``. | +-----------------+---------------------------------------------------------------------------------------------+ | @@ -524,7 +496,7 @@ Exponential and Common Math Functions +-----------------+---------------------------------------------------------------------------------------------+ | | |vec_int_type| | :ref:`max` ( |vec_int_type| a, int b) | | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`clamp` (vecType x, |vec_type| min, |vec_type| max) | Clamp ``x`` between ``min`` and ``max`` (inclusive). | +| |vec_type| | :ref:`clamp` (|vec_type| x, |vec_type| min, |vec_type| max) | Clamp ``x`` between ``min`` and ``max`` (inclusive). | +-----------------+---------------------------------------------------------------------------------------------+ | | |vec_type| | :ref:`clamp` ( |vec_type| x, float min, float max) | | +-----------------+---------------------------------------------------------------------------------------------+ | @@ -532,25 +504,23 @@ Exponential and Common Math Functions +-----------------+---------------------------------------------------------------------------------------------+ | | |vec_uint_type| | :ref:`clamp` ( |vec_int_type| x, float min, float max) | | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_int_type| | :ref:`clamp` (vecType x, |vec_type| min, |vec_type| max) | | +| |vec_int_type| | :ref:`clamp` (|vec_type| x, |vec_type| min, |vec_type| max) | | +-----------------+---------------------------------------------------------------------------------------------+ | | |vec_int_type| | :ref:`clamp` ( |vec_type| x, float min, float max) | | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| float | :ref:`mix` (float a, float b, float c) | Linear interpolate between ``a`` and ``b`` by ``c``. | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_type| | :ref:`mix` (vecType a, |vec_type| b, float c) | | +| |vec_type| | :ref:`mix` (|vec_type| a, |vec_type| b, |vec_type| c) | Linear interpolate between ``a`` and ``b`` by ``c``. | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_type| | :ref:`mix` (vecType a, |vec_type| b, |vec_type| c) | | +| |vec_type| | :ref:`mix` (|vec_type| a, |vec_type| b, float c) | | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_type| | :ref:`mix` (vecType a, |vec_type| b, |vec_bool_type| c) | | +| |vec_type| | :ref:`mix` (|vec_type| a, |vec_type| b, |vec_bool_type| c) | | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`fma` (vecType a, |vec_type| b, |vec_type| c) | Fused multiply-add operation: ``(a * b + c)`` | +| |vec_type| | :ref:`fma` (|vec_type| a, |vec_type| b, |vec_type| c) | Fused multiply-add operation: ``(a * b + c)`` | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ | |vec_type| | :ref:`step` ( |vec_type| a, |vec_type| b) | ``b[i] < a[i] ? 0.0 : 1.0``. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ | |vec_type| | :ref:`step` (float a, |vec_type| b) | ``b[i] < a ? 0.0 : 1.0``. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`smoothstep` (vecType a, |vec_type| b, |vec_type| c) | Hermite interpolate between ``a`` and ``b`` by ``c``. | +| |vec_type| | :ref:`smoothstep` (|vec_type| a, |vec_type| b, |vec_type| c) | Hermite interpolate between ``a`` and ``b`` by ``c``. | +-----------------+---------------------------------------------------------------------------------------------+ | | |vec_type| | :ref:`smoothstep` (float a, float b, |vec_type| c) | | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ @@ -592,8 +562,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: Returns the value of ``x`` raised to the ``y`` power. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/pow.xhtml .. rst-class:: classref-item-separator @@ -616,9 +584,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: The natural exponentiation of x. i.e., e\ :sup:`x` - - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/exp.xhtml .. rst-class:: classref-item-separator @@ -642,8 +607,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: 2 raised to the power of x. i.e., 2\ :sup:`x` - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/exp2.xhtml .. rst-class:: classref-item-separator @@ -668,8 +631,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the natural logarithm of x, - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/log.xhtml .. rst-class:: classref-item-separator @@ -694,9 +655,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the base 2 logarithm of x, i.e. the value y which satisfies x=2\ :sup:`y` - - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/log2.xhtml .. rst-class:: classref-item-separator @@ -721,8 +679,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/sqrt.xhtml .. rst-class:: classref-item-separator @@ -748,8 +704,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: The inverse of the square root of the parameter. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/inversesqrt.xhtml .. rst-class:: classref-item-separator @@ -773,8 +727,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the absolute value of x - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/abs.xhtml .. rst-class:: classref-item-separator @@ -794,8 +746,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the absolute value of x - :rtype: |vec_int_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/abs.xhtml .. rst-class:: classref-item-separator @@ -819,8 +769,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: 1, -1 or 0. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/sign.xhtml .. rst-class:: classref-item-separator @@ -841,8 +789,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: 1, -1 or 0. - :rtype: |vec_int_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/sign.xhtml .. rst-class:: classref-item-separator @@ -866,8 +812,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the nearest integer that is less than or equal to x. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/floor.xhtml .. rst-class:: classref-item-separator @@ -895,8 +839,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the rounded value. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/round.xhtml .. rst-class:: classref-item-separator @@ -923,8 +865,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the rounded value. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/roundEven.xhtml .. rst-class:: classref-item-separator @@ -948,8 +888,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the truncated value. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/trunc.xhtml .. rst-class:: classref-item-separator @@ -973,8 +911,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the ceiling-ed value. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/ceil.xhtml .. rst-class:: classref-item-separator @@ -1000,8 +936,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the fraction part of x. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/fract.xhtml .. rst-class:: classref-item-separator @@ -1028,8 +962,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the value of ``x modulo y``. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/mod.xhtml .. rst-class:: classref-item-separator @@ -1052,8 +984,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the value of ``x modulo y``. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/mod.xhtml .. rst-class:: classref-item-separator @@ -1067,7 +997,7 @@ vec_type pow( |vec_type| x, |vec_type| y) .. rst-class:: classref-method -|vec_type| **modf** ( vecType x, out |vec_type| i ) +|vec_type| **modf** ( |vec_type| x, out |vec_type| i ) Separates a floating point value x into its integer and fractional parts. @@ -1083,8 +1013,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the fractional part of the number. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/modf.xhtml .. rst-class:: classref-item-separator @@ -1113,8 +1041,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the minimum of the two parameters. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/min.xhtml .. rst-class:: classref-item-separator @@ -1139,8 +1065,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the minimum of the two parameters. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/min.xhtml .. rst-class:: classref-item-separator @@ -1166,8 +1090,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the minimum of the two parameters. - :rtype: |vec_int_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/min.xhtml .. rst-class:: classref-item-separator @@ -1193,8 +1115,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the minimum of the two parameters. - :rtype: |vec_int_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/min.xhtml .. rst-class:: classref-item-separator @@ -1219,8 +1139,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the minimum of the two parameters. - :rtype: |vec_uint_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/min.xhtml .. rst-class:: classref-item-separator @@ -1246,8 +1164,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the minimum of the two parameters. - :rtype: |vec_uint_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/min.xhtml .. rst-class:: classref-item-separator @@ -1276,8 +1192,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the maximum value. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml .. rst-class:: classref-item-separator @@ -1303,8 +1217,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the maximum value. - :rtype: |vec_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml .. rst-class:: classref-item-separator @@ -1330,8 +1242,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the maximum value. - :rtype: |vec_uint_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml .. rst-class:: classref-item-separator @@ -1357,8 +1267,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the maximum value. - :rtype: |vec_uint_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml .. rst-class:: classref-item-separator @@ -1384,8 +1292,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the maximum value. - :rtype: |vec_int_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml .. rst-class:: classref-item-separator @@ -1410,8 +1316,6 @@ vec_type pow( |vec_type| x, |vec_type| y) :return: the maximum value. - :rtype: |vec_int_type| - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml .. rst-class:: classref-item-separator @@ -1425,23 +1329,23 @@ vec_type pow( |vec_type| x, |vec_type| y) .. rst-class:: classref-method -|vec_type| **clamp** ( vecType x, |vec_type| min, |vec_type| max ) +|vec_type| **clamp** ( |vec_type| x, |vec_type| min, |vec_type| max ) + + Returns the value of x constrained to the range minVal to maxVal. - + The returned value is computed as min(max(x, minVal), maxVal). :param x: - + the value to constrain. :param min: - + the lower end of the range into which to constrain x. :param max: - + the upper end of the range into which to constrain x. :return: - - - :rtype: |vec_type| + the constrained value. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml @@ -1454,21 +1358,21 @@ vec_type pow( |vec_type| x, |vec_type| y) |vec_type| **clamp** ( |vec_type| x, float min, float max ) - + Returns the value of x constrained to the range minVal to maxVal. + + The returned value is computed as min(max(x, minVal), maxVal). :param x: - + the value to constrain. :param min: - + the lower end of the range into which to constrain x. :param max: - + the upper end of the range into which to constrain x. :return: - - - :rtype: |vec_type| + the constrained value. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml @@ -1481,21 +1385,21 @@ vec_type pow( |vec_type| x, |vec_type| y) |vec_uint_type| **clamp** ( |vec_int_type| x, |vec_int_type| min, |vec_int_type| max ) - + Returns the value of x constrained to the range minVal to maxVal. + + The returned value is computed as min(max(x, minVal), maxVal). :param x: - + the value to constrain. :param min: - + the lower end of the range into which to constrain x. :param max: - + the upper end of the range into which to constrain x. :return: - - - :rtype: |vec_uint_type| + the constrained value. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml @@ -1508,21 +1412,21 @@ vec_type pow( |vec_type| x, |vec_type| y) |vec_uint_type| **clamp** ( |vec_int_type| x, float min, float max ) - + Returns the value of x constrained to the range minVal to maxVal. + + The returned value is computed as min(max(x, minVal), maxVal). :param x: - + the value to constrain. :param min: - + the lower end of the range into which to constrain x. :param max: - + the upper end of the range into which to constrain x. :return: - - - :rtype: |vec_uint_type| + the constrained value. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml @@ -1533,23 +1437,23 @@ vec_type pow( |vec_type| x, |vec_type| y) .. rst-class:: classref-method -|vec_int_type| **clamp** ( vecType x, |vec_type| min, |vec_type| max ) +|vec_int_type| **clamp** ( |vec_type| x, |vec_type| min, |vec_type| max ) - + Returns the value of x constrained to the range minVal to maxVal. + + The returned value is computed as min(max(x, minVal), maxVal). :param x: - + the value to constrain. :param min: - + the lower end of the range into which to constrain x. :param max: - + the upper end of the range into which to constrain x. :return: - - - :rtype: |vec_int_type| + the constrained value. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml @@ -1562,21 +1466,21 @@ vec_type pow( |vec_type| x, |vec_type| y) |vec_int_type| **clamp** ( |vec_type| x, float min, float max ) - + Returns the value of x constrained to the range minVal to maxVal. + + The returned value is computed as min(max(x, minVal), maxVal). :param x: - + the value to constrain. :param min: - + the lower end of the range into which to constrain x. :param max: - + the upper end of the range into which to constrain x. :return: - - - :rtype: |vec_int_type| + the constrained value. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml @@ -1591,23 +1495,23 @@ vec_type pow( |vec_type| x, |vec_type| y) .. rst-class:: classref-method -float **mix** ( float a, float b, float c ) +|vec_type| **mix** ( |vec_type| a, |vec_type| b, |vec_type| c ) + + Performs a linear interpolation between a and b using c to weight between them. - + computed as ``a × (1 − c) + b × c``. :param a: - + the start of the range in which to interpolate. :param b: - + the end of the range in which to interpolate. :param c: - + the value to use to interpolate between x and y. :return: - - - :rtype: float + The interpolated value. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/mix.xhtml @@ -1618,23 +1522,23 @@ float **mix** ( float a, float b, float c ) .. rst-class:: classref-method -|vec_type| **mix** ( vecType a, |vec_type| b, float c ) +|vec_type| **mix** ( |vec_type| a, |vec_type| b, float c ) - + Performs a linear interpolation between a and b using c to weight between them. + + computed as ``a × (1 − c) + b × c``. :param a: - + the start of the range in which to interpolate. :param b: - + the end of the range in which to interpolate. :param c: - + the value to use to interpolate between x and y. :return: - - - :rtype: |vec_type| + The interpolated value. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/mix.xhtml @@ -1645,23 +1549,27 @@ float **mix** ( float a, float b, float c ) .. rst-class:: classref-method -|vec_type| **mix** ( vecType a, |vec_type| b, |vec_type| c ) +|vec_type| **mix** ( |vec_type| a, |vec_type| b, |vec_bool_type| c ) + + Selects either value a or value b based on the value of c. + For a component of c that is false, the corresponding component of a is returned. + For a component of c that is true, the corresponding component of b is returned. + Components of a and b that are not selected are allowed to be invalid floating-point values and will have no effect on the results. - + If a, b, and c are vector types the operation is performed component-wise. + ie. ``mix(vec2(42, 314), vec2(9.8, 6e23), vec_bool_type(true, false)))`` will return ``vec2(9.8, 314)``. :param a: - + value returned when a is false. :param b: - + value returned when a is true. :param c: - + the value to use to interpolate between x and y. :return: - - - :rtype: |vec_type| + The interpolated value. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/mix.xhtml @@ -1670,56 +1578,38 @@ float **mix** ( float a, float b, float c ) ---- -.. rst-class:: classref-method - -|vec_type| **mix** ( vecType a, |vec_type| b, |vec_bool_type| c ) - - - :param a: - - - :param b: - - :param c: - - - :return: - - - :rtype: |vec_type| - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/mix.xhtml - -.. rst-class:: classref-item-separator +.. _shader_func_fma: ----- +.. rst-class:: classref-method +|vec_type| **fma** ( |vec_type| a, |vec_type| b, |vec_type| c ) + Performs, where possible, a fused multiply-add operation, returning a * b + c. In use cases where the + return value is eventually consumed by a variable declared as precise: + - fma() is considered a single operation, whereas the expression a * b + c consumed by a variable declared as precise is considered two operations. -.. _shader_func_fma: + - The precision of fma() can differ from the precision of the expression a * b + c. -.. rst-class:: classref-method + - fma() will be computed with the same precision as any other fma() consumed by a precise variable, + giving invariant results for the same input values of a, b and c. -|vec_type| **fma** ( vecType a, |vec_type| b, |vec_type| c ) - - + Otherwise, in the absence of precise consumption, there are no special constraints on the number of operations + or difference in precision between fma() and the expression a * b + c. :param a: - + the first multiplicand. :param b: - + the second multiplicand. :param c: - + the value to be added to the result. :return: - - - :rtype: |vec_type| + value of ``a * b + c`` https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/fma.xhtml @@ -1736,21 +1626,22 @@ float **mix** ( float a, float b, float c ) |vec_type| **step** ( |vec_type| a, |vec_type| b ) - + Generates a step function by comparing b to a. + + Equivalent to ``if (b < a) { return 0.0; } else { return 1.0; }``. + Or if vec_type is a vector, a vector where the above operation has been performed on each component of the input vectors. + ie. ``step(vec2(4.2, 314), vec2(2.4, 980))`` would return ``vec2(step(a[0], b[0]), step(a[1], b[1]))``. + + For element i of the return value, 0.0 is returned if b[i] < a[i], and 1.0 is returned otherwise. :param a: - + the location of the edge of the step function. :param b: - - - :param : - + the value to be used to generate the step function. :return: - - - :rtype: |vec_type| + 0.0 or 1.0 https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/step.xhtml @@ -1763,21 +1654,22 @@ float **mix** ( float a, float b, float c ) |vec_type| **step** ( float a, |vec_type| b ) - + Generates a step function by comparing b to a. + + Equivalent to ``if (b < a) { return 0.0; } else { return 1.0; }``. + Or rather, the above operation will be performed on each component of the input vector. + ie. ``step(4.2, vec2(2.4, 980))`` would return the equivalent of ``vec2(step(42, b[0]), step(42, b[1]))``. + + For element i of the return value, 0.0 is returned if b[i] < a[i], and 1.0 is returned otherwise. :param a: - + the location of the edge of the step function. :param b: - - - :param : - + the value to be used to generate the step function. :return: - - - :rtype: |vec_type| + 0.0 or 1.0 https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/step.xhtml @@ -1792,23 +1684,30 @@ float **mix** ( float a, float b, float c ) .. rst-class:: classref-method -|vec_type| **smoothstep** ( vecType a, |vec_type| b, |vec_type| c ) +|vec_type| **smoothstep** ( |vec_type| a, |vec_type| b, |vec_type| c ) - + Performs smooth Hermite interpolation between 0 and 1 when a < c < b. + This is useful in cases where a threshold function with a smooth transition is desired. + + Smoothstep is equivalent to:: + + vec_type t; + t = clamp((c - a) / (b - a), 0.0, 1.0); + return t * t * (3.0 - 2.0 * t); + + Results are undefined if a ≥ b. :param a: - + the value of the lower edge of the Hermite function. :param b: - + the value of the upper edge of the Hermite function. :param c: - + the source value for interpolation. :return: - - - :rtype: |vec_type| + the interpolated value https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/smoothstep.xhtml @@ -1821,21 +1720,28 @@ float **mix** ( float a, float b, float c ) |vec_type| **smoothstep** ( float a, float b, |vec_type| c ) - + Performs smooth Hermite interpolation between 0 and 1 when a < c < b. + This is useful in cases where a threshold function with a smooth transition is desired. + + Smoothstep is equivalent to:: + + vec_type t; + t = clamp((c - a) / (b - a), 0.0, 1.0); + return t * t * (3.0 - 2.0 * t); + + Results are undefined if a ≥ b. :param a: - + the value of the lower edge of the Hermite function. :param b: - + the value of the upper edge of the Hermite function. :param c: - + the source value for interpolation. :return: - - - :rtype: |vec_type| + the interpolated value https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/smoothstep.xhtml @@ -1852,21 +1758,14 @@ float **mix** ( float a, float b, float c ) |vec_bool_type| **isnan** ( |vec_type| x ) - + For each element i of the result, returns true if x[i] is positive + or negative floating point NaN (Not a Number) and false otherwise. :param x: - - - :param : - - - :param : - + the value to test for NaN. :return: - - - :rtype: |vec_bool_type| + true or false https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/isnan.xhtml @@ -1883,21 +1782,14 @@ float **mix** ( float a, float b, float c ) |vec_bool_type| **isinf** ( |vec_type| x ) - + For each element i of the result, returns true if x[i] is positive or negative + floating point infinity and false otherwise. :param x: - - - :param : - - - :param : - + the value to test for infinity. :return: - - - :rtype: |vec_bool_type| + true or false https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/isinf.xhtml @@ -1914,21 +1806,15 @@ float **mix** ( float a, float b, float c ) |vec_int_type| **floatBitsToInt** ( |vec_type| x ) - + Returns the encoding of the floating-point parameters as int. - :param x: - - - :param : - + The floating-point bit-level representation is preserved. - :param : - + :param x: + the value whose floating point encoding to return. :return: - - - :rtype: |vec_int_type| + the floating-point encoding of x. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/floatBitsToInt.xhtml @@ -1945,21 +1831,15 @@ float **mix** ( float a, float b, float c ) |vec_uint_type| **floatBitsToUint** ( |vec_type| x ) - + Returns the encoding of the floating-point parameters as uint. - :param x: - - - :param : - + The floating-point bit-level representation is preserved. - :param : - + :param x: + the value whose floating point encoding to return. :return: - - - :rtype: |vec_uint_type| + the floating-point encoding of x. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/floatBitsToUint.xhtml @@ -1976,21 +1856,18 @@ float **mix** ( float a, float b, float c ) |vec_type| **intBitsToFloat** ( |vec_int_type| x ) - + Converts a bit encoding to a floating-point value. Opposite of `floatBitsToInt<_shader_func_floatBitsToInt>` - :param x: - + If the encoding of a NaN is passed in x, it will not signal and the resulting value will be undefined. - :param : - + If the encoding of a floating point infinity is passed in parameter x, the resulting floating-point value is + the corresponding (positive or negative) floating point infinity. - :param : - + :param x: + the bit encoding to return as a floating point value. :return: - - - :rtype: |vec_type| + a floating point value https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/intBitsToFloat.xhtml @@ -2007,21 +1884,18 @@ float **mix** ( float a, float b, float c ) |vec_type| **uintBitsToFloat** ( |vec_uint_type| x ) - + Converts a bit encoding to a floating-point value. Opposite of `floatBitsToUint<_shader_func_floatBitsToUint>` - :param x: - + If the encoding of a NaN is passed in x, it will not signal and the resulting value will be undefined. - :param : - + If the encoding of a floating point infinity is passed in parameter x, the resulting floating-point value is + the corresponding (positive or negative) floating point infinity. - :param : - + :param x: + the bit encoding to return as a floating point value. :return: - - - :rtype: |vec_type| + a floating point value https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/uintBitsToFloat.xhtml @@ -2038,33 +1912,33 @@ float **mix** ( float a, float b, float c ) Geometric Functions ^^^^^^^^^^^^^^^^^^^ -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`length` ( |vec_type| x) | Vector length. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`distance` ( |vec_type| a, |vec_type| b) | Distance between vectors i.e ``length(a - b)``. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`dot` ( |vec_type| a, |vec_type| b) | Dot product. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| vec3 | :ref:`cross` (vec3 a, vec3 b) | Cross product. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |vec_type| | :ref:`normalize` ( |vec_type| x) | Normalize to unit length. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| vec3 | :ref:`reflect` (vec3 I, vec3 N) | Reflect. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| vec3 | :ref:`refract` (vec3 I, vec3 N, float eta) | Refract. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |vec_type| | :ref:`faceforward` (vecType N, |vec_type| I, |vec_type| Nref) | If ``dot(Nref, I)`` < 0, return ``N``, otherwise ``-N``. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`matrixCompMult` (|mat_type| x, |mat_type| y) | Matrix component multiplication. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`outerProduct` ( |vec_type| column, |vec_type| row) | Matrix outer product. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`transpose` (|mat_type| m) | Transpose matrix. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`determinant` (|mat_type| m) | Matrix determinant. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`inverse` (|mat_type| m) | Inverse matrix. | -+------------+----------------------------------------------------------------------------------------+----------------------------------------------------------+ ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| float | :ref:`length` ( |vec_type| x) | Vector length. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| float | :ref:`distance` ( |vec_type| a, |vec_type| b) | Distance between vectors i.e ``length(a - b)``. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| float | :ref:`dot` ( |vec_type| a, |vec_type| b) | Dot product. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| vec3 | :ref:`cross` (vec3 a, vec3 b) | Cross product. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |vec_type| | :ref:`normalize` ( |vec_type| x) | Normalize to unit length. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| vec3 | :ref:`reflect` (vec3 I, vec3 N) | Reflect. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| vec3 | :ref:`refract` (vec3 I, vec3 N, float eta) | Refract. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |vec_type| | :ref:`faceforward` (|vec_type| N, |vec_type| I, |vec_type| Nref) | If ``dot(Nref, I)`` < 0, return ``N``, otherwise ``-N``. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |mat_type| | :ref:`matrixCompMult` (|mat_type| x, |mat_type| y) | Matrix component multiplication. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |mat_type| | :ref:`outerProduct` ( |vec_type| column, |vec_type| row) | Matrix outer product. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |mat_type| | :ref:`transpose` (|mat_type| m) | Transpose matrix. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| float | :ref:`determinant` (|mat_type| m) | Matrix determinant. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |mat_type| | :ref:`inverse` (|mat_type| m) | Inverse matrix. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -2318,9 +2192,9 @@ Bitwise operations +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ | |vec_uint_type| | :ref:`usubBorrow` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| borrow) | Subtracts two unsigned integers and generates borrow. | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`ldexp` (vecType x, out |vec_int_type| exp) | Assemble a floating-point number from a value and exponent. | +| |vec_type| | :ref:`ldexp` (|vec_type| x, out |vec_int_type| exp) | Assemble a floating-point number from a value and exponent. | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`frexp` (vecType x, out |vec_int_type| exp) | Splits a floating-point number (``x``) into significand integral | +| |vec_type| | :ref:`frexp` (|vec_type| x, out |vec_int_type| exp) | Splits a floating-point number (``x``) into significand integral | | | | components | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ From 01bc15aa26abaf30daed757212762f217673edab Mon Sep 17 00:00:00 2001 From: ashbygeek Date: Mon, 6 May 2024 23:30:52 -0400 Subject: [PATCH 05/25] complete the Geometric Functions section --- .../shader_reference/shader_functions.rst | 2938 ++++++++++++++++- 1 file changed, 2872 insertions(+), 66 deletions(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index 324d5fe4d54..8f8045585d8 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -1945,6 +1945,386 @@ Geometric Functions ---------- +.. _shader_func_length: + +.. rst-class:: classref-method + +float **length** ( |vec_type| x ) + + Returns the length of the vector. + ie. ``sqrt(x[0] * x[0] + x[1] * x[1] + ... + x[n] * x[n])`` + + :param x: + the vector + + :return: + the length of the vector. + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/length.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + + +.. _shader_func_distance: + +.. rst-class:: classref-method + +float **distance** ( |vec_type| a, |vec_type| b ) + + Returns the distance between the two points a and b. + + i.e., ``length(b - a);`` + + :param a: + the first point + + :param b: + the second point + + :return: + the scalar distance between the points + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/distance.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + + +.. _shader_func_dot: + +.. rst-class:: classref-method + +float **dot** ( |vec_type| a, |vec_type| b ) + + Returns the dot product of two vectors, a and b. + i.e., ``a.x * b.x + a.y * b.y + ...`` + + :param a: + the first vector + + :param b: + the second vector + + :return: + the dot product + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/dot.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + + +.. _shader_func_cross: + +.. rst-class:: classref-method + +vec3 **cross** ( vec3 a, vec3 b ) + + Returns the cross product of two vectors. + ie:: + vec2( a.y * b.z - b.y * a.z, + a.z * b.x - b.z * a.x, + a.x * b.z - b.x * a.y ) + + :param a: + the first vector + + :param b: + the second vector + + :return: + the cross product + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/cross.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + + +.. _shader_func_normalize: + +.. rst-class:: classref-method + +|vec_type| **normalize** ( |vec_type| x ) + + Returns a vector with the same direction as x but with length 1. + + :param x: + the vector to normalize. + + :return: + the normalized vector. + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/normalize.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + + +.. _shader_func_reflect: + +.. rst-class:: classref-method + +vec3 **reflect** ( vec3 I, vec3 N ) + + Calculate the reflection direction for an incident vector. + + For a given incident vector I and surface normal N reflect returns the reflection direction calculated as ``I - 2.0 * dot(N, I) * N``. + + .. Note:: + N should be normalized in order to achieve the desired result. + + :param I: + the incident vector + + :param N: + the normal vector + + :return: + the reflection vector + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/reflect.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + + +.. _shader_func_refract: + +.. rst-class:: classref-method + +vec3 **refract** ( vec3 I, vec3 N, float eta ) + + Calculate the refraction direction for an incident vector. + + For a given incident vector I, surface normal N and ratio of indices of refraction, eta, refract returns the refraction vector, R. + + R is calculated as:: + + k = 1.0 - eta * eta * (1.0 - dot(N, I) * dot(N, I)); + if (k < 0.0) + R = genType(0.0); // or genDType(0.0) + else + R = eta * I - (eta * dot(N, I) + sqrt(k)) * N; + + .. Note:: + The input parameters I and N should be normalized in order to achieve the desired result. + + :param I: + the incident vector. + + :param N: + the normal vector. + + :param eta: + the ratio of indices of refraction. + + :return: + the refraction vector. + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/refract.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + + +.. _shader_func_faceforward: + +.. rst-class:: classref-method + +|vec_type| **faceforward** ( |vec_type| N, |vec_type| I, |vec_type| Nref ) + + Return a vector pointing in the same direction as another. + + Orients a vector to point away from a surface as defined by its normal. + If ``dot(Nref, I) < 0`` faceforward returns ``N``, otherwise it returns ``-N``. + + :param N: + the vector to orient. + + :param I: + the incident vector. + + :param Nref: + the reference vector. + + :return: + the oriented vector. + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/faceforward.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + + +.. _shader_func_matrixCompMult: + +.. rst-class:: classref-method + +|mat_type| **matrixCompMult** ( |mat_type| x, |mat_type| y ) + + Perform a component-wise multiplication of two matrices. + + Performs a component-wise multiplication of two matrices, yielding a result + matrix where each component, ``result[i][j]`` is computed as the scalar + product of ``x[i][j]`` and ``y[i][j]``. + + :param x: + the first matrix multiplicand. + + :param y: + the second matrix multiplicand. + + :return: + the resultant matrix. + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/matrixCompMult.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + + +.. _shader_func_outerProduct: + +.. rst-class:: classref-method + +|mat_type| **outerProduct** ( |vec_type| column, |vec_type| row ) + + Calculate the outer product of a pair of vectors. + + Does a linear algebraic matrix multiply ``column * row``, yielding a matrix whose number of + rows is the number of components in ``column`` and whose number of columns is the number of + components in ``row``. + + :param column: + the column vector for multiplication. + + :param row: + the row vector for multiplication. + + :return: + the outer product matrix. + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/outerProduct.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + + +.. _shader_func_transpose: + +.. rst-class:: classref-method + +|mat_type| **transpose** ( |mat_type| m ) + + Calculate the transpose of a matrix. + + :param m: + the matrix to transpose. + + :return: + a new matrix that is the transpose of the input matrix. + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/transpose.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + + +.. _shader_func_determinant: + +.. rst-class:: classref-method + +float **determinant** ( |mat_type| m ) + + Calculate the determinant of a matrix. + + :param m: + the matrix. + + :return: + the determinant of the input matrix. + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/determinant.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + + +.. _shader_func_inverse: + +.. rst-class:: classref-method + +|mat_type| **inverse** ( |mat_type| m ) + + Calculate the inverse of a matrix. + + The values in the returned matrix are undefined if m is singular or poorly-conditioned (nearly singular). + + :param m: + the matrix of which to take the inverse. + + :return: + a new matrix which is the inverse of the input matrix. + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/inverse.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + Comparison Functions ^^^^^^^^^^^^^^^^^^^^ @@ -1973,12 +2353,272 @@ Comparison Functions ---- +.. _shader_func_lessThan: -Texture Functions -^^^^^^^^^^^^^^^^^ +.. rst-class:: classref-method -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec2 | :ref:`textureSize` ( |gsampler2D| s, int lod) | Get the size of a texture. | +|vec_bool_type| **lessThan** ( |vec_type| x, |vec_type| y ) + + + + :param x: + + + :param y: + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/lessThan.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_greaterThan: + +.. rst-class:: classref-method + +|vec_bool_type| **greaterThan** ( |vec_type| x, |vec_type| y ) + + + + :param x: + + + :param y: + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/greaterThan.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_lessThanEqual: + +.. rst-class:: classref-method + +|vec_bool_type| **lessThanEqual** ( |vec_type| x, |vec_type| y ) + + + + :param x: + + + :param y: + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/lessThanEqual.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_greaterThanEqual: + +.. rst-class:: classref-method + +|vec_bool_type| **greaterThanEqual** ( |vec_type| x, |vec_type| y ) + + + + :param x: + + + :param y: + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/greaterThanEqual.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_equal: + +.. rst-class:: classref-method + +|vec_bool_type| **equal** ( |vec_type| x, |vec_type| y ) + + + + :param x: + + + :param y: + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/equal.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_notEqual: + +.. rst-class:: classref-method + +|vec_bool_type| **notEqual** ( |vec_type| x, |vec_type| y ) + + + + :param x: + + + :param y: + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/notEqual.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_any: + +.. rst-class:: classref-method + +bool **any** ( |vec_bool_type| x ) + + + + :param x: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/any.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_all: + +.. rst-class:: classref-method + +bool **all** ( |vec_bool_type| x ) + + + + :param x: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/all.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_not: + +.. rst-class:: classref-method + +|vec_bool_type| **not** ( |vec_bool_type| x ) + + + + :param x: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/not.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +Texture Functions +^^^^^^^^^^^^^^^^^ + ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| ivec2 | :ref:`textureSize` ( |gsampler2D| s, int lod) | Get the size of a texture. | +--------------+-----------------------------------------------------------------------------------------------------+ | | ivec2 | :ref:`textureSize` (samplerCube s, int lod) | The LOD defines which mipmap level is used. An LOD value of ``0`` | +--------------+-----------------------------------------------------------------------------------------------------+ | @@ -2117,77 +2757,1744 @@ Texture Functions -Packing/Unpacking Functions -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _shader_func_textureSize: -+------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packHalf2x16` (vec2 v) | Convert two 32-bit floating-point numbers into 16-bit | -| | | and pack them into a 32-bit unsigned integer and vice-versa. | -+------+--------------------------------------------------------------+ + -| vec2 | :ref:`unpackHalf2x16` (uint v) | | -+------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packUnorm2x16` (vec2 v) | Convert two 32-bit floating-point numbers (clamped | -| | | within 0..1 range) into 16-bit and pack them | -+------+--------------------------------------------------------------+ + -| vec2 | :ref:`unpackUnorm2x16` (uint v) | into a 32-bit unsigned integer and vice-versa. | -+------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packSnorm2x16` (vec2 v) | Convert two 32-bit floating-point numbers (clamped | -| | | within -1..1 range) into 16-bit and pack them | -+------+--------------------------------------------------------------+ + -| vec2 | :ref:`unpackSnorm2x16` (uint v) | into a 32-bit unsigned integer and vice-versa. | -+------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packUnorm4x8` (vec4 v) | Convert four 32-bit floating-point numbers (clamped | -| | | within 0..1 range) into 8-bit and pack them | -+------+--------------------------------------------------------------+ + -| vec4 | :ref:`unpackUnorm4x8` (uint v) | into a 32-bit unsigned integer and vice-versa. | -+------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packSnorm4x8` (vec4 v) | Convert four 32-bit floating-point numbers (clamped | -| | | within -1..1 range) into 8-bit and pack them | -+------+--------------------------------------------------------------+ + -| vec4 | :ref:`unpackSnorm4x8` (uint v) | into a 32-bit unsigned integer and vice-versa. | -+------+--------------------------------------------------------------+--------------------------------------------------------------+ +.. rst-class:: classref-method -.. rst-class:: classref-section-separator +ivec2 **textureSize** ( |gsampler2D| s, int lod ) + + + + :param s: + + + :param lod: + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureSize.xhtml + +.. rst-class:: classref-item-separator ---- +.. rst-class:: classref-method +ivec2 **textureSize** ( samplerCube s, int lod ) -Bitwise operations -^^^^^^^^^^^^^^^^^^ + + :param s: + + + :param lod: + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureSize.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +ivec2 **textureSize** ( samplerCubeArray s, int lod ) + + + + :param s: + + + :param lod: + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureSize.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +ivec3 **textureSize** ( |gsampler2DArray| s, int lod ) + + + + :param s: + + + :param lod: + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureSize.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +ivec3 **textureSize** ( |gsampler3D| s, int lod ) + + + + :param s: + + + :param lod: + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureSize.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_textureQueryLod: + +.. rst-class:: classref-method + +vec2 **textureQueryLod** ( |gsampler2D| s, vec2 p ) + + + + :param s: + + + :param p: + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLod.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +vec3 **textureQueryLod** ( |gsampler2DArray| s, vec2 p ) + + + + :param s: + + + :param p: + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLod.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +vec2 **textureQueryLod** ( |gsampler3D| s, vec3 p ) + + + + :param s: + + + :param p: + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLod.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +vec2 **textureQueryLod** ( samplerCube s, vec3 p ) + + + + :param s: + + + :param p: + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLod.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_textureQueryLevels: + +.. rst-class:: classref-method + +int **textureQueryLevels** ( |gsampler2D| s ) + + + + :param s: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLevels.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +int **textureQueryLevels** ( |gsampler2DArray| s ) + + + + :param s: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLevels.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +int **textureQueryLevels** ( |gsampler3D| s ) + + + + :param s: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLevels.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +int **textureQueryLevels** ( samplerCube s ) + + + + :param s: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLevels.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_texture: + +.. rst-class:: classref-method + +|gvec4_type| **texture** ( |gsampler2D| s, vec2 p [, float bias] ) + + + + :param s: + + + :param p: + + + :param bias]: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texture.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|gvec4_type| **texture** ( |gsampler2DArray| s, vec3 p [, float bias] ) + + + + :param s: + + + :param p: + + + :param bias]: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texture.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|gvec4_type| **texture** ( |gsampler3D| s, vec3 p [, float bias] ) + + + + :param s: + + + :param p: + + + :param bias]: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texture.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +vec4 **texture** ( samplerCube s, vec3 p [, float bias] ) + + + + :param s: + + + :param p: + + + :param bias]: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texture.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +vec4 **texture** ( samplerCubeArray s, vec4 p [, float bias] ) + + + + :param s: + + + :param p: + + + :param bias]: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texture.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_textureProj: + +.. rst-class:: classref-method + +|gvec4_type| **textureProj** ( |gsampler2D| s, vec3 p [, float bias] ) + + + + :param s: + + + :param p: + + + :param bias]: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProj.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|gvec4_type| **textureProj** ( |gsampler2D| s, vec4 p [, float bias] ) + + + + :param s: + + + :param p: + + + :param bias]: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProj.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|gvec4_type| **textureProj** ( |gsampler3D| s, vec4 p [, float bias] ) + + + + :param s: + + + :param p: + + + :param bias]: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProj.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_textureLod: + +.. rst-class:: classref-method + +|gvec4_type| **textureLod** ( |gsampler2D| s, vec2 p, float lod ) + + + + :param s: + + + :param p: + + + :param lod: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureLod.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|gvec4_type| **textureLod** ( |gsampler2DArray| s, vec3 p, float lod ) + + + + :param s: + + + :param p: + + + :param lod: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureLod.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|gvec4_type| **textureLod** ( |gsampler3D| s, vec3 p, float lod ) + + + + :param s: + + + :param p: + + + :param lod: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureLod.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +vec4 **textureLod** ( samplerCube s, vec3 p, float lod ) + + + + :param s: + + + :param p: + + + :param lod: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureLod.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +vec4 **textureLod** ( samplerCubeArray s, vec4 p, float lod ) + + + + :param s: + + + :param p: + + + :param lod: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureLod.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_textureProjLod: + +.. rst-class:: classref-method + +|gvec4_type| **textureProjLod** ( |gsampler2D| s, vec3 p, float lod ) + + + + :param s: + + + :param p: + + + :param lod: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjLod.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|gvec4_type| **textureProjLod** ( |gsampler2D| s, vec4 p, float lod ) + + + + :param s: + + + :param p: + + + :param lod: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjLod.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|gvec4_type| **textureProjLod** ( |gsampler3D| s, vec4 p, float lod ) + + + + :param s: + + + :param p: + + + :param lod: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjLod.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_textureGrad: + +.. rst-class:: classref-method + +|gvec4_type| **textureGrad** ( |gsampler2D| s, vec2 p, vec2 dPdx, vec2 dPdy ) + + + + :param s: + + + :param p: + + + :param dPdx: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGrad.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|gvec4_type| **textureGrad** ( |gsampler2DArray| s, vec3 p, vec2 dPdx, vec2 dPdy ) + + + + :param s: + + + :param p: + + + :param dPdx: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGrad.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|gvec4_type| **textureGrad** ( |gsampler3D| s, vec3 p, vec2 dPdx, vec2 dPdy ) + + + + :param s: + + + :param p: + + + :param dPdx: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGrad.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +vec4 **textureGrad** ( samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy ) + + + + :param s: + + + :param p: + + + :param dPdx: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGrad.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) + + + + :param s: + + + :param p: + + + :param dPdx: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGrad.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_textureProjGrad: + +.. rst-class:: classref-method + +|gvec4_type| **textureProjGrad** ( |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy ) + + + + :param s: + + + :param p: + + + :param dPdx: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjGrad.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|gvec4_type| **textureProjGrad** ( |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy ) + + + + :param s: + + + :param p: + + + :param dPdx: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjGrad.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|gvec4_type| **textureProjGrad** ( |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy ) + + + + :param s: + + + :param p: + + + :param dPdx: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjGrad.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_texelFetch: + +.. rst-class:: classref-method + +|gvec4_type| **texelFetch** ( |gsampler2D| s, ivec2 p, int lod ) + + + + :param s: + + + :param p: + + + :param lod: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texelFetch.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|gvec4_type| **texelFetch** ( |gsampler2DArray| s, ivec3 p, int lod ) + + + + :param s: + + + :param p: + + + :param lod: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texelFetch.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|gvec4_type| **texelFetch** ( |gsampler3D| s, ivec3 p, int lod ) + + + + :param s: + + + :param p: + + + :param lod: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texelFetch.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_textureGather: + +.. rst-class:: classref-method + +|gvec4_type| **textureGather** ( |gsampler2D| s, vec2 p [, int comps] ) + + + + :param s: + + + :param p: + + + :param comps]: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGather.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|gvec4_type| **textureGather** ( |gsampler2DArray| s, vec3 p [, int comps] ) + + + + :param s: + + + :param p: + + + :param comps]: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGather.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) + + + + :param s: + + + :param p: + + + :param comps]: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGather.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_dFdx: + +.. rst-class:: classref-method + +|vec_type| **dFdx** ( |vec_type| p ) + + + + :param p: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/dFdx.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_dFdxCoarse: + +.. rst-class:: classref-method + +|vec_type| **dFdxCoarse** ( |vec_type| p ) + + + + :param p: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/dFdxCoarse.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_dFdxFine: + +.. rst-class:: classref-method + +|vec_type| **dFdxFine** ( |vec_type| p ) + + + + :param p: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/dFdxFine.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_dFdy: + +.. rst-class:: classref-method + +|vec_type| **dFdy** ( |vec_type| p ) + + + + :param p: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/dFdy.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_dFdyCoarse: + +.. rst-class:: classref-method + +|vec_type| **dFdyCoarse** ( |vec_type| p ) + + + + :param p: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/dFdyCoarse.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_dFdyFine: + +.. rst-class:: classref-method + +|vec_type| **dFdyFine** ( |vec_type| p ) + + + + :param p: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/dFdyFine.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_fwidth: + +.. rst-class:: classref-method + +|vec_type| **fwidth** ( |vec_type| p ) + + + + :param p: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/fwidth.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_fwidthCoarse: + +.. rst-class:: classref-method + +|vec_type| **fwidthCoarse** ( |vec_type| p ) + + + + :param p: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/fwidthCoarse.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_fwidthFine: + +.. rst-class:: classref-method + +|vec_type| **fwidthFine** ( |vec_type| p ) + + + + :param p: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/fwidthFine.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +Packing/Unpacking Functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ++------+--------------------------------------------------------------+--------------------------------------------------------------+ +| uint | :ref:`packHalf2x16` (vec2 v) | Convert two 32-bit floating-point numbers into 16-bit | +| | | and pack them into a 32-bit unsigned integer and vice-versa. | ++------+--------------------------------------------------------------+ + +| vec2 | :ref:`unpackHalf2x16` (uint v) | | ++------+--------------------------------------------------------------+--------------------------------------------------------------+ +| uint | :ref:`packUnorm2x16` (vec2 v) | Convert two 32-bit floating-point numbers (clamped | +| | | within 0..1 range) into 16-bit and pack them | ++------+--------------------------------------------------------------+ + +| vec2 | :ref:`unpackUnorm2x16` (uint v) | into a 32-bit unsigned integer and vice-versa. | ++------+--------------------------------------------------------------+--------------------------------------------------------------+ +| uint | :ref:`packSnorm2x16` (vec2 v) | Convert two 32-bit floating-point numbers (clamped | +| | | within -1..1 range) into 16-bit and pack them | ++------+--------------------------------------------------------------+ + +| vec2 | :ref:`unpackSnorm2x16` (uint v) | into a 32-bit unsigned integer and vice-versa. | ++------+--------------------------------------------------------------+--------------------------------------------------------------+ +| uint | :ref:`packUnorm4x8` (vec4 v) | Convert four 32-bit floating-point numbers (clamped | +| | | within 0..1 range) into 8-bit and pack them | ++------+--------------------------------------------------------------+ + +| vec4 | :ref:`unpackUnorm4x8` (uint v) | into a 32-bit unsigned integer and vice-versa. | ++------+--------------------------------------------------------------+--------------------------------------------------------------+ +| uint | :ref:`packSnorm4x8` (vec4 v) | Convert four 32-bit floating-point numbers (clamped | +| | | within -1..1 range) into 8-bit and pack them | ++------+--------------------------------------------------------------+ + +| vec4 | :ref:`unpackSnorm4x8` (uint v) | into a 32-bit unsigned integer and vice-versa. | ++------+--------------------------------------------------------------+--------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + + + +.. _shader_func_packHalf2x16: + +.. rst-class:: classref-method + +uint **packHalf2x16** ( vec2 v ) + + + + :param v: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/packHalf2x16.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_unpackHalf2x16: + +.. rst-class:: classref-method + +vec2 **unpackHalf2x16** ( uint v ) + + + + :param v: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/unpackHalf2x16.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_packUnorm2x16: + +.. rst-class:: classref-method + +uint **packUnorm2x16** ( vec2 v ) + + + + :param v: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/packUnorm2x16.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_unpackUnorm2x16: + +.. rst-class:: classref-method + +vec2 **unpackUnorm2x16** ( uint v ) + + + + :param v: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/unpackUnorm2x16.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_packSnorm2x16: + +.. rst-class:: classref-method + +uint **packSnorm2x16** ( vec2 v ) + + + + :param v: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/packSnorm2x16.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_unpackSnorm2x16: + +.. rst-class:: classref-method + +vec2 **unpackSnorm2x16** ( uint v ) + + + + :param v: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/unpackSnorm2x16.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_packUnorm4x8: + +.. rst-class:: classref-method + +uint **packUnorm4x8** ( vec4 v ) + + + + :param v: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/packUnorm4x8.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_unpackUnorm4x8: + +.. rst-class:: classref-method + +vec4 **unpackUnorm4x8** ( uint v ) + + + + :param v: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/unpackUnorm4x8.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_packSnorm4x8: + +.. rst-class:: classref-method + +uint **packSnorm4x8** ( vec4 v ) + + + + :param v: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/packSnorm4x8.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_unpackSnorm4x8: + +.. rst-class:: classref-method + +vec4 **unpackSnorm4x8** ( uint v ) + + + + :param v: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/unpackSnorm4x8.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +Bitwise operations +^^^^^^^^^^^^^^^^^^ + ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_int_type| | :ref:`bitfieldExtract` ( |vec_int_type| value, int offset, int bits) | Extracts a range of bits from an integer. | +| | | | +| |vec_uint_type| | :ref:`bitfieldExtract` ( |vec_uint_type| value, int offset, int bits) | | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_int_type| | :ref:`bitfieldInsert` ( |vec_int_type| base, |vec_int_type| insert,int offset, int bits) | Insert a range of bits into an integer. | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | +| |vec_uint_type| | :ref:`bitfieldInsert` (|vec_uint_type| base, |vec_uint_type| insert, int offset, int bits) | | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_int_type| | :ref:`bitfieldReverse` ( |vec_int_type| value) | Reverse the order of bits in an integer. | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | +| |vec_uint_type| | :ref:`bitfieldReverse` ( |vec_uint_type| value) | | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_int_type| | :ref:`bitCount` ( |vec_int_type| value) | Counts the number of 1 bits in an integer. | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | +| |vec_uint_type| | :ref:`bitCount` ( |vec_uint_type| value) | | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_int_type| | :ref:`findLSB` ( |vec_int_type| value) | Find the index of the least significant bit set to 1 in an integer. | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | +| |vec_uint_type| | :ref:`findLSB` ( |vec_uint_type| value) | | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_int_type| | :ref:`findMSB` ( |vec_int_type| value) | Find the index of the most significant bit set to 1 in an integer. | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | +| |vec_uint_type| | :ref:`findMSB` ( |vec_uint_type| value) | | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |void| | :ref:`imulExtended` ( |vec_int_type| x, |vec_int_type| y, out |vec_int_type| msb, out |vec_int_type| lsb) | Multiplies two 32-bit numbers and produce a 64-bit result. | ++-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | +| |void| | :ref:`umulExtended` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| msb, out |vec_uint_type| lsb) | | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`bitfieldExtract` ( |vec_int_type| value, int offset, int bits) | Extracts a range of bits from an integer. | -| | | | -| |vec_uint_type| | :ref:`bitfieldExtract` ( |vec_uint_type| value, int offset, int bits) | | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`bitfieldInsert` ( |vec_int_type| base, |vec_int_type| insert, | Insert a range of bits into an integer. | -| | int offset, int bits) | | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`bitfieldInsert` (|vec_uint_type| base, |vec_uint_type| insert, int offset, | | -| | int bits) | | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`bitfieldReverse` ( |vec_int_type| value) | Reverse the order of bits in an integer. | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`bitfieldReverse` ( |vec_uint_type| value) | | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`bitCount` ( |vec_int_type| value) | Counts the number of 1 bits in an integer. | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`bitCount` ( |vec_uint_type| value) | | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`findLSB` ( |vec_int_type| value) | Find the index of the least significant bit set to 1 in an integer. | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`findLSB` ( |vec_uint_type| value) | | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`findMSB` ( |vec_int_type| value) | Find the index of the most significant bit set to 1 in an integer. | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`findMSB` ( |vec_uint_type| value) | | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |void| | :ref:`imulExtended` ( |vec_int_type| x, |vec_int_type| y,out |vec_int_type| msb, out |vec_int_type| lsb) | Multiplies two 32-bit numbers and produce a 64-bit result. | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | -| |void| | :ref:`umulExtended` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| msb, out |vec_uint_type| lsb) | | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ | |vec_uint_type| | :ref:`uaddCarry` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| carry) | Adds two unsigned integers and generates carry. | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ | |vec_uint_type| | :ref:`usubBorrow` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| borrow) | Subtracts two unsigned integers and generates borrow. | @@ -2199,12 +4506,511 @@ Bitwise operations +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -.. rst-class:: classref-section-separator +.. rst-class:: classref-section-separator + +---- + + + +.. _shader_func_bitfieldExtract: + +.. rst-class:: classref-method + +|vec_int_type| **bitfieldExtract** ( |vec_int_type| value, int offset, int bits ) + + + + :param value: + + + :param offset: + + + :param bits: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitfieldExtract.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_uint_type| **bitfieldExtract** ( |vec_uint_type| value, int offset, int bits ) + + + + :param value: + + + :param offset: + + + :param bits: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitfieldExtract.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_bitfieldInsert: + +.. rst-class:: classref-method + +|vec_int_type| **bitfieldInsert** ( |vec_int_type| base, |vec_int_type| insert, int offset, int bits ) + + + + :param base: + + + :param insert: + + + :param offset: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitfieldInsert.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_uint_type| **bitfieldInsert** ( |vec_uint_type| base, |vec_uint_type| insert, int offset, int bits ) + + + + :param base: + + + :param insert: + + + :param offset: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitfieldInsert.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_bitfieldReverse: + +.. rst-class:: classref-method + +|vec_int_type| **bitfieldReverse** ( |vec_int_type| value ) + + + + :param value: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitfieldReverse.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_uint_type| **bitfieldReverse** ( |vec_uint_type| value ) + + + + :param value: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitfieldReverse.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_bitCount: + +.. rst-class:: classref-method + +|vec_int_type| **bitCount** ( |vec_int_type| value ) + + + + :param value: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitCount.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_uint_type| **bitCount** ( |vec_uint_type| value ) + + + + :param value: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitCount.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_findLSB: + +.. rst-class:: classref-method + +|vec_int_type| **findLSB** ( |vec_int_type| value ) + + + + :param value: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/findLSB.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_uint_type| **findLSB** ( |vec_uint_type| value ) + + + + :param value: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/findLSB.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_findMSB: + +.. rst-class:: classref-method + +|vec_int_type| **findMSB** ( |vec_int_type| value ) + + + + :param value: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/findMSB.xhtml + +.. rst-class:: classref-item-separator + +---- + + +.. rst-class:: classref-method + +|vec_uint_type| **findMSB** ( |vec_uint_type| value ) + + + + :param value: + + + :param : + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/findMSB.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_imulExtended: + +.. rst-class:: classref-method + +|void| **imulExtended** ( |vec_int_type| x, |vec_int_type| y, out |vec_int_type| msb, out |vec_int_type| lsb ) + + + + :param x: + + + :param y: + + + :param msb: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/imulExtended.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_umulExtended: + +.. rst-class:: classref-method + +|void| **umulExtended** ( |vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| msb, out |vec_uint_type| lsb ) + + + + :param x: + + + :param y: + + + :param msb: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/umulExtended.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_uaddCarry: + +.. rst-class:: classref-method + +|vec_uint_type| **uaddCarry** ( |vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| carry ) + + + + :param x: + + + :param y: + + + :param carry: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/uaddCarry.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_usubBorrow: + +.. rst-class:: classref-method + +|vec_uint_type| **usubBorrow** ( |vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| borrow ) + + + + :param x: + + + :param y: + + + :param borrow: + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/usubBorrow.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_ldexp: + +.. rst-class:: classref-method + +|vec_type| **ldexp** ( |vec_type| x, out |vec_int_type| exp ) + + + + :param x: + + + :param exp: + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/ldexp.xhtml + +.. rst-class:: classref-item-separator + +---- + + + + +.. _shader_func_frexp: + +.. rst-class:: classref-method + +|vec_type| **frexp** ( |vec_type| x, out |vec_int_type| exp ) + + + + :param x: + + + :param exp: + + + :param : + + + :return: + + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/frexp.xhtml + +.. rst-class:: classref-item-separator ---- + + .. |void| replace:: :abbr:`void (No return value.)` .. |vec_type| replace:: :abbr:`vec_type (Any of: float, vec2, vec3, vec4)` .. |vec_int_type| replace:: :abbr:`vec_int_type (Any of: int, ivec2, ivec3, ivec4)` From 12204a1e8fd5e13c061cedb9698748d7cd760d7e Mon Sep 17 00:00:00 2001 From: ashbygeek Date: Tue, 7 May 2024 00:17:40 -0400 Subject: [PATCH 06/25] completed comparison functions --- .../shader_reference/shader_functions.rst | 125 ++++++++---------- 1 file changed, 57 insertions(+), 68 deletions(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index 8f8045585d8..496e8eff500 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -2034,7 +2034,8 @@ float **dot** ( |vec_type| a, |vec_type| b ) vec3 **cross** ( vec3 a, vec3 b ) Returns the cross product of two vectors. - ie:: + i.e.:: + vec2( a.y * b.z - b.y * a.z, a.z * b.x - b.z * a.x, a.x * b.z - b.x * a.y ) @@ -2359,19 +2360,16 @@ Comparison Functions |vec_bool_type| **lessThan** ( |vec_type| x, |vec_type| y ) - + Perform a component-wise less-than comparison of two vectors. :param x: - + the first vector for comparison. :param y: - - - :param : - + the first vector for comparison. :return: - + a boolean vector in which each element i is computed as ``x[i] < y[i]``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/lessThan.xhtml @@ -2388,19 +2386,16 @@ Comparison Functions |vec_bool_type| **greaterThan** ( |vec_type| x, |vec_type| y ) - + Perform a component-wise greater-than comparison of two vectors. :param x: - + the first vector for comparison. :param y: - - - :param : - + the first vector for comparison. :return: - + a boolean vector in which each element i is computed as ``x[i] > y[i]``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/greaterThan.xhtml @@ -2417,19 +2412,16 @@ Comparison Functions |vec_bool_type| **lessThanEqual** ( |vec_type| x, |vec_type| y ) - + Perform a component-wise less-than-or-equal comparison of two vectors. :param x: - + the first vector for comparison. :param y: - - - :param : - + the first vector for comparison. :return: - + a boolean vector in which each element i is computed as ``x[i] ≤ y[i]``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/lessThanEqual.xhtml @@ -2446,19 +2438,16 @@ Comparison Functions |vec_bool_type| **greaterThanEqual** ( |vec_type| x, |vec_type| y ) - + Perform a component-wise greater-than-or-equal comparison of two vectors. :param x: - + the first vector for comparison. :param y: - - - :param : - + the first vector for comparison. :return: - + a boolean vector in which each element i is computed as ``x[i] ≥ y[i]``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/greaterThanEqual.xhtml @@ -2475,19 +2464,16 @@ Comparison Functions |vec_bool_type| **equal** ( |vec_type| x, |vec_type| y ) - + Perform a component-wise equal-to comparison of two vectors. :param x: - + the first vector for comparison. :param y: - - - :param : - + the first vector for comparison. :return: - + a boolean vector in which each element i is computed as ``x[i] == y[i]``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/equal.xhtml @@ -2504,19 +2490,16 @@ Comparison Functions |vec_bool_type| **notEqual** ( |vec_type| x, |vec_type| y ) - + Perform a component-wise not-equal-to comparison of two vectors. :param x: - + the first vector for comparison. :param y: - - - :param : - + the first vector for comparison. :return: - + a boolean vector in which each element i is computed as ``x[i] != y[i]``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/notEqual.xhtml @@ -2533,19 +2516,24 @@ Comparison Functions bool **any** ( |vec_bool_type| x ) - + Check whether any element of a boolean vector is true. - :param x: - + Functionally equivalent to:: - :param : - + bool any(bvec x) { // bvec can be bvec2, bvec3 or bvec4 + bool result = false; + int i; + for (i = 0; i < x.length(); ++i) { + result |= x[i]; + } + return result; + } - :param : - + :param x: + the vector to be tested for truth. :return: - + true if any element of x is true and false otherwise. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/any.xhtml @@ -2562,19 +2550,26 @@ bool **any** ( |vec_bool_type| x ) bool **all** ( |vec_bool_type| x ) - + Check whether all elements of a boolean vector are true. - :param x: - + Functionally equivalent to:: - :param : - + bool all(bvec x) // bvec can be bvec2, bvec3 or bvec4 + { + bool result = true; + int i; + for (i = 0; i < x.length(); ++i) + { + result &= x[i]; + } + return result; + } - :param : - + :param x: + the vector to be tested for truth. :return: - + true if all elements of x are true and false otherwise. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/all.xhtml @@ -2591,19 +2586,13 @@ bool **all** ( |vec_bool_type| x ) |vec_bool_type| **not** ( |vec_bool_type| x ) - + Logically invert a boolean vector. :param x: - - - :param : - - - :param : - + the vector to be inverted. :return: - + a new boolean vector for which each element i is computed as !x[i]. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/not.xhtml From 673ec8c928ba51b3b2de11539c9f77c5f51ab3d6 Mon Sep 17 00:00:00 2001 From: ashbygeek Date: Tue, 7 May 2024 00:18:24 -0400 Subject: [PATCH 07/25] halfway through texture functions --- .../shader_reference/shader_functions.rst | 631 +++++++++++------- 1 file changed, 395 insertions(+), 236 deletions(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index 496e8eff500..77fb3ba4b15 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -2608,10 +2608,10 @@ Texture Functions +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ | ivec2 | :ref:`textureSize` ( |gsampler2D| s, int lod) | Get the size of a texture. | ++--------------+-----------------------------------------------------------------------------------------------------+ The LOD defines which mipmap level is used. An LOD value of ``0`` | +| ivec2 | :ref:`textureSize` (samplerCube s, int lod) | will use the full resolution texture. | +--------------+-----------------------------------------------------------------------------------------------------+ | -| ivec2 | :ref:`textureSize` (samplerCube s, int lod) | The LOD defines which mipmap level is used. An LOD value of ``0`` | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| ivec2 | :ref:`textureSize` (samplerCubeArray s, int lod) | will use the full resolution texture. | +| ivec2 | :ref:`textureSize` (samplerCubeArray s, int lod) | | +--------------+-----------------------------------------------------------------------------------------------------+ | | ivec3 | :ref:`textureSize` ( |gsampler2DArray| s, int lod) | | +--------------+-----------------------------------------------------------------------------------------------------+ | @@ -2626,9 +2626,9 @@ Texture Functions | vec2 | :ref:`textureQueryLod` (samplerCube s, vec3 p) | | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ | int | :ref:`textureQueryLevels` ( |gsampler2D| s) | Get the number of accessible mipmap levels of a texture. | ++--------------+-----------------------------------------------------------------------------------------------------+ If the texture is unassigned to a sampler, ``1`` is returned (Godot | +| int | :ref:`textureQueryLevels` ( |gsampler2DArray| s) | always internally assigns a texture even to an empty sampler). | +--------------+-----------------------------------------------------------------------------------------------------+ | -| int | :ref:`textureQueryLevels` ( |gsampler2DArray| s) | If the texture is unassigned to a sampler, ``1`` is returned (Godot | -+--------------+-----------------------------------------------------------------------------------------------------+ always internally assigns a texture even to an empty sampler). | | int | :ref:`textureQueryLevels` ( |gsampler3D| s) | | +--------------+-----------------------------------------------------------------------------------------------------+ | | int | :ref:`textureQueryLevels` (samplerCube s) | | @@ -2650,22 +2650,20 @@ Texture Functions | |gvec4_type| | :ref:`textureProj` ( |gsampler3D| s, vec4 p [, float bias]) | | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ | |gvec4_type| | :ref:`textureLod` ( |gsampler2D| s, vec2 p, float lod) | Perform a texture read at custom mipmap. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureLod` ( |gsampler2DArray| s, vec3 p, float lod) | The LOD defines which mipmap level is used. An LOD value of ``0.0`` | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| | | will use the full resolution texture. If the texture lacks mipmaps, | -| |gvec4_type| | :ref:`textureLod` ( |gsampler3D| s, vec3 p, float lod) | all LOD values will act like ``0.0``. | ++--------------+-----------------------------------------------------------------------------------------------------+ The LOD defines which mipmap level is used. An LOD value of ``0.0`` | +| |gvec4_type| | :ref:`textureLod` ( |gsampler2DArray| s, vec3 p, float lod) | will use the full resolution texture. If the texture lacks mipmaps, | ++--------------+-----------------------------------------------------------------------------------------------------+ all LOD values will act like ``0.0``. | +| |gvec4_type| | :ref:`textureLod` ( |gsampler3D| s, vec3 p, float lod) | | +--------------+-----------------------------------------------------------------------------------------------------+ | | vec4 | :ref:`textureLod` (samplerCube s, vec3 p, float lod) | | +--------------+-----------------------------------------------------------------------------------------------------+ | | vec4 | :ref:`textureLod` (samplerCubeArray s, vec4 p, float lod) | | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ | |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec3 p, float lod) | Performs a texture read with projection/LOD. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec4 p, float lod) | The LOD defines which mipmap level is used. An LOD value of ``0.0`` | -| | | will use the full resolution texture. If the texture lacks mipmaps, | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureProjLod` ( |gsampler3D| s, vec4 p, float lod) | all LOD values will act like ``0.0``. | ++--------------+-----------------------------------------------------------------------------------------------------+ The LOD defines which mipmap level is used. An LOD value of ``0.0`` | +| |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec4 p, float lod) | will use the full resolution texture. If the texture lacks mipmaps, | ++--------------+-----------------------------------------------------------------------------------------------------+ all LOD values will act like ``0.0``. | +| |gvec4_type| | :ref:`textureProjLod` ( |gsampler3D| s, vec4 p, float lod) | | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ | |gvec4_type| | :ref:`textureGrad` ( |gsampler2D| s, vec2 p, vec2 dPdx, vec2 dPdy) | Performs a texture read with explicit gradients. | +--------------+-----------------------------------------------------------------------------------------------------+ | @@ -2678,25 +2676,21 @@ Texture Functions | vec4 | :ref:`textureGrad` (samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy) | | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ | |gvec4_type| | :ref:`textureProjGrad` ( |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy) | Performs a texture read with projection/LOD and with explicit | -| | | gradients. | -+--------------+-----------------------------------------------------------------------------------------------------+ | ++--------------+-----------------------------------------------------------------------------------------------------+ gradients. | | |gvec4_type| | :ref:`textureProjGrad` ( |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy) | | +--------------+-----------------------------------------------------------------------------------------------------+ | | |gvec4_type| | :ref:`textureProjGrad` ( |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy) | | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ | |gvec4_type| | :ref:`texelFetch` ( |gsampler2D| s, ivec2 p, int lod) | Fetches a single texel using integer coordinates. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`texelFetch` ( |gsampler2DArray| s, ivec3 p, int lod) | The LOD defines which mipmap level is used. An LOD value of ``0`` | -| | | will use the full resolution texture. | ++--------------+-----------------------------------------------------------------------------------------------------+ The LOD defines which mipmap level is used. An LOD value of ``0`` | +| |gvec4_type| | :ref:`texelFetch` ( |gsampler2DArray| s, ivec3 p, int lod) | will use the full resolution texture. | +--------------+-----------------------------------------------------------------------------------------------------+ | | |gvec4_type| | :ref:`texelFetch` ( |gsampler3D| s, ivec3 p, int lod) | | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ | |gvec4_type| | :ref:`textureGather` ( |gsampler2D| s, vec2 p [, int comps]) | Gathers four texels from a texture. | -| | | Use ``comps`` within range of 0..3 to | -+--------------+-----------------------------------------------------------------------------------------------------+ | ++--------------+-----------------------------------------------------------------------------------------------------+ Use ``comps`` within range of 0..3 to | | |gvec4_type| | :ref:`textureGather` ( |gsampler2DArray| s, vec3 p [, int comps]) | define which component (x, y, z, w) is returned. | -| | | If ``comps`` is not provided: 0 (or x-component) is used. | -+--------------+-----------------------------------------------------------------------------------------------------+ | ++--------------+-----------------------------------------------------------------------------------------------------+ If ``comps`` is not provided: 0 (or x-component) is used. | | vec4 | :ref:`textureGather` (samplerCube s, vec3 p [, int comps]) | | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ | |vec_type| | :ref:`dFdx` ( |vec_type| p) | Derivative in ``x`` using local differencing. | @@ -2752,19 +2746,22 @@ Texture Functions ivec2 **textureSize** ( |gsampler2D| s, int lod ) - + Retrieve the dimensions of a level of a texture. + + Returns the dimensions of level lod (if present) of the texture bound to sampler. + + The components in the return value are filled in, in order, with the width, height and depth + of the texture. For the array forms, the last component of the return value is + the number of layers in the texture array. :param s: - + the sampler to which the texture whose dimensions to retrieve is bound. :param lod: - - - :param : - + the level of the texture for which to retrieve the dimensions. :return: - + the dimensions of level lod (if present) of the texture bound to sampler. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureSize.xhtml @@ -2777,19 +2774,22 @@ ivec2 **textureSize** ( |gsampler2D| s, int lod ) ivec2 **textureSize** ( samplerCube s, int lod ) - + Retrieve the dimensions of a level of a texture. + + Returns the dimensions of level lod (if present) of the texture bound to sampler. + + The components in the return value are filled in, in order, with the width, height and depth + of the texture. For the array forms, the last component of the return value is + the number of layers in the texture array. :param s: - + the sampler to which the texture whose dimensions to retrieve is bound. :param lod: - - - :param : - + the level of the texture for which to retrieve the dimensions. :return: - + the dimensions of level lod (if present) of the texture bound to sampler. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureSize.xhtml @@ -2802,19 +2802,22 @@ ivec2 **textureSize** ( samplerCube s, int lod ) ivec2 **textureSize** ( samplerCubeArray s, int lod ) - + Retrieve the dimensions of a level of a texture. + + Returns the dimensions of level lod (if present) of the texture bound to sampler. + + The components in the return value are filled in, in order, with the width, height and depth + of the texture. For the array forms, the last component of the return value is + the number of layers in the texture array. :param s: - + the sampler to which the texture whose dimensions to retrieve is bound. :param lod: - - - :param : - + the level of the texture for which to retrieve the dimensions. :return: - + the dimensions of level lod (if present) of the texture bound to sampler. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureSize.xhtml @@ -2827,19 +2830,22 @@ ivec2 **textureSize** ( samplerCubeArray s, int lod ) ivec3 **textureSize** ( |gsampler2DArray| s, int lod ) - + Retrieve the dimensions of a level of a texture. + + Returns the dimensions of level lod (if present) of the texture bound to sampler. + + The components in the return value are filled in, in order, with the width, height and depth + of the texture. For the array forms, the last component of the return value is + the number of layers in the texture array. :param s: - + the sampler to which the texture whose dimensions to retrieve is bound. :param lod: - - - :param : - + the level of the texture for which to retrieve the dimensions. :return: - + the dimensions of level lod (if present) of the texture bound to sampler. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureSize.xhtml @@ -2852,19 +2858,22 @@ ivec3 **textureSize** ( |gsampler2DArray| s, int lod ) ivec3 **textureSize** ( |gsampler3D| s, int lod ) - + Retrieve the dimensions of a level of a texture. + + Returns the dimensions of level lod (if present) of the texture bound to sampler. + + The components in the return value are filled in, in order, with the width, height and depth + of the texture. For the array forms, the last component of the return value is + the number of layers in the texture array. :param s: - + the sampler to which the texture whose dimensions to retrieve is bound. :param lod: - - - :param : - + the level of the texture for which to retrieve the dimensions. :return: - + the dimensions of level lod (if present) of the texture bound to sampler. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureSize.xhtml @@ -2881,19 +2890,23 @@ ivec3 **textureSize** ( |gsampler3D| s, int lod ) vec2 **textureQueryLod** ( |gsampler2D| s, vec2 p ) - + Compute the level-of-detail that would be used to sample from a texture. + + Available only in the fragment shader, textureQueryLod computes the level-of-detail + that would be used to sample from a texture. The mipmap array(s) that would be + accessed is returned in the x component of the return value. The computed level-of-detail + relative to the base level is returned in the y component of the return value. + + If called on an incomplete texture, the result of the operation is undefined. :param s: - + the sampler to which the texture whose level-of-detail will be queried is bound. :param p: - - - :param : - + the texture coordinates at which the level-of-detail will be queried. :return: - + see description. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLod.xhtml @@ -2906,19 +2919,23 @@ vec2 **textureQueryLod** ( |gsampler2D| s, vec2 p ) vec3 **textureQueryLod** ( |gsampler2DArray| s, vec2 p ) - + Compute the level-of-detail that would be used to sample from a texture. + + Available only in the fragment shader, textureQueryLod computes the level-of-detail + that would be used to sample from a texture. The mipmap array(s) that would be + accessed is returned in the x component of the return value. The computed level-of-detail + relative to the base level is returned in the y component of the return value. + + If called on an incomplete texture, the result of the operation is undefined. :param s: - + the sampler to which the texture whose level-of-detail will be queried is bound. :param p: - - - :param : - + the texture coordinates at which the level-of-detail will be queried. :return: - + see description. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLod.xhtml @@ -2931,19 +2948,23 @@ vec3 **textureQueryLod** ( |gsampler2DArray| s, vec2 p ) vec2 **textureQueryLod** ( |gsampler3D| s, vec3 p ) - + Compute the level-of-detail that would be used to sample from a texture. + + Available only in the fragment shader, textureQueryLod computes the level-of-detail + that would be used to sample from a texture. The mipmap array(s) that would be + accessed is returned in the x component of the return value. The computed level-of-detail + relative to the base level is returned in the y component of the return value. + + If called on an incomplete texture, the result of the operation is undefined. :param s: - + the sampler to which the texture whose level-of-detail will be queried is bound. :param p: - - - :param : - + the texture coordinates at which the level-of-detail will be queried. :return: - + see description. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLod.xhtml @@ -2956,19 +2977,23 @@ vec2 **textureQueryLod** ( |gsampler3D| s, vec3 p ) vec2 **textureQueryLod** ( samplerCube s, vec3 p ) - + Compute the level-of-detail that would be used to sample from a texture. + + Available only in the fragment shader, textureQueryLod computes the level-of-detail + that would be used to sample from a texture. The mipmap array(s) that would be + accessed is returned in the x component of the return value. The computed level-of-detail + relative to the base level is returned in the y component of the return value. + + If called on an incomplete texture, the result of the operation is undefined. :param s: - + the sampler to which the texture whose level-of-detail will be queried is bound. :param p: - - - :param : - + the texture coordinates at which the level-of-detail will be queried. :return: - + see description. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLod.xhtml @@ -2985,19 +3010,15 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) int **textureQueryLevels** ( |gsampler2D| s ) - + Compute the number of accessible mipmap levels of a texture. - :param s: - + If called on an incomplete texture, or if no texture is associated with sampler, zero is returned. - :param : - - - :param : - + :param s: + the sampler to which the texture whose mipmap level count will be queried is bound. :return: - + the number of accessible mipmap levels in the texture, or zero. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLevels.xhtml @@ -3010,19 +3031,15 @@ int **textureQueryLevels** ( |gsampler2D| s ) int **textureQueryLevels** ( |gsampler2DArray| s ) - - - :param s: - + Compute the number of accessible mipmap levels of a texture. - :param : - + If called on an incomplete texture, or if no texture is associated with sampler, zero is returned. - :param : - + :param s: + the sampler to which the texture whose mipmap level count will be queried is bound. :return: - + the number of accessible mipmap levels in the texture, or zero. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLevels.xhtml @@ -3035,19 +3052,15 @@ int **textureQueryLevels** ( |gsampler2DArray| s ) int **textureQueryLevels** ( |gsampler3D| s ) - + Compute the number of accessible mipmap levels of a texture. - :param s: - - - :param : - + If called on an incomplete texture, or if no texture is associated with sampler, zero is returned. - :param : - + :param s: + the sampler to which the texture whose mipmap level count will be queried is bound. :return: - + the number of accessible mipmap levels in the texture, or zero. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLevels.xhtml @@ -3060,19 +3073,15 @@ int **textureQueryLevels** ( |gsampler3D| s ) int **textureQueryLevels** ( samplerCube s ) - + Compute the number of accessible mipmap levels of a texture. - :param s: - + If called on an incomplete texture, or if no texture is associated with sampler, zero is returned. - :param : - - - :param : - + :param s: + the sampler to which the texture whose mipmap level count will be queried is bound. :return: - + the number of accessible mipmap levels in the texture, or zero. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLevels.xhtml @@ -3089,19 +3098,27 @@ int **textureQueryLevels** ( samplerCube s ) |gvec4_type| **texture** ( |gsampler2D| 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 + included in the level-of-detail computation that is used to choose mipmap(s) from which to sample. + + For shadow forms, the last component of ``p`` is used as Dsub and the array layer is specified in the second to last + component of ``p``. (The second component of ``p`` is unused for 1D shadow lookups.) + + For non-shadow variants, the array layer comes from the last component of P. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. - :param bias]: - + :param bias: + an optional bias to be applied during level-of-detail computation. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texture.xhtml @@ -3114,19 +3131,27 @@ int **textureQueryLevels** ( samplerCube s ) |gvec4_type| **texture** ( |gsampler2DArray| s, vec3 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 + included in the level-of-detail computation that is used to choose mipmap(s) from which to sample. + + For shadow forms, the last component of ``p`` is used as Dsub and the array layer is specified in the second to last + component of ``p``. (The second component of ``p`` is unused for 1D shadow lookups.) + + For non-shadow variants, the array layer comes from the last component of P. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. - :param bias]: - + :param bias: + an optional bias to be applied during level-of-detail computation. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texture.xhtml @@ -3139,19 +3164,27 @@ int **textureQueryLevels** ( samplerCube s ) |gvec4_type| **texture** ( |gsampler3D| s, vec3 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 + included in the level-of-detail computation that is used to choose mipmap(s) from which to sample. + + For shadow forms, the last component of ``p`` is used as Dsub and the array layer is specified in the second to last + component of ``p``. (The second component of ``p`` is unused for 1D shadow lookups.) + + For non-shadow variants, the array layer comes from the last component of P. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. - :param bias]: - + :param bias: + an optional bias to be applied during level-of-detail computation. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texture.xhtml @@ -3164,19 +3197,27 @@ int **textureQueryLevels** ( samplerCube s ) vec4 **texture** ( samplerCube s, vec3 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 + included in the level-of-detail computation that is used to choose mipmap(s) from which to sample. + + For shadow forms, the last component of ``p`` is used as Dsub and the array layer is specified in the second to last + component of ``p``. (The second component of ``p`` is unused for 1D shadow lookups.) + + For non-shadow variants, the array layer comes from the last component of P. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. - :param bias]: - + :param bias: + an optional bias to be applied during level-of-detail computation. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texture.xhtml @@ -3189,19 +3230,27 @@ vec4 **texture** ( samplerCube s, vec3 p [, float bias] ) vec4 **texture** ( samplerCubeArray s, vec4 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 + included in the level-of-detail computation that is used to choose mipmap(s) from which to sample. + + For shadow forms, the last component of ``p`` is used as Dsub and the array layer is specified in the second to last + component of ``p``. (The second component of ``p`` is unused for 1D shadow lookups.) + + For non-shadow variants, the array layer comes from the last component of P. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. - :param bias]: - + :param bias: + an optional bias to be applied during level-of-detail computation. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texture.xhtml @@ -3218,19 +3267,23 @@ vec4 **texture** ( samplerCubeArray s, vec4 p [, float bias] ) |gvec4_type| **textureProj** ( |gsampler2D| s, vec3 p [, float bias] ) - + Perform a texture lookup with projection. + + The texture coordinates consumed from ``p``, not including the last component of ``p``, are + divided by the last component of ``p``. The resulting 3rd component of ``p`` in the shadow + forms is used as Dref. After these values are computed, the texture lookup proceeds as in texture. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. - :param bias]: - + :param bias: + optional bias to be applied during level-of-detail computation. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProj.xhtml @@ -3243,19 +3296,23 @@ vec4 **texture** ( samplerCubeArray s, vec4 p [, float bias] ) |gvec4_type| **textureProj** ( |gsampler2D| s, vec4 p [, float bias] ) - + Perform a texture lookup with projection. + + The texture coordinates consumed from ``p``, not including the last component of ``p``, are + divided by the last component of ``p``. The resulting 3rd component of ``p`` in the shadow + forms is used as Dref. After these values are computed, the texture lookup proceeds as in texture. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. - :param bias]: - + :param bias: + optional bias to be applied during level-of-detail computation. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProj.xhtml @@ -3268,19 +3325,23 @@ vec4 **texture** ( samplerCubeArray s, vec4 p [, float bias] ) |gvec4_type| **textureProj** ( |gsampler3D| s, vec4 p [, float bias] ) - + Perform a texture lookup with projection. + + The texture coordinates consumed from ``p``, not including the last component of ``p``, are + divided by the last component of ``p``. The resulting 3rd component of ``p`` in the shadow + forms is used as Dref. After these values are computed, the texture lookup proceeds as in texture. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. - :param bias]: - + :param bias: + optional bias to be applied during level-of-detail computation. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProj.xhtml @@ -3297,19 +3358,24 @@ vec4 **texture** ( samplerCubeArray s, vec4 p [, float bias] ) |gvec4_type| **textureLod** ( |gsampler2D| s, vec2 p, float lod ) - + Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with + an explicit level-of-detail as specified in ``lod``. ``lod`` specifies λbase and sets the + partial derivatives as follows:: + + δu/δx=0, δv/δx=0, δw/δx=0 + δu/δy=0, δv/δy=0, δw/δy=0 :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. :param lod: - + the explicit level-of-detail :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureLod.xhtml @@ -3322,19 +3388,24 @@ vec4 **texture** ( samplerCubeArray s, vec4 p [, float bias] ) |gvec4_type| **textureLod** ( |gsampler2DArray| s, vec3 p, float lod ) - + Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with + an explicit level-of-detail as specified in ``lod``. ``lod`` specifies λbase and sets the + partial derivatives as follows:: + + δu/δx=0, δv/δx=0, δw/δx=0 + δu/δy=0, δv/δy=0, δw/δy=0 :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. :param lod: - + the explicit level-of-detail :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureLod.xhtml @@ -3347,19 +3418,24 @@ vec4 **texture** ( samplerCubeArray s, vec4 p [, float bias] ) |gvec4_type| **textureLod** ( |gsampler3D| s, vec3 p, float lod ) - + Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with + an explicit level-of-detail as specified in ``lod``. ``lod`` specifies λbase and sets the + partial derivatives as follows:: + + δu/δx=0, δv/δx=0, δw/δx=0 + δu/δy=0, δv/δy=0, δw/δy=0 :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. :param lod: - + the explicit level-of-detail :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureLod.xhtml @@ -3372,19 +3448,24 @@ vec4 **texture** ( samplerCubeArray s, vec4 p [, float bias] ) vec4 **textureLod** ( samplerCube s, vec3 p, float lod ) - + Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with + an explicit level-of-detail as specified in ``lod``. ``lod`` specifies λbase and sets the + partial derivatives as follows:: + + δu/δx=0, δv/δx=0, δw/δx=0 + δu/δy=0, δv/δy=0, δw/δy=0 :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. :param lod: - + the explicit level-of-detail :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureLod.xhtml @@ -3397,19 +3478,24 @@ vec4 **textureLod** ( samplerCube s, vec3 p, float lod ) vec4 **textureLod** ( samplerCubeArray s, vec4 p, float lod ) - + Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with + an explicit level-of-detail as specified in ``lod``. ``lod`` specifies λbase and sets the + partial derivatives as follows:: + + δu/δx=0, δv/δx=0, δw/δx=0 + δu/δy=0, δv/δy=0, δw/δy=0 :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. :param lod: - + the explicit level-of-detail :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureLod.xhtml @@ -3426,19 +3512,25 @@ vec4 **textureLod** ( samplerCubeArray s, vec4 p, float lod ) |gvec4_type| **textureProjLod** ( |gsampler2D| s, vec3 p, float lod ) - + Performs a texture lookup with projection from an explicitly specified level-of-detail. + + The texture coordinates consumed from P, not including the last component of ``p``, are + divided by the last component of ``p``. The resulting 3rd component of ``p`` in the shadow + forms is used as Dref. After these values are computed, the texture lookup proceeds as in + `textureLod`, with ``lod`` used to specify the level-of-detail from + which the texture will be sampled. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. :param lod: - + the explicit level-of-detail from which to fetch texels. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjLod.xhtml @@ -3451,19 +3543,25 @@ vec4 **textureLod** ( samplerCubeArray s, vec4 p, float lod ) |gvec4_type| **textureProjLod** ( |gsampler2D| s, vec4 p, float lod ) - + Performs a texture lookup with projection from an explicitly specified level-of-detail. + + The texture coordinates consumed from P, not including the last component of ``p``, are + divided by the last component of ``p``. The resulting 3rd component of ``p`` in the shadow + forms is used as Dref. After these values are computed, the texture lookup proceeds as in + `textureLod`, with ``lod`` used to specify the level-of-detail from + which the texture will be sampled. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. :param lod: - + the explicit level-of-detail from which to fetch texels. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjLod.xhtml @@ -3476,19 +3574,25 @@ vec4 **textureLod** ( samplerCubeArray s, vec4 p, float lod ) |gvec4_type| **textureProjLod** ( |gsampler3D| s, vec4 p, float lod ) - + Performs a texture lookup with projection from an explicitly specified level-of-detail. + + The texture coordinates consumed from P, not including the last component of ``p``, are + divided by the last component of ``p``. The resulting 3rd component of ``p`` in the shadow + forms is used as Dref. After these values are computed, the texture lookup proceeds as in + `textureLod`, with ``lod`` used to specify the level-of-detail from + which the texture will be sampled. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. :param lod: - + the explicit level-of-detail from which to fetch texels. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjLod.xhtml @@ -3505,19 +3609,30 @@ vec4 **textureLod** ( samplerCubeArray s, vec4 p, float lod ) |gvec4_type| **textureGrad** ( |gsampler2D| s, vec2 p, vec2 dPdx, vec2 dPdy ) - + Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with explicit texture coordinate gradiends as specified in ``dPdx`` and ``dPdy``. Set: + - ``δs/δx=δp/δx`` for a 1D texture, ``δp.s/δx`` otherwise + - ``δs/δy=δp/δy`` for a 1D texture, ``δp.s/δy`` otherwise + - ``δt/δx=0.0`` for a 1D texture, ``δp.t/δx`` otherwise + - ``δt/δy=0.0`` for a 1D texture, ``δp.t/δy`` otherwise + - ``δr/δx=0.0`` for a 1D or 2D texture, ``δp.p/δx`` otherwise + - ``δr/δy=0.0`` for a 1D or 2D texture, ``δp.p/δy`` otherwise + + For the cube version, the partial derivatives of ``p`` are assumed to be in the coordinate system used before texture coordinates are projected onto the appropriate cube face. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. :param dPdx: - + the partial derivative of P with respect to window x. + + :param dPdy: + the partial derivative of P with respect to window y. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGrad.xhtml @@ -3530,19 +3645,30 @@ vec4 **textureLod** ( samplerCubeArray s, vec4 p, float lod ) |gvec4_type| **textureGrad** ( |gsampler2DArray| s, vec3 p, vec2 dPdx, vec2 dPdy ) - + Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with explicit texture coordinate gradiends as specified in ``dPdx`` and ``dPdy``. Set: + - ``δs/δx=δp/δx`` for a 1D texture, ``δp.s/δx`` otherwise + - ``δs/δy=δp/δy`` for a 1D texture, ``δp.s/δy`` otherwise + - ``δt/δx=0.0`` for a 1D texture, ``δp.t/δx`` otherwise + - ``δt/δy=0.0`` for a 1D texture, ``δp.t/δy`` otherwise + - ``δr/δx=0.0`` for a 1D or 2D texture, ``δp.p/δx`` otherwise + - ``δr/δy=0.0`` for a 1D or 2D texture, ``δp.p/δy`` otherwise + + For the cube version, the partial derivatives of ``p`` are assumed to be in the coordinate system used before texture coordinates are projected onto the appropriate cube face. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. :param dPdx: - + the partial derivative of P with respect to window x. + + :param dPdy: + the partial derivative of P with respect to window y. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGrad.xhtml @@ -3555,19 +3681,30 @@ vec4 **textureLod** ( samplerCubeArray s, vec4 p, float lod ) |gvec4_type| **textureGrad** ( |gsampler3D| s, vec3 p, vec2 dPdx, vec2 dPdy ) - + Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with explicit texture coordinate gradiends as specified in ``dPdx`` and ``dPdy``. Set: + - ``δs/δx=δp/δx`` for a 1D texture, ``δp.s/δx`` otherwise + - ``δs/δy=δp/δy`` for a 1D texture, ``δp.s/δy`` otherwise + - ``δt/δx=0.0`` for a 1D texture, ``δp.t/δx`` otherwise + - ``δt/δy=0.0`` for a 1D texture, ``δp.t/δy`` otherwise + - ``δr/δx=0.0`` for a 1D or 2D texture, ``δp.p/δx`` otherwise + - ``δr/δy=0.0`` for a 1D or 2D texture, ``δp.p/δy`` otherwise + + For the cube version, the partial derivatives of ``p`` are assumed to be in the coordinate system used before texture coordinates are projected onto the appropriate cube face. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. :param dPdx: - + the partial derivative of P with respect to window x. + + :param dPdy: + the partial derivative of P with respect to window y. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGrad.xhtml @@ -3580,19 +3717,30 @@ vec4 **textureLod** ( samplerCubeArray s, vec4 p, float lod ) vec4 **textureGrad** ( samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy ) - + Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with explicit texture coordinate gradiends as specified in ``dPdx`` and ``dPdy``. Set: + - ``δs/δx=δp/δx`` for a 1D texture, ``δp.s/δx`` otherwise + - ``δs/δy=δp/δy`` for a 1D texture, ``δp.s/δy`` otherwise + - ``δt/δx=0.0`` for a 1D texture, ``δp.t/δx`` otherwise + - ``δt/δy=0.0`` for a 1D texture, ``δp.t/δy`` otherwise + - ``δr/δx=0.0`` for a 1D or 2D texture, ``δp.p/δx`` otherwise + - ``δr/δy=0.0`` for a 1D or 2D texture, ``δp.p/δy`` otherwise + + For the cube version, the partial derivatives of ``p`` are assumed to be in the coordinate system used before texture coordinates are projected onto the appropriate cube face. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. :param dPdx: - + the partial derivative of P with respect to window x. + + :param dPdy: + the partial derivative of P with respect to window y. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGrad.xhtml @@ -3605,19 +3753,30 @@ vec4 **textureGrad** ( samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy ) vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) - + Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with explicit texture coordinate gradiends as specified in ``dPdx`` and ``dPdy``. Set: + - ``δs/δx=δp/δx`` for a 1D texture, ``δp.s/δx`` otherwise + - ``δs/δy=δp/δy`` for a 1D texture, ``δp.s/δy`` otherwise + - ``δt/δx=0.0`` for a 1D texture, ``δp.t/δx`` otherwise + - ``δt/δy=0.0`` for a 1D texture, ``δp.t/δy`` otherwise + - ``δr/δx=0.0`` for a 1D or 2D texture, ``δp.p/δx`` otherwise + - ``δr/δy=0.0`` for a 1D or 2D texture, ``δp.p/δy`` otherwise + + For the cube version, the partial derivatives of ``p`` are assumed to be in the coordinate system used before texture coordinates are projected onto the appropriate cube face. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. :param dPdx: - + the partial derivative of P with respect to window x. + + :param dPdy: + the partial derivative of P with respect to window y. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGrad.xhtml From a64aa2a8a7ea32ef2b7f75bdd6304f541b2b4b60 Mon Sep 17 00:00:00 2001 From: ashbygeek Date: Wed, 8 May 2024 16:04:16 -0400 Subject: [PATCH 08/25] finished texture functions and packing functions --- .../shader_reference/shader_functions.rst | 501 ++++++++++-------- 1 file changed, 289 insertions(+), 212 deletions(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index 77fb3ba4b15..c7595db3b2f 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -3793,19 +3793,25 @@ vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) |gvec4_type| **textureProjGrad** ( |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy ) - + Perform a texture lookup with projection and explicit gradients. + + The texture coordinates consumed from ``p``, not including the last component of ``p``, are divided by the last component of ``p``. + After these values are computed, the texture lookup proceeds as in `textureGrad`, passing ``dPdx`` and ``dPdy`` as gradients. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. :param dPdx: - + the partial derivative of ``p`` with respect to window x. + + :param dPdy: + the partial derivative of ``p`` with respect to window y. :return: - + a texel. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjGrad.xhtml @@ -3818,19 +3824,25 @@ vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) |gvec4_type| **textureProjGrad** ( |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy ) - + Perform a texture lookup with projection and explicit gradients. + + The texture coordinates consumed from ``p``, not including the last component of ``p``, are divided by the last component of ``p``. + After these values are computed, the texture lookup proceeds as in `textureGrad`, passing ``dPdx`` and ``dPdy`` as gradients. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. :param dPdx: - + the partial derivative of ``p`` with respect to window x. + + :param dPdy: + the partial derivative of ``p`` with respect to window y. :return: - + a texel. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjGrad.xhtml @@ -3843,19 +3855,25 @@ vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) |gvec4_type| **textureProjGrad** ( |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy ) - + Perform a texture lookup with projection and explicit gradients. + + The texture coordinates consumed from ``p``, not including the last component of ``p``, are divided by the last component of ``p``. + After these values are computed, the texture lookup proceeds as in `textureGrad`, passing ``dPdx`` and ``dPdy`` as gradients. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. :param dPdx: - + the partial derivative of ``p`` with respect to window x. + + :param dPdy: + the partial derivative of ``p`` with respect to window y. :return: - + a texel. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjGrad.xhtml @@ -3872,19 +3890,19 @@ vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) |gvec4_type| **texelFetch** ( |gsampler2D| s, ivec2 p, int lod ) - + Performs a lookup of a single texel from texture coordinate ``p`` in the texture bound to sampler. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. :param lod: - + specifies the level-of-detail within the texture from which the texel will be fetched. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texelFetch.xhtml @@ -3897,19 +3915,21 @@ vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) |gvec4_type| **texelFetch** ( |gsampler2DArray| s, ivec3 p, int lod ) - + Performs a lookup of a single texel from texture coordinate ``p`` in the texture bound to sampler. + + The array layer is specified in the last component of P for array forms. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. ``p.z`` specifies which layer of ``s`` is fetched. :param lod: - + specifies the level-of-detail within the texture from which the texel will be fetched. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texelFetch.xhtml @@ -3922,19 +3942,19 @@ vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) |gvec4_type| **texelFetch** ( |gsampler3D| s, ivec3 p, int lod ) - + Performs a lookup of a single texel from texture coordinate ``p`` in the texture bound to sampler. :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. :param lod: - + specifies the level-of-detail within the texture from which the texel will be fetched. :return: - + a texel https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texelFetch.xhtml @@ -3951,19 +3971,26 @@ vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) |gvec4_type| **textureGather** ( |gsampler2D| s, vec2 p [, int comps] ) - + Gathers four texels from a texture. + + Returns the value:: + + vec4(Sample_i0_j1(p, base).comps, + Sample_i1_j1(p, base).comps, + Sample_i1_j0(p, base).comps, + Sample_i0_j0(p, base).comps); :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. - :param comps]: - + :param comps: + *optional* the component of the source texture (0 -> x, 1 -> y, 2 -> z, 3 -> w) that will be used to generate the resulting vector. Zero if not specified. :return: - + the gathered texel. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGather.xhtml @@ -3976,19 +4003,26 @@ vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) |gvec4_type| **textureGather** ( |gsampler2DArray| s, vec3 p [, int comps] ) - + Gathers four texels from a texture. + + Returns the value:: + + vec4(Sample_i0_j1(p, base).comps, + Sample_i1_j1(p, base).comps, + Sample_i1_j0(p, base).comps, + Sample_i0_j0(p, base).comps); :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. - :param comps]: - + :param comps: + *optional* the component of the source texture (0 -> x, 1 -> y, 2 -> z, 3 -> w) that will be used to generate the resulting vector. Zero if not specified. :return: - + the gathered texel. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGather.xhtml @@ -4001,19 +4035,26 @@ vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) - + Gathers four texels from a texture. + + Returns the value:: + + vec4(Sample_i0_j1(p, base).comps, + Sample_i1_j1(p, base).comps, + Sample_i1_j0(p, base).comps, + Sample_i0_j0(p, base).comps); :param s: - + the sampler to which the texture from which texels will be retrieved is bound. :param p: - + the texture coordinates at which texture will be sampled. - :param comps]: - + :param comps: + *optional* the component of the source texture (0 -> x, 1 -> y, 2 -> z, 3 -> w) that will be used to generate the resulting vector. Zero if not specified. :return: - + the gathered texel. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGather.xhtml @@ -4030,19 +4071,27 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) |vec_type| **dFdx** ( |vec_type| p ) - + Return the partial derivative of ``p`` with respect to the window x coordinate. + + .. note:: + + Available only in the fragment shader + + Returns either `dFdxCoarse` or `dFdxFine`. The implementation may choose which calculation to perform based upon factors + such as performance or the value of the API GL_FRAGMENT_SHADER_DERIVATIVE_HINT hint. + + .. warning:: + Expressions that imply higher order derivatives such as ``dFdx(dFdx(n))`` have undefined results, as do mixed-order derivatives such as ``dFdx(dFdy(n))``. :param p: - + the expression of which to take the partial derivative. - :param : - + .. note:: - :param : - + It is assumed that the expression ``p`` is continuous and therefore expressions evaluated via non-uniform control flow may be undefined. :return: - + the partial derivative of ``p``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/dFdx.xhtml @@ -4059,19 +4108,29 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) |vec_type| **dFdxCoarse** ( |vec_type| p ) - + Return the partial derivative of ``p`` with respect to the window x coordinate. + + .. note:: + + Available only in the fragment shader + + Calculates derivatives using local differencing based on the value of ``p`` for the current fragment's neighbors, and will possibly, + but not necessarily, include the value for the current fragment. That is, over a given area, the implementation can compute derivatives in fewer unique locations than + would be allowed for the corresponding `dFdxFine`` function. + + + .. warning:: + Expressions that imply higher order derivatives such as ``dFdx(dFdx(n))`` have undefined results, as do mixed-order derivatives such as ``dFdx(dFdy(n))``. :param p: - + the expression of which to take the partial derivative. - :param : - + .. note:: - :param : - + It is assumed that the expression ``p`` is continuous and therefore expressions evaluated via non-uniform control flow may be undefined. :return: - + the partial derivative of ``p``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/dFdxCoarse.xhtml @@ -4088,19 +4147,21 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) |vec_type| **dFdxFine** ( |vec_type| p ) - + Return the partial derivative of ``p`` with respect to the window x coordinate. - :param p: - + .. note:: Available only in the fragment shader - :param : - + Calculates derivatives using local differencing based on the value of ``p`` for the current fragment and its immediate neighbor(s). - :param : - + .. warning:: Expressions that imply higher order derivatives such as ``dFdx(dFdx(n))`` have undefined results, as do mixed-order derivatives such as ``dFdx(dFdy(n))``. + + :param p: + the expression of which to take the partial derivative. + + .. note:: It is assumed that the expression ``p`` is continuous and therefore expressions evaluated via non-uniform control flow may be undefined. :return: - + the partial derivative of ``p``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/dFdxFine.xhtml @@ -4117,19 +4178,22 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) |vec_type| **dFdy** ( |vec_type| p ) - + Return the partial derivative of ``p`` with respect to the window y coordinate. - :param p: - + .. note:: Available only in the fragment shader - :param : - + Returns either `dFdyCoarse` or `dFdyFine`. The implementation may choose which calculation to perform based upon factors + such as performance or the value of the API GL_FRAGMENT_SHADER_DERIVATIVE_HINT hint. - :param : - + .. warning:: Expressions that imply higher order derivatives such as ``dFdx(dFdx(n))`` have undefined results, as do mixed-order derivatives such as ``dFdx(dFdy(n))``. + + :param p: + the expression of which to take the partial derivative. + + .. note:: It is assumed that the expression ``p`` is continuous and therefore expressions evaluated via non-uniform control flow may be undefined. :return: - + the partial derivative of ``p``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/dFdy.xhtml @@ -4146,19 +4210,23 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) |vec_type| **dFdyCoarse** ( |vec_type| p ) - + Return the partial derivative of ``p`` with respect to the window y coordinate. - :param p: - + .. note:: Available only in the fragment shader - :param : - + Calculates derivatives using local differencing based on the value of ``p`` for the current fragment's neighbors, and will possibly, + but not necessarily, include the value for the current fragment. That is, over a given area, the implementation can compute derivatives in fewer unique locations than + would be allowed for the corresponding dFdyFine and dFdyFine functions. - :param : - + .. warning:: Expressions that imply higher order derivatives such as ``dFdx(dFdx(n))`` have undefined results, as do mixed-order derivatives such as ``dFdx(dFdy(n))``. + + :param p: + the expression of which to take the partial derivative. + + .. note:: It is assumed that the expression ``p`` is continuous and therefore expressions evaluated via non-uniform control flow may be undefined. :return: - + the partial derivative of ``p``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/dFdyCoarse.xhtml @@ -4175,19 +4243,21 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) |vec_type| **dFdyFine** ( |vec_type| p ) - + Return the partial derivative of ``p`` with respect to the window y coordinate. - :param p: - + .. note:: Available only in the fragment shader - :param : - + Calculates derivatives using local differencing based on the value of ``p`` for the current fragment and its immediate neighbor(s). - :param : - + .. warning:: Expressions that imply higher order derivatives such as ``dFdx(dFdx(n))`` have undefined results, as do mixed-order derivatives such as ``dFdx(dFdy(n))``. + + :param p: + the expression of which to take the partial derivative. + + .. note:: It is assumed that the expression ``p`` is continuous and therefore expressions evaluated via non-uniform control flow may be undefined. :return: - + the partial derivative of ``p``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/dFdyFine.xhtml @@ -4204,19 +4274,20 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) |vec_type| **fwidth** ( |vec_type| p ) - + Return the sum of the absolute value of derivatives in x and y. - :param p: - + Uses local differencing for the input argument p. - :param : - + Equivalent to ``abs(dFdx(p)) + abs(dFdy(p))``. - :param : - + fwidthCoarse is equivalent to ``abs(dFdxCoarse(p)) + abs(dFdyCoarse(p))``. + fwidthFine is equivalent to ``abs(dFdxFine(p)) + abs(dFdyFine(p))``. + + :param p: + the expression of which to take the partial derivative. :return: - + the partial derivative. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/fwidth.xhtml @@ -4233,19 +4304,17 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) |vec_type| **fwidthCoarse** ( |vec_type| p ) - + Return the sum of the absolute value of derivatives in x and y. - :param p: - + Uses local differencing for the input argument p. - :param : - + Equivalent to ``abs(dFdxCoarse(p)) + abs(dFdyCoarse(p))``. - :param : - + :param p: + the expression of which to take the partial derivative. :return: - + the partial derivative. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/fwidthCoarse.xhtml @@ -4262,19 +4331,17 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) |vec_type| **fwidthFine** ( |vec_type| p ) - + Return the sum of the absolute value of derivatives in x and y. - :param p: - + Uses local differencing for the input argument p. - :param : - + Equivalent to ``abs(dFdxFine(p)) + abs(dFdyFine(p))``. - :param : - + :param p: + the expression of which to take the partial derivative. :return: - + the partial derivative. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/fwidthFine.xhtml @@ -4327,19 +4394,18 @@ Packing/Unpacking Functions uint **packHalf2x16** ( vec2 v ) - - - :param v: - + Convert two 32-bit floating-point quantities to 16-bit quantities and pack them into a single 32-bit integer. - :param : - + Returns an unsigned integer obtained by converting the components of a two-component floating-point vector to + the 16-bit floating-point representation found in the OpenGL Specification, and then packing these two + 16-bit integers into a 32-bit unsigned integer. The first vector component specifies the 16 least-significant + bits of the result; the second component specifies the 16 most-significant bits. - :param : - + :param v: + a vector of two 32-bit floating point values that are to be converted to 16-bit representation and packed into the result. :return: - + the packed value. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/packHalf2x16.xhtml @@ -4356,19 +4422,18 @@ uint **packHalf2x16** ( vec2 v ) vec2 **unpackHalf2x16** ( uint v ) - - - :param v: - + Convert two 16-bit floating-point values packed into a single 32-bit integer into a vector of two 32-bit floating-point quantities. - :param : - + Returns a two-component floating-point vector with components obtained by unpacking a 32-bit unsigned integer into a pair of 16-bit + values, interpreting those values as 16-bit floating-point numbers according to the OpenGL Specification, and converting them to + 32-bit floating-point values. The first component of the vector is obtained from the 16 least-significant bits of v; the second + component is obtained from the 16 most-significant bits of v. - :param : - + :param v: + a single 32-bit unsigned integer containing 2 packed 16-bit floating point values. :return: - + two unpacked floating point values. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/unpackHalf2x16.xhtml @@ -4385,21 +4450,24 @@ vec2 **unpackHalf2x16** ( uint v ) uint **packUnorm2x16** ( vec2 v ) - + Pack floating-point values into an unsigned integer. - :param v: - + Convert each component of the normalized floating-point value v into 16-bit integer values and then packs the results into a 32-bit unsigned integer. - :param : - + The conversion for component c of v to fixed-point is performed as follows:: - :param : - + round(clamp(c, 0.0, 1.0) * 65535.0) + + The first component of the vector will be written to the least significant bits of the output; the last component will be written to the most significant bits. + + + :param v: + a vector of values to be packed into an unsigned integer. :return: - + unsigned 32 bit integer containing the packed encoding of the vector. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/packUnorm2x16.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/packUnorm.xhtml .. rst-class:: classref-item-separator @@ -4414,21 +4482,21 @@ uint **packUnorm2x16** ( vec2 v ) vec2 **unpackUnorm2x16** ( uint v ) - + Unpack floating-point values from an unsigned integer. - :param v: - + Unpack single 32-bit unsigned integers into a pair of 16-bit unsigned integers. + Then, each component is converted to a normalized floating-point value to generate the returned two-component vector. - :param : - + The conversion for unpacked fixed point value f to floating-point is performed as follows: - :param : - + f / 65535.0 - :return: - + The first component of the returned vector will be extracted from the least significant bits of the input; the last component will be extracted from the most significant bits. + + :param v: + an unsigned integer containing packed floating-point values. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/unpackUnorm2x16.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/unpackUnorm.xhtml .. rst-class:: classref-item-separator @@ -4443,21 +4511,23 @@ vec2 **unpackUnorm2x16** ( uint v ) uint **packSnorm2x16** ( vec2 v ) - + Pack floating-point values into an unsigned integer. - :param v: - + Convert each component of the normalized floating-point value v into 16-bit integer values and then packs the results into a 32-bit unsigned integer. - :param : - + The conversion for component c of v to fixed-point is performed as follows:: - :param : - + round(clamp(c, -1.0, 1.0) * 32767.0) + + The first component of the vector will be written to the least significant bits of the output; the last component will be written to the most significant bits. + + :param v: + a vector of values to be packed into an unsigned integer. :return: - + unsigned 32 bit integer containing the packed encoding of the vector. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/packSnorm2x16.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/packUnorm.xhtml .. rst-class:: classref-item-separator @@ -4472,21 +4542,22 @@ uint **packSnorm2x16** ( vec2 v ) vec2 **unpackSnorm2x16** ( uint v ) - + Unpack floating-point values from an unsigned integer. - :param v: - + Unpack single 32-bit unsigned integers into a pair of 16-bit signed integers. + Then, each component is converted to a normalized floating-point value to generate the returned two- + four-component vector. - :param : - + The conversion for unpacked fixed point value f to floating-point is performed as follows: - :param : - + clamp(f / 32727.0, -1.0, 1.0) - :return: - + The first component of the returned vector will be extracted from the least significant bits of the input; the last component will be extracted from the most significant bits. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/unpackSnorm2x16.xhtml + :param v: + an unsigned integer containing packed floating-point values. + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/unpackUnorm.xhtml .. rst-class:: classref-item-separator @@ -4501,21 +4572,24 @@ vec2 **unpackSnorm2x16** ( uint v ) uint **packUnorm4x8** ( vec4 v ) - + Pack floating-point values into an unsigned integer. - :param v: - + Convert each component of the normalized floating-point value v into 16-bit integer values and then packs the results into a 32-bit unsigned integer. - :param : - + The conversion for component c of v to fixed-point is performed as follows:: - :param : - + round(clamp(c, 0.0, 1.0) * 255.0) + + The first component of the vector will be written to the least significant bits of the output; the last component will be written to the most significant bits. + + + :param v: + a vector of values to be packed into an unsigned integer. :return: - + unsigned 32 bit integer containing the packed encoding of the vector. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/packUnorm4x8.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/packUnorm.xhtml .. rst-class:: classref-item-separator @@ -4530,21 +4604,21 @@ uint **packUnorm4x8** ( vec4 v ) vec4 **unpackUnorm4x8** ( uint v ) - + Unpack floating-point values from an unsigned integer. - :param v: - + Unpack single 32-bit unsigned integers into four 8-bit unsigned integers. + Then, each component is converted to a normalized floating-point value to generate the returned four-component vector. - :param : - + The conversion for unpacked fixed point value f to floating-point is performed as follows: - :param : - + f / 255.0 - :return: - + The first component of the returned vector will be extracted from the least significant bits of the input; the last component will be extracted from the most significant bits. + + :param v: + an unsigned integer containing packed floating-point values. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/unpackUnorm4x8.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/unpackUnorm.xhtml .. rst-class:: classref-item-separator @@ -4559,21 +4633,24 @@ vec4 **unpackUnorm4x8** ( uint v ) uint **packSnorm4x8** ( vec4 v ) - + Pack floating-point values into an unsigned integer. - :param v: - + Convert each component of the normalized floating-point value v into 16-bit integer values and then packs the results into a 32-bit unsigned integer. - :param : - + The conversion for component c of v to fixed-point is performed as follows:: - :param : - + round(clamp(c, -1.0, 1.0) * 127.0) + + The first component of the vector will be written to the least significant bits of the output; the last component will be written to the most significant bits. + + + :param v: + a vector of values to be packed into an unsigned integer. :return: - + unsigned 32 bit integer containing the packed encoding of the vector. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/packSnorm4x8.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/packUnorm.xhtml .. rst-class:: classref-item-separator @@ -4588,21 +4665,21 @@ uint **packSnorm4x8** ( vec4 v ) vec4 **unpackSnorm4x8** ( uint v ) - + Unpack floating-point values from an unsigned integer. - :param v: - + Unpack single 32-bit unsigned integers into four 8-bit signed integers. + Then, each component is converted to a normalized floating-point value to generate the returned four-component vector. - :param : - + The conversion for unpacked fixed point value f to floating-point is performed as follows: - :param : - + clamp(f / 127.0, -1.0, 1.0) - :return: - + The first component of the returned vector will be extracted from the least significant bits of the input; the last component will be extracted from the most significant bits. + + :param v: + an unsigned integer containing packed floating-point values. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/unpackSnorm4x8.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/unpackUnorm.xhtml .. rst-class:: classref-item-separator From ef9f5640387ad4c1f86ba4dfc16399e4e662bb60 Mon Sep 17 00:00:00 2001 From: ashbygeek Date: Wed, 8 May 2024 16:39:47 -0400 Subject: [PATCH 09/25] finished Bitwise Operations --- .../shader_reference/shader_functions.rst | 282 ++++++++++-------- 1 file changed, 154 insertions(+), 128 deletions(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index c7595db3b2f..d0ae8ea8baa 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -4743,19 +4743,30 @@ Bitwise operations |vec_int_type| **bitfieldExtract** ( |vec_int_type| value, int offset, int bits ) - + Eextracts a subset of the bits of value and returns it in the least significant bits of the result. + The range of bits extracted is ``[offset, offset + bits - 1]``. + + The most significant bits of the result will be set to zero. + + .. note:: + If bits is zero, the result will be zero. + + .. warning:: + The result will be undefined if: + - offset or bits is negative + - if the sum of offset and bits is greater than the number of bits used to store the operand. :param value: - + the integer from which to extract bits. :param offset: - + the index of the first bit to extract. :param bits: - + the number of bits to extract. :return: - + integer with the requested bits https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitfieldExtract.xhtml @@ -4768,19 +4779,30 @@ Bitwise operations |vec_uint_type| **bitfieldExtract** ( |vec_uint_type| value, int offset, int bits ) - + Eextracts a subset of the bits of value and returns it in the least significant bits of the result. + The range of bits extracted is ``[offset, offset + bits - 1]``. + + The most significant bits will be set to the value of ``offset + base - 1`` (i.e., it is sign extended to the width of the return type). + + .. note:: + If bits is zero, the result will be zero. + + .. warning:: + The result will be undefined if: + - offset or bits is negative + - if the sum of offset and bits is greater than the number of bits used to store the operand. :param value: - + the integer from which to extract bits. :param offset: - + the index of the first bit to extract. :param bits: - + the number of bits to extract. :return: - + integer with the requested bits https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitfieldExtract.xhtml @@ -4797,19 +4819,32 @@ Bitwise operations |vec_int_type| **bitfieldInsert** ( |vec_int_type| base, |vec_int_type| insert, int offset, int bits ) - + Inserts the ``bits`` least significant bits of ``insert`` into ``base`` at offset ``offset``. + + The returned value will have bits [offset, offset + bits + 1] taken from [0, bits - 1] of ``insert`` and + all other bits taken directly from the corresponding bits of base. + + .. note:: If bits is zero, the result will simply be the original value of base. + + .. warning:: + The result will be undefined if: + - offset or bits is negative + - if the sum of offset and bits is greater than the number of bits used to store the operand. :param base: - + the integer into which to insert ``insert``. :param insert: - + the value of the bits to insert. :param offset: - + the index of the first bit to insert. + + :param bits: + the number of bits to insert. :return: - + ``base`` with inserted bits. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitfieldInsert.xhtml @@ -4822,19 +4857,32 @@ Bitwise operations |vec_uint_type| **bitfieldInsert** ( |vec_uint_type| base, |vec_uint_type| insert, int offset, int bits ) - + Inserts the ``bits`` least significant bits of ``insert`` into ``base`` at offset ``offset``. + + The returned value will have bits [offset, offset + bits + 1] taken from [0, bits - 1] of ``insert`` and + all other bits taken directly from the corresponding bits of base. + + .. note:: If bits is zero, the result will simply be the original value of base. + + .. warning:: + The result will be undefined if: + - offset or bits is negative + - if the sum of offset and bits is greater than the number of bits used to store the operand. :param base: - + the integer into which to insert ``insert``. :param insert: - + the value of the bits to insert. :param offset: - + the index of the first bit to insert. + + :param bits: + the number of bits to insert. :return: - + ``base`` with inserted bits. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitfieldInsert.xhtml @@ -4851,19 +4899,15 @@ Bitwise operations |vec_int_type| **bitfieldReverse** ( |vec_int_type| value ) - - - :param value: - + Reverse the order of bits in an integer. - :param : - + The bit numbered n will be taken from bit (bits - 1) - n of ``value``, where bits is the total number of bits used to represent ``value``. - :param : - + :param value: + the value whose bits to reverse. :return: - + ``value`` but with its bits reversed. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitfieldReverse.xhtml @@ -4876,19 +4920,15 @@ Bitwise operations |vec_uint_type| **bitfieldReverse** ( |vec_uint_type| value ) - + Reverse the order of bits in an integer. - :param value: - - - :param : - + The bit numbered n will be taken from bit (bits - 1) - n of ``value``, where bits is the total number of bits used to represent ``value``. - :param : - + :param value: + the value whose bits to reverse. :return: - + ``value`` but with its bits reversed. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitfieldReverse.xhtml @@ -4905,19 +4945,13 @@ Bitwise operations |vec_int_type| **bitCount** ( |vec_int_type| value ) - + Counts the number of 1 bits in an integer. :param value: - - - :param : - - - :param : - + the value whose bits to count. :return: - + the number of bits that are set to 1 in the binary representation of ``value``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitCount.xhtml @@ -4930,19 +4964,13 @@ Bitwise operations |vec_uint_type| **bitCount** ( |vec_uint_type| value ) - + Counts the number of 1 bits in an integer. :param value: - - - :param : - - - :param : - + the value whose bits to count. :return: - + the number of bits that are set to 1 in the binary representation of ``value``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitCount.xhtml @@ -4959,19 +4987,15 @@ Bitwise operations |vec_int_type| **findLSB** ( |vec_int_type| value ) - + Find the index of the least significant bit set to 1. - :param value: - - - :param : - + .. note:: If ``value`` is zero, -1 will be returned. - :param : - + :param value: + the value whose bits to scan. :return: - + the bit number of the least significant bit that is set to 1 in the binary representation of value. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/findLSB.xhtml @@ -4984,19 +5008,15 @@ Bitwise operations |vec_uint_type| **findLSB** ( |vec_uint_type| value ) - - - :param value: - + Find the index of the least significant bit set to 1. - :param : - + .. note:: If ``value`` is zero, -1 will be returned. - :param : - + :param value: + the value whose bits to scan. :return: - + the bit number of the least significant bit that is set to 1 in the binary representation of value. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/findLSB.xhtml @@ -5013,19 +5033,19 @@ Bitwise operations |vec_int_type| **findMSB** ( |vec_int_type| value ) - + Find the index of the most significant bit set to 1. - :param value: - + For positive integers, the result will be the bit number of the most significant bit that is set to 1. + + For negative integers, the result will be the bit number of the most significant bit set to 0. - :param : - + .. note:: For a value of zero or negative 1, -1 will be returned. - :param : - + :param value: + the value whose bits to scan. :return: - + the bit number of the most significant bit that is set to 1 in the binary representation of value. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/findMSB.xhtml @@ -5038,19 +5058,15 @@ Bitwise operations |vec_uint_type| **findMSB** ( |vec_uint_type| value ) - + Find the index of the most significant bit set to 1. - :param value: - + .. note:: For a value of zero or negative 1, -1 will be returned. - :param : - - - :param : - + :param value: + the value whose bits to scan. :return: - + the bit number of the most significant bit that is set to 1 in the binary representation of value. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/findMSB.xhtml @@ -5067,21 +5083,23 @@ Bitwise operations |void| **imulExtended** ( |vec_int_type| x, |vec_int_type| y, out |vec_int_type| msb, out |vec_int_type| lsb ) - + Perform 32-bit by 32-bit signed multiplication to produce a 64-bit result. + + The 32 least significant bits of this product are returned in ``lsb`` and the 32 most significant bits are returned in ``msb``. :param x: - + the first multiplicand. :param y: - + the second multiplicand. :param msb: - + the variable to receive the most significant word of the product. - :return: - + :param lsb: + the variable to receive the least significant word of the product. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/imulExtended.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/umulExtended.xhtml .. rst-class:: classref-item-separator @@ -5096,19 +5114,21 @@ Bitwise operations |void| **umulExtended** ( |vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| msb, out |vec_uint_type| lsb ) - + Perform 32-bit by 32-bit unsigned multiplication to produce a 64-bit result. + + The 32 least significant bits of this product are returned in ``lsb`` and the 32 most significant bits are returned in ``msb``. :param x: - + the first multiplicand. :param y: - + the second multiplicand. :param msb: - + the variable to receive the most significant word of the product. - :return: - + :param lsb: + the variable to receive the least significant word of the product. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/umulExtended.xhtml @@ -5125,19 +5145,22 @@ Bitwise operations |vec_uint_type| **uaddCarry** ( |vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| carry ) - + Add unsigned integers and generate carry. + + adds two 32-bit unsigned integer variables (scalars or vectors) and generates a 32-bit unsigned integer result, along with a carry output. + The value carry is . :param x: - + the first operand :param y: - + the second operand :param carry: - + 0 if the sum is less than 2\ :sup:`32` otherwise 1 :return: - + ``(x + y) % 2^32``. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/uaddCarry.xhtml @@ -5154,19 +5177,19 @@ Bitwise operations |vec_uint_type| **usubBorrow** ( |vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| borrow ) - + Subtract unsigned integers and generate borrow. :param x: - + the first operand :param y: - + the second operand :param borrow: - + 0 if ``x`` ≥ ``y`` and 1 otherwise. :return: - + the difference of ``x`` and ``y`` if non-negative, or 2\ :sup:`32` plus that difference otherwise. https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/usubBorrow.xhtml @@ -5183,19 +5206,19 @@ Bitwise operations |vec_type| **ldexp** ( |vec_type| x, out |vec_int_type| exp ) - + Assemble a floating point number from a value and exponent. + + .. warning:: + If this product is too large to be represented in the floating point type, the result is undefined. :param x: - + the value to be used as a source of significand. :param exp: - - - :param : - + the value to be used as a source of exponent. :return: - + ``x * 2^exp`` https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/ldexp.xhtml @@ -5212,19 +5235,22 @@ Bitwise operations |vec_type| **frexp** ( |vec_type| x, out |vec_int_type| exp ) - + Extracts ``x`` into a floating-point significand in the range [0.5, 1.0) and in integral exponent of two, such that:: + + x = significand * 2 ^ exponent + + For a floating-point value of zero, the significand and exponent are both zero. + + .. warning:: For a floating-point value that is an infinity or a floating-point NaN, the results are undefined. :param x: - + the value from which significand and exponent are to be extracted. :param exp: - - - :param : - + the variable into which to place the exponent of ``x`` :return: - + the significand of ``x`` https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/frexp.xhtml From dcdae1564cf37afd5240ef47d64e96606d1f2c3f Mon Sep 17 00:00:00 2001 From: ashbygeek Date: Wed, 8 May 2024 16:46:06 -0400 Subject: [PATCH 10/25] Fixed typo --- tutorials/shaders/shader_reference/shader_functions.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index d0ae8ea8baa..f43ce859281 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -4545,8 +4545,7 @@ vec2 **unpackSnorm2x16** ( uint v ) Unpack floating-point values from an unsigned integer. Unpack single 32-bit unsigned integers into a pair of 16-bit signed integers. - Then, each component is converted to a normalized floating-point value to generate the returned two- - four-component vector. + Then, each component is converted to a normalized floating-point value to generate the returned two-component vector. The conversion for unpacked fixed point value f to floating-point is performed as follows: From 37229bcf0b5941842f69bc58b601d99651f5bf2e Mon Sep 17 00:00:00 2001 From: Daniel Ashby Date: Fri, 10 May 2024 10:45:12 -0400 Subject: [PATCH 11/25] Minor Typo and formatting fixes Co-authored-by: Yuri Rubinsky Co-authored-by: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com> --- tutorials/shaders/shader_reference/shader_functions.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index f43ce859281..0dfe69e47cf 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -19,7 +19,7 @@ GLSL 4.00 specification. +-----------------+--------------------------------------------------+--------------------------+ | vec_uint_type | uint, uvec2, uvec3, or uvec4 | genUType | +-----------------+--------------------------------------------------+--------------------------+ - | vec_bool_type | bool, bvec2, bvec3, or bvec4 | genUType | + | vec_bool_type | bool, bvec2, bvec3, or bvec4 | genBType | +-----------------+--------------------------------------------------+--------------------------+ | mat_type | mat2, mat3, or mat4 | mat | +-----------------+--------------------------------------------------+--------------------------+ @@ -36,8 +36,8 @@ GLSL 4.00 specification. .. note:: Most operations on vectors (multiplication, division, etc) are performed component-wise. - For example, the operation ``vec2(3,4) * vec2(10,20)`` would result in ``vec2(3 * 10, 4 * 20)``. - or the operation ``min(vec2(3,4), vec2(1,8))`` would result in ``vec2(min(3,1),min(4,8))``. + For example, the operation ``vec2(3, 4) * vec2(10, 20)`` would result in ``vec2(3 * 10, 4 * 20)``. + or the operation ``min(vec2(3, 4), vec2(1, 8))`` would result in ``vec2(min(3, 1), min(4, 8))``. The `GLSL Language Specification ` says under section 5.10 Vector and Matrix Operations: From 2f8f256ca8d88e14070235a6049126876881b11d Mon Sep 17 00:00:00 2001 From: ashbygeek Date: Fri, 10 May 2024 10:48:13 -0400 Subject: [PATCH 12/25] Another minor typo fix --- .../shader_reference/shader_functions.rst | 42 +++++++++---------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index 0dfe69e47cf..5ae79d2062b 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -10,27 +10,27 @@ GLSL 4.00 specification. The following type aliases only used in documentation to reduce repetitive function declarations. They can each refer to any of several actual types. - +-----------------+--------------------------------------------------+--------------------------+ - | alias | actual types | glsl documentation alias | - +=================+==================================================+==========================+ - | vec_type | float, vec2, vec3, or vec4 | genType | - +-----------------+--------------------------------------------------+--------------------------+ - | vec_int_type | int, ivec2, ivec3, or ivec4 | genIType | - +-----------------+--------------------------------------------------+--------------------------+ - | vec_uint_type | uint, uvec2, uvec3, or uvec4 | genUType | - +-----------------+--------------------------------------------------+--------------------------+ - | vec_bool_type | bool, bvec2, bvec3, or bvec4 | genBType | - +-----------------+--------------------------------------------------+--------------------------+ - | mat_type | mat2, mat3, or mat4 | mat | - +-----------------+--------------------------------------------------+--------------------------+ - | gvec4_type | vec4, ivec4, or uvec4 | | - +-----------------+--------------------------------------------------+--------------------------+ - | gsampler2D | sampler2D, isampler2D, uSampler2D | | - +-----------------+--------------------------------------------------+--------------------------+ - | gsampler2DArray | sampler2DArray, isampler2DArray, uSampler2DArray | | - +-----------------+--------------------------------------------------+--------------------------+ - | gsampler3D | sampler3D, isampler3D, uSampler3D | | - +-----------------+--------------------------------------------------+--------------------------+ + +-----------------+-----------------------------------------------------+--------------------------+ + | alias | actual types | glsl documentation alias | + +=================+=====================================================+==========================+ + | vec_type | float, vec2, vec3, or vec4 | genType | + +-----------------+-----------------------------------------------------+--------------------------+ + | vec_int_type | int, ivec2, ivec3, or ivec4 | genIType | + +-----------------+-----------------------------------------------------+--------------------------+ + | vec_uint_type | uint, uvec2, uvec3, or uvec4 | genUType | + +-----------------+-----------------------------------------------------+--------------------------+ + | vec_bool_type | bool, bvec2, bvec3, or bvec4 | genBType | + +-----------------+-----------------------------------------------------+--------------------------+ + | mat_type | mat2, mat3, or mat4 | mat | + +-----------------+-----------------------------------------------------+--------------------------+ + | gvec4_type | vec4, ivec4, or uvec4 | gvec4 | + +-----------------+-----------------------------------------------------+--------------------------+ + | gsampler2D | sampler2D, isampler2D, or uSampler2D | gsampler2D | + +-----------------+-----------------------------------------------------+--------------------------+ + | gsampler2DArray | sampler2DArray, isampler2DArray, or uSampler2DArray | gsampler2DArray | + +-----------------+-----------------------------------------------------+--------------------------+ + | gsampler3D | sampler3D, isampler3D, or uSampler3D | gsampler3D | + +-----------------+-----------------------------------------------------+--------------------------+ If any of these are specified for multiple parameters, they must all be the same type unless otherwise noted. From 6eeba26cab01d4efb345305988ac2d1fb5123e56 Mon Sep 17 00:00:00 2001 From: ashbygeek Date: Thu, 4 Jul 2024 22:59:00 -0400 Subject: [PATCH 13/25] Improve table summaries, fix typos, add availability notes Fixes suggested by clayjohn and chaosus --- .../shader_reference/shader_functions.rst | 482 +++++++++--------- .../shader_reference/shading_language.rst | 8 + 2 files changed, 249 insertions(+), 241 deletions(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index 5ae79d2062b..9c5490daf49 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -55,35 +55,35 @@ Trigonometric Functions +-----------------+-------------------------------------------------------------+-----------------------------+ | Return Type | Function | Description / Return value | +=================+=============================================================+=============================+ -| |vec_type| | :ref:`radians` ( |vec_type| degrees) | Convert degrees to radians. | +| |vec_type| | :ref:`radians` ( |vec_type| degrees ) | Convert degrees to radians. | +-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`degrees` ( |vec_type| radians) | Convert radians to degrees. | +| |vec_type| | :ref:`degrees` ( |vec_type| radians ) | Convert radians to degrees. | +-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`sin` ( |vec_type| x) | Sine. | +| |vec_type| | :ref:`sin` ( |vec_type| x ) | Sine. | +-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`cos` ( |vec_type| x) | Cosine. | +| |vec_type| | :ref:`cos` ( |vec_type| x ) | Cosine. | +-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`tan` ( |vec_type| x) | Tangent. | +| |vec_type| | :ref:`tan` ( |vec_type| x ) | Tangent. | +-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`asin` ( |vec_type| x) | Arcsine. | +| |vec_type| | :ref:`asin` ( |vec_type| x ) | Arcsine. | +-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`acos` ( |vec_type| x) | Arccosine. | +| |vec_type| | :ref:`acos` ( |vec_type| x ) | Arccosine. | +-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`atan` ( |vec_type| y_over_x) | Arctangent. | +| |vec_type| | :ref:`atan` ( |vec_type| y_over_x ) | Arctangent. | +-----------------+-------------------------------------------------------------+ | -| |vec_type| | :ref:`atan` ( |vec_type| y, |vec_type| x) | | +| |vec_type| | :ref:`atan` ( |vec_type| y, |vec_type| x )| | +-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`sinh` ( |vec_type| x) | Hyperbolic sine. | +| |vec_type| | :ref:`sinh` ( |vec_type| x ) | Hyperbolic sine. | +-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`cosh` ( |vec_type| x) | Hyperbolic cosine. | +| |vec_type| | :ref:`cosh` ( |vec_type| x ) | Hyperbolic cosine. | +-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`tanh` ( |vec_type| x) | Hyperbolic tangent. | +| |vec_type| | :ref:`tanh` ( |vec_type| x ) | Hyperbolic tangent. | +-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`asinh` ( |vec_type| x) | Inverse hyperbolic sine. | +| |vec_type| | :ref:`asinh` ( |vec_type| x ) | Inverse hyperbolic sine. | +-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`acosh` ( |vec_type| x) | Inverse hyperbolic cosine. | +| |vec_type| | :ref:`acosh` ( |vec_type| x ) | Inverse hyperbolic cosine. | +-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`atanh` ( |vec_type| x) | Inverse hyperbolic tangent. | +| |vec_type| | :ref:`atanh` ( |vec_type| x ) | Inverse hyperbolic tangent. | +-----------------+-------------------------------------------------------------+-----------------------------+ .. rst-class:: classref-section-separator @@ -248,10 +248,12 @@ vec_type acos( |vec_type| x) vec_type atan( |vec_type| y_over_x) - Calculate the arctangent given a tangent value of ``y/x``. Note: becuase of - the sign ambiguity, the function cannot determine with certainty in which - quadrant the angle falls only by its tangent value. If you need to know the - quadrant, use ``atan( |vec_type| y, |vec_type| x )``. + Calculate the arctangent given a tangent value of ``y/x``. + + .. Note:: + because of the sign ambiguity, the function cannot determine with certainty in + which quadrant the angle falls only by its tangent value. If you need to know the + quadrant, use ``atan( |vec_type| y, |vec_type| x )``. :param y_over_x: The fraction whose arctangent to return. @@ -406,7 +408,7 @@ vec_type acosh( |vec_type| x) vec_type atanh( |vec_type| x) - Calculate the arctangent given a tangent value of ``y/x``. Note: becuase of + Calculate the arctangent given a tangent value of ``y/x``. Note: because of the sign ambiguity, the function cannot determine with certainty in which quadrant the angle falls only by its tangent value. If you need to know the quadrant, use the other overload of ``atan``. @@ -432,109 +434,109 @@ Exponential and Common Math Functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`pow` ( |vec_type| x, |vec_type| y) | Power (undefined if ``x < 0`` or if ``x == 0`` and ``y <= 0``). | +| |vec_type| | :ref:`pow` ( |vec_type| x, |vec_type| y ) | Power (undefined if ``x < 0`` or if ``x == 0`` and ``y <= 0``). | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`exp` ( |vec_type| x) | Base-e exponential. | +| |vec_type| | :ref:`exp` ( |vec_type| x ) | Base-e exponential. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`exp2` ( |vec_type| x) | Base-2 exponential. | +| |vec_type| | :ref:`exp2` ( |vec_type| x ) | Base-2 exponential. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`log` ( |vec_type| x) | Natural logarithm. | +| |vec_type| | :ref:`log` ( |vec_type| x ) | Natural logarithm. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`log2` ( |vec_type| x) | Base-2 logarithm. | +| |vec_type| | :ref:`log2` ( |vec_type| x ) | Base-2 logarithm. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`sqrt` ( |vec_type| x) | Square root. | +| |vec_type| | :ref:`sqrt` ( |vec_type| x ) | Square root. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`inversesqrt` ( |vec_type| x) | Inverse square root. | +| |vec_type| | :ref:`inversesqrt` ( |vec_type| x ) | Inverse square root. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`abs` ( |vec_type| x) | Absolute value (returns positive value if negative). | +| |vec_type| | :ref:`abs` ( |vec_type| x ) | Absolute value (returns positive value if negative). | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_int_type| | :ref:`abs` ( |vec_int_type| x) | | +| |vec_int_type| | :ref:`abs` ( |vec_int_type| x ) | | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`sign` ( |vec_type| x) | returns ``1.0`` if positive, ``-1.0`` if negative, | +| |vec_type| | :ref:`sign` ( |vec_type| x ) | returns ``1.0`` if positive, ``-1.0`` if negative, | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_int_type| | :ref:`sign` ( |vec_int_type| x) | returns ``1`` if positive, ``-1`` if negative, | +| |vec_int_type| | :ref:`sign` ( |vec_int_type| x ) | returns ``1`` if positive, ``-1`` if negative, | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`floor` ( |vec_type| x) | Round to the integer below. | +| |vec_type| | :ref:`floor` ( |vec_type| x ) | Round to the integer below. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`round` ( |vec_type| x) | Round to the nearest integer. | +| |vec_type| | :ref:`round` ( |vec_type| x ) | Round to the nearest integer. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`roundEven` ( |vec_type| x) | Round to the nearest even integer. | +| |vec_type| | :ref:`roundEven` ( |vec_type| x ) | Round to the nearest even integer. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`trunc` ( |vec_type| x) | Truncation. | +| |vec_type| | :ref:`trunc` ( |vec_type| x ) | Truncation. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`ceil` ( |vec_type| x) | Round to the integer above. | +| |vec_type| | :ref:`ceil` ( |vec_type| x ) | Round to the integer above. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`fract` ( |vec_type| x) | Fractional (returns ``x - floor(x)``). | +| |vec_type| | :ref:`fract` ( |vec_type| x ) | Fractional (returns ``x - floor(x)``). | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`mod` ( |vec_type| x, |vec_type| y) | Modulo (division remainder). | +| |vec_type| | :ref:`mod` ( |vec_type| x, |vec_type| y ) | Modulo (division remainder). | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_type| | :ref:`mod` ( |vec_type| x, float y) | | +| |vec_type| | :ref:`mod` ( |vec_type| x, float y ) | | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`modf` (|vec_type| x, out |vec_type| i) | Fractional of ``x``, with ``i`` as integer part. | +| |vec_type| | :ref:`modf` (|vec_type| x, out |vec_type| i ) | Fractional of ``x``, with ``i`` as integer part. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`min` ( |vec_type| a, |vec_type| b) | Lowest value between ``a`` and ``b``. | +| |vec_type| | :ref:`min` ( |vec_type| a, |vec_type| b ) | Lowest value between ``a`` and ``b``. | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_type| | :ref:`min` ( |vec_type| a, float b) | | +| |vec_type| | :ref:`min` ( |vec_type| a, float b ) | | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_int_type| | :ref:`min` ( |vec_int_type| a, |vec_int_type| b) | | +| |vec_int_type| | :ref:`min` ( |vec_int_type| a, |vec_int_type| b ) | | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_int_type| | :ref:`min` ( |vec_int_type| a, int b) | | +| |vec_int_type| | :ref:`min` ( |vec_int_type| a, int b ) | | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`min` ( |vec_uint_type| a, |vec_uint_type| b) | | +| |vec_uint_type| | :ref:`min` ( |vec_uint_type| a, |vec_uint_type| b ) | | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`min` ( |vec_uint_type| a, uint b) | | +| |vec_uint_type| | :ref:`min` ( |vec_uint_type| a, uint b ) | | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`max` ( |vec_type| a, |vec_type| b) | Highest value between ``a`` and ``b``. | +| |vec_type| | :ref:`max` ( |vec_type| a, |vec_type| b ) | Highest value between ``a`` and ``b``. | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_type| | :ref:`max` ( |vec_type| a, float b) | | +| |vec_type| | :ref:`max` ( |vec_type| a, float b ) | | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`max` ( |vec_uint_type| a, |vec_uint_type| b) | | +| |vec_uint_type| | :ref:`max` ( |vec_uint_type| a, |vec_uint_type| b ) | | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`max` ( |vec_uint_type| a, uint b) | | +| |vec_uint_type| | :ref:`max` ( |vec_uint_type| a, uint b ) | | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_int_type| | :ref:`max` ( |vec_int_type| a, |vec_int_type| b) | | +| |vec_int_type| | :ref:`max` ( |vec_int_type| a, |vec_int_type| b ) | | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_int_type| | :ref:`max` ( |vec_int_type| a, int b) | | +| |vec_int_type| | :ref:`max` ( |vec_int_type| a, int b ) | | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`clamp` (|vec_type| x, |vec_type| min, |vec_type| max) | Clamp ``x`` between ``min`` and ``max`` (inclusive). | +| |vec_type| | :ref:`clamp` (|vec_type| x, |vec_type| min, |vec_type| max ) | Clamp ``x`` between ``min`` and ``max`` (inclusive). | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_type| | :ref:`clamp` ( |vec_type| x, float min, float max) | | +| |vec_type| | :ref:`clamp` ( |vec_type| x, float min, float max ) | | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`clamp` ( |vec_int_type| x, |vec_int_type| min, |vec_int_type| max) | | +| |vec_uint_type| | :ref:`clamp` ( |vec_int_type| x, |vec_int_type| min, |vec_int_type| max )| | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`clamp` ( |vec_int_type| x, float min, float max) | | +| |vec_uint_type| | :ref:`clamp` ( |vec_int_type| x, float min, float max ) | | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_int_type| | :ref:`clamp` (|vec_type| x, |vec_type| min, |vec_type| max) | | +| |vec_int_type| | :ref:`clamp` (|vec_type| x, |vec_type| min, |vec_type| max ) | | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_int_type| | :ref:`clamp` ( |vec_type| x, float min, float max) | | +| |vec_int_type| | :ref:`clamp` ( |vec_type| x, float min, float max ) | | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`mix` (|vec_type| a, |vec_type| b, |vec_type| c) | Linear interpolate between ``a`` and ``b`` by ``c``. | +| |vec_type| | :ref:`mix` (|vec_type| a, |vec_type| b, |vec_type| c ) | Linear interpolate between ``a`` and ``b`` by ``c``. | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_type| | :ref:`mix` (|vec_type| a, |vec_type| b, float c) | | +| |vec_type| | :ref:`mix` (|vec_type| a, |vec_type| b, float c ) | | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_type| | :ref:`mix` (|vec_type| a, |vec_type| b, |vec_bool_type| c) | | +| |vec_type| | :ref:`mix` (|vec_type| a, |vec_type| b, |vec_bool_type| c ) | | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`fma` (|vec_type| a, |vec_type| b, |vec_type| c) | Fused multiply-add operation: ``(a * b + c)`` | +| |vec_type| | :ref:`fma` (|vec_type| a, |vec_type| b, |vec_type| c ) | Fused multiply-add operation: ``(a * b + c)`` | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`step` ( |vec_type| a, |vec_type| b) | ``b[i] < a[i] ? 0.0 : 1.0``. | +| |vec_type| | :ref:`step` ( |vec_type| a, |vec_type| b ) | ``b[i] < a[i] ? 0.0 : 1.0``. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`step` (float a, |vec_type| b) | ``b[i] < a ? 0.0 : 1.0``. | +| |vec_type| | :ref:`step` (float a, |vec_type| b ) | ``b[i] < a ? 0.0 : 1.0``. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`smoothstep` (|vec_type| a, |vec_type| b, |vec_type| c) | Hermite interpolate between ``a`` and ``b`` by ``c``. | +| |vec_type| | :ref:`smoothstep` (|vec_type| a, |vec_type| b, |vec_type| c ) | Hermite interpolate between ``a`` and ``b`` by ``c``. | +-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_type| | :ref:`smoothstep` (float a, float b, |vec_type| c) | | +| |vec_type| | :ref:`smoothstep` (float a, float b, |vec_type| c ) | | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_bool_type| | :ref:`isnan` ( |vec_type| x) | Returns ``true`` if scalar or vector component is ``NaN``. | +| |vec_bool_type| | :ref:`isnan` ( |vec_type| x ) | Returns ``true`` if scalar or vector component is ``NaN``. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_bool_type| | :ref:`isinf` ( |vec_type| x) | Returns ``true`` if scalar or vector component is ``INF``. | +| |vec_bool_type| | :ref:`isinf` ( |vec_type| x ) | Returns ``true`` if scalar or vector component is ``INF``. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_int_type| | :ref:`floatBitsToInt` ( |vec_type| x) | Float->Int bit copying, no conversion. | +| |vec_int_type| | :ref:`floatBitsToInt` ( |vec_type| x ) | Float->Int bit copying, no conversion. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_uint_type| | :ref:`floatBitsToUint` ( |vec_type| x) | Float->UInt bit copying, no conversion. | +| |vec_uint_type| | :ref:`floatBitsToUint` ( |vec_type| x ) | Float->UInt bit copying, no conversion. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`intBitsToFloat` ( |vec_int_type| x) | Int->Float bit copying, no conversion. | +| |vec_type| | :ref:`intBitsToFloat` ( |vec_int_type| x ) | Int->Float bit copying, no conversion. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`uintBitsToFloat` ( |vec_uint_type| x) | UInt->Float bit copying, no conversion. | +| |vec_type| | :ref:`uintBitsToFloat` ( |vec_uint_type| x ) | UInt->Float bit copying, no conversion. | +-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -1913,31 +1915,31 @@ Geometric Functions ^^^^^^^^^^^^^^^^^^^ +------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`length` ( |vec_type| x) | Vector length. | +| float | :ref:`length` ( |vec_type| x ) | Vector length. | +------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`distance` ( |vec_type| a, |vec_type| b) | Distance between vectors i.e ``length(a - b)``. | +| float | :ref:`distance` ( |vec_type| a, |vec_type| b ) | Distance between vectors i.e ``length(a - b)``. | +------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`dot` ( |vec_type| a, |vec_type| b) | Dot product. | +| float | :ref:`dot` ( |vec_type| a, |vec_type| b ) | Dot product. | +------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| vec3 | :ref:`cross` (vec3 a, vec3 b) | Cross product. | +| vec3 | :ref:`cross` (vec3 a, vec3 b ) | Cross product. | +------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |vec_type| | :ref:`normalize` ( |vec_type| x) | Normalize to unit length. | +| |vec_type| | :ref:`normalize` ( |vec_type| x ) | Normalize to unit length. | +------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| vec3 | :ref:`reflect` (vec3 I, vec3 N) | Reflect. | +| vec3 | :ref:`reflect` (vec3 I, vec3 N ) | Reflect. | +------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| vec3 | :ref:`refract` (vec3 I, vec3 N, float eta) | Refract. | +| vec3 | :ref:`refract` (vec3 I, vec3 N, float eta ) | Refract. | +------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |vec_type| | :ref:`faceforward` (|vec_type| N, |vec_type| I, |vec_type| Nref) | If ``dot(Nref, I)`` < 0, return ``N``, otherwise ``-N``. | +| |vec_type| | :ref:`faceforward` (|vec_type| N, |vec_type| I, |vec_type| Nref )| If ``dot(Nref, I)`` < 0, return ``N``, otherwise ``-N``. | +------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`matrixCompMult` (|mat_type| x, |mat_type| y) | Matrix component multiplication. | +| |mat_type| | :ref:`matrixCompMult` (|mat_type| x, |mat_type| y ) | Matrix component multiplication. | +------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`outerProduct` ( |vec_type| column, |vec_type| row) | Matrix outer product. | +| |mat_type| | :ref:`outerProduct` ( |vec_type| column, |vec_type| row ) | Matrix outer product. | +------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`transpose` (|mat_type| m) | Transpose matrix. | +| |mat_type| | :ref:`transpose` (|mat_type| m ) | Transpose matrix. | +------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`determinant` (|mat_type| m) | Matrix determinant. | +| float | :ref:`determinant` (|mat_type| m ) | Matrix determinant. | +------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`inverse` (|mat_type| m) | Inverse matrix. | +| |mat_type| | :ref:`inverse` (|mat_type| m ) | Inverse matrix. | +------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -2330,23 +2332,23 @@ Comparison Functions ^^^^^^^^^^^^^^^^^^^^ +-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`lessThan` ( |vec_type| x, |vec_type| y) | Bool vector comparison on < int/uint/float vectors. | +| |vec_bool_type| | :ref:`lessThan` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on < int/uint/float vectors. | +-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`greaterThan` ( |vec_type| x, |vec_type| y) | Bool vector comparison on > int/uint/float vectors. | +| |vec_bool_type| | :ref:`greaterThan` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on > int/uint/float vectors. | +-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`lessThanEqual` ( |vec_type| x, |vec_type| y) | Bool vector comparison on <= int/uint/float vectors. | +| |vec_bool_type| | :ref:`lessThanEqual` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on <= int/uint/float vectors. | +-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`greaterThanEqual` ( |vec_type| x, |vec_type| y) | Bool vector comparison on >= int/uint/float vectors. | +| |vec_bool_type| | :ref:`greaterThanEqual` ( |vec_type| x, |vec_type| y )| Bool vector comparison on >= int/uint/float vectors. | +-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`equal` ( |vec_type| x, |vec_type| y) | Bool vector comparison on == int/uint/float vectors. | +| |vec_bool_type| | :ref:`equal` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on == int/uint/float vectors. | +-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`notEqual` ( |vec_type| x, |vec_type| y) | Bool vector comparison on != int/uint/float vectors. | +| |vec_bool_type| | :ref:`notEqual` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on != int/uint/float vectors. | +-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| bool | :ref:`any` ( |vec_bool_type| x) | ``true`` if any component is ``true``, ``false`` otherwise. | +| bool | :ref:`any` ( |vec_bool_type| x ) | ``true`` if any component is ``true``, ``false`` otherwise. | +-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| bool | :ref:`all` ( |vec_bool_type| x) | ``true`` if all components are ``true``, ``false`` otherwise. | +| bool | :ref:`all` ( |vec_bool_type| x ) | ``true`` if all components are ``true``, ``false`` otherwise. | +-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`not` ( |vec_bool_type| x) | Invert boolean vector. | +| |vec_bool_type| | :ref:`not` ( |vec_bool_type| x ) | Invert boolean vector. | +-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -2607,129 +2609,126 @@ Texture Functions ^^^^^^^^^^^^^^^^^ +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec2 | :ref:`textureSize` ( |gsampler2D| s, int lod) | Get the size of a texture. | -+--------------+-----------------------------------------------------------------------------------------------------+ The LOD defines which mipmap level is used. An LOD value of ``0`` | -| ivec2 | :ref:`textureSize` (samplerCube s, int lod) | will use the full resolution texture. | +| ivec2 | :ref:`textureSize` ( |gsampler2D| s, int lod ) | Get the size of a texture. | +--------------+-----------------------------------------------------------------------------------------------------+ | -| ivec2 | :ref:`textureSize` (samplerCubeArray s, int lod) | | +| ivec2 | :ref:`textureSize` (samplerCube s, int lod ) | | +--------------+-----------------------------------------------------------------------------------------------------+ | -| ivec3 | :ref:`textureSize` ( |gsampler2DArray| s, int lod) | | +| ivec2 | :ref:`textureSize` (samplerCubeArray s, int lod ) | | +--------------+-----------------------------------------------------------------------------------------------------+ | -| ivec3 | :ref:`textureSize` ( |gsampler3D| s, int lod) | | +| ivec3 | :ref:`textureSize` ( |gsampler2DArray| s, int lod ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| ivec3 | :ref:`textureSize` ( |gsampler3D| s, int lod ) | | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec2 | :ref:`textureQueryLod` ( |gsampler2D| s, vec2 p) | Compute the level-of-detail that would be used to sample from a | -+--------------+-----------------------------------------------------------------------------------------------------+ texture. The ``x`` component of the resulted value is the mipmap | -| vec3 | :ref:`textureQueryLod` ( |gsampler2DArray| s, vec2 p) | array that would be accessed. The ``y`` component is computed | -+--------------+-----------------------------------------------------------------------------------------------------+ level-of-detail relative to the base level (regardless of the | -| vec2 | :ref:`textureQueryLod` ( |gsampler3D| s, vec3 p) | mipmap levels of the texture). | +| vec2 | :ref:`textureQueryLod` ( |gsampler2D| s, vec2 p ) | Compute the level-of-detail that would be used to sample from a | ++--------------+-----------------------------------------------------------------------------------------------------+ texture. | +| vec3 | :ref:`textureQueryLod` ( |gsampler2DArray| s, vec2 p ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec2 | :ref:`textureQueryLod` ( |gsampler3D| s, vec3 p ) | | +--------------+-----------------------------------------------------------------------------------------------------+ | -| vec2 | :ref:`textureQueryLod` (samplerCube s, vec3 p) | | +| vec2 | :ref:`textureQueryLod` (samplerCube s, vec3 p ) | | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| int | :ref:`textureQueryLevels` ( |gsampler2D| s) | Get the number of accessible mipmap levels of a texture. | -+--------------+-----------------------------------------------------------------------------------------------------+ If the texture is unassigned to a sampler, ``1`` is returned (Godot | -| int | :ref:`textureQueryLevels` ( |gsampler2DArray| s) | always internally assigns a texture even to an empty sampler). | +| int | :ref:`textureQueryLevels` ( |gsampler2D| s ) | Get the number of accessible mipmap levels of a texture. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| int | :ref:`textureQueryLevels` ( |gsampler2DArray| s ) | | +--------------+-----------------------------------------------------------------------------------------------------+ | -| int | :ref:`textureQueryLevels` ( |gsampler3D| s) | | +| int | :ref:`textureQueryLevels` ( |gsampler3D| s ) | | +--------------+-----------------------------------------------------------------------------------------------------+ | -| int | :ref:`textureQueryLevels` (samplerCube s) | | +| int | :ref:`textureQueryLevels` (samplerCube s ) | | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`texture` ( |gsampler2D| s, vec2 p [, float bias]) | Perform a texture read. | +| |gvec4_type| | :ref:`texture` ( |gsampler2D| s, vec2 p [, float bias] ) | Perform a texture read. | +--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`texture` ( |gsampler2DArray| s, vec3 p [, float bias]) | | +| |gvec4_type| | :ref:`texture` ( |gsampler2DArray| s, vec3 p [, float bias] ) | | +--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`texture` ( |gsampler3D| s, vec3 p [, float bias]) | | +| |gvec4_type| | :ref:`texture` ( |gsampler3D| s, vec3 p [, float bias] ) | | +--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`texture` (samplerCube 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` (samplerCubeArray s, vec4 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, vec3 p [, float bias] ) | Perform a texture read with projection. | +--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureProj` ( |gsampler2D| s, vec4 p [, float bias]) | | +| |gvec4_type| | :ref:`textureProj` ( |gsampler2D| s, vec4 p [, float bias] ) | | +--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureProj` ( |gsampler3D| s, vec4 p [, float bias]) | | +| |gvec4_type| | :ref:`textureProj` ( |gsampler3D| s, vec4 p [, float bias] ) | | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureLod` ( |gsampler2D| s, vec2 p, float lod) | Perform a texture read at custom mipmap. | -+--------------+-----------------------------------------------------------------------------------------------------+ The LOD defines which mipmap level is used. An LOD value of ``0.0`` | -| |gvec4_type| | :ref:`textureLod` ( |gsampler2DArray| s, vec3 p, float lod) | will use the full resolution texture. If the texture lacks mipmaps, | -+--------------+-----------------------------------------------------------------------------------------------------+ all LOD values will act like ``0.0``. | -| |gvec4_type| | :ref:`textureLod` ( |gsampler3D| s, vec3 p, float lod) | | +| |gvec4_type| | :ref:`textureLod` ( |gsampler2D| s, vec2 p, float lod ) | Perform a texture read at custom mipmap. | +--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureLod` (samplerCube s, vec3 p, float lod) | | +| |gvec4_type| | :ref:`textureLod` ( |gsampler2DArray| s, vec3 p, float lod ) | | +--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureLod` (samplerCubeArray s, vec4 p, float lod) | | +| |gvec4_type| | :ref:`textureLod` ( |gsampler3D| s, vec3 p, float lod ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec4 | :ref:`textureLod` (samplerCube s, vec3 p, float lod ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec4 | :ref:`textureLod` (samplerCubeArray s, vec4 p, float lod ) | | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec3 p, float lod) | Performs a texture read with projection/LOD. | -+--------------+-----------------------------------------------------------------------------------------------------+ The LOD defines which mipmap level is used. An LOD value of ``0.0`` | -| |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec4 p, float lod) | will use the full resolution texture. If the texture lacks mipmaps, | -+--------------+-----------------------------------------------------------------------------------------------------+ all LOD values will act like ``0.0``. | -| |gvec4_type| | :ref:`textureProjLod` ( |gsampler3D| s, vec4 p, float lod) | | +| |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec3 p, float lod ) | Performs a texture read with projection/LOD. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec4 p, float lod ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureProjLod` ( |gsampler3D| s, vec4 p, float lod ) | | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureGrad` ( |gsampler2D| s, vec2 p, vec2 dPdx, vec2 dPdy) | Performs a texture read with explicit gradients. | +| |gvec4_type| | :ref:`textureGrad` ( |gsampler2D| s, vec2 p, vec2 dPdx, vec2 dPdy ) | Performs a texture read with explicit gradients. | +--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureGrad` ( |gsampler2DArray| s, vec3 p, vec2 dPdx, vec2 dPdy) | | +| |gvec4_type| | :ref:`textureGrad` ( |gsampler2DArray| s, vec3 p, vec2 dPdx, vec2 dPdy ) | | +--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureGrad` ( |gsampler3D| s, vec3 p, vec2 dPdx, vec2 dPdy) | | +| |gvec4_type| | :ref:`textureGrad` ( |gsampler3D| s, vec3 p, vec2 dPdx, vec2 dPdy ) | | +--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureGrad` (samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy) | | +| vec4 | :ref:`textureGrad` (samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy ) | | +--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureGrad` (samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy) | | +| vec4 | :ref:`textureGrad` (samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) | | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy) | Performs a texture read with projection/LOD and with explicit | +| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy )| Performs a texture read with projection/LOD and with explicit | +--------------+-----------------------------------------------------------------------------------------------------+ gradients. | -| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy) | | +| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy )| | +--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy) | | +| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy )| | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`texelFetch` ( |gsampler2D| s, ivec2 p, int lod) | Fetches a single texel using integer coordinates. | -+--------------+-----------------------------------------------------------------------------------------------------+ The LOD defines which mipmap level is used. An LOD value of ``0`` | -| |gvec4_type| | :ref:`texelFetch` ( |gsampler2DArray| s, ivec3 p, int lod) | will use the full resolution texture. | +| |gvec4_type| | :ref:`texelFetch` ( |gsampler2D| s, ivec2 p, int lod ) | Fetches a single texel using integer coordinates. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`texelFetch` ( |gsampler2DArray| s, ivec3 p, int lod ) | | +--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`texelFetch` ( |gsampler3D| s, ivec3 p, int lod) | | +| |gvec4_type| | :ref:`texelFetch` ( |gsampler3D| s, ivec3 p, int lod ) | | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureGather` ( |gsampler2D| s, vec2 p [, int comps]) | Gathers four texels from a texture. | -+--------------+-----------------------------------------------------------------------------------------------------+ Use ``comps`` within range of 0..3 to | -| |gvec4_type| | :ref:`textureGather` ( |gsampler2DArray| s, vec3 p [, int comps]) | define which component (x, y, z, w) is returned. | -+--------------+-----------------------------------------------------------------------------------------------------+ If ``comps`` is not provided: 0 (or x-component) is used. | -| vec4 | :ref:`textureGather` (samplerCube s, vec3 p [, int comps]) | | +| |gvec4_type| | :ref:`textureGather` ( |gsampler2D| s, vec2 p [, int comps] ) | Gathers four texels from a texture. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureGather` ( |gsampler2DArray| s, vec3 p [, int comps] ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec4 | :ref:`textureGather` (samplerCube s, vec3 p [, int comps] ) | | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdx` ( |vec_type| p) | Derivative in ``x`` using local differencing. | -| | | Internally, can use either ``dFdxCoarse`` or ``dFdxFine``, but the | -| | | decision for which to use is made by the GPU driver. | +| |vec_type| | :ref:`dFdx` ( |vec_type| p ) | Derivative with respect to ``x`` window coordinate, | +| | | automatic granularity. | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdxCoarse` ( |vec_type| p) | Calculates derivative with respect to ``x`` window coordinate using | -| | | local differencing based on the value of ``p`` for the current | -| | | fragment neighbour(s), and will possibly, but not necessarily, | -| | | include the value for the current fragment. | +| |vec_type| | :ref:`dFdxCoarse` ( |vec_type| p ) | Derivative with respect to ``x`` window coordinate, | +| | | course granularity. | +| | | | | | | Not available on ``gl_compatibility`` profile. | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdxFine` ( |vec_type| p) | Calculates derivative with respect to ``x`` window coordinate using | -| | | local differencing based on the value of ``p`` for the current | -| | | fragment and its immediate neighbour(s). | +| |vec_type| | :ref:`dFdxFine` ( |vec_type| p ) | Derivative with respect to ``x`` window coordinate, | +| | | fine granularity. | +| | | | | | | Not available on ``gl_compatibility`` profile. | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdy` ( |vec_type| p) | Derivative in ``y`` using local differencing. | -| | | Internally, can use either ``dFdyCoarse`` or ``dFdyFine``, but the | -| | | decision for which to use is made by the GPU driver. | +| |vec_type| | :ref:`dFdy` ( |vec_type| p ) | Derivative with respect to ``y`` window coordinate. | +| | | Automatic granularity. | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdyCoarse` ( |vec_type| p) | Calculates derivative with respect to ``y`` window coordinate using | -| | | local differencing based on the value of ``p`` for the current | -| | | fragment neighbour(s), and will possibly, but not necessarily, | -| | | include the value for the current fragment. | +| |vec_type| | :ref:`dFdyCoarse` ( |vec_type| p ) | Derivative with respect to ``y`` window coordinate, | +| | | course granularity. | +| | | | | | | Not available on ``gl_compatibility`` profile. | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdyFine` ( |vec_type| p) | Calculates derivative with respect to ``y`` window coordinate using | -| | | local differencing based on the value of ``p`` for the current | -| | | fragment and its immediate neighbour(s). | +| |vec_type| | :ref:`dFdyFine` ( |vec_type| p ) | Derivative with respect to ``y`` window coordinate, | +| | | fine granularity. | +| | | | | | | Not available on ``gl_compatibility`` profile. | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`fwidth` ( |vec_type| p) | Sum of absolute derivative in ``x`` and ``y``. | -| | | This is the equivalent of using ``abs(dFdx(p)) + abs(dFdy(p))``. | +| |vec_type| | :ref:`fwidth` ( |vec_type| p ) | Sum of absolute derivative in ``x`` and ``y``. | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`fwidthCoarse` ( |vec_type| p) | Sum of absolute derivative in ``x`` and ``y``. | +| |vec_type| | :ref:`fwidthCoarse` ( |vec_type| p ) | Sum of absolute derivative in ``x`` and ``y``. | +| | | | | | | Not available on ``gl_compatibility`` profile. | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`fwidthFine` ( |vec_type| p) | Sum of absolute derivative in ``x`` and ``y``. | +| |vec_type| | :ref:`fwidthFine` ( |vec_type| p ) | Sum of absolute derivative in ``x`` and ``y``. | +| | | | | | | Not available on ``gl_compatibility`` profile. | +--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ @@ -4071,11 +4070,9 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) |vec_type| **dFdx** ( |vec_type| p ) - Return the partial derivative of ``p`` with respect to the window x coordinate. - - .. note:: + .. note:: Available only in the fragment shader. - Available only in the fragment shader + Return the partial derivative of ``p`` with respect to the window x coordinate using local differencing. Returns either `dFdxCoarse` or `dFdxFine`. The implementation may choose which calculation to perform based upon factors such as performance or the value of the API GL_FRAGMENT_SHADER_DERIVATIVE_HINT hint. @@ -4086,9 +4083,7 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) :param p: the expression of which to take the partial derivative. - .. note:: - - It is assumed that the expression ``p`` is continuous and therefore expressions evaluated via non-uniform control flow may be undefined. + .. note:: It is assumed that the expression ``p`` is continuous and therefore expressions evaluated via non-uniform control flow may be undefined. :return: the partial derivative of ``p``. @@ -4108,26 +4103,23 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) |vec_type| **dFdxCoarse** ( |vec_type| p ) - Return the partial derivative of ``p`` with respect to the window x coordinate. - .. note:: + | Available only in the fragment shader. + | Not available when using the GL_Compatibility rendering backend. - Available only in the fragment shader + Return the partial derivative of ``p`` with respect to the window x coordinate. Calculates derivatives using local differencing based on the value of ``p`` for the current fragment's neighbors, and will possibly, but not necessarily, include the value for the current fragment. That is, over a given area, the implementation can compute derivatives in fewer unique locations than would be allowed for the corresponding `dFdxFine`` function. - .. warning:: Expressions that imply higher order derivatives such as ``dFdx(dFdx(n))`` have undefined results, as do mixed-order derivatives such as ``dFdx(dFdy(n))``. :param p: the expression of which to take the partial derivative. - .. note:: - - It is assumed that the expression ``p`` is continuous and therefore expressions evaluated via non-uniform control flow may be undefined. + .. note:: It is assumed that the expression ``p`` is continuous and therefore expressions evaluated via non-uniform control flow may be undefined. :return: the partial derivative of ``p``. @@ -4147,9 +4139,11 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) |vec_type| **dFdxFine** ( |vec_type| p ) - Return the partial derivative of ``p`` with respect to the window x coordinate. + .. note:: + | Available only in the fragment shader. + | Not available when using the GL_Compatibility rendering backend. - .. note:: Available only in the fragment shader + Return the partial derivative of ``p`` with respect to the window x coordinate. Calculates derivatives using local differencing based on the value of ``p`` for the current fragment and its immediate neighbor(s). @@ -4178,10 +4172,10 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) |vec_type| **dFdy** ( |vec_type| p ) - Return the partial derivative of ``p`` with respect to the window y coordinate. - .. note:: Available only in the fragment shader + Return the partial derivative of ``p`` with respect to the window y coordinate using local differencing. + Returns either `dFdyCoarse` or `dFdyFine`. The implementation may choose which calculation to perform based upon factors such as performance or the value of the API GL_FRAGMENT_SHADER_DERIVATIVE_HINT hint. @@ -4210,9 +4204,11 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) |vec_type| **dFdyCoarse** ( |vec_type| p ) - Return the partial derivative of ``p`` with respect to the window y coordinate. + .. note:: + | Available only in the fragment shader. + | Not available when using the GL_Compatibility rendering backend. - .. note:: Available only in the fragment shader + Return the partial derivative of ``p`` with respect to the window y coordinate. Calculates derivatives using local differencing based on the value of ``p`` for the current fragment's neighbors, and will possibly, but not necessarily, include the value for the current fragment. That is, over a given area, the implementation can compute derivatives in fewer unique locations than @@ -4243,9 +4239,11 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) |vec_type| **dFdyFine** ( |vec_type| p ) - Return the partial derivative of ``p`` with respect to the window y coordinate. + .. note:: + | Available only in the fragment shader. + | Not available when using the GL_Compatibility rendering backend. - .. note:: Available only in the fragment shader + Return the partial derivative of ``p`` with respect to the window y coordinate. Calculates derivatives using local differencing based on the value of ``p`` for the current fragment and its immediate neighbor(s). @@ -4280,9 +4278,6 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) Equivalent to ``abs(dFdx(p)) + abs(dFdy(p))``. - fwidthCoarse is equivalent to ``abs(dFdxCoarse(p)) + abs(dFdyCoarse(p))``. - fwidthFine is equivalent to ``abs(dFdxFine(p)) + abs(dFdyFine(p))``. - :param p: the expression of which to take the partial derivative. @@ -4304,6 +4299,10 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) |vec_type| **fwidthCoarse** ( |vec_type| p ) + .. note:: + | Available only in the fragment shader. + | Not available when using the GL_Compatibility rendering backend. + Return the sum of the absolute value of derivatives in x and y. Uses local differencing for the input argument p. @@ -4331,6 +4330,10 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) |vec_type| **fwidthFine** ( |vec_type| p ) + .. note:: + | Available only in the fragment shader. + | Not available when using the GL_Compatibility rendering backend. + Return the sum of the absolute value of derivatives in x and y. Uses local differencing for the input argument p. @@ -4355,31 +4358,29 @@ vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) Packing/Unpacking Functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^ +These functions convert floating point numbers into various sized integers and then pack those integers into a single 32bit unsigned integer. +The 'unpack' functions perform the opposite operation, returning the original floating point numbers. + +------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packHalf2x16` (vec2 v) | Convert two 32-bit floating-point numbers into 16-bit | -| | | and pack them into a 32-bit unsigned integer and vice-versa. | +| uint | :ref:`packHalf2x16` (vec2 v ) | Convert two 32-bit floats to 16 bit floats and pack them. | +------+--------------------------------------------------------------+ + -| vec2 | :ref:`unpackHalf2x16` (uint v) | | +| vec2 | :ref:`unpackHalf2x16` (uint v ) | | +------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packUnorm2x16` (vec2 v) | Convert two 32-bit floating-point numbers (clamped | -| | | within 0..1 range) into 16-bit and pack them | -+------+--------------------------------------------------------------+ + -| vec2 | :ref:`unpackUnorm2x16` (uint v) | into a 32-bit unsigned integer and vice-versa. | +| uint | :ref:`packUnorm2x16` (vec2 v ) | Convert two normalized (range 0..1) 32-bit floats | ++------+--------------------------------------------------------------+ to 16-bit floats and pack them. + +| vec2 | :ref:`unpackUnorm2x16` (uint v )| | +------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packSnorm2x16` (vec2 v) | Convert two 32-bit floating-point numbers (clamped | -| | | within -1..1 range) into 16-bit and pack them | -+------+--------------------------------------------------------------+ + -| vec2 | :ref:`unpackSnorm2x16` (uint v) | into a 32-bit unsigned integer and vice-versa. | +| uint | :ref:`packSnorm2x16` (vec2 v ) | Convert two signed normalized (range -1..1) 32-bit floats | ++------+--------------------------------------------------------------+ to 16-bit floats and pack them. + +| vec2 | :ref:`unpackSnorm2x16` (uint v )| | +------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packUnorm4x8` (vec4 v) | Convert four 32-bit floating-point numbers (clamped | -| | | within 0..1 range) into 8-bit and pack them | -+------+--------------------------------------------------------------+ + -| vec4 | :ref:`unpackUnorm4x8` (uint v) | into a 32-bit unsigned integer and vice-versa. | +| uint | :ref:`packUnorm4x8` (vec4 v ) | Convert four normalized (range 0..1) 32-bit floats | ++------+--------------------------------------------------------------+ into 8-bit floats and pack them. + +| vec4 | :ref:`unpackUnorm4x8` (uint v ) | | +------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packSnorm4x8` (vec4 v) | Convert four 32-bit floating-point numbers (clamped | -| | | within -1..1 range) into 8-bit and pack them | -+------+--------------------------------------------------------------+ + -| vec4 | :ref:`unpackSnorm4x8` (uint v) | into a 32-bit unsigned integer and vice-versa. | +| uint | :ref:`packSnorm4x8` (vec4 v ) | Convert four signed normalized (range -1..1) 32-bit floats | ++------+--------------------------------------------------------------+ into 8-bit floats and pack them. + +| vec4 | :ref:`unpackSnorm4x8` (uint v ) | | +------+--------------------------------------------------------------+--------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -4394,7 +4395,7 @@ Packing/Unpacking Functions uint **packHalf2x16** ( vec2 v ) - Convert two 32-bit floating-point quantities to 16-bit quantities and pack them into a single 32-bit integer. + Convert two 32-bit floating-point quantities to 16-bit floating point quantities and pack them into a single 32-bit integer. Returns an unsigned integer obtained by converting the components of a two-component floating-point vector to the 16-bit floating-point representation found in the OpenGL Specification, and then packing these two @@ -4422,12 +4423,11 @@ uint **packHalf2x16** ( vec2 v ) vec2 **unpackHalf2x16** ( uint v ) - Convert two 16-bit floating-point values packed into a single 32-bit integer into a vector of two 32-bit floating-point quantities. + Inverse of :ref:`packHalf2x16`. - Returns a two-component floating-point vector with components obtained by unpacking a 32-bit unsigned integer into a pair of 16-bit - values, interpreting those values as 16-bit floating-point numbers according to the OpenGL Specification, and converting them to - 32-bit floating-point values. The first component of the vector is obtained from the 16 least-significant bits of v; the second - component is obtained from the 16 most-significant bits of v. + Unpack a 32-bit integer into two 16-bit floating-point values, convert them to 32-bit floating-point values, and put them into a vector. + The first component of the vector is obtained from the 16 least-significant bits of v; the second component is obtained from the + 16 most-significant bits of v. :param v: a single 32-bit unsigned integer containing 2 packed 16-bit floating point values. @@ -4452,7 +4452,7 @@ uint **packUnorm2x16** ( vec2 v ) Pack floating-point values into an unsigned integer. - Convert each component of the normalized floating-point value v into 16-bit integer values and then packs the results into a 32-bit unsigned integer. + Converts each component of the normalized floating-point value v into 16-bit integer values and then packs the results into a 32-bit unsigned integer. The conversion for component c of v to fixed-point is performed as follows:: @@ -4691,41 +4691,41 @@ Bitwise operations ^^^^^^^^^^^^^^^^^^ +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`bitfieldExtract` ( |vec_int_type| value, int offset, int bits) | Extracts a range of bits from an integer. | +| |vec_int_type| | :ref:`bitfieldExtract` ( |vec_int_type| value, int offset, int bits ) | Extracts a range of bits from an integer. | | | | | -| |vec_uint_type| | :ref:`bitfieldExtract` ( |vec_uint_type| value, int offset, int bits) | | +| |vec_uint_type| | :ref:`bitfieldExtract` ( |vec_uint_type| value, int offset, int bits ) | | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`bitfieldInsert` ( |vec_int_type| base, |vec_int_type| insert,int offset, int bits) | Insert a range of bits into an integer. | +| |vec_int_type| | :ref:`bitfieldInsert` ( |vec_int_type| base, |vec_int_type| insert, int offset, int bits ) | Insert a range of bits into an integer. | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`bitfieldInsert` (|vec_uint_type| base, |vec_uint_type| insert, int offset, int bits) | | +| |vec_uint_type| | :ref:`bitfieldInsert` (|vec_uint_type| base, |vec_uint_type| insert, int offset, int bits ) | | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`bitfieldReverse` ( |vec_int_type| value) | Reverse the order of bits in an integer. | +| |vec_int_type| | :ref:`bitfieldReverse` ( |vec_int_type| value ) | Reverse the order of bits in an integer. | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`bitfieldReverse` ( |vec_uint_type| value) | | +| |vec_uint_type| | :ref:`bitfieldReverse` ( |vec_uint_type| value ) | | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`bitCount` ( |vec_int_type| value) | Counts the number of 1 bits in an integer. | +| |vec_int_type| | :ref:`bitCount` ( |vec_int_type| value ) | Counts the number of 1 bits in an integer. | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`bitCount` ( |vec_uint_type| value) | | +| |vec_uint_type| | :ref:`bitCount` ( |vec_uint_type| value ) | | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`findLSB` ( |vec_int_type| value) | Find the index of the least significant bit set to 1 in an integer. | +| |vec_int_type| | :ref:`findLSB` ( |vec_int_type| value ) | Find the index of the least significant bit set to 1 in an integer. | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`findLSB` ( |vec_uint_type| value) | | +| |vec_uint_type| | :ref:`findLSB` ( |vec_uint_type| value ) | | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`findMSB` ( |vec_int_type| value) | Find the index of the most significant bit set to 1 in an integer. | +| |vec_int_type| | :ref:`findMSB` ( |vec_int_type| value ) | Find the index of the most significant bit set to 1 in an integer. | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`findMSB` ( |vec_uint_type| value) | | +| |vec_uint_type| | :ref:`findMSB` ( |vec_uint_type| value ) | | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |void| | :ref:`imulExtended` ( |vec_int_type| x, |vec_int_type| y, out |vec_int_type| msb, out |vec_int_type| lsb) | Multiplies two 32-bit numbers and produce a 64-bit result. | +| |void| | :ref:`imulExtended` ( |vec_int_type| x, |vec_int_type| y, out |vec_int_type| msb, out |vec_int_type| lsb ) | Multiplies two 32-bit numbers and produce a 64-bit result. | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | -| |void| | :ref:`umulExtended` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| msb, out |vec_uint_type| lsb) | | +| |void| | :ref:`umulExtended` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| msb, out |vec_uint_type| lsb )| | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_uint_type| | :ref:`uaddCarry` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| carry) | Adds two unsigned integers and generates carry. | +| |vec_uint_type| | :ref:`uaddCarry` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| carry ) | Adds two unsigned integers and generates carry. | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_uint_type| | :ref:`usubBorrow` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| borrow) | Subtracts two unsigned integers and generates borrow. | +| |vec_uint_type| | :ref:`usubBorrow` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| borrow ) | Subtracts two unsigned integers and generates borrow. | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`ldexp` (|vec_type| x, out |vec_int_type| exp) | Assemble a floating-point number from a value and exponent. | +| |vec_type| | :ref:`ldexp` (|vec_type| x, out |vec_int_type| exp ) | Assemble a floating-point number from a value and exponent. | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`frexp` (|vec_type| x, out |vec_int_type| exp) | Splits a floating-point number (``x``) into significand integral | +| |vec_type| | :ref:`frexp` (|vec_type| x, out |vec_int_type| exp ) | Splits a floating-point number (``x``) into significand integral | | | | components | +-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ diff --git a/tutorials/shaders/shader_reference/shading_language.rst b/tutorials/shaders/shader_reference/shading_language.rst index 20a453c8285..47a2635f833 100644 --- a/tutorials/shaders/shader_reference/shading_language.rst +++ b/tutorials/shaders/shader_reference/shading_language.rst @@ -1134,3 +1134,11 @@ please see the corresponding pages: - :ref:`Particle shaders ` - :ref:`Sky shaders ` - :ref:`Fog shaders ` + +Built-in functions +------------------ + +A large number of built-in functions are supported, conforming to GLSL ES 3.0. +See the following page for details: + +- :ref:`Built-In Functions ` From 7e5282385bd943032cfe9ae056b1f17a2c69980e Mon Sep 17 00:00:00 2001 From: ashbygeek Date: Thu, 4 Jul 2024 23:43:18 -0400 Subject: [PATCH 14/25] Combine docs for very similar functions --- .../shader_reference/shader_functions.rst | 3146 +++++------------ 1 file changed, 827 insertions(+), 2319 deletions(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index 9c5490daf49..16c7aa1e799 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -719,26 +719,8 @@ vec_type pow( |vec_type| x, |vec_type| y) .. rst-class:: classref-method -|vec_type| **abs** ( |vec_type| x ) - - Returns the absolute value of x. Returns X if X is positive or X * -1 if X is negative. - - :param x: - the value of which to return the absolute. - - :return: - the absolute value of x - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/abs.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -|vec_int_type| **abs** ( |vec_int_type| x ) +| |vec_type| **abs** ( |vec_type| x ) +| |vec_int_type| **abs** ( |vec_int_type| x ) Returns the absolute value of x. Returns X if X is positive or X * -1 if X is negative. @@ -761,27 +743,8 @@ vec_type pow( |vec_type| x, |vec_type| y) .. rst-class:: classref-method -|vec_type| **sign** ( |vec_type| x ) - - Returns -1.0 if x is less than 0.0, 0.0 if x is equal to 0.0, and +1.0 if x is greater than 0.0. - - :param x: - the value from which to extract the sign. - - :return: - 1, -1 or 0. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/sign.xhtml - -.. rst-class:: classref-item-separator - ----- - - - -.. rst-class:: classref-method - -|vec_int_type| **sign** ( |vec_int_type| x ) +| |vec_type| **sign** ( |vec_type| x ) +| |vec_int_type| **sign** ( |vec_int_type| x ) Returns -1.0 if x is less than 0.0, 0.0 if x is equal to 0.0, and +1.0 if x is greater than 0.0. @@ -951,29 +914,8 @@ vec_type pow( |vec_type| x, |vec_type| y) .. rst-class:: classref-method -|vec_type| **mod** ( |vec_type| x, |vec_type| y ) - - Returns the value of ``x modulo y``. - This is also sometimes called the remainder. - - This is computed as ``x - y * floor(x/y)``. - - :param x: - the value to evaluate. - - :return: - the value of ``x modulo y``. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/mod.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -|vec_type| **mod** ( |vec_type| x, float y ) +| |vec_type| **mod** ( |vec_type| x, |vec_type| y ) +| |vec_type| **mod** ( |vec_type| x, float y ) Returns the value of ``x modulo y``. This is also sometimes called the remainder. @@ -1028,11 +970,16 @@ vec_type pow( |vec_type| x, |vec_type| y) .. rst-class:: classref-method -|vec_type| **min** ( |vec_type| a, |vec_type| b ) +| |vec_type| **min** ( |vec_type| a, |vec_type| b ) +| |vec_type| **min** ( |vec_type| a, float b ) +| |vec_int_type| **min** ( |vec_int_type| a, |vec_int_type| b ) +| |vec_int_type| **min** ( |vec_int_type| a, int b ) +| |vec_uint_type| **min** ( |vec_uint_type| a, |vec_uint_type| b ) +| |vec_uint_type| **min** ( |vec_uint_type| a, uint b ) Returns the minimum of the two parameters. - It returns y if y is less than x, otherwise it returns x. + It returns b if b is less than a, otherwise it returns a. :param a: the first value to compare. @@ -1050,13 +997,22 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- + + +.. _shader_func_max: + .. rst-class:: classref-method -|vec_type| **min** ( |vec_type| a, float b ) +| |vec_type| **max** ( |vec_type| a, |vec_type| b ) +| |vec_type| **max** ( |vec_type| a, float b ) +| |vec_uint_type| **max** ( |vec_uint_type| a, |vec_uint_type| b ) +| |vec_uint_type| **max** ( |vec_uint_type| a, uint b ) +| |vec_int_type| **max** ( |vec_int_type| a, |vec_int_type| b ) +| |vec_int_type| **max** ( |vec_int_type| a, int b ) - Returns the minimum of the two parameters. + Returns the maximum of the two parameters. - It returns y if y is less than x, otherwise it returns x. + It returns b if b is greater than a, otherwise it returns a. :param a: the first value to compare. @@ -1065,9 +1021,9 @@ vec_type pow( |vec_type| x, |vec_type| y) the second value to compare. :return: - the minimum of the two parameters. + the maximum value. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/min.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml .. rst-class:: classref-item-separator @@ -1075,24 +1031,35 @@ vec_type pow( |vec_type| x, |vec_type| y) + +.. _shader_func_clamp: + .. rst-class:: classref-method -|vec_int_type| **min** ( |vec_int_type| a, |vec_int_type| b ) +| |vec_type| **clamp** ( |vec_type| x, |vec_type| minVal, |vec_type| maxVal ) +| |vec_type| **clamp** ( |vec_type| x, float min, float max ) +| |vec_type| **clamp** ( |vec_type| x, float min, float max ) +| |vec_uint_type| **clamp** ( |vec_int_type| x, float min, float max ) +| |vec_int_type| **clamp** ( |vec_type| x, |vec_type| min, |vec_type| max ) +| |vec_int_type| **clamp** ( |vec_type| x, float min, float max ) - Returns the minimum of the two parameters. + Returns the value of x constrained to the range minVal to maxVal. - It returns y if y is less than x, otherwise it returns x. + The returned value is computed as ``min(max(x, minVal), maxVal)``. - :param a: - the first value to compare. + :param x: + the value to constrain. - :param b: - the second value to compare. + :param minVal: + the lower end of the range into which to constrain x. + + :param maxVal: + the upper end of the range into which to constrain x. :return: - the minimum of the two parameters. + the constrained value. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/min.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml .. rst-class:: classref-item-separator @@ -1100,24 +1067,31 @@ vec_type pow( |vec_type| x, |vec_type| y) + +.. _shader_func_mix: + .. rst-class:: classref-method -|vec_int_type| **min** ( |vec_int_type| a, int b ) +| |vec_type| **mix** ( |vec_type| a, |vec_type| b, |vec_type| c ) +| |vec_type| **mix** ( |vec_type| a, |vec_type| b, float c ) - Returns the minimum of the two parameters. + Performs a linear interpolation between a and b using c to weight between them. - It returns y if y is less than x, otherwise it returns x. + computed as ``a × (1 − c) + b × c``. :param a: - the first value to compare. + the start of the range in which to interpolate. :param b: - the second value to compare. + the end of the range in which to interpolate. + + :param c: + the value to use to interpolate between x and y. :return: - the minimum of the two parameters. + The interpolated value. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/min.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/mix.xhtml .. rst-class:: classref-item-separator @@ -1126,22 +1100,29 @@ vec_type pow( |vec_type| x, |vec_type| y) .. rst-class:: classref-method -|vec_uint_type| **min** ( |vec_uint_type| a, |vec_uint_type| b ) +|vec_type| **mix** ( |vec_type| a, |vec_type| b, |vec_bool_type| c ) - Returns the minimum of the two parameters. + Selects either value a or value b based on the value of c. + For a component of c that is false, the corresponding component of a is returned. + For a component of c that is true, the corresponding component of b is returned. + Components of a and b that are not selected are allowed to be invalid floating-point values and will have no effect on the results. - It returns y if y is less than x, otherwise it returns x. + If a, b, and c are vector types the operation is performed component-wise. + ie. ``mix(vec2(42, 314), vec2(9.8, 6e23), vec_bool_type(true, false)))`` will return ``vec2(9.8, 314)``. :param a: - the first value to compare. + value returned when a is false. :param b: - the second value to compare. + value returned when a is true. + + :param c: + the value to use to interpolate between x and y. :return: - the minimum of the two parameters. + The interpolated value. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/min.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/mix.xhtml .. rst-class:: classref-item-separator @@ -1149,24 +1130,39 @@ vec_type pow( |vec_type| x, |vec_type| y) + +.. _shader_func_fma: + .. rst-class:: classref-method -|vec_uint_type| **min** ( |vec_uint_type| a, uint b ) +|vec_type| **fma** ( |vec_type| a, |vec_type| b, |vec_type| c ) - Returns the minimum of the two parameters. + Performs, where possible, a fused multiply-add operation, returning a * b + c. In use cases where the + return value is eventually consumed by a variable declared as precise: + + - fma() is considered a single operation, whereas the expression a * b + c consumed by a variable declared as precise is considered two operations. + + - The precision of fma() can differ from the precision of the expression a * b + c. + + - fma() will be computed with the same precision as any other fma() consumed by a precise variable, + giving invariant results for the same input values of a, b and c. - It returns y if y is less than x, otherwise it returns x. + Otherwise, in the absence of precise consumption, there are no special constraints on the number of operations + or difference in precision between fma() and the expression a * b + c. :param a: - the first value to compare. + the first multiplicand. :param b: - the second value to compare. + the second multiplicand. + + :param c: + the value to be added to the result. :return: - the minimum of the two parameters. + value of ``a * b + c`` - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/min.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/fma.xhtml .. rst-class:: classref-item-separator @@ -1175,51 +1171,58 @@ vec_type pow( |vec_type| x, |vec_type| y) -.. _shader_func_max: +.. _shader_func_step: .. rst-class:: classref-method -|vec_type| **max** ( |vec_type| a, |vec_type| b ) +|vec_type| **step** ( |vec_type| a, |vec_type| b ) + + Generates a step function by comparing b to a. - Returns the maximum of the two parameters. + Equivalent to ``if (b < a) { return 0.0; } else { return 1.0; }``. + Or if vec_type is a vector, a vector where the above operation has been performed on each component of the input vectors. + ie. ``step(vec2(4.2, 314), vec2(2.4, 980))`` would return ``vec2(step(a[0], b[0]), step(a[1], b[1]))``. - It returns y if y is greater than x, otherwise it returns x. + For element i of the return value, 0.0 is returned if b[i] < a[i], and 1.0 is returned otherwise. :param a: - the first value to compare. + the location of the edge of the step function. :param b: - the second value to compare. + the value to be used to generate the step function. :return: - the maximum value. + 0.0 or 1.0 - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/step.xhtml .. rst-class:: classref-item-separator ---- - .. rst-class:: classref-method -|vec_type| **max** ( |vec_type| a, float b ) +|vec_type| **step** ( float a, |vec_type| b ) - Returns the maximum of the two parameters. + Generates a step function by comparing b to a. + + Equivalent to ``if (b < a) { return 0.0; } else { return 1.0; }``. + Or rather, the above operation will be performed on each component of the input vector. + ie. ``step(4.2, vec2(2.4, 980))`` would return the equivalent of ``vec2(step(42, b[0]), step(42, b[1]))``. - It returns y if y is greater than x, otherwise it returns x. + For element i of the return value, 0.0 is returned if b[i] < a[i], and 1.0 is returned otherwise. :param a: - the first value to compare. + the location of the edge of the step function. :param b: - the second value to compare. + the value to be used to generate the step function. :return: - the maximum value. + 0.0 or 1.0 - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/step.xhtml .. rst-class:: classref-item-separator @@ -1227,24 +1230,38 @@ vec_type pow( |vec_type| x, |vec_type| y) + +.. _shader_func_smoothstep: + .. rst-class:: classref-method -|vec_uint_type| **max** ( |vec_uint_type| a, |vec_uint_type| b ) +| |vec_type| **smoothstep** ( |vec_type| a, |vec_type| b, |vec_type| c ) +| |vec_type| **smoothstep** ( float a, float b, |vec_type| c ) - Returns the maximum of the two parameters. + Performs smooth Hermite interpolation between 0 and 1 when a < c < b. + This is useful in cases where a threshold function with a smooth transition is desired. + + Smoothstep is equivalent to:: - It returns y if y is greater than x, otherwise it returns x. + vec_type t; + t = clamp((c - a) / (b - a), 0.0, 1.0); + return t * t * (3.0 - 2.0 * t); + + Results are undefined if a ≥ b. :param a: - the first value to compare. + the value of the lower edge of the Hermite function. :param b: - the second value to compare. + the value of the upper edge of the Hermite function. + + :param c: + the source value for interpolation. :return: - the maximum value. + the interpolated value - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/smoothstep.xhtml .. rst-class:: classref-item-separator @@ -1252,24 +1269,23 @@ vec_type pow( |vec_type| x, |vec_type| y) -.. rst-class:: classref-method -|vec_uint_type| **max** ( |vec_uint_type| a, uint b ) +.. _shader_func_isnan: - Returns the maximum of the two parameters. +.. rst-class:: classref-method - It returns y if y is greater than x, otherwise it returns x. +|vec_bool_type| **isnan** ( |vec_type| x ) - :param a: - the first value to compare. + For each element i of the result, returns true if x[i] is positive + or negative floating point NaN (Not a Number) and false otherwise. - :param b: - the second value to compare. + :param x: + the value to test for NaN. :return: - the maximum value. + true or false - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/isnan.xhtml .. rst-class:: classref-item-separator @@ -1277,48 +1293,48 @@ vec_type pow( |vec_type| x, |vec_type| y) -.. rst-class:: classref-method -|vec_int_type| **max** ( |vec_int_type| a, |vec_int_type| b ) +.. _shader_func_isinf: - Returns the maximum of the two parameters. +.. rst-class:: classref-method - It returns y if y is greater than x, otherwise it returns x. +|vec_bool_type| **isinf** ( |vec_type| x ) - :param a: - the first value to compare. + For each element i of the result, returns true if x[i] is positive or negative + floating point infinity and false otherwise. - :param b: - the second value to compare. + :param x: + the value to test for infinity. :return: - the maximum value. + true or false - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/isinf.xhtml .. rst-class:: classref-item-separator ---- -.. rst-class:: classref-method -|vec_int_type| **max** ( |vec_int_type| a, int b ) - Returns the maximum of the two parameters. +.. _shader_func_floatBitsToInt: - It returns y if y is greater than x, otherwise it returns x. +.. rst-class:: classref-method - :param a: - the first value to compare. +|vec_int_type| **floatBitsToInt** ( |vec_type| x ) - :param b: - the second value to compare. + Returns the encoding of the floating-point parameters as int. - :return: - the maximum value. + The floating-point bit-level representation is preserved. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/max.xhtml + :param x: + the value whose floating point encoding to return. + + :return: + the floating-point encoding of x. + + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/floatBitsToInt.xhtml .. rst-class:: classref-item-separator @@ -1327,164 +1343,171 @@ vec_type pow( |vec_type| x, |vec_type| y) -.. _shader_func_clamp: +.. _shader_func_floatBitsToUint: .. rst-class:: classref-method -|vec_type| **clamp** ( |vec_type| x, |vec_type| min, |vec_type| max ) +|vec_uint_type| **floatBitsToUint** ( |vec_type| x ) - Returns the value of x constrained to the range minVal to maxVal. + Returns the encoding of the floating-point parameters as uint. - The returned value is computed as min(max(x, minVal), maxVal). + The floating-point bit-level representation is preserved. :param x: - the value to constrain. - - :param min: - the lower end of the range into which to constrain x. - - :param max: - the upper end of the range into which to constrain x. + the value whose floating point encoding to return. :return: - the constrained value. + the floating-point encoding of x. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/floatBitsToUint.xhtml .. rst-class:: classref-item-separator ---- -.. rst-class:: classref-method -|vec_type| **clamp** ( |vec_type| x, float min, float max ) - Returns the value of x constrained to the range minVal to maxVal. +.. _shader_func_intBitsToFloat: - The returned value is computed as min(max(x, minVal), maxVal). +.. rst-class:: classref-method - :param x: - the value to constrain. +|vec_type| **intBitsToFloat** ( |vec_int_type| x ) - :param min: - the lower end of the range into which to constrain x. + Converts a bit encoding to a floating-point value. Opposite of `floatBitsToInt<_shader_func_floatBitsToInt>` - :param max: - the upper end of the range into which to constrain x. + If the encoding of a NaN is passed in x, it will not signal and the resulting value will be undefined. + + If the encoding of a floating point infinity is passed in parameter x, the resulting floating-point value is + the corresponding (positive or negative) floating point infinity. + + :param x: + the bit encoding to return as a floating point value. :return: - the constrained value. + a floating point value - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/intBitsToFloat.xhtml .. rst-class:: classref-item-separator ---- -.. rst-class:: classref-method -|vec_uint_type| **clamp** ( |vec_int_type| x, |vec_int_type| min, |vec_int_type| max ) - Returns the value of x constrained to the range minVal to maxVal. +.. _shader_func_uintBitsToFloat: + +.. rst-class:: classref-method - The returned value is computed as min(max(x, minVal), maxVal). +|vec_type| **uintBitsToFloat** ( |vec_uint_type| x ) - :param x: - the value to constrain. + Converts a bit encoding to a floating-point value. Opposite of `floatBitsToUint<_shader_func_floatBitsToUint>` - :param min: - the lower end of the range into which to constrain x. + If the encoding of a NaN is passed in x, it will not signal and the resulting value will be undefined. - :param max: - the upper end of the range into which to constrain x. + If the encoding of a floating point infinity is passed in parameter x, the resulting floating-point value is + the corresponding (positive or negative) floating point infinity. + + :param x: + the bit encoding to return as a floating point value. :return: - the constrained value. + a floating point value - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/uintBitsToFloat.xhtml .. rst-class:: classref-item-separator ---- -.. rst-class:: classref-method - -|vec_uint_type| **clamp** ( |vec_int_type| x, float min, float max ) - Returns the value of x constrained to the range minVal to maxVal. - The returned value is computed as min(max(x, minVal), maxVal). - :param x: - the value to constrain. - :param min: - the lower end of the range into which to constrain x. - :param max: - the upper end of the range into which to constrain x. +Geometric Functions +^^^^^^^^^^^^^^^^^^^ - :return: - the constrained value. ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| float | :ref:`length` ( |vec_type| x ) | Vector length. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| float | :ref:`distance` ( |vec_type| a, |vec_type| b ) | Distance between vectors i.e ``length(a - b)``. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| float | :ref:`dot` ( |vec_type| a, |vec_type| b ) | Dot product. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| vec3 | :ref:`cross` (vec3 a, vec3 b ) | Cross product. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |vec_type| | :ref:`normalize` ( |vec_type| x ) | Normalize to unit length. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| vec3 | :ref:`reflect` (vec3 I, vec3 N ) | Reflect. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| vec3 | :ref:`refract` (vec3 I, vec3 N, float eta ) | Refract. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |vec_type| | :ref:`faceforward` (|vec_type| N, |vec_type| I, |vec_type| Nref )| If ``dot(Nref, I)`` < 0, return ``N``, otherwise ``-N``. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |mat_type| | :ref:`matrixCompMult` (|mat_type| x, |mat_type| y ) | Matrix component multiplication. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |mat_type| | :ref:`outerProduct` ( |vec_type| column, |vec_type| row ) | Matrix outer product. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |mat_type| | :ref:`transpose` (|mat_type| m ) | Transpose matrix. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| float | :ref:`determinant` (|mat_type| m ) | Matrix determinant. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +| |mat_type| | :ref:`inverse` (|mat_type| m ) | Inverse matrix. | ++------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml +.. rst-class:: classref-section-separator -.. rst-class:: classref-item-separator +---------- ----- +.. _shader_func_length: .. rst-class:: classref-method -|vec_int_type| **clamp** ( |vec_type| x, |vec_type| min, |vec_type| max ) - - Returns the value of x constrained to the range minVal to maxVal. +float **length** ( |vec_type| x ) - The returned value is computed as min(max(x, minVal), maxVal). + Returns the length of the vector. + ie. ``sqrt(x[0] * x[0] + x[1] * x[1] + ... + x[n] * x[n])`` :param x: - the value to constrain. - - :param min: - the lower end of the range into which to constrain x. - - :param max: - the upper end of the range into which to constrain x. + the vector :return: - the constrained value. + the length of the vector. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/length.xhtml .. rst-class:: classref-item-separator ---- -.. rst-class:: classref-method -|vec_int_type| **clamp** ( |vec_type| x, float min, float max ) - Returns the value of x constrained to the range minVal to maxVal. - The returned value is computed as min(max(x, minVal), maxVal). +.. _shader_func_distance: - :param x: - the value to constrain. +.. rst-class:: classref-method - :param min: - the lower end of the range into which to constrain x. +float **distance** ( |vec_type| a, |vec_type| b ) - :param max: - the upper end of the range into which to constrain x. + Returns the distance between the two points a and b. + + i.e., ``length(b - a);`` + + :param a: + the first point + + :param b: + the second point :return: - the constrained value. + the scalar distance between the points - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/clamp.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/distance.xhtml .. rst-class:: classref-item-separator @@ -1493,87 +1516,82 @@ vec_type pow( |vec_type| x, |vec_type| y) -.. _shader_func_mix: -.. rst-class:: classref-method +.. _shader_func_dot: -|vec_type| **mix** ( |vec_type| a, |vec_type| b, |vec_type| c ) +.. rst-class:: classref-method - Performs a linear interpolation between a and b using c to weight between them. +float **dot** ( |vec_type| a, |vec_type| b ) - computed as ``a × (1 − c) + b × c``. + Returns the dot product of two vectors, a and b. + i.e., ``a.x * b.x + a.y * b.y + ...`` :param a: - the start of the range in which to interpolate. + the first vector :param b: - the end of the range in which to interpolate. - - :param c: - the value to use to interpolate between x and y. + the second vector :return: - The interpolated value. + the dot product - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/mix.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/dot.xhtml .. rst-class:: classref-item-separator ---- + + + +.. _shader_func_cross: + .. rst-class:: classref-method -|vec_type| **mix** ( |vec_type| a, |vec_type| b, float c ) +vec3 **cross** ( vec3 a, vec3 b ) - Performs a linear interpolation between a and b using c to weight between them. + Returns the cross product of two vectors. + i.e.:: - computed as ``a × (1 − c) + b × c``. + vec2( a.y * b.z - b.y * a.z, + a.z * b.x - b.z * a.x, + a.x * b.z - b.x * a.y ) :param a: - the start of the range in which to interpolate. + the first vector :param b: - the end of the range in which to interpolate. - - :param c: - the value to use to interpolate between x and y. + the second vector :return: - The interpolated value. + the cross product - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/mix.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/cross.xhtml .. rst-class:: classref-item-separator ---- -.. rst-class:: classref-method -|vec_type| **mix** ( |vec_type| a, |vec_type| b, |vec_bool_type| c ) - Selects either value a or value b based on the value of c. - For a component of c that is false, the corresponding component of a is returned. - For a component of c that is true, the corresponding component of b is returned. - Components of a and b that are not selected are allowed to be invalid floating-point values and will have no effect on the results. - If a, b, and c are vector types the operation is performed component-wise. - ie. ``mix(vec2(42, 314), vec2(9.8, 6e23), vec_bool_type(true, false)))`` will return ``vec2(9.8, 314)``. +.. _shader_func_normalize: - :param a: - value returned when a is false. +.. rst-class:: classref-method - :param b: - value returned when a is true. +|vec_type| **normalize** ( |vec_type| x ) - :param c: - the value to use to interpolate between x and y. + Returns a vector with the same direction as x but with length 1. + + :param x: + the vector to normalize. :return: - The interpolated value. + the normalized vector. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/mix.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/normalize.xhtml .. rst-class:: classref-item-separator @@ -1582,38 +1600,30 @@ vec_type pow( |vec_type| x, |vec_type| y) -.. _shader_func_fma: - -.. rst-class:: classref-method - -|vec_type| **fma** ( |vec_type| a, |vec_type| b, |vec_type| c ) - Performs, where possible, a fused multiply-add operation, returning a * b + c. In use cases where the - return value is eventually consumed by a variable declared as precise: +.. _shader_func_reflect: - - fma() is considered a single operation, whereas the expression a * b + c consumed by a variable declared as precise is considered two operations. +.. rst-class:: classref-method - - The precision of fma() can differ from the precision of the expression a * b + c. +vec3 **reflect** ( vec3 I, vec3 N ) - - fma() will be computed with the same precision as any other fma() consumed by a precise variable, - giving invariant results for the same input values of a, b and c. + Calculate the reflection direction for an incident vector. - Otherwise, in the absence of precise consumption, there are no special constraints on the number of operations - or difference in precision between fma() and the expression a * b + c. + For a given incident vector I and surface normal N reflect returns the reflection direction calculated as ``I - 2.0 * dot(N, I) * N``. - :param a: - the first multiplicand. + .. Note:: + N should be normalized in order to achieve the desired result. - :param b: - the second multiplicand. + :param I: + the incident vector - :param c: - the value to be added to the result. + :param N: + the normal vector :return: - value of ``a * b + c`` + the reflection vector - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/fma.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/reflect.xhtml .. rst-class:: classref-item-separator @@ -1622,58 +1632,74 @@ vec_type pow( |vec_type| x, |vec_type| y) -.. _shader_func_step: + +.. _shader_func_refract: .. rst-class:: classref-method -|vec_type| **step** ( |vec_type| a, |vec_type| b ) +vec3 **refract** ( vec3 I, vec3 N, float eta ) - Generates a step function by comparing b to a. + Calculate the refraction direction for an incident vector. - Equivalent to ``if (b < a) { return 0.0; } else { return 1.0; }``. - Or if vec_type is a vector, a vector where the above operation has been performed on each component of the input vectors. - ie. ``step(vec2(4.2, 314), vec2(2.4, 980))`` would return ``vec2(step(a[0], b[0]), step(a[1], b[1]))``. + For a given incident vector I, surface normal N and ratio of indices of refraction, eta, refract returns the refraction vector, R. - For element i of the return value, 0.0 is returned if b[i] < a[i], and 1.0 is returned otherwise. + R is calculated as:: - :param a: - the location of the edge of the step function. + k = 1.0 - eta * eta * (1.0 - dot(N, I) * dot(N, I)); + if (k < 0.0) + R = genType(0.0); // or genDType(0.0) + else + R = eta * I - (eta * dot(N, I) + sqrt(k)) * N; - :param b: - the value to be used to generate the step function. + .. Note:: + The input parameters I and N should be normalized in order to achieve the desired result. + + :param I: + the incident vector. + + :param N: + the normal vector. + + :param eta: + the ratio of indices of refraction. :return: - 0.0 or 1.0 + the refraction vector. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/step.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/refract.xhtml .. rst-class:: classref-item-separator ---- + + + +.. _shader_func_faceforward: + .. rst-class:: classref-method -|vec_type| **step** ( float a, |vec_type| b ) +|vec_type| **faceforward** ( |vec_type| N, |vec_type| I, |vec_type| Nref ) - Generates a step function by comparing b to a. + Return a vector pointing in the same direction as another. - Equivalent to ``if (b < a) { return 0.0; } else { return 1.0; }``. - Or rather, the above operation will be performed on each component of the input vector. - ie. ``step(4.2, vec2(2.4, 980))`` would return the equivalent of ``vec2(step(42, b[0]), step(42, b[1]))``. + Orients a vector to point away from a surface as defined by its normal. + If ``dot(Nref, I) < 0`` faceforward returns ``N``, otherwise it returns ``-N``. - For element i of the return value, 0.0 is returned if b[i] < a[i], and 1.0 is returned otherwise. + :param N: + the vector to orient. - :param a: - the location of the edge of the step function. + :param I: + the incident vector. - :param b: - the value to be used to generate the step function. + :param Nref: + the reference vector. :return: - 0.0 or 1.0 + the oriented vector. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/step.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/faceforward.xhtml .. rst-class:: classref-item-separator @@ -1682,70 +1708,60 @@ vec_type pow( |vec_type| x, |vec_type| y) -.. _shader_func_smoothstep: - -.. rst-class:: classref-method - -|vec_type| **smoothstep** ( |vec_type| a, |vec_type| b, |vec_type| c ) - Performs smooth Hermite interpolation between 0 and 1 when a < c < b. - This is useful in cases where a threshold function with a smooth transition is desired. +.. _shader_func_matrixCompMult: - Smoothstep is equivalent to:: +.. rst-class:: classref-method - vec_type t; - t = clamp((c - a) / (b - a), 0.0, 1.0); - return t * t * (3.0 - 2.0 * t); +|mat_type| **matrixCompMult** ( |mat_type| x, |mat_type| y ) - Results are undefined if a ≥ b. + Perform a component-wise multiplication of two matrices. - :param a: - the value of the lower edge of the Hermite function. + Performs a component-wise multiplication of two matrices, yielding a result + matrix where each component, ``result[i][j]`` is computed as the scalar + product of ``x[i][j]`` and ``y[i][j]``. - :param b: - the value of the upper edge of the Hermite function. + :param x: + the first matrix multiplicand. - :param c: - the source value for interpolation. + :param y: + the second matrix multiplicand. :return: - the interpolated value + the resultant matrix. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/smoothstep.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/matrixCompMult.xhtml .. rst-class:: classref-item-separator ---- -.. rst-class:: classref-method -|vec_type| **smoothstep** ( float a, float b, |vec_type| c ) - Performs smooth Hermite interpolation between 0 and 1 when a < c < b. - This is useful in cases where a threshold function with a smooth transition is desired. - Smoothstep is equivalent to:: +.. _shader_func_outerProduct: - vec_type t; - t = clamp((c - a) / (b - a), 0.0, 1.0); - return t * t * (3.0 - 2.0 * t); +.. rst-class:: classref-method - Results are undefined if a ≥ b. +|mat_type| **outerProduct** ( |vec_type| column, |vec_type| row ) - :param a: - the value of the lower edge of the Hermite function. + Calculate the outer product of a pair of vectors. - :param b: - the value of the upper edge of the Hermite function. + Does a linear algebraic matrix multiply ``column * row``, yielding a matrix whose number of + rows is the number of components in ``column`` and whose number of columns is the number of + components in ``row``. - :param c: - the source value for interpolation. + :param column: + the column vector for multiplication. + + :param row: + the row vector for multiplication. :return: - the interpolated value + the outer product matrix. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/smoothstep.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/outerProduct.xhtml .. rst-class:: classref-item-separator @@ -1754,22 +1770,22 @@ vec_type pow( |vec_type| x, |vec_type| y) -.. _shader_func_isnan: + +.. _shader_func_transpose: .. rst-class:: classref-method -|vec_bool_type| **isnan** ( |vec_type| x ) +|mat_type| **transpose** ( |mat_type| m ) - For each element i of the result, returns true if x[i] is positive - or negative floating point NaN (Not a Number) and false otherwise. + Calculate the transpose of a matrix. - :param x: - the value to test for NaN. + :param m: + the matrix to transpose. :return: - true or false + a new matrix that is the transpose of the input matrix. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/isnan.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/transpose.xhtml .. rst-class:: classref-item-separator @@ -1778,22 +1794,22 @@ vec_type pow( |vec_type| x, |vec_type| y) -.. _shader_func_isinf: + +.. _shader_func_determinant: .. rst-class:: classref-method -|vec_bool_type| **isinf** ( |vec_type| x ) +float **determinant** ( |mat_type| m ) - For each element i of the result, returns true if x[i] is positive or negative - floating point infinity and false otherwise. + Calculate the determinant of a matrix. - :param x: - the value to test for infinity. + :param m: + the matrix. :return: - true or false + the determinant of the input matrix. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/isinf.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/determinant.xhtml .. rst-class:: classref-item-separator @@ -1802,23 +1818,24 @@ vec_type pow( |vec_type| x, |vec_type| y) -.. _shader_func_floatBitsToInt: + +.. _shader_func_inverse: .. rst-class:: classref-method -|vec_int_type| **floatBitsToInt** ( |vec_type| x ) +|mat_type| **inverse** ( |mat_type| m ) - Returns the encoding of the floating-point parameters as int. + Calculate the inverse of a matrix. - The floating-point bit-level representation is preserved. + The values in the returned matrix are undefined if m is singular or poorly-conditioned (nearly singular). - :param x: - the value whose floating point encoding to return. + :param m: + the matrix of which to take the inverse. :return: - the floating-point encoding of x. + a new matrix which is the inverse of the input matrix. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/floatBitsToInt.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/inverse.xhtml .. rst-class:: classref-item-separator @@ -1827,23 +1844,52 @@ vec_type pow( |vec_type| x, |vec_type| y) -.. _shader_func_floatBitsToUint: +Comparison Functions +^^^^^^^^^^^^^^^^^^^^ -.. rst-class:: classref-method ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`lessThan` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on < int/uint/float vectors. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`greaterThan` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on > int/uint/float vectors. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`lessThanEqual` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on <= int/uint/float vectors. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`greaterThanEqual` ( |vec_type| x, |vec_type| y )| Bool vector comparison on >= int/uint/float vectors. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`equal` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on == int/uint/float vectors. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`notEqual` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on != int/uint/float vectors. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| bool | :ref:`any` ( |vec_bool_type| x ) | ``true`` if any component is ``true``, ``false`` otherwise. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| bool | :ref:`all` ( |vec_bool_type| x ) | ``true`` if all components are ``true``, ``false`` otherwise. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +| |vec_bool_type| | :ref:`not` ( |vec_bool_type| x ) | Invert boolean vector. | ++-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -|vec_uint_type| **floatBitsToUint** ( |vec_type| x ) +.. rst-class:: classref-section-separator - Returns the encoding of the floating-point parameters as uint. +---- - The floating-point bit-level representation is preserved. + +.. _shader_func_lessThan: + +.. rst-class:: classref-method + +|vec_bool_type| **lessThan** ( |vec_type| x, |vec_type| y ) + + Perform a component-wise less-than comparison of two vectors. :param x: - the value whose floating point encoding to return. + the first vector for comparison. + + :param y: + the first vector for comparison. :return: - the floating-point encoding of x. + a boolean vector in which each element i is computed as ``x[i] < y[i]``. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/floatBitsToUint.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/lessThan.xhtml .. rst-class:: classref-item-separator @@ -1852,26 +1898,24 @@ vec_type pow( |vec_type| x, |vec_type| y) -.. _shader_func_intBitsToFloat: +.. _shader_func_greaterThan: .. rst-class:: classref-method -|vec_type| **intBitsToFloat** ( |vec_int_type| x ) - - Converts a bit encoding to a floating-point value. Opposite of `floatBitsToInt<_shader_func_floatBitsToInt>` - - If the encoding of a NaN is passed in x, it will not signal and the resulting value will be undefined. +|vec_bool_type| **greaterThan** ( |vec_type| x, |vec_type| y ) - If the encoding of a floating point infinity is passed in parameter x, the resulting floating-point value is - the corresponding (positive or negative) floating point infinity. + Perform a component-wise greater-than comparison of two vectors. :param x: - the bit encoding to return as a floating point value. + the first vector for comparison. + + :param y: + the first vector for comparison. :return: - a floating point value + a boolean vector in which each element i is computed as ``x[i] > y[i]``. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/intBitsToFloat.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/greaterThan.xhtml .. rst-class:: classref-item-separator @@ -1880,26 +1924,24 @@ vec_type pow( |vec_type| x, |vec_type| y) -.. _shader_func_uintBitsToFloat: +.. _shader_func_lessThanEqual: .. rst-class:: classref-method -|vec_type| **uintBitsToFloat** ( |vec_uint_type| x ) - - Converts a bit encoding to a floating-point value. Opposite of `floatBitsToUint<_shader_func_floatBitsToUint>` - - If the encoding of a NaN is passed in x, it will not signal and the resulting value will be undefined. +|vec_bool_type| **lessThanEqual** ( |vec_type| x, |vec_type| y ) - If the encoding of a floating point infinity is passed in parameter x, the resulting floating-point value is - the corresponding (positive or negative) floating point infinity. + Perform a component-wise less-than-or-equal comparison of two vectors. :param x: - the bit encoding to return as a floating point value. + the first vector for comparison. + + :param y: + the first vector for comparison. :return: - a floating point value + a boolean vector in which each element i is computed as ``x[i] ≤ y[i]``. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/uintBitsToFloat.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/lessThanEqual.xhtml .. rst-class:: classref-item-separator @@ -1908,118 +1950,24 @@ vec_type pow( |vec_type| x, |vec_type| y) - - - -Geometric Functions -^^^^^^^^^^^^^^^^^^^ - -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`length` ( |vec_type| x ) | Vector length. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`distance` ( |vec_type| a, |vec_type| b ) | Distance between vectors i.e ``length(a - b)``. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`dot` ( |vec_type| a, |vec_type| b ) | Dot product. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| vec3 | :ref:`cross` (vec3 a, vec3 b ) | Cross product. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |vec_type| | :ref:`normalize` ( |vec_type| x ) | Normalize to unit length. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| vec3 | :ref:`reflect` (vec3 I, vec3 N ) | Reflect. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| vec3 | :ref:`refract` (vec3 I, vec3 N, float eta ) | Refract. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |vec_type| | :ref:`faceforward` (|vec_type| N, |vec_type| I, |vec_type| Nref )| If ``dot(Nref, I)`` < 0, return ``N``, otherwise ``-N``. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`matrixCompMult` (|mat_type| x, |mat_type| y ) | Matrix component multiplication. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`outerProduct` ( |vec_type| column, |vec_type| row ) | Matrix outer product. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`transpose` (|mat_type| m ) | Transpose matrix. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`determinant` (|mat_type| m ) | Matrix determinant. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`inverse` (|mat_type| m ) | Inverse matrix. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ - -.. rst-class:: classref-section-separator - ----------- - - -.. _shader_func_length: +.. _shader_func_greaterThanEqual: .. rst-class:: classref-method -float **length** ( |vec_type| x ) +|vec_bool_type| **greaterThanEqual** ( |vec_type| x, |vec_type| y ) - Returns the length of the vector. - ie. ``sqrt(x[0] * x[0] + x[1] * x[1] + ... + x[n] * x[n])`` + Perform a component-wise greater-than-or-equal comparison of two vectors. :param x: - the vector - - :return: - the length of the vector. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/length.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - - -.. _shader_func_distance: - -.. rst-class:: classref-method - -float **distance** ( |vec_type| a, |vec_type| b ) - - Returns the distance between the two points a and b. - - i.e., ``length(b - a);`` - - :param a: - the first point - - :param b: - the second point - - :return: - the scalar distance between the points - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/distance.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - - -.. _shader_func_dot: - -.. rst-class:: classref-method - -float **dot** ( |vec_type| a, |vec_type| b ) - - Returns the dot product of two vectors, a and b. - i.e., ``a.x * b.x + a.y * b.y + ...`` - - :param a: - the first vector + the first vector for comparison. - :param b: - the second vector + :param y: + the first vector for comparison. :return: - the dot product + a boolean vector in which each element i is computed as ``x[i] ≥ y[i]``. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/dot.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/greaterThanEqual.xhtml .. rst-class:: classref-item-separator @@ -2028,30 +1976,24 @@ float **dot** ( |vec_type| a, |vec_type| b ) - -.. _shader_func_cross: +.. _shader_func_equal: .. rst-class:: classref-method -vec3 **cross** ( vec3 a, vec3 b ) - - Returns the cross product of two vectors. - i.e.:: +|vec_bool_type| **equal** ( |vec_type| x, |vec_type| y ) - vec2( a.y * b.z - b.y * a.z, - a.z * b.x - b.z * a.x, - a.x * b.z - b.x * a.y ) + Perform a component-wise equal-to comparison of two vectors. - :param a: - the first vector + :param x: + the first vector for comparison. - :param b: - the second vector + :param y: + the first vector for comparison. :return: - the cross product + a boolean vector in which each element i is computed as ``x[i] == y[i]``. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/cross.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/equal.xhtml .. rst-class:: classref-item-separator @@ -2060,22 +2002,24 @@ vec3 **cross** ( vec3 a, vec3 b ) - -.. _shader_func_normalize: +.. _shader_func_notEqual: .. rst-class:: classref-method -|vec_type| **normalize** ( |vec_type| x ) +|vec_bool_type| **notEqual** ( |vec_type| x, |vec_type| y ) - Returns a vector with the same direction as x but with length 1. + Perform a component-wise not-equal-to comparison of two vectors. :param x: - the vector to normalize. + the first vector for comparison. + + :param y: + the first vector for comparison. :return: - the normalized vector. + a boolean vector in which each element i is computed as ``x[i] != y[i]``. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/normalize.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/notEqual.xhtml .. rst-class:: classref-item-separator @@ -2084,30 +2028,32 @@ vec3 **cross** ( vec3 a, vec3 b ) - -.. _shader_func_reflect: +.. _shader_func_any: .. rst-class:: classref-method -vec3 **reflect** ( vec3 I, vec3 N ) - - Calculate the reflection direction for an incident vector. +bool **any** ( |vec_bool_type| x ) - For a given incident vector I and surface normal N reflect returns the reflection direction calculated as ``I - 2.0 * dot(N, I) * N``. + Check whether any element of a boolean vector is true. - .. Note:: - N should be normalized in order to achieve the desired result. + Functionally equivalent to:: - :param I: - the incident vector + bool any(bvec x) { // bvec can be bvec2, bvec3 or bvec4 + bool result = false; + int i; + for (i = 0; i < x.length(); ++i) { + result |= x[i]; + } + return result; + } - :param N: - the normal vector + :param x: + the vector to be tested for truth. :return: - the reflection vector + true if any element of x is true and false otherwise. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/reflect.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/any.xhtml .. rst-class:: classref-item-separator @@ -2116,41 +2062,34 @@ vec3 **reflect** ( vec3 I, vec3 N ) - -.. _shader_func_refract: +.. _shader_func_all: .. rst-class:: classref-method -vec3 **refract** ( vec3 I, vec3 N, float eta ) - - Calculate the refraction direction for an incident vector. - - For a given incident vector I, surface normal N and ratio of indices of refraction, eta, refract returns the refraction vector, R. - - R is calculated as:: - - k = 1.0 - eta * eta * (1.0 - dot(N, I) * dot(N, I)); - if (k < 0.0) - R = genType(0.0); // or genDType(0.0) - else - R = eta * I - (eta * dot(N, I) + sqrt(k)) * N; +bool **all** ( |vec_bool_type| x ) - .. Note:: - The input parameters I and N should be normalized in order to achieve the desired result. + Check whether all elements of a boolean vector are true. - :param I: - the incident vector. + Functionally equivalent to:: - :param N: - the normal vector. + bool all(bvec x) // bvec can be bvec2, bvec3 or bvec4 + { + bool result = true; + int i; + for (i = 0; i < x.length(); ++i) + { + result &= x[i]; + } + return result; + } - :param eta: - the ratio of indices of refraction. + :param x: + the vector to be tested for truth. :return: - the refraction vector. + true if all elements of x are true and false otherwise. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/refract.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/all.xhtml .. rst-class:: classref-item-separator @@ -2159,31 +2098,21 @@ vec3 **refract** ( vec3 I, vec3 N, float eta ) - -.. _shader_func_faceforward: +.. _shader_func_not: .. rst-class:: classref-method -|vec_type| **faceforward** ( |vec_type| N, |vec_type| I, |vec_type| Nref ) - - Return a vector pointing in the same direction as another. - - Orients a vector to point away from a surface as defined by its normal. - If ``dot(Nref, I) < 0`` faceforward returns ``N``, otherwise it returns ``-N``. - - :param N: - the vector to orient. +|vec_bool_type| **not** ( |vec_bool_type| x ) - :param I: - the incident vector. + Logically invert a boolean vector. - :param Nref: - the reference vector. + :param x: + the vector to be inverted. :return: - the oriented vector. + a new boolean vector for which each element i is computed as !x[i]. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/faceforward.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/not.xhtml .. rst-class:: classref-item-separator @@ -2192,1408 +2121,168 @@ vec3 **refract** ( vec3 I, vec3 N, float eta ) +Texture Functions +^^^^^^^^^^^^^^^^^ -.. _shader_func_matrixCompMult: - -.. rst-class:: classref-method - -|mat_type| **matrixCompMult** ( |mat_type| x, |mat_type| y ) - - Perform a component-wise multiplication of two matrices. - - Performs a component-wise multiplication of two matrices, yielding a result - matrix where each component, ``result[i][j]`` is computed as the scalar - product of ``x[i][j]`` and ``y[i][j]``. - - :param x: - the first matrix multiplicand. - - :param y: - the second matrix multiplicand. - - :return: - the resultant matrix. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/matrixCompMult.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - - -.. _shader_func_outerProduct: - -.. rst-class:: classref-method - -|mat_type| **outerProduct** ( |vec_type| column, |vec_type| row ) - - Calculate the outer product of a pair of vectors. - - Does a linear algebraic matrix multiply ``column * row``, yielding a matrix whose number of - rows is the number of components in ``column`` and whose number of columns is the number of - components in ``row``. - - :param column: - the column vector for multiplication. - - :param row: - the row vector for multiplication. - - :return: - the outer product matrix. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/outerProduct.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - - -.. _shader_func_transpose: - -.. rst-class:: classref-method - -|mat_type| **transpose** ( |mat_type| m ) - - Calculate the transpose of a matrix. - - :param m: - the matrix to transpose. - - :return: - a new matrix that is the transpose of the input matrix. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/transpose.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - - -.. _shader_func_determinant: - -.. rst-class:: classref-method - -float **determinant** ( |mat_type| m ) - - Calculate the determinant of a matrix. - - :param m: - the matrix. - - :return: - the determinant of the input matrix. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/determinant.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - - -.. _shader_func_inverse: - -.. rst-class:: classref-method - -|mat_type| **inverse** ( |mat_type| m ) - - Calculate the inverse of a matrix. - - The values in the returned matrix are undefined if m is singular or poorly-conditioned (nearly singular). - - :param m: - the matrix of which to take the inverse. - - :return: - a new matrix which is the inverse of the input matrix. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/inverse.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - -Comparison Functions -^^^^^^^^^^^^^^^^^^^^ - -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`lessThan` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on < int/uint/float vectors. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`greaterThan` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on > int/uint/float vectors. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`lessThanEqual` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on <= int/uint/float vectors. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`greaterThanEqual` ( |vec_type| x, |vec_type| y )| Bool vector comparison on >= int/uint/float vectors. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`equal` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on == int/uint/float vectors. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`notEqual` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on != int/uint/float vectors. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| bool | :ref:`any` ( |vec_bool_type| x ) | ``true`` if any component is ``true``, ``false`` otherwise. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| bool | :ref:`all` ( |vec_bool_type| x ) | ``true`` if all components are ``true``, ``false`` otherwise. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`not` ( |vec_bool_type| x ) | Invert boolean vector. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ - -.. rst-class:: classref-section-separator - ----- - - -.. _shader_func_lessThan: - -.. rst-class:: classref-method - -|vec_bool_type| **lessThan** ( |vec_type| x, |vec_type| y ) - - Perform a component-wise less-than comparison of two vectors. - - :param x: - the first vector for comparison. - - :param y: - the first vector for comparison. - - :return: - a boolean vector in which each element i is computed as ``x[i] < y[i]``. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/lessThan.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - -.. _shader_func_greaterThan: - -.. rst-class:: classref-method - -|vec_bool_type| **greaterThan** ( |vec_type| x, |vec_type| y ) - - Perform a component-wise greater-than comparison of two vectors. - - :param x: - the first vector for comparison. - - :param y: - the first vector for comparison. - - :return: - a boolean vector in which each element i is computed as ``x[i] > y[i]``. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/greaterThan.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - -.. _shader_func_lessThanEqual: - -.. rst-class:: classref-method - -|vec_bool_type| **lessThanEqual** ( |vec_type| x, |vec_type| y ) - - Perform a component-wise less-than-or-equal comparison of two vectors. - - :param x: - the first vector for comparison. - - :param y: - the first vector for comparison. - - :return: - a boolean vector in which each element i is computed as ``x[i] ≤ y[i]``. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/lessThanEqual.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - -.. _shader_func_greaterThanEqual: - -.. rst-class:: classref-method - -|vec_bool_type| **greaterThanEqual** ( |vec_type| x, |vec_type| y ) - - Perform a component-wise greater-than-or-equal comparison of two vectors. - - :param x: - the first vector for comparison. - - :param y: - the first vector for comparison. - - :return: - a boolean vector in which each element i is computed as ``x[i] ≥ y[i]``. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/greaterThanEqual.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - -.. _shader_func_equal: - -.. rst-class:: classref-method - -|vec_bool_type| **equal** ( |vec_type| x, |vec_type| y ) - - Perform a component-wise equal-to comparison of two vectors. - - :param x: - the first vector for comparison. - - :param y: - the first vector for comparison. - - :return: - a boolean vector in which each element i is computed as ``x[i] == y[i]``. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/equal.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - -.. _shader_func_notEqual: - -.. rst-class:: classref-method - -|vec_bool_type| **notEqual** ( |vec_type| x, |vec_type| y ) - - Perform a component-wise not-equal-to comparison of two vectors. - - :param x: - the first vector for comparison. - - :param y: - the first vector for comparison. - - :return: - a boolean vector in which each element i is computed as ``x[i] != y[i]``. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/notEqual.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - -.. _shader_func_any: - -.. rst-class:: classref-method - -bool **any** ( |vec_bool_type| x ) - - Check whether any element of a boolean vector is true. - - Functionally equivalent to:: - - bool any(bvec x) { // bvec can be bvec2, bvec3 or bvec4 - bool result = false; - int i; - for (i = 0; i < x.length(); ++i) { - result |= x[i]; - } - return result; - } - - :param x: - the vector to be tested for truth. - - :return: - true if any element of x is true and false otherwise. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/any.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - -.. _shader_func_all: - -.. rst-class:: classref-method - -bool **all** ( |vec_bool_type| x ) - - Check whether all elements of a boolean vector are true. - - Functionally equivalent to:: - - bool all(bvec x) // bvec can be bvec2, bvec3 or bvec4 - { - bool result = true; - int i; - for (i = 0; i < x.length(); ++i) - { - result &= x[i]; - } - return result; - } - - :param x: - the vector to be tested for truth. - - :return: - true if all elements of x are true and false otherwise. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/all.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - -.. _shader_func_not: - -.. rst-class:: classref-method - -|vec_bool_type| **not** ( |vec_bool_type| x ) - - Logically invert a boolean vector. - - :param x: - the vector to be inverted. - - :return: - a new boolean vector for which each element i is computed as !x[i]. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/not.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - -Texture Functions -^^^^^^^^^^^^^^^^^ - -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec2 | :ref:`textureSize` ( |gsampler2D| s, int lod ) | Get the size of a texture. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| ivec2 | :ref:`textureSize` (samplerCube s, int lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| ivec2 | :ref:`textureSize` (samplerCubeArray s, int lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| ivec3 | :ref:`textureSize` ( |gsampler2DArray| s, int lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| ivec3 | :ref:`textureSize` ( |gsampler3D| s, int lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec2 | :ref:`textureQueryLod` ( |gsampler2D| s, vec2 p ) | Compute the level-of-detail that would be used to sample from a | -+--------------+-----------------------------------------------------------------------------------------------------+ texture. | -| vec3 | :ref:`textureQueryLod` ( |gsampler2DArray| s, vec2 p ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec2 | :ref:`textureQueryLod` ( |gsampler3D| s, vec3 p ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec2 | :ref:`textureQueryLod` (samplerCube s, vec3 p ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| int | :ref:`textureQueryLevels` ( |gsampler2D| s ) | Get the number of accessible mipmap levels of a texture. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| int | :ref:`textureQueryLevels` ( |gsampler2DArray| s ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| int | :ref:`textureQueryLevels` ( |gsampler3D| s ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| int | :ref:`textureQueryLevels` (samplerCube s ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`texture` ( |gsampler2D| s, vec2 p [, float bias] ) | Perform a texture read. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`texture` ( |gsampler2DArray| s, vec3 p [, float bias] ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |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] ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |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] ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureProj` ( |gsampler3D| s, vec4 p [, float bias] ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureLod` ( |gsampler2D| s, vec2 p, float lod ) | Perform a texture read at custom mipmap. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureLod` ( |gsampler2DArray| s, vec3 p, float lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureLod` ( |gsampler3D| s, vec3 p, float lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureLod` (samplerCube s, vec3 p, float lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureLod` (samplerCubeArray s, vec4 p, float lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec3 p, float lod ) | Performs a texture read with projection/LOD. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec4 p, float lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureProjLod` ( |gsampler3D| s, vec4 p, float lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureGrad` ( |gsampler2D| s, vec2 p, vec2 dPdx, vec2 dPdy ) | Performs a texture read with explicit gradients. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureGrad` ( |gsampler2DArray| s, vec3 p, vec2 dPdx, vec2 dPdy ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureGrad` ( |gsampler3D| s, vec3 p, vec2 dPdx, vec2 dPdy ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureGrad` (samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureGrad` (samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy )| Performs a texture read with projection/LOD and with explicit | -+--------------+-----------------------------------------------------------------------------------------------------+ gradients. | -| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy )| | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy )| | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`texelFetch` ( |gsampler2D| s, ivec2 p, int lod ) | Fetches a single texel using integer coordinates. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`texelFetch` ( |gsampler2DArray| s, ivec3 p, int lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`texelFetch` ( |gsampler3D| s, ivec3 p, int lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureGather` ( |gsampler2D| s, vec2 p [, int comps] ) | Gathers four texels from a texture. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureGather` ( |gsampler2DArray| s, vec3 p [, int comps] ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureGather` (samplerCube s, vec3 p [, int comps] ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdx` ( |vec_type| p ) | Derivative with respect to ``x`` window coordinate, | -| | | automatic granularity. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdxCoarse` ( |vec_type| p ) | Derivative with respect to ``x`` window coordinate, | -| | | course granularity. | -| | | | -| | | Not available on ``gl_compatibility`` profile. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdxFine` ( |vec_type| p ) | Derivative with respect to ``x`` window coordinate, | -| | | fine granularity. | -| | | | -| | | Not available on ``gl_compatibility`` profile. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdy` ( |vec_type| p ) | Derivative with respect to ``y`` window coordinate. | -| | | Automatic granularity. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdyCoarse` ( |vec_type| p ) | Derivative with respect to ``y`` window coordinate, | -| | | course granularity. | -| | | | -| | | Not available on ``gl_compatibility`` profile. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdyFine` ( |vec_type| p ) | Derivative with respect to ``y`` window coordinate, | -| | | fine granularity. | -| | | | -| | | Not available on ``gl_compatibility`` profile. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`fwidth` ( |vec_type| p ) | Sum of absolute derivative in ``x`` and ``y``. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`fwidthCoarse` ( |vec_type| p ) | Sum of absolute derivative in ``x`` and ``y``. | -| | | | -| | | Not available on ``gl_compatibility`` profile. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`fwidthFine` ( |vec_type| p ) | Sum of absolute derivative in ``x`` and ``y``. | -| | | | -| | | Not available on ``gl_compatibility`` profile. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ - -.. rst-class:: classref-section-separator - ----- - - - - -.. _shader_func_textureSize: - -.. rst-class:: classref-method - -ivec2 **textureSize** ( |gsampler2D| s, int lod ) - - Retrieve the dimensions of a level of a texture. - - Returns the dimensions of level lod (if present) of the texture bound to sampler. - - The components in the return value are filled in, in order, with the width, height and depth - of the texture. For the array forms, the last component of the return value is - the number of layers in the texture array. - - :param s: - the sampler to which the texture whose dimensions to retrieve is bound. - - :param lod: - the level of the texture for which to retrieve the dimensions. - - :return: - the dimensions of level lod (if present) of the texture bound to sampler. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureSize.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -ivec2 **textureSize** ( samplerCube s, int lod ) - - Retrieve the dimensions of a level of a texture. - - Returns the dimensions of level lod (if present) of the texture bound to sampler. - - The components in the return value are filled in, in order, with the width, height and depth - of the texture. For the array forms, the last component of the return value is - the number of layers in the texture array. - - :param s: - the sampler to which the texture whose dimensions to retrieve is bound. - - :param lod: - the level of the texture for which to retrieve the dimensions. - - :return: - the dimensions of level lod (if present) of the texture bound to sampler. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureSize.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -ivec2 **textureSize** ( samplerCubeArray s, int lod ) - - Retrieve the dimensions of a level of a texture. - - Returns the dimensions of level lod (if present) of the texture bound to sampler. - - The components in the return value are filled in, in order, with the width, height and depth - of the texture. For the array forms, the last component of the return value is - the number of layers in the texture array. - - :param s: - the sampler to which the texture whose dimensions to retrieve is bound. - - :param lod: - the level of the texture for which to retrieve the dimensions. - - :return: - the dimensions of level lod (if present) of the texture bound to sampler. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureSize.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -ivec3 **textureSize** ( |gsampler2DArray| s, int lod ) - - Retrieve the dimensions of a level of a texture. - - Returns the dimensions of level lod (if present) of the texture bound to sampler. - - The components in the return value are filled in, in order, with the width, height and depth - of the texture. For the array forms, the last component of the return value is - the number of layers in the texture array. - - :param s: - the sampler to which the texture whose dimensions to retrieve is bound. - - :param lod: - the level of the texture for which to retrieve the dimensions. - - :return: - the dimensions of level lod (if present) of the texture bound to sampler. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureSize.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -ivec3 **textureSize** ( |gsampler3D| s, int lod ) - - Retrieve the dimensions of a level of a texture. - - Returns the dimensions of level lod (if present) of the texture bound to sampler. - - The components in the return value are filled in, in order, with the width, height and depth - of the texture. For the array forms, the last component of the return value is - the number of layers in the texture array. - - :param s: - the sampler to which the texture whose dimensions to retrieve is bound. - - :param lod: - the level of the texture for which to retrieve the dimensions. - - :return: - the dimensions of level lod (if present) of the texture bound to sampler. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureSize.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - -.. _shader_func_textureQueryLod: - -.. rst-class:: classref-method - -vec2 **textureQueryLod** ( |gsampler2D| s, vec2 p ) - - Compute the level-of-detail that would be used to sample from a texture. - - Available only in the fragment shader, textureQueryLod computes the level-of-detail - that would be used to sample from a texture. The mipmap array(s) that would be - accessed is returned in the x component of the return value. The computed level-of-detail - relative to the base level is returned in the y component of the return value. - - If called on an incomplete texture, the result of the operation is undefined. - - :param s: - the sampler to which the texture whose level-of-detail will be queried is bound. - - :param p: - the texture coordinates at which the level-of-detail will be queried. - - :return: - see description. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLod.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -vec3 **textureQueryLod** ( |gsampler2DArray| s, vec2 p ) - - Compute the level-of-detail that would be used to sample from a texture. - - Available only in the fragment shader, textureQueryLod computes the level-of-detail - that would be used to sample from a texture. The mipmap array(s) that would be - accessed is returned in the x component of the return value. The computed level-of-detail - relative to the base level is returned in the y component of the return value. - - If called on an incomplete texture, the result of the operation is undefined. - - :param s: - the sampler to which the texture whose level-of-detail will be queried is bound. - - :param p: - the texture coordinates at which the level-of-detail will be queried. - - :return: - see description. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLod.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -vec2 **textureQueryLod** ( |gsampler3D| s, vec3 p ) - - Compute the level-of-detail that would be used to sample from a texture. - - Available only in the fragment shader, textureQueryLod computes the level-of-detail - that would be used to sample from a texture. The mipmap array(s) that would be - accessed is returned in the x component of the return value. The computed level-of-detail - relative to the base level is returned in the y component of the return value. - - If called on an incomplete texture, the result of the operation is undefined. - - :param s: - the sampler to which the texture whose level-of-detail will be queried is bound. - - :param p: - the texture coordinates at which the level-of-detail will be queried. - - :return: - see description. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLod.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -vec2 **textureQueryLod** ( samplerCube s, vec3 p ) - - Compute the level-of-detail that would be used to sample from a texture. - - Available only in the fragment shader, textureQueryLod computes the level-of-detail - that would be used to sample from a texture. The mipmap array(s) that would be - accessed is returned in the x component of the return value. The computed level-of-detail - relative to the base level is returned in the y component of the return value. - - If called on an incomplete texture, the result of the operation is undefined. - - :param s: - the sampler to which the texture whose level-of-detail will be queried is bound. - - :param p: - the texture coordinates at which the level-of-detail will be queried. - - :return: - see description. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLod.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - -.. _shader_func_textureQueryLevels: - -.. rst-class:: classref-method - -int **textureQueryLevels** ( |gsampler2D| s ) - - Compute the number of accessible mipmap levels of a texture. - - If called on an incomplete texture, or if no texture is associated with sampler, zero is returned. - - :param s: - the sampler to which the texture whose mipmap level count will be queried is bound. - - :return: - the number of accessible mipmap levels in the texture, or zero. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLevels.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -int **textureQueryLevels** ( |gsampler2DArray| s ) - - Compute the number of accessible mipmap levels of a texture. - - If called on an incomplete texture, or if no texture is associated with sampler, zero is returned. - - :param s: - the sampler to which the texture whose mipmap level count will be queried is bound. - - :return: - the number of accessible mipmap levels in the texture, or zero. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLevels.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -int **textureQueryLevels** ( |gsampler3D| s ) - - Compute the number of accessible mipmap levels of a texture. - - If called on an incomplete texture, or if no texture is associated with sampler, zero is returned. - - :param s: - the sampler to which the texture whose mipmap level count will be queried is bound. - - :return: - the number of accessible mipmap levels in the texture, or zero. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLevels.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -int **textureQueryLevels** ( samplerCube s ) - - Compute the number of accessible mipmap levels of a texture. - - If called on an incomplete texture, or if no texture is associated with sampler, zero is returned. - - :param s: - the sampler to which the texture whose mipmap level count will be queried is bound. - - :return: - the number of accessible mipmap levels in the texture, or zero. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLevels.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - -.. _shader_func_texture: - -.. rst-class:: classref-method - -|gvec4_type| **texture** ( |gsampler2D| 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 - included in the level-of-detail computation that is used to choose mipmap(s) from which to sample. - - For shadow forms, the last component of ``p`` is used as Dsub and the array layer is specified in the second to last - component of ``p``. (The second component of ``p`` is unused for 1D shadow lookups.) - - For non-shadow variants, the array layer comes from the last component of P. - - :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param bias: - an optional bias to be applied during level-of-detail computation. - - :return: - a texel - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texture.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -|gvec4_type| **texture** ( |gsampler2DArray| s, vec3 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 - included in the level-of-detail computation that is used to choose mipmap(s) from which to sample. - - For shadow forms, the last component of ``p`` is used as Dsub and the array layer is specified in the second to last - component of ``p``. (The second component of ``p`` is unused for 1D shadow lookups.) - - For non-shadow variants, the array layer comes from the last component of P. - - :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param bias: - an optional bias to be applied during level-of-detail computation. - - :return: - a texel - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texture.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -|gvec4_type| **texture** ( |gsampler3D| s, vec3 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 - included in the level-of-detail computation that is used to choose mipmap(s) from which to sample. - - For shadow forms, the last component of ``p`` is used as Dsub and the array layer is specified in the second to last - component of ``p``. (The second component of ``p`` is unused for 1D shadow lookups.) - - For non-shadow variants, the array layer comes from the last component of P. - - :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param bias: - an optional bias to be applied during level-of-detail computation. - - :return: - a texel - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texture.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -vec4 **texture** ( samplerCube s, vec3 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 - included in the level-of-detail computation that is used to choose mipmap(s) from which to sample. - - For shadow forms, the last component of ``p`` is used as Dsub and the array layer is specified in the second to last - component of ``p``. (The second component of ``p`` is unused for 1D shadow lookups.) - - For non-shadow variants, the array layer comes from the last component of P. - - :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param bias: - an optional bias to be applied during level-of-detail computation. - - :return: - a texel - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texture.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -vec4 **texture** ( samplerCubeArray s, vec4 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 - included in the level-of-detail computation that is used to choose mipmap(s) from which to sample. - - For shadow forms, the last component of ``p`` is used as Dsub and the array layer is specified in the second to last - component of ``p``. (The second component of ``p`` is unused for 1D shadow lookups.) - - For non-shadow variants, the array layer comes from the last component of P. - - :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param bias: - an optional bias to be applied during level-of-detail computation. - - :return: - a texel - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texture.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - -.. _shader_func_textureProj: - -.. rst-class:: classref-method - -|gvec4_type| **textureProj** ( |gsampler2D| s, vec3 p [, float bias] ) - - Perform a texture lookup with projection. - - The texture coordinates consumed from ``p``, not including the last component of ``p``, are - divided by the last component of ``p``. The resulting 3rd component of ``p`` in the shadow - forms is used as Dref. After these values are computed, the texture lookup proceeds as in texture. - - :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param bias: - optional bias to be applied during level-of-detail computation. - - :return: - a texel - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProj.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -|gvec4_type| **textureProj** ( |gsampler2D| s, vec4 p [, float bias] ) - - Perform a texture lookup with projection. - - The texture coordinates consumed from ``p``, not including the last component of ``p``, are - divided by the last component of ``p``. The resulting 3rd component of ``p`` in the shadow - forms is used as Dref. After these values are computed, the texture lookup proceeds as in texture. - - :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param bias: - optional bias to be applied during level-of-detail computation. - - :return: - a texel - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProj.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -|gvec4_type| **textureProj** ( |gsampler3D| s, vec4 p [, float bias] ) - - Perform a texture lookup with projection. - - The texture coordinates consumed from ``p``, not including the last component of ``p``, are - divided by the last component of ``p``. The resulting 3rd component of ``p`` in the shadow - forms is used as Dref. After these values are computed, the texture lookup proceeds as in texture. - - :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param bias: - optional bias to be applied during level-of-detail computation. - - :return: - a texel - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProj.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - -.. _shader_func_textureLod: - -.. rst-class:: classref-method - -|gvec4_type| **textureLod** ( |gsampler2D| s, vec2 p, float lod ) - - Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with - an explicit level-of-detail as specified in ``lod``. ``lod`` specifies λbase and sets the - partial derivatives as follows:: - - δu/δx=0, δv/δx=0, δw/δx=0 - δu/δy=0, δv/δy=0, δw/δy=0 - - :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param lod: - the explicit level-of-detail - - :return: - a texel - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureLod.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -|gvec4_type| **textureLod** ( |gsampler2DArray| s, vec3 p, float lod ) - - Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with - an explicit level-of-detail as specified in ``lod``. ``lod`` specifies λbase and sets the - partial derivatives as follows:: - - δu/δx=0, δv/δx=0, δw/δx=0 - δu/δy=0, δv/δy=0, δw/δy=0 - - :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param lod: - the explicit level-of-detail - - :return: - a texel - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureLod.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -|gvec4_type| **textureLod** ( |gsampler3D| s, vec3 p, float lod ) - - Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with - an explicit level-of-detail as specified in ``lod``. ``lod`` specifies λbase and sets the - partial derivatives as follows:: - - δu/δx=0, δv/δx=0, δw/δx=0 - δu/δy=0, δv/δy=0, δw/δy=0 - - :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param lod: - the explicit level-of-detail - - :return: - a texel - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureLod.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -vec4 **textureLod** ( samplerCube s, vec3 p, float lod ) - - Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with - an explicit level-of-detail as specified in ``lod``. ``lod`` specifies λbase and sets the - partial derivatives as follows:: - - δu/δx=0, δv/δx=0, δw/δx=0 - δu/δy=0, δv/δy=0, δw/δy=0 - - :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param lod: - the explicit level-of-detail - - :return: - a texel - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureLod.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -vec4 **textureLod** ( samplerCubeArray s, vec4 p, float lod ) - - Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with - an explicit level-of-detail as specified in ``lod``. ``lod`` specifies λbase and sets the - partial derivatives as follows:: - - δu/δx=0, δv/δx=0, δw/δx=0 - δu/δy=0, δv/δy=0, δw/δy=0 - - :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param lod: - the explicit level-of-detail - - :return: - a texel - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureLod.xhtml - -.. rst-class:: classref-item-separator - ----- - - - - -.. _shader_func_textureProjLod: - -.. rst-class:: classref-method - -|gvec4_type| **textureProjLod** ( |gsampler2D| s, vec3 p, float lod ) - - Performs a texture lookup with projection from an explicitly specified level-of-detail. - - The texture coordinates consumed from P, not including the last component of ``p``, are - divided by the last component of ``p``. The resulting 3rd component of ``p`` in the shadow - forms is used as Dref. After these values are computed, the texture lookup proceeds as in - `textureLod`, with ``lod`` used to specify the level-of-detail from - which the texture will be sampled. - - :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param lod: - the explicit level-of-detail from which to fetch texels. - - :return: - a texel - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjLod.xhtml ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| ivec2 | :ref:`textureSize` ( |gsampler2D| s, int lod ) | Get the size of a texture. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| ivec2 | :ref:`textureSize` (samplerCube s, int lod ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| ivec2 | :ref:`textureSize` (samplerCubeArray s, int lod ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| ivec3 | :ref:`textureSize` ( |gsampler2DArray| s, int lod ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| ivec3 | :ref:`textureSize` ( |gsampler3D| s, int lod ) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| vec2 | :ref:`textureQueryLod` ( |gsampler2D| s, vec2 p ) | Compute the level-of-detail that would be used to sample from a | ++--------------+-----------------------------------------------------------------------------------------------------+ texture. | +| vec3 | :ref:`textureQueryLod` ( |gsampler2DArray| s, vec2 p ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec2 | :ref:`textureQueryLod` ( |gsampler3D| s, vec3 p ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec2 | :ref:`textureQueryLod` (samplerCube s, vec3 p ) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| int | :ref:`textureQueryLevels` ( |gsampler2D| s ) | Get the number of accessible mipmap levels of a texture. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| int | :ref:`textureQueryLevels` ( |gsampler2DArray| s ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| int | :ref:`textureQueryLevels` ( |gsampler3D| s ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| int | :ref:`textureQueryLevels` (samplerCube s ) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`texture` ( |gsampler2D| s, vec2 p [, float bias] ) | Perform a texture read. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`texture` ( |gsampler2DArray| s, vec3 p [, float bias] ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |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] ) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |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] ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureProj` ( |gsampler3D| s, vec4 p [, float bias] ) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`textureLod` ( |gsampler2D| s, vec2 p, float lod ) | Perform a texture read at custom mipmap. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureLod` ( |gsampler2DArray| s, vec3 p, float lod ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureLod` ( |gsampler3D| s, vec3 p, float lod ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec4 | :ref:`textureLod` (samplerCube s, vec3 p, float lod ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec4 | :ref:`textureLod` (samplerCubeArray s, vec4 p, float lod ) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec3 p, float lod ) | Performs a texture read with projection/LOD. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec4 p, float lod ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureProjLod` ( |gsampler3D| s, vec4 p, float lod ) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`textureGrad` ( |gsampler2D| s, vec2 p, vec2 dPdx, vec2 dPdy ) | Performs a texture read with explicit gradients. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureGrad` ( |gsampler2DArray| s, vec3 p, vec2 dPdx, vec2 dPdy ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureGrad` ( |gsampler3D| s, vec3 p, vec2 dPdx, vec2 dPdy ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec4 | :ref:`textureGrad` (samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec4 | :ref:`textureGrad` (samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy )| Performs a texture read with projection/LOD and with explicit | ++--------------+-----------------------------------------------------------------------------------------------------+ gradients. | +| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy )| | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy )| | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`texelFetch` ( |gsampler2D| s, ivec2 p, int lod ) | Fetches a single texel using integer coordinates. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`texelFetch` ( |gsampler2DArray| s, ivec3 p, int lod ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`texelFetch` ( |gsampler3D| s, ivec3 p, int lod ) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |gvec4_type| | :ref:`textureGather` ( |gsampler2D| s, vec2 p [, int comps] ) | Gathers four texels from a texture. | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| |gvec4_type| | :ref:`textureGather` ( |gsampler2DArray| s, vec3 p [, int comps] ) | | ++--------------+-----------------------------------------------------------------------------------------------------+ | +| vec4 | :ref:`textureGather` (samplerCube s, vec3 p [, int comps] ) | | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`dFdx` ( |vec_type| p ) | Derivative with respect to ``x`` window coordinate, | +| | | automatic granularity. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`dFdxCoarse` ( |vec_type| p ) | Derivative with respect to ``x`` window coordinate, | +| | | course granularity. | +| | | | +| | | Not available on ``gl_compatibility`` profile. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`dFdxFine` ( |vec_type| p ) | Derivative with respect to ``x`` window coordinate, | +| | | fine granularity. | +| | | | +| | | Not available on ``gl_compatibility`` profile. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`dFdy` ( |vec_type| p ) | Derivative with respect to ``y`` window coordinate. | +| | | Automatic granularity. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`dFdyCoarse` ( |vec_type| p ) | Derivative with respect to ``y`` window coordinate, | +| | | course granularity. | +| | | | +| | | Not available on ``gl_compatibility`` profile. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`dFdyFine` ( |vec_type| p ) | Derivative with respect to ``y`` window coordinate, | +| | | fine granularity. | +| | | | +| | | Not available on ``gl_compatibility`` profile. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`fwidth` ( |vec_type| p ) | Sum of absolute derivative in ``x`` and ``y``. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`fwidthCoarse` ( |vec_type| p ) | Sum of absolute derivative in ``x`` and ``y``. | +| | | | +| | | Not available on ``gl_compatibility`` profile. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ +| |vec_type| | :ref:`fwidthFine` ( |vec_type| p ) | Sum of absolute derivative in ``x`` and ``y``. | +| | | | +| | | Not available on ``gl_compatibility`` profile. | ++--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -.. rst-class:: classref-item-separator +.. rst-class:: classref-section-separator ---- -.. rst-class:: classref-method - -|gvec4_type| **textureProjLod** ( |gsampler2D| s, vec4 p, float lod ) - - Performs a texture lookup with projection from an explicitly specified level-of-detail. - - The texture coordinates consumed from P, not including the last component of ``p``, are - divided by the last component of ``p``. The resulting 3rd component of ``p`` in the shadow - forms is used as Dref. After these values are computed, the texture lookup proceeds as in - `textureLod`, with ``lod`` used to specify the level-of-detail from - which the texture will be sampled. - - :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param lod: - the explicit level-of-detail from which to fetch texels. - - :return: - a texel - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjLod.xhtml - -.. rst-class:: classref-item-separator ----- +.. _shader_func_textureSize: .. rst-class:: classref-method -|gvec4_type| **textureProjLod** ( |gsampler3D| s, vec4 p, float lod ) +| ivec2 **textureSize** ( |gsampler2D| s, int lod ) +| ivec2 **textureSize** ( samplerCube s, int lod ) +| ivec2 **textureSize** ( samplerCubeArray s, int lod ) +| ivec3 **textureSize** ( |gsampler2DArray| s, int lod ) +| ivec3 **textureSize** ( |gsampler3D| s, int lod ) - Performs a texture lookup with projection from an explicitly specified level-of-detail. + Retrieve the dimensions of a level of a texture. - The texture coordinates consumed from P, not including the last component of ``p``, are - divided by the last component of ``p``. The resulting 3rd component of ``p`` in the shadow - forms is used as Dref. After these values are computed, the texture lookup proceeds as in - `textureLod`, with ``lod`` used to specify the level-of-detail from - which the texture will be sampled. + Returns the dimensions of level lod (if present) of the texture bound to sampler. - :param s: - the sampler to which the texture from which texels will be retrieved is bound. + The components in the return value are filled in, in order, with the width, height and depth + of the texture. For the array forms, the last component of the return value is + the number of layers in the texture array. - :param p: - the texture coordinates at which texture will be sampled. + :param s: + the sampler to which the texture whose dimensions to retrieve is bound. :param lod: - the explicit level-of-detail from which to fetch texels. + the level of the texture for which to retrieve the dimensions. :return: - a texel + the dimensions of level lod (if present) of the texture bound to sampler. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjLod.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureSize.xhtml .. rst-class:: classref-item-separator @@ -3602,38 +2291,31 @@ vec4 **textureLod** ( samplerCubeArray s, vec4 p, float lod ) -.. _shader_func_textureGrad: +.. _shader_func_textureQueryLod: .. rst-class:: classref-method -|gvec4_type| **textureGrad** ( |gsampler2D| s, vec2 p, vec2 dPdx, vec2 dPdy ) +vec2 **textureQueryLod** ( |gsampler2D| s, vec2 p ) - Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with explicit texture coordinate gradiends as specified in ``dPdx`` and ``dPdy``. Set: - - ``δs/δx=δp/δx`` for a 1D texture, ``δp.s/δx`` otherwise - - ``δs/δy=δp/δy`` for a 1D texture, ``δp.s/δy`` otherwise - - ``δt/δx=0.0`` for a 1D texture, ``δp.t/δx`` otherwise - - ``δt/δy=0.0`` for a 1D texture, ``δp.t/δy`` otherwise - - ``δr/δx=0.0`` for a 1D or 2D texture, ``δp.p/δx`` otherwise - - ``δr/δy=0.0`` for a 1D or 2D texture, ``δp.p/δy`` otherwise + Compute the level-of-detail that would be used to sample from a texture. - For the cube version, the partial derivatives of ``p`` are assumed to be in the coordinate system used before texture coordinates are projected onto the appropriate cube face. + Available only in the fragment shader, textureQueryLod computes the level-of-detail + that would be used to sample from a texture. The mipmap array(s) that would be + accessed is returned in the x component of the return value. The computed level-of-detail + relative to the base level is returned in the y component of the return value. + + If called on an incomplete texture, the result of the operation is undefined. :param s: - the sampler to which the texture from which texels will be retrieved is bound. + the sampler to which the texture whose level-of-detail will be queried is bound. :param p: - the texture coordinates at which texture will be sampled. - - :param dPdx: - the partial derivative of P with respect to window x. - - :param dPdy: - the partial derivative of P with respect to window y. + the texture coordinates at which the level-of-detail will be queried. :return: - a texel + see description. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGrad.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLod.xhtml .. rst-class:: classref-item-separator @@ -3642,142 +2324,59 @@ vec4 **textureLod** ( samplerCubeArray s, vec4 p, float lod ) .. rst-class:: classref-method -|gvec4_type| **textureGrad** ( |gsampler2DArray| s, vec3 p, vec2 dPdx, vec2 dPdy ) - - Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with explicit texture coordinate gradiends as specified in ``dPdx`` and ``dPdy``. Set: - - ``δs/δx=δp/δx`` for a 1D texture, ``δp.s/δx`` otherwise - - ``δs/δy=δp/δy`` for a 1D texture, ``δp.s/δy`` otherwise - - ``δt/δx=0.0`` for a 1D texture, ``δp.t/δx`` otherwise - - ``δt/δy=0.0`` for a 1D texture, ``δp.t/δy`` otherwise - - ``δr/δx=0.0`` for a 1D or 2D texture, ``δp.p/δx`` otherwise - - ``δr/δy=0.0`` for a 1D or 2D texture, ``δp.p/δy`` otherwise - - For the cube version, the partial derivatives of ``p`` are assumed to be in the coordinate system used before texture coordinates are projected onto the appropriate cube face. - - :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param dPdx: - the partial derivative of P with respect to window x. - - :param dPdy: - the partial derivative of P with respect to window y. - - :return: - a texel - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGrad.xhtml - -.. rst-class:: classref-item-separator - ----- - +vec2 **textureQueryLod** ( |gsampler2D| s, vec2 p ) +vec2 **textureQueryLod** ( |gsampler2DArray| s, vec2 p ) +vec2 **textureQueryLod** ( |gsampler3D| s, vec3 p ) +vec2 **textureQueryLod** ( samplerCube s, vec3 p ) -.. rst-class:: classref-method + .. note:: Available only in the fragment shader. -|gvec4_type| **textureGrad** ( |gsampler3D| s, vec3 p, vec2 dPdx, vec2 dPdy ) + Compute the level-of-detail that would be used to sample from a texture. - Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with explicit texture coordinate gradiends as specified in ``dPdx`` and ``dPdy``. Set: - - ``δs/δx=δp/δx`` for a 1D texture, ``δp.s/δx`` otherwise - - ``δs/δy=δp/δy`` for a 1D texture, ``δp.s/δy`` otherwise - - ``δt/δx=0.0`` for a 1D texture, ``δp.t/δx`` otherwise - - ``δt/δy=0.0`` for a 1D texture, ``δp.t/δy`` otherwise - - ``δr/δx=0.0`` for a 1D or 2D texture, ``δp.p/δx`` otherwise - - ``δr/δy=0.0`` for a 1D or 2D texture, ``δp.p/δy`` otherwise + The mipmap array(s) that would be accessed is returned in the x component of + the return value. The computed level-of-detail relative to the base level is + returned in the y component of the return value. - For the cube version, the partial derivatives of ``p`` are assumed to be in the coordinate system used before texture coordinates are projected onto the appropriate cube face. + If called on an incomplete texture, the result of the operation is undefined. :param s: - the sampler to which the texture from which texels will be retrieved is bound. + the sampler to which the texture whose level-of-detail will be queried is bound. :param p: - the texture coordinates at which texture will be sampled. - - :param dPdx: - the partial derivative of P with respect to window x. - - :param dPdy: - the partial derivative of P with respect to window y. + the texture coordinates at which the level-of-detail will be queried. :return: - a texel + see description. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGrad.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLod.xhtml .. rst-class:: classref-item-separator ---- -.. rst-class:: classref-method - -vec4 **textureGrad** ( samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy ) - - Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with explicit texture coordinate gradiends as specified in ``dPdx`` and ``dPdy``. Set: - - ``δs/δx=δp/δx`` for a 1D texture, ``δp.s/δx`` otherwise - - ``δs/δy=δp/δy`` for a 1D texture, ``δp.s/δy`` otherwise - - ``δt/δx=0.0`` for a 1D texture, ``δp.t/δx`` otherwise - - ``δt/δy=0.0`` for a 1D texture, ``δp.t/δy`` otherwise - - ``δr/δx=0.0`` for a 1D or 2D texture, ``δp.p/δx`` otherwise - - ``δr/δy=0.0`` for a 1D or 2D texture, ``δp.p/δy`` otherwise - - For the cube version, the partial derivatives of ``p`` are assumed to be in the coordinate system used before texture coordinates are projected onto the appropriate cube face. - - :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param dPdx: - the partial derivative of P with respect to window x. - - :param dPdy: - the partial derivative of P with respect to window y. - :return: - a texel - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGrad.xhtml - -.. rst-class:: classref-item-separator - ----- +.. _shader_func_textureQueryLevels: .. rst-class:: classref-method -vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) +| int **textureQueryLevels** ( |gsampler2D| s ) +| int **textureQueryLevels** ( |gsampler2DArray| s ) +| int **textureQueryLevels** ( |gsampler3D| s ) +| int **textureQueryLevels** ( samplerCube s ) - Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with explicit texture coordinate gradiends as specified in ``dPdx`` and ``dPdy``. Set: - - ``δs/δx=δp/δx`` for a 1D texture, ``δp.s/δx`` otherwise - - ``δs/δy=δp/δy`` for a 1D texture, ``δp.s/δy`` otherwise - - ``δt/δx=0.0`` for a 1D texture, ``δp.t/δx`` otherwise - - ``δt/δy=0.0`` for a 1D texture, ``δp.t/δy`` otherwise - - ``δr/δx=0.0`` for a 1D or 2D texture, ``δp.p/δx`` otherwise - - ``δr/δy=0.0`` for a 1D or 2D texture, ``δp.p/δy`` otherwise + Compute the number of accessible mipmap levels of a texture. - For the cube version, the partial derivatives of ``p`` are assumed to be in the coordinate system used before texture coordinates are projected onto the appropriate cube face. + If called on an incomplete texture, or if no texture is associated with sampler, zero is returned. :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param dPdx: - the partial derivative of P with respect to window x. - - :param dPdy: - the partial derivative of P with respect to window y. + the sampler to which the texture whose mipmap level count will be queried is bound. :return: - a texel + the number of accessible mipmap levels in the texture, or zero. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGrad.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureQueryLevels.xhtml .. rst-class:: classref-item-separator @@ -3786,47 +2385,25 @@ vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) -.. _shader_func_textureProjGrad: +.. _shader_func_texture: .. rst-class:: classref-method -|gvec4_type| **textureProjGrad** ( |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy ) - - Perform a texture lookup with projection and explicit gradients. - - The texture coordinates consumed from ``p``, not including the last component of ``p``, are divided by the last component of ``p``. - After these values are computed, the texture lookup proceeds as in `textureGrad`, passing ``dPdx`` and ``dPdy`` as gradients. - - :param s: - the sampler to which the texture from which texels will be retrieved is bound. - - :param p: - the texture coordinates at which texture will be sampled. - - :param dPdx: - the partial derivative of ``p`` with respect to window x. - - :param dPdy: - the partial derivative of ``p`` with respect to window y. - - :return: - a texel. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjGrad.xhtml - -.. rst-class:: classref-item-separator - ----- - +| |gvec4_type| **texture** ( |gsampler2D| s, vec2 p [, float bias] ) +| |gvec4_type| **texture** ( |gsampler2DArray| s, vec3 p [, float bias] ) +| |gvec4_type| **texture** ( |gsampler3D| s, vec3 p [, float bias] ) +| vec4 **texture** ( samplerCube s, vec3 p [, float bias] ) +| vec4 **texture** ( samplerCubeArray s, vec4 p [, float bias] ) -.. rst-class:: classref-method + Retrieves texels from a texture. -|gvec4_type| **textureProjGrad** ( |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy ) + Samples texels from the texture bound to ``s`` at texture coordinate ``p``. An optional bias, specified in ``bias`` is + included in the level-of-detail computation that is used to choose mipmap(s) from which to sample. - Perform a texture lookup with projection and explicit gradients. + For shadow forms, the last component of ``p`` is used as Dsub and the array layer is specified in the second to last + component of ``p``. (The second component of ``p`` is unused for 1D shadow lookups.) - The texture coordinates consumed from ``p``, not including the last component of ``p``, are divided by the last component of ``p``. - After these values are computed, the texture lookup proceeds as in `textureGrad`, passing ``dPdx`` and ``dPdy`` as gradients. + For non-shadow variants, the array layer comes from the last component of P. :param s: the sampler to which the texture from which texels will be retrieved is bound. @@ -3834,30 +2411,34 @@ vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) :param p: the texture coordinates at which texture will be sampled. - :param dPdx: - the partial derivative of ``p`` with respect to window x. - - :param dPdy: - the partial derivative of ``p`` with respect to window y. + :param bias: + an optional bias to be applied during level-of-detail computation. :return: - a texel. + a texel - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjGrad.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texture.xhtml .. rst-class:: classref-item-separator ---- + + +.. _shader_func_textureProj: + .. rst-class:: classref-method -|gvec4_type| **textureProjGrad** ( |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy ) +| |gvec4_type| **textureProj** ( |gsampler2D| s, vec3 p [, float bias] ) +| |gvec4_type| **textureProj** ( |gsampler2D| s, vec4 p [, float bias] ) +| |gvec4_type| **textureProj** ( |gsampler3D| s, vec4 p [, float bias] ) - Perform a texture lookup with projection and explicit gradients. + Perform a texture lookup with projection. - The texture coordinates consumed from ``p``, not including the last component of ``p``, are divided by the last component of ``p``. - After these values are computed, the texture lookup proceeds as in `textureGrad`, passing ``dPdx`` and ``dPdy`` as gradients. + The texture coordinates consumed from ``p``, not including the last component of ``p``, are + divided by the last component of ``p``. The resulting 3rd component of ``p`` in the shadow + forms is used as Dref. After these values are computed, the texture lookup proceeds as in texture. :param s: the sampler to which the texture from which texels will be retrieved is bound. @@ -3865,16 +2446,13 @@ vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) :param p: the texture coordinates at which texture will be sampled. - :param dPdx: - the partial derivative of ``p`` with respect to window x. - - :param dPdy: - the partial derivative of ``p`` with respect to window y. + :param bias: + optional bias to be applied during level-of-detail computation. :return: - a texel. + a texel - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjGrad.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProj.xhtml .. rst-class:: classref-item-separator @@ -3883,13 +2461,22 @@ vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) -.. _shader_func_texelFetch: +.. _shader_func_textureLod: .. rst-class:: classref-method -|gvec4_type| **texelFetch** ( |gsampler2D| s, ivec2 p, int lod ) +| |gvec4_type| **textureLod** ( |gsampler2D| s, vec2 p, float lod ) +| |gvec4_type| **textureLod** ( |gsampler2DArray| s, vec3 p, float lod ) +| |gvec4_type| **textureLod** ( |gsampler3D| s, vec3 p, float lod ) +| vec4 **textureLod** ( samplerCube s, vec3 p, float lod ) +| vec4 **textureLod** ( samplerCubeArray s, vec4 p, float lod ) - Performs a lookup of a single texel from texture coordinate ``p`` in the texture bound to sampler. + Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with + an explicit level-of-detail as specified in ``lod``. ``lod`` specifies λbase and sets the + partial derivatives as follows:: + + δu/δx=0, δv/δx=0, δw/δx=0 + δu/δy=0, δv/δy=0, δw/δy=0 :param s: the sampler to which the texture from which texels will be retrieved is bound. @@ -3898,50 +2485,76 @@ vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) the texture coordinates at which texture will be sampled. :param lod: - specifies the level-of-detail within the texture from which the texel will be fetched. + the explicit level-of-detail :return: a texel - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texelFetch.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureLod.xhtml .. rst-class:: classref-item-separator ---- + + +.. _shader_func_textureProjLod: + .. rst-class:: classref-method -|gvec4_type| **texelFetch** ( |gsampler2DArray| s, ivec3 p, int lod ) +|gvec4_type| **textureProjLod** ( |gsampler2D| s, vec3 p, float lod ) +|gvec4_type| **textureProjLod** ( |gsampler2D| s, vec4 p, float lod ) +|gvec4_type| **textureProjLod** ( |gsampler3D| s, vec4 p, float lod ) - Performs a lookup of a single texel from texture coordinate ``p`` in the texture bound to sampler. + Performs a texture lookup with projection from an explicitly specified level-of-detail. - The array layer is specified in the last component of P for array forms. + The texture coordinates consumed from P, not including the last component of ``p``, are + divided by the last component of ``p``. The resulting 3rd component of ``p`` in the shadow + forms is used as Dref. After these values are computed, the texture lookup proceeds as in + `textureLod`, with ``lod`` used to specify the level-of-detail from + which the texture will be sampled. :param s: the sampler to which the texture from which texels will be retrieved is bound. :param p: - the texture coordinates at which texture will be sampled. ``p.z`` specifies which layer of ``s`` is fetched. + the texture coordinates at which texture will be sampled. :param lod: - specifies the level-of-detail within the texture from which the texel will be fetched. + the explicit level-of-detail from which to fetch texels. :return: - a texel + a texel - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texelFetch.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjLod.xhtml .. rst-class:: classref-item-separator ---- + + +.. _shader_func_textureGrad: + .. rst-class:: classref-method -|gvec4_type| **texelFetch** ( |gsampler3D| s, ivec3 p, int lod ) +| |gvec4_type| **textureGrad** ( |gsampler2D| s, vec2 p, vec2 dPdx, vec2 dPdy ) +| |gvec4_type| **textureGrad** ( |gsampler2DArray| s, vec3 p, vec2 dPdx, vec2 dPdy ) +| |gvec4_type| **textureGrad** ( |gsampler3D| s, vec3 p, vec2 dPdx, vec2 dPdy ) +| vec4 **textureGrad** ( samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy ) +| vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) - Performs a lookup of a single texel from texture coordinate ``p`` in the texture bound to sampler. + Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with explicit texture coordinate gradiends as specified in ``dPdx`` and ``dPdy``. Set: + - ``δs/δx=δp/δx`` for a 1D texture, ``δp.s/δx`` otherwise + - ``δs/δy=δp/δy`` for a 1D texture, ``δp.s/δy`` otherwise + - ``δt/δx=0.0`` for a 1D texture, ``δp.t/δx`` otherwise + - ``δt/δy=0.0`` for a 1D texture, ``δp.t/δy`` otherwise + - ``δr/δx=0.0`` for a 1D or 2D texture, ``δp.p/δx`` otherwise + - ``δr/δy=0.0`` for a 1D or 2D texture, ``δp.p/δy`` otherwise + + For the cube version, the partial derivatives of ``p`` are assumed to be in the coordinate system used before texture coordinates are projected onto the appropriate cube face. :param s: the sampler to which the texture from which texels will be retrieved is bound. @@ -3949,13 +2562,16 @@ vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) :param p: the texture coordinates at which texture will be sampled. - :param lod: - specifies the level-of-detail within the texture from which the texel will be fetched. + :param dPdx: + the partial derivative of P with respect to window x. + + :param dPdy: + the partial derivative of P with respect to window y. :return: a texel - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texelFetch.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGrad.xhtml .. rst-class:: classref-item-separator @@ -3964,20 +2580,18 @@ vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) -.. _shader_func_textureGather: +.. _shader_func_textureProjGrad: .. rst-class:: classref-method -|gvec4_type| **textureGather** ( |gsampler2D| s, vec2 p [, int comps] ) - - Gathers four texels from a texture. +| |gvec4_type| **textureProjGrad** ( |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy ) +| |gvec4_type| **textureProjGrad** ( |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy ) +| |gvec4_type| **textureProjGrad** ( |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy ) - Returns the value:: + Perform a texture lookup with projection and explicit gradients. - vec4(Sample_i0_j1(p, base).comps, - Sample_i1_j1(p, base).comps, - Sample_i1_j0(p, base).comps, - Sample_i0_j0(p, base).comps); + The texture coordinates consumed from ``p``, not including the last component of ``p``, are divided by the last component of ``p``. + After these values are computed, the texture lookup proceeds as in `textureGrad`, passing ``dPdx`` and ``dPdy`` as gradients. :param s: the sampler to which the texture from which texels will be retrieved is bound. @@ -3985,31 +2599,33 @@ vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) :param p: the texture coordinates at which texture will be sampled. - :param comps: - *optional* the component of the source texture (0 -> x, 1 -> y, 2 -> z, 3 -> w) that will be used to generate the resulting vector. Zero if not specified. + :param dPdx: + the partial derivative of ``p`` with respect to window x. + + :param dPdy: + the partial derivative of ``p`` with respect to window y. :return: - the gathered texel. + a texel. - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGather.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureProjGrad.xhtml .. rst-class:: classref-item-separator ---- -.. rst-class:: classref-method -|gvec4_type| **textureGather** ( |gsampler2DArray| s, vec3 p [, int comps] ) - Gathers four texels from a texture. +.. _shader_func_texelFetch: - Returns the value:: +.. rst-class:: classref-method - vec4(Sample_i0_j1(p, base).comps, - Sample_i1_j1(p, base).comps, - Sample_i1_j0(p, base).comps, - Sample_i0_j0(p, base).comps); +| |gvec4_type| **texelFetch** ( |gsampler2D| s, ivec2 p, int lod ) +| |gvec4_type| **texelFetch** ( |gsampler2DArray| s, ivec3 p, int lod ) +| |gvec4_type| **texelFetch** ( |gsampler3D| s, ivec3 p, int lod ) + + Performs a lookup of a single texel from texture coordinate ``p`` in the texture bound to sampler. :param s: the sampler to which the texture from which texels will be retrieved is bound. @@ -4017,22 +2633,28 @@ vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) :param p: the texture coordinates at which texture will be sampled. - :param comps: - *optional* the component of the source texture (0 -> x, 1 -> y, 2 -> z, 3 -> w) that will be used to generate the resulting vector. Zero if not specified. + :param lod: + specifies the level-of-detail within the texture from which the texel will be fetched. :return: - the gathered texel. + a texel - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/textureGather.xhtml + https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/texelFetch.xhtml .. rst-class:: classref-item-separator ---- + + +.. _shader_func_textureGather: + .. rst-class:: classref-method -vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) +| |gvec4_type| **textureGather** ( |gsampler2D| s, vec2 p [, int comps] ) +| |gvec4_type| **textureGather** ( |gsampler2DArray| s, vec3 p [, int comps] ) +| vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) Gathers four texels from a texture. @@ -4816,45 +3438,8 @@ Bitwise operations .. rst-class:: classref-method -|vec_int_type| **bitfieldInsert** ( |vec_int_type| base, |vec_int_type| insert, int offset, int bits ) - - Inserts the ``bits`` least significant bits of ``insert`` into ``base`` at offset ``offset``. - - The returned value will have bits [offset, offset + bits + 1] taken from [0, bits - 1] of ``insert`` and - all other bits taken directly from the corresponding bits of base. - - .. note:: If bits is zero, the result will simply be the original value of base. - - .. warning:: - The result will be undefined if: - - offset or bits is negative - - if the sum of offset and bits is greater than the number of bits used to store the operand. - - :param base: - the integer into which to insert ``insert``. - - :param insert: - the value of the bits to insert. - - :param offset: - the index of the first bit to insert. - - :param bits: - the number of bits to insert. - - :return: - ``base`` with inserted bits. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitfieldInsert.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -|vec_uint_type| **bitfieldInsert** ( |vec_uint_type| base, |vec_uint_type| insert, int offset, int bits ) +| |vec_int_type| **bitfieldInsert** ( |vec_int_type| base, |vec_int_type| insert, int offset, int bits ) +| |vec_uint_type| **bitfieldInsert** ( |vec_uint_type| base, |vec_uint_type| insert, int offset, int bits ) Inserts the ``bits`` least significant bits of ``insert`` into ``base`` at offset ``offset``. @@ -4896,28 +3481,8 @@ Bitwise operations .. rst-class:: classref-method -|vec_int_type| **bitfieldReverse** ( |vec_int_type| value ) - - Reverse the order of bits in an integer. - - The bit numbered n will be taken from bit (bits - 1) - n of ``value``, where bits is the total number of bits used to represent ``value``. - - :param value: - the value whose bits to reverse. - - :return: - ``value`` but with its bits reversed. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitfieldReverse.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -|vec_uint_type| **bitfieldReverse** ( |vec_uint_type| value ) +| |vec_int_type| **bitfieldReverse** ( |vec_int_type| value ) +| |vec_uint_type| **bitfieldReverse** ( |vec_uint_type| value ) Reverse the order of bits in an integer. @@ -4942,26 +3507,8 @@ Bitwise operations .. rst-class:: classref-method -|vec_int_type| **bitCount** ( |vec_int_type| value ) - - Counts the number of 1 bits in an integer. - - :param value: - the value whose bits to count. - - :return: - the number of bits that are set to 1 in the binary representation of ``value``. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/bitCount.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -|vec_uint_type| **bitCount** ( |vec_uint_type| value ) +| |vec_int_type| **bitCount** ( |vec_int_type| value ) +| |vec_uint_type| **bitCount** ( |vec_uint_type| value ) Counts the number of 1 bits in an integer. @@ -4984,28 +3531,8 @@ Bitwise operations .. rst-class:: classref-method -|vec_int_type| **findLSB** ( |vec_int_type| value ) - - Find the index of the least significant bit set to 1. - - .. note:: If ``value`` is zero, -1 will be returned. - - :param value: - the value whose bits to scan. - - :return: - the bit number of the least significant bit that is set to 1 in the binary representation of value. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/findLSB.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -|vec_uint_type| **findLSB** ( |vec_uint_type| value ) +| |vec_int_type| **findLSB** ( |vec_int_type| value ) +| |vec_uint_type| **findLSB** ( |vec_uint_type| value ) Find the index of the least significant bit set to 1. @@ -5031,34 +3558,15 @@ Bitwise operations .. rst-class:: classref-method |vec_int_type| **findMSB** ( |vec_int_type| value ) - - Find the index of the most significant bit set to 1. - - For positive integers, the result will be the bit number of the most significant bit that is set to 1. - - For negative integers, the result will be the bit number of the most significant bit set to 0. - - .. note:: For a value of zero or negative 1, -1 will be returned. - - :param value: - the value whose bits to scan. - - :return: - the bit number of the most significant bit that is set to 1 in the binary representation of value. - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/findMSB.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - |vec_uint_type| **findMSB** ( |vec_uint_type| value ) Find the index of the most significant bit set to 1. + .. note:: + For signed integer types, the sign bit is checked first and then: + - For positive integers, the result will be the bit number of the most significant bit that is set to 1. + - For negative integers, the result will be the bit number of the most significant bit set to 0. + .. note:: For a value of zero or negative 1, -1 will be returned. :param value: From 5042d00c7fd8a4c10a0669205851adcfec6e168d Mon Sep 17 00:00:00 2001 From: ashbygeek Date: Thu, 4 Jul 2024 23:49:09 -0400 Subject: [PATCH 15/25] Fix two hyperlinks --- .../shaders/shader_reference/shader_functions.rst | 2 +- .../shaders/shader_reference/shading_language.rst | 13 +++++++++++++ 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index 16c7aa1e799..3bc8af4ae68 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -39,7 +39,7 @@ GLSL 4.00 specification. For example, the operation ``vec2(3, 4) * vec2(10, 20)`` would result in ``vec2(3 * 10, 4 * 20)``. or the operation ``min(vec2(3, 4), vec2(1, 8))`` would result in ``vec2(min(3, 1), min(4, 8))``. - The `GLSL Language Specification ` says under section 5.10 Vector and Matrix Operations: + The `GLSL Language Specification `_ says under section 5.10 Vector and Matrix Operations: With a few exceptions, operations are component-wise. Usually, when an operator operates on a vector or matrix, it is operating independently on each component of the vector or matrix, diff --git a/tutorials/shaders/shader_reference/shading_language.rst b/tutorials/shaders/shader_reference/shading_language.rst index 47a2635f833..010daf2f830 100644 --- a/tutorials/shaders/shader_reference/shading_language.rst +++ b/tutorials/shaders/shader_reference/shading_language.rst @@ -85,6 +85,19 @@ Most GLSL ES 3.0 datatypes are supported: | **samplerCubeArray** | Sampler type for binding Cubemap arrays, which are read as float. | +----------------------+---------------------------------------------------------------------------------+ +.. note:: + Most operations on vectors (multiplication, division, etc) are performed component-wise. + For example, the operation ``vec2(3, 4) * vec2(10, 20)`` would result in ``vec2(3 * 10, 4 * 20)``. + or the operation ``min(vec2(3, 4), vec2(1, 8))`` would result in ``vec2(min(3, 1), min(4, 8))``. + + The `GLSL Language Specification `_ says under section 5.10 Vector and Matrix Operations: + + With a few exceptions, operations are component-wise. Usually, when an operator operates on a + vector or matrix, it is operating independently on each component of the vector or matrix, + in a component-wise fashion. [...] The exceptions are matrix multiplied by vector, + vector multiplied by matrix, and matrix multiplied by matrix. These do not operate component-wise, + but rather perform the correct linear algebraic multiply. + Comments ~~~~~~~~ From cb3ee13287ed43bd99e8fe4713fecad9e7a80345 Mon Sep 17 00:00:00 2001 From: Daniel Ashby Date: Wed, 7 Aug 2024 15:40:09 -0400 Subject: [PATCH 16/25] Update tutorials/shaders/shader_reference/shader_functions.rst Co-authored-by: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com> --- tutorials/shaders/shader_reference/shader_functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index 3bc8af4ae68..05f563fe1c1 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -37,7 +37,7 @@ GLSL 4.00 specification. .. note:: Most operations on vectors (multiplication, division, etc) are performed component-wise. For example, the operation ``vec2(3, 4) * vec2(10, 20)`` would result in ``vec2(3 * 10, 4 * 20)``. - or the operation ``min(vec2(3, 4), vec2(1, 8))`` would result in ``vec2(min(3, 1), min(4, 8))``. + Or the operation ``min(vec2(3, 4), vec2(1, 8))`` would result in ``vec2(min(3, 1), min(4, 8))``. The `GLSL Language Specification `_ says under section 5.10 Vector and Matrix Operations: From cc797b05ac061f582ba09e8a897497e9d72a60c0 Mon Sep 17 00:00:00 2001 From: Daniel Ashby Date: Fri, 13 Sep 2024 09:44:01 -0400 Subject: [PATCH 17/25] Update tutorials/shaders/shader_reference/shader_functions.rst Co-authored-by: tetrapod <145553014+tetrapod00@users.noreply.github.com> --- tutorials/shaders/shader_reference/shader_functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index 05f563fe1c1..d3a593783f4 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -3400,7 +3400,7 @@ Bitwise operations |vec_uint_type| **bitfieldExtract** ( |vec_uint_type| value, int offset, int bits ) - Eextracts a subset of the bits of value and returns it in the least significant bits of the result. + Extracts a subset of the bits of value and returns it in the least significant bits of the result. The range of bits extracted is ``[offset, offset + bits - 1]``. The most significant bits will be set to the value of ``offset + base - 1`` (i.e., it is sign extended to the width of the return type). From 3247c9cefc8619b8dbd3df4ff5a85210c5ffdf62 Mon Sep 17 00:00:00 2001 From: Daniel Ashby Date: Fri, 13 Sep 2024 09:44:11 -0400 Subject: [PATCH 18/25] Update tutorials/shaders/shader_reference/shader_functions.rst Co-authored-by: tetrapod <145553014+tetrapod00@users.noreply.github.com> --- tutorials/shaders/shader_reference/shader_functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index d3a593783f4..2be2627dcc5 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -819,7 +819,7 @@ vec_type pow( |vec_type| x, |vec_type| y) |vec_type| **roundEven** ( |vec_type| x ) - returns a value equal to the nearest integer to x. + Returns a value equal to the nearest integer to x. The fractional part of 0.5 will round toward the nearest even integer. For example, both 3.5 and 4.5 will round to 4.0. From f084d80897afc057b447d97438f3337cb5297a4b Mon Sep 17 00:00:00 2001 From: Daniel Ashby Date: Fri, 13 Sep 2024 09:45:34 -0400 Subject: [PATCH 19/25] Update tutorials/shaders/shader_reference/shader_functions.rst Co-authored-by: tetrapod <145553014+tetrapod00@users.noreply.github.com> --- tutorials/shaders/shader_reference/shader_functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index 2be2627dcc5..f96ba1f4b75 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -3364,7 +3364,7 @@ Bitwise operations |vec_int_type| **bitfieldExtract** ( |vec_int_type| value, int offset, int bits ) - Eextracts a subset of the bits of value and returns it in the least significant bits of the result. + Extracts a subset of the bits of value and returns it in the least significant bits of the result. The range of bits extracted is ``[offset, offset + bits - 1]``. The most significant bits of the result will be set to zero. From f10efe27b5e3bcb7331e564ce22723370f6fb207 Mon Sep 17 00:00:00 2001 From: Daniel Ashby Date: Fri, 13 Sep 2024 09:48:11 -0400 Subject: [PATCH 20/25] Fix Typo --- tutorials/shaders/shader_reference/shader_functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index f96ba1f4b75..486e88e71a7 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -143,7 +143,7 @@ vec_type sin( |vec_type| angle) Return the sine of the parameter. :param angle: - takehe quantity, in radians, of which to return the sine + the quantity, in radians, of which to return the sine :return: the trigonometric sine of ``angle``. From 87c01b16107d2f6e6261143072e54d4e990eae2c Mon Sep 17 00:00:00 2001 From: ashbygeek Date: Thu, 19 Sep 2024 14:18:10 -0400 Subject: [PATCH 21/25] Fix Component-Wise notes & some formatting --- _static/css/custom.css | 26 + .../shader_reference/shader_functions.rst | 1501 +++++++++-------- .../shader_reference/shading_language.rst | 19 +- 3 files changed, 806 insertions(+), 740 deletions(-) diff --git a/_static/css/custom.css b/_static/css/custom.css index 8654cd14d6f..dc4782a9c55 100644 --- a/_static/css/custom.css +++ b/_static/css/custom.css @@ -809,6 +809,31 @@ html.writer-html5 .rst-content table.docutils th { .wy-table-responsive table.wrap-normal th { white-space: normal; } +/* Turn nowrap on per-column */ +.wy-table-responsive table.nowrap-col1 td:nth-child(1), +.wy-table-responsive table.nowrap-col1 th:nth-child(1) { + white-space: nowrap; +} +.wy-table-responsive table.nowrap-col2 td:nth-child(2), +.wy-table-responsive table.nowrap-col2 th:nth-child(2) { + white-space: nowrap; +} +.wy-table-responsive table.nowrap-col3 td:nth-child(3), +.wy-table-responsive table.nowrap-col3 th:nth-child(3) { + white-space: nowrap; +} +.wy-table-responsive table.nowrap-col4 td:nth-child(4), +.wy-table-responsive table.nowrap-col4 th:nth-child(4) { + white-space: nowrap; +} +.wy-table-responsive table.nowrap-col5 td:nth-child(5), +.wy-table-responsive table.nowrap-col5 th:nth-child(5) { + white-space: nowrap; +} +.wy-table-responsive table.nowrap-col6 td:nth-child(6), +.wy-table-responsive table.nowrap-col6 th:nth-child(6) { + white-space: nowrap; +} /* Make sure line blocks don't stretch tables */ .wy-table-responsive table .line-block { @@ -1135,6 +1160,7 @@ kbd.compound > .kbd, .classref-descriptions-group > p.classref-annotation, .classref-descriptions-group > p.classref-themeproperty, .classref-descriptions-group > p.classref-method, +.classref-descriptions-group > div.classref-method.line-block, .classref-descriptions-group > p.classref-constructor, .classref-descriptions-group > p.classref-operator, .classref-descriptions-group > p.classref-constant, diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index 3bc8af4ae68..c1189c467e7 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -1,7 +1,7 @@ .. _doc_shader_functions: Built-in functions ------------------------------------------- +================== Godot supports a large number of built-in functions, conforming roughly to the GLSL 4.00 specification. @@ -34,10 +34,25 @@ GLSL 4.00 specification. If any of these are specified for multiple parameters, they must all be the same type unless otherwise noted. +.. _shading_componentwise: + .. note:: - Most operations on vectors (multiplication, division, etc) are performed component-wise. - For example, the operation ``vec2(3, 4) * vec2(10, 20)`` would result in ``vec2(3 * 10, 4 * 20)``. - or the operation ``min(vec2(3, 4), vec2(1, 8))`` would result in ``vec2(min(3, 1), min(4, 8))``. + Many functions that accept one or more vectors or matrices perform the described function on each component of the vector/matrix. + Some examples: + + +-----------------------------------+-----------------------------------------------------+ + | Operation | Equivalent Scalar Operation | + +===================================+=====================================================+ + | ``sqrt(vec2(4,64))`` | ``vec2(sqrt(4),sqrt(64))`` | + +-----------------------------------+-----------------------------------------------------+ + | ``min(vec2(3,4),1)`` | ``vec2(min(3,1),min(4,1))`` | + +-----------------------------------+-----------------------------------------------------+ + | ``min(vec3(1,2,3),vec3(5,1,3))`` | ``vec3(min(1,5),min(2,1),min(3,3))`` | + +-----------------------------------+-----------------------------------------------------+ + | ``pow(vec3(3,8,5),2)`` | ``vec3(pow(3,2),pow(8,2),pow(5,2))`` | + +-----------------------------------+-----------------------------------------------------+ + | ``pow(vec3(3,8,5),vec3(1,2,4))`` | ``vec3(pow(3,1),pow(8,2),pow(5,4))`` | + +-----------------------------------+-----------------------------------------------------+ The `GLSL Language Specification `_ says under section 5.10 Vector and Matrix Operations: @@ -47,56 +62,67 @@ GLSL 4.00 specification. vector multiplied by matrix, and matrix multiplied by matrix. These do not operate component-wise, but rather perform the correct linear algebraic multiply. +.. rst-class:: classref-section-separator + +---- + + + .. rst-class:: classref-reftable-group Trigonometric Functions -^^^^^^^^^^^^^^^^^^^^^^^ - -+-----------------+-------------------------------------------------------------+-----------------------------+ -| Return Type | Function | Description / Return value | -+=================+=============================================================+=============================+ -| |vec_type| | :ref:`radians` ( |vec_type| degrees ) | Convert degrees to radians. | -+-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`degrees` ( |vec_type| radians ) | Convert radians to degrees. | -+-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`sin` ( |vec_type| x ) | Sine. | -+-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`cos` ( |vec_type| x ) | Cosine. | -+-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`tan` ( |vec_type| x ) | Tangent. | -+-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`asin` ( |vec_type| x ) | Arcsine. | -+-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`acos` ( |vec_type| x ) | Arccosine. | -+-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`atan` ( |vec_type| y_over_x ) | Arctangent. | -+-----------------+-------------------------------------------------------------+ | -| |vec_type| | :ref:`atan` ( |vec_type| y, |vec_type| x )| | -+-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`sinh` ( |vec_type| x ) | Hyperbolic sine. | -+-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`cosh` ( |vec_type| x ) | Hyperbolic cosine. | -+-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`tanh` ( |vec_type| x ) | Hyperbolic tangent. | -+-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`asinh` ( |vec_type| x ) | Inverse hyperbolic sine. | -+-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`acosh` ( |vec_type| x ) | Inverse hyperbolic cosine. | -+-----------------+-------------------------------------------------------------+-----------------------------+ -| |vec_type| | :ref:`atanh` ( |vec_type| x ) | Inverse hyperbolic tangent. | -+-----------------+-------------------------------------------------------------+-----------------------------+ +----------------------- + +.. table:: + :class: nowrap-col2 + :widths: auto + + +-----------------+-----------------------------------------------------------------+-----------------------------+ + | Return Type | Function | Description / Return value | + +=================+=================================================================+=============================+ + | |vec_type| | :ref:`radians`\ (\ |vec_type| degrees) | Convert degrees to radians. | + +-----------------+-----------------------------------------------------------------+-----------------------------+ + | |vec_type| | :ref:`degrees`\ (\ |vec_type| radians) | Convert radians to degrees. | + +-----------------+-----------------------------------------------------------------+-----------------------------+ + | |vec_type| | :ref:`sin`\ (\ |vec_type| x) | Sine. | + +-----------------+-----------------------------------------------------------------+-----------------------------+ + | |vec_type| | :ref:`cos`\ (\ |vec_type| x) | Cosine. | + +-----------------+-----------------------------------------------------------------+-----------------------------+ + | |vec_type| | :ref:`tan`\ (\ |vec_type| x) | Tangent. | + +-----------------+-----------------------------------------------------------------+-----------------------------+ + | |vec_type| | :ref:`asin`\ (\ |vec_type| x) | Arcsine. | + +-----------------+-----------------------------------------------------------------+-----------------------------+ + | |vec_type| | :ref:`acos`\ (\ |vec_type| x) | Arccosine. | + +-----------------+-----------------------------------------------------------------+-----------------------------+ + | | |vec_type| | | :ref:`atan`\ (\ |vec_type| y_over_x) | Arctangent. | + | | |vec_type| | | :ref:`atan`\ (\ |vec_type| y, |vec_type| x)| | + +-----------------+-----------------------------------------------------------------+-----------------------------+ + | |vec_type| | :ref:`sinh`\ (\ |vec_type| x) | Hyperbolic sine. | + +-----------------+-----------------------------------------------------------------+-----------------------------+ + | |vec_type| | :ref:`cosh`\ (\ |vec_type| x) | Hyperbolic cosine. | + +-----------------+-----------------------------------------------------------------+-----------------------------+ + | |vec_type| | :ref:`tanh`\ (\ |vec_type| x) | Hyperbolic tangent. | + +-----------------+-----------------------------------------------------------------+-----------------------------+ + | |vec_type| | :ref:`asinh`\ (\ |vec_type| x) | Inverse hyperbolic sine. | + +-----------------+-----------------------------------------------------------------+-----------------------------+ + | |vec_type| | :ref:`acosh`\ (\ |vec_type| x) | Inverse hyperbolic cosine. | + +-----------------+-----------------------------------------------------------------+-----------------------------+ + | |vec_type| | :ref:`atanh`\ (\ |vec_type| x) | Inverse hyperbolic tangent. | + +-----------------+-----------------------------------------------------------------+-----------------------------+ -.. rst-class:: classref-section-separator - ----- .. rst-class:: classref-descriptions-group +Trigonometric Function Details +""""""""""""""""""""""""""""""" + .. _shader_func_radians: .. rst-class:: classref-method -|vec_type| **radians** ( |vec_type| degrees ) +|vec_type| **radians**\ (\ |vec_type| degrees) + + |componentwise| Converts a quantity specified in degrees into radians. @@ -117,7 +143,9 @@ Trigonometric Functions .. rst-class:: classref-method -|vec_type| degrees( |vec_type| radians) +|vec_type| **degrees**\ (\ |vec_type| radians) + + |componentwise| Converts a quantity specified in radians into degrees. @@ -138,12 +166,14 @@ Trigonometric Functions .. rst-class:: classref-method -vec_type sin( |vec_type| angle) +|vec_type| **sin**\ (\ |vec_type| angle) + + |componentwise| Return the sine of the parameter. :param angle: - takehe quantity, in radians, of which to return the sine + the quantity, in radians, of which to return the sine :return: the trigonometric sine of ``angle``. @@ -159,7 +189,9 @@ vec_type sin( |vec_type| angle) .. rst-class:: classref-method -vec_type cos( |vec_type| angle) +|vec_type| **cos**\ (\ |vec_type| angle) + + |componentwise| Return the cosine of the parameter. @@ -180,7 +212,9 @@ vec_type cos( |vec_type| angle) .. rst-class:: classref-method -vec_type tan( |vec_type| angle) +|vec_type| **tan**\ (\ |vec_type| angle) + + |componentwise| Return the tangent of the parameter. @@ -201,7 +235,9 @@ vec_type tan( |vec_type| angle) .. rst-class:: classref-method -vec_type asin( |vec_type| x) +|vec_type| **asin**\ (\ |vec_type| x) + + |componentwise| Calculates the angle whose sine is ``x``. The result is undefined if ``x < -1`` or ``x > 1``. @@ -223,7 +259,9 @@ vec_type asin( |vec_type| x) .. rst-class:: classref-method -vec_type acos( |vec_type| x) +|vec_type| **acos**\ (\ |vec_type| x) + + |componentwise| Calculates the angle whose cosine is ``x``. The result is undefined if ``x < -1`` or ``x > 1``. @@ -246,14 +284,16 @@ vec_type acos( |vec_type| x) .. rst-class:: classref-method -vec_type atan( |vec_type| y_over_x) +|vec_type| **atan**\ (\ |vec_type| y_over_x) + + |componentwise| Calculate the arctangent given a tangent value of ``y/x``. .. Note:: because of the sign ambiguity, the function cannot determine with certainty in which quadrant the angle falls only by its tangent value. If you need to know the - quadrant, use ``atan( |vec_type| y, |vec_type| x )``. + quadrant, use :ref:`atan(vec_type y, vec_type x)`. :param y_over_x: The fraction whose arctangent to return. @@ -264,15 +304,18 @@ vec_type atan( |vec_type| y_over_x) https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/atan.xhtml - .. rst-class:: classref-item-separator ---- +.. _shader_func_atan2: + .. rst-class:: classref-method -vec_type atan( |vec_type| y, |vec_type| x) +|vec_type| **atan**\ (\ |vec_type| y, |vec_type| x) + + |componentwise| Calculate the arctangent given a numerator and denominator. The signs of ``y`` and ``x`` are used to determine the quadrant that the angle lies in. @@ -299,7 +342,9 @@ vec_type atan( |vec_type| y, |vec_type| x) .. rst-class:: classref-method -vec_type sinh( |vec_type| x) +|vec_type| **sinh**\ (\ |vec_type| x) + + |componentwise| Calculates the hyperbolic sine using ``(e^x - e^-x)/2``. @@ -320,7 +365,9 @@ vec_type sinh( |vec_type| x) .. rst-class:: classref-method -vec_type cosh( |vec_type| x) +|vec_type| **cosh**\ (\ |vec_type| x) + + |componentwise| Calculates the hyperbolic cosine using ``(e^x + e^-x)/2``. @@ -341,7 +388,9 @@ vec_type cosh( |vec_type| x) .. rst-class:: classref-method -vec_type tanh( |vec_type| x) +|vec_type| **tanh**\ (\ |vec_type| x) + + |componentwise| Calculates the hyperbolic tangent using ``sinh(x)/cosh(x)``. @@ -362,7 +411,9 @@ vec_type tanh( |vec_type| x) .. rst-class:: classref-method -vec_type asinh( |vec_type| x) +|vec_type| **asinh**\ (\ |vec_type| x) + + |componentwise| Calculates the arc hyperbolic sine of a value. @@ -384,7 +435,9 @@ vec_type asinh( |vec_type| x) .. rst-class:: classref-method -vec_type acosh( |vec_type| x) +|vec_type| **acosh**\ (\ |vec_type| x) + + |componentwise| Calculates the arc hyperbolic cosine of a value. The result is undefined if ``x < 1``. @@ -406,7 +459,9 @@ vec_type acosh( |vec_type| x) .. rst-class:: classref-method -vec_type atanh( |vec_type| x) +|vec_type| **atanh**\ (\ |vec_type| x) + + |componentwise| Calculate the arctangent given a tangent value of ``y/x``. Note: because of the sign ambiguity, the function cannot determine with certainty in which @@ -424,132 +479,126 @@ vec_type atanh( |vec_type| x) https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/atan.xhtml -.. rst-class:: classref-item-separator + +.. rst-class:: classref-section-separator ---- + + + + + +.. rst-class:: classref-reftable-group + Exponential and Common Math Functions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`pow` ( |vec_type| x, |vec_type| y ) | Power (undefined if ``x < 0`` or if ``x == 0`` and ``y <= 0``). | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`exp` ( |vec_type| x ) | Base-e exponential. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`exp2` ( |vec_type| x ) | Base-2 exponential. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`log` ( |vec_type| x ) | Natural logarithm. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`log2` ( |vec_type| x ) | Base-2 logarithm. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`sqrt` ( |vec_type| x ) | Square root. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`inversesqrt` ( |vec_type| x ) | Inverse square root. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`abs` ( |vec_type| x ) | Absolute value (returns positive value if negative). | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_int_type| | :ref:`abs` ( |vec_int_type| x ) | | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`sign` ( |vec_type| x ) | returns ``1.0`` if positive, ``-1.0`` if negative, | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_int_type| | :ref:`sign` ( |vec_int_type| x ) | returns ``1`` if positive, ``-1`` if negative, | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`floor` ( |vec_type| x ) | Round to the integer below. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`round` ( |vec_type| x ) | Round to the nearest integer. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`roundEven` ( |vec_type| x ) | Round to the nearest even integer. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`trunc` ( |vec_type| x ) | Truncation. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`ceil` ( |vec_type| x ) | Round to the integer above. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`fract` ( |vec_type| x ) | Fractional (returns ``x - floor(x)``). | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`mod` ( |vec_type| x, |vec_type| y ) | Modulo (division remainder). | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_type| | :ref:`mod` ( |vec_type| x, float y ) | | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`modf` (|vec_type| x, out |vec_type| i ) | Fractional of ``x``, with ``i`` as integer part. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`min` ( |vec_type| a, |vec_type| b ) | Lowest value between ``a`` and ``b``. | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_type| | :ref:`min` ( |vec_type| a, float b ) | | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_int_type| | :ref:`min` ( |vec_int_type| a, |vec_int_type| b ) | | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_int_type| | :ref:`min` ( |vec_int_type| a, int b ) | | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`min` ( |vec_uint_type| a, |vec_uint_type| b ) | | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`min` ( |vec_uint_type| a, uint b ) | | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`max` ( |vec_type| a, |vec_type| b ) | Highest value between ``a`` and ``b``. | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_type| | :ref:`max` ( |vec_type| a, float b ) | | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`max` ( |vec_uint_type| a, |vec_uint_type| b ) | | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`max` ( |vec_uint_type| a, uint b ) | | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_int_type| | :ref:`max` ( |vec_int_type| a, |vec_int_type| b ) | | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_int_type| | :ref:`max` ( |vec_int_type| a, int b ) | | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`clamp` (|vec_type| x, |vec_type| min, |vec_type| max ) | Clamp ``x`` between ``min`` and ``max`` (inclusive). | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_type| | :ref:`clamp` ( |vec_type| x, float min, float max ) | | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`clamp` ( |vec_int_type| x, |vec_int_type| min, |vec_int_type| max )| | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`clamp` ( |vec_int_type| x, float min, float max ) | | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_int_type| | :ref:`clamp` (|vec_type| x, |vec_type| min, |vec_type| max ) | | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_int_type| | :ref:`clamp` ( |vec_type| x, float min, float max ) | | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`mix` (|vec_type| a, |vec_type| b, |vec_type| c ) | Linear interpolate between ``a`` and ``b`` by ``c``. | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_type| | :ref:`mix` (|vec_type| a, |vec_type| b, float c ) | | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_type| | :ref:`mix` (|vec_type| a, |vec_type| b, |vec_bool_type| c ) | | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`fma` (|vec_type| a, |vec_type| b, |vec_type| c ) | Fused multiply-add operation: ``(a * b + c)`` | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`step` ( |vec_type| a, |vec_type| b ) | ``b[i] < a[i] ? 0.0 : 1.0``. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`step` (float a, |vec_type| b ) | ``b[i] < a ? 0.0 : 1.0``. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`smoothstep` (|vec_type| a, |vec_type| b, |vec_type| c ) | Hermite interpolate between ``a`` and ``b`` by ``c``. | -+-----------------+---------------------------------------------------------------------------------------------+ | -| |vec_type| | :ref:`smoothstep` (float a, float b, |vec_type| c ) | | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_bool_type| | :ref:`isnan` ( |vec_type| x ) | Returns ``true`` if scalar or vector component is ``NaN``. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_bool_type| | :ref:`isinf` ( |vec_type| x ) | Returns ``true`` if scalar or vector component is ``INF``. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_int_type| | :ref:`floatBitsToInt` ( |vec_type| x ) | Float->Int bit copying, no conversion. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_uint_type| | :ref:`floatBitsToUint` ( |vec_type| x ) | Float->UInt bit copying, no conversion. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`intBitsToFloat` ( |vec_int_type| x ) | Int->Float bit copying, no conversion. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| |vec_type| | :ref:`uintBitsToFloat` ( |vec_uint_type| x ) | UInt->Float bit copying, no conversion. | -+-----------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ +------------------------------------- + +.. table:: + :class: nowrap-col2 + :widths: auto + + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_type| | :ref:`pow`\ (\ |vec_type| x, |vec_type| y) | Power (undefined if ``x < 0`` or if ``x == 0`` and ``y <= 0``). | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_type| | :ref:`exp`\ (\ |vec_type| x) | Base-e exponential. | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_type| | :ref:`exp2`\ (\ |vec_type| x) | Base-2 exponential. | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_type| | :ref:`log`\ (\ |vec_type| x) | Natural logarithm. | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_type| | :ref:`log2`\ (\ |vec_type| x) | Base-2 logarithm. | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_type| | :ref:`sqrt`\ (\ |vec_type| x) | Square root. | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_type| | :ref:`inversesqrt`\ (\ |vec_type| x) | Inverse square root. | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | | |vec_type| | | :ref:`abs`\ (\ |vec_type| x) | Absolute value (returns positive value if negative). | + | | |vec_int_type| | | :ref:`abs`\ (\ |vec_int_type| x) | | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_type| | :ref:`sign`\ (\ |vec_type| x) | returns ``1.0`` if positive, ``-1.0`` if negative, | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_int_type| | :ref:`sign`\ (\ |vec_int_type| x) | returns ``1`` if positive, ``-1`` if negative, | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_type| | :ref:`floor`\ (\ |vec_type| x) | Round to the integer below. | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_type| | :ref:`round`\ (\ |vec_type| x) | Round to the nearest integer. | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_type| | :ref:`roundEven`\ (\ |vec_type| x) | Round to the nearest even integer. | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_type| | :ref:`trunc`\ (\ |vec_type| x) | Truncation. | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_type| | :ref:`ceil`\ (\ |vec_type| x) | Round to the integer above. | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_type| | :ref:`fract`\ (\ |vec_type| x) | Fractional (returns ``x - floor(x)``). | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | | |vec_type| | | :ref:`mod`\ (\ |vec_type| x, |vec_type| y) | Modulo (division remainder). | + | | |vec_type| | | :ref:`mod`\ (\ |vec_type| x, float y) | | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_type| | :ref:`modf`\ (\ |vec_type| x, out |vec_type| i) | Fractional of ``x``, with ``i`` as integer part. | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | | |vec_type| | | :ref:`min`\ (\ |vec_type| a, |vec_type| b) | Lowest value between ``a`` and ``b``. | + | | |vec_type| | | :ref:`min`\ (\ |vec_type| a, float b) | | + | | |vec_int_type| | | :ref:`min`\ (\ |vec_int_type| a, |vec_int_type| b) | | + | | |vec_int_type| | | :ref:`min`\ (\ |vec_int_type| a, int b) | | + | | |vec_uint_type| | | :ref:`min`\ (\ |vec_uint_type| a, |vec_uint_type| b) | | + | | |vec_uint_type| | | :ref:`min`\ (\ |vec_uint_type| a, uint b) | | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | | |vec_type| | | :ref:`max`\ (\ |vec_type| a, |vec_type| b) | Highest value between ``a`` and ``b``. | + | | |vec_type| | | :ref:`max`\ (\ |vec_type| a, float b) | | + | | |vec_uint_type| | | :ref:`max`\ (\ |vec_uint_type| a, |vec_uint_type| b) | | + | | |vec_uint_type| | | :ref:`max`\ (\ |vec_uint_type| a, uint b) | | + | | |vec_int_type| | | :ref:`max`\ (\ |vec_int_type| a, |vec_int_type| b) | | + | | |vec_int_type| | | :ref:`max`\ (\ |vec_int_type| a, int b) | | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | | |vec_type| | | :ref:`clamp`\ (\ |vec_type| x, |vec_type| min, |vec_type| max) | Clamp ``x`` between ``min`` and ``max`` (inclusive). | + | | |vec_type| | | :ref:`clamp`\ (\ |vec_type| x, float min, float max) | | + | | |vec_uint_type| | | :ref:`clamp`\ (\ |vec_int_type| x, |vec_int_type| min, |vec_int_type| max) | | + | | |vec_uint_type| | | :ref:`clamp`\ (\ |vec_int_type| x, float min, float max) | | + | | |vec_int_type| | | :ref:`clamp`\ (\ |vec_type| x, |vec_type| min, |vec_type| max) | | + | | |vec_int_type| | | :ref:`clamp`\ (\ |vec_type| x, float min, float max) | | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | | |vec_type| | | :ref:`mix`\ (\ |vec_type| a, |vec_type| b, |vec_type| c) | Linear interpolate between ``a`` and ``b`` by ``c``. | + | | |vec_type| | | :ref:`mix`\ (\ |vec_type| a, |vec_type| b, float c) | | + | | |vec_type| | | :ref:`mix`\ (\ |vec_type| a, |vec_type| b, |vec_bool_type| c) | | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_type| | :ref:`fma`\ (\ |vec_type| a, |vec_type| b, |vec_type| c) | Fused multiply-add operation: ``(a * b + c)`` | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | | |vec_type| | | :ref:`step`\ (\ |vec_type| a, |vec_type| b) | ``b < a ? 0.0 : 1.0`` | + | | |vec_type| | | :ref:`step`\ (\ float a, |vec_type| b) | | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | | |vec_type| | | :ref:`smoothstep`\ (\ |vec_type| a, |vec_type| b, |vec_type| c) | Hermite interpolate between ``a`` and ``b`` by ``c``. | + | | |vec_type| | | :ref:`smoothstep`\ (\ float a, float b, |vec_type| c) | | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_bool_type| | :ref:`isnan`\ (\ |vec_type| x) | Returns ``true`` if scalar or vector component is ``NaN``. | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_bool_type| | :ref:`isinf`\ (\ |vec_type| x) | Returns ``true`` if scalar or vector component is ``INF``. | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_int_type| | :ref:`floatBitsToInt`\ (\ |vec_type| x) | Float->Int bit copying, no conversion. | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_uint_type| | :ref:`floatBitsToUint`\ (\ |vec_type| x) | Float->UInt bit copying, no conversion. | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_type| | :ref:`intBitsToFloat`\ (\ |vec_int_type| x) | Int->Float bit copying, no conversion. | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ + | |vec_type| | :ref:`uintBitsToFloat`\ (\ |vec_uint_type| x) | UInt->Float bit copying, no conversion. | + +---------------------+-------------------------------------------------------------------------------------------------+-----------------------------------------------------------------+ -.. rst-class:: classref-section-separator ----- +.. rst-class:: classref-descriptions-group + +Exponential Function Descriptions +""""""""""""""""""""""""""""""""""" .. _shader_func_pow: .. rst-class:: classref-method +|vec_type| **pow**\ (\ |vec_type| x, |vec_type| y) -vec_type pow( |vec_type| x, |vec_type| y) + |componentwise| Raises ``x`` to the power of ``y``. @@ -571,12 +620,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - .. _shader_func_exp: .. rst-class:: classref-method -|vec_type| **exp** ( |vec_type| x ) +|vec_type| **exp**\ (\ |vec_type| x) + + |componentwise| Return the natural exponentiation of the parameter. @@ -593,13 +643,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_exp2: .. rst-class:: classref-method -|vec_type| **exp2** ( |vec_type| x ) +|vec_type| **exp2**\ (\ |vec_type| x) + + |componentwise| Return 2 raised to the power of the parameter. @@ -616,13 +666,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_log: .. rst-class:: classref-method -|vec_type| **log** ( |vec_type| x ) +|vec_type| **log**\ (\ |vec_type| x) + + |componentwise| Return the natural logarithm of the parameter, i.e. the value y which satisfies x=e\ :sup:`y`. The result is undefined if x ≤ 0. @@ -640,13 +690,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_log2: .. rst-class:: classref-method -|vec_type| **log2** ( |vec_type| x ) +|vec_type| **log2**\ (\ |vec_type| x) + + |componentwise| Return the base 2 logarithm of the parameter. The result is undefined if x ≤ 0. @@ -664,13 +714,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_sqrt: .. rst-class:: classref-method -|vec_type| **sqrt** ( |vec_type| x ) +|vec_type| **sqrt**\ (\ |vec_type| x) + + |componentwise| Returns the square root of x. The result is undefined if x < 0. @@ -679,7 +729,7 @@ vec_type pow( |vec_type| x, |vec_type| y) the value of which to take the square root. :return: - + the square root of x https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/sqrt.xhtml @@ -688,18 +738,17 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_inversesqrt: .. rst-class:: classref-method -|vec_type| **inversesqrt** ( |vec_type| x ) +|vec_type| **inversesqrt**\ (\ |vec_type| x) + + |componentwise| Returns the inverse of the square root of x. The result is undefined if x ≤ 0. - :param x: The value of which to take the inverse of the square root. @@ -713,14 +762,14 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_abs: .. rst-class:: classref-method -| |vec_type| **abs** ( |vec_type| x ) -| |vec_int_type| **abs** ( |vec_int_type| x ) +| |vec_type| **abs**\ (\ |vec_type| x) +| |vec_int_type| **abs**\ (\ |vec_int_type| x) + + |componentwise| Returns the absolute value of x. Returns X if X is positive or X * -1 if X is negative. @@ -737,14 +786,14 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_sign: .. rst-class:: classref-method -| |vec_type| **sign** ( |vec_type| x ) -| |vec_int_type| **sign** ( |vec_int_type| x ) +| |vec_type| **sign**\ (\ |vec_type| x) +| |vec_int_type| **sign**\ (\ |vec_int_type| x) + + |componentwise| Returns -1.0 if x is less than 0.0, 0.0 if x is equal to 0.0, and +1.0 if x is greater than 0.0. @@ -761,13 +810,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_floor: .. rst-class:: classref-method -|vec_type| **floor** ( |vec_type| x ) +|vec_type| **floor**\ (\ |vec_type| x) + + |componentwise| Returns a value equal to the nearest integer that is less than or equal to x. @@ -784,13 +833,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_round: .. rst-class:: classref-method -|vec_type| **round** ( |vec_type| x ) +|vec_type| **round**\ (\ |vec_type| x) + + |componentwise| Returns a value equal to the nearest integer to x. @@ -811,13 +860,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_roundEven: .. rst-class:: classref-method -|vec_type| **roundEven** ( |vec_type| x ) +|vec_type| **roundEven**\ (\ |vec_type| x) + + |componentwise| returns a value equal to the nearest integer to x. @@ -837,13 +886,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_trunc: .. rst-class:: classref-method -|vec_type| **trunc** ( |vec_type| x ) +|vec_type| **trunc**\ (\ |vec_type| x) + + |componentwise| Returns a value equal to the nearest integer to x whose absolute value is not larger than the absolute value of x. @@ -860,13 +909,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_ceil: .. rst-class:: classref-method -|vec_type| **ceil** ( |vec_type| x ) +|vec_type| **ceil**\ (\ |vec_type| x) + + |componentwise| Returns a value equal to the nearest integer that is greater than or equal to x. @@ -883,13 +932,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_fract: .. rst-class:: classref-method -|vec_type| **fract** ( |vec_type| x ) +|vec_type| **fract**\ (\ |vec_type| x) + + |componentwise| Returns the fractional part of x. @@ -908,14 +957,14 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_mod: .. rst-class:: classref-method -| |vec_type| **mod** ( |vec_type| x, |vec_type| y ) -| |vec_type| **mod** ( |vec_type| x, float y ) +| |vec_type| **mod**\ (\ |vec_type| x, |vec_type| y) +| |vec_type| **mod**\ (\ |vec_type| x, float y) + + |componentwise| Returns the value of ``x modulo y``. This is also sometimes called the remainder. @@ -935,13 +984,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_modf: .. rst-class:: classref-method -|vec_type| **modf** ( |vec_type| x, out |vec_type| i ) +|vec_type| **modf**\ (\ |vec_type| x, out |vec_type| i) + + |componentwise| Separates a floating point value x into its integer and fractional parts. @@ -964,18 +1013,18 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_min: .. rst-class:: classref-method -| |vec_type| **min** ( |vec_type| a, |vec_type| b ) -| |vec_type| **min** ( |vec_type| a, float b ) -| |vec_int_type| **min** ( |vec_int_type| a, |vec_int_type| b ) -| |vec_int_type| **min** ( |vec_int_type| a, int b ) -| |vec_uint_type| **min** ( |vec_uint_type| a, |vec_uint_type| b ) -| |vec_uint_type| **min** ( |vec_uint_type| a, uint b ) +| |vec_type| **min**\ (\ |vec_type| a, |vec_type| b) +| |vec_type| **min**\ (\ |vec_type| a, float b) +| |vec_int_type| **min**\ (\ |vec_int_type| a, |vec_int_type| b) +| |vec_int_type| **min**\ (\ |vec_int_type| a, int b) +| |vec_uint_type| **min**\ (\ |vec_uint_type| a, |vec_uint_type| b) +| |vec_uint_type| **min**\ (\ |vec_uint_type| a, uint b) + + |componentwise| Returns the minimum of the two parameters. @@ -997,18 +1046,18 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_max: .. rst-class:: classref-method -| |vec_type| **max** ( |vec_type| a, |vec_type| b ) -| |vec_type| **max** ( |vec_type| a, float b ) -| |vec_uint_type| **max** ( |vec_uint_type| a, |vec_uint_type| b ) -| |vec_uint_type| **max** ( |vec_uint_type| a, uint b ) -| |vec_int_type| **max** ( |vec_int_type| a, |vec_int_type| b ) -| |vec_int_type| **max** ( |vec_int_type| a, int b ) +| |vec_type| **max**\ (\ |vec_type| a, |vec_type| b) +| |vec_type| **max**\ (\ |vec_type| a, float b) +| |vec_uint_type| **max**\ (\ |vec_uint_type| a, |vec_uint_type| b) +| |vec_uint_type| **max**\ (\ |vec_uint_type| a, uint b) +| |vec_int_type| **max**\ (\ |vec_int_type| a, |vec_int_type| b) +| |vec_int_type| **max**\ (\ |vec_int_type| a, int b) + + |componentwise| Returns the maximum of the two parameters. @@ -1030,18 +1079,18 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_clamp: .. rst-class:: classref-method -| |vec_type| **clamp** ( |vec_type| x, |vec_type| minVal, |vec_type| maxVal ) -| |vec_type| **clamp** ( |vec_type| x, float min, float max ) -| |vec_type| **clamp** ( |vec_type| x, float min, float max ) -| |vec_uint_type| **clamp** ( |vec_int_type| x, float min, float max ) -| |vec_int_type| **clamp** ( |vec_type| x, |vec_type| min, |vec_type| max ) -| |vec_int_type| **clamp** ( |vec_type| x, float min, float max ) +| |vec_type| **clamp**\ (\ |vec_type| x, |vec_type| minVal, |vec_type| maxVal) +| |vec_type| **clamp**\ (\ |vec_type| x, float min, float max) +| |vec_type| **clamp**\ (\ |vec_type| x, float min, float max) +| |vec_uint_type| **clamp**\ (\ |vec_int_type| x, float min, float max) +| |vec_int_type| **clamp**\ (\ |vec_type| x, |vec_type| min, |vec_type| max) +| |vec_int_type| **clamp**\ (\ |vec_type| x, float min, float max) + + |componentwise| Returns the value of x constrained to the range minVal to maxVal. @@ -1066,14 +1115,14 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_mix: .. rst-class:: classref-method -| |vec_type| **mix** ( |vec_type| a, |vec_type| b, |vec_type| c ) -| |vec_type| **mix** ( |vec_type| a, |vec_type| b, float c ) +| |vec_type| **mix**\ (\ |vec_type| a, |vec_type| b, |vec_type| c) +| |vec_type| **mix**\ (\ |vec_type| a, |vec_type| b, float c) + + |componentwise| Performs a linear interpolation between a and b using c to weight between them. @@ -1100,7 +1149,9 @@ vec_type pow( |vec_type| x, |vec_type| y) .. rst-class:: classref-method -|vec_type| **mix** ( |vec_type| a, |vec_type| b, |vec_bool_type| c ) +|vec_type| **mix**\ (\ |vec_type| a, |vec_type| b, |vec_bool_type| c) + + |componentwise| Selects either value a or value b based on the value of c. For a component of c that is false, the corresponding component of a is returned. @@ -1129,13 +1180,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_fma: .. rst-class:: classref-method -|vec_type| **fma** ( |vec_type| a, |vec_type| b, |vec_type| c ) +|vec_type| **fma**\ (\ |vec_type| a, |vec_type| b, |vec_type| c) + + |componentwise| Performs, where possible, a fused multiply-add operation, returning a * b + c. In use cases where the return value is eventually consumed by a variable declared as precise: @@ -1169,48 +1220,18 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_step: .. rst-class:: classref-method -|vec_type| **step** ( |vec_type| a, |vec_type| b ) - - Generates a step function by comparing b to a. - - Equivalent to ``if (b < a) { return 0.0; } else { return 1.0; }``. - Or if vec_type is a vector, a vector where the above operation has been performed on each component of the input vectors. - ie. ``step(vec2(4.2, 314), vec2(2.4, 980))`` would return ``vec2(step(a[0], b[0]), step(a[1], b[1]))``. - - For element i of the return value, 0.0 is returned if b[i] < a[i], and 1.0 is returned otherwise. +| |vec_type| **step**\ (\ |vec_type| a, |vec_type| b) +| |vec_type| **step**\ (\ float a, |vec_type| b) - :param a: - the location of the edge of the step function. - - :param b: - the value to be used to generate the step function. - - :return: - 0.0 or 1.0 - - https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/step.xhtml - -.. rst-class:: classref-item-separator - ----- - - -.. rst-class:: classref-method - -|vec_type| **step** ( float a, |vec_type| b ) + |componentwise| Generates a step function by comparing b to a. Equivalent to ``if (b < a) { return 0.0; } else { return 1.0; }``. - Or rather, the above operation will be performed on each component of the input vector. - ie. ``step(4.2, vec2(2.4, 980))`` would return the equivalent of ``vec2(step(42, b[0]), step(42, b[1]))``. - For element i of the return value, 0.0 is returned if b[i] < a[i], and 1.0 is returned otherwise. :param a: @@ -1229,14 +1250,14 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_smoothstep: .. rst-class:: classref-method -| |vec_type| **smoothstep** ( |vec_type| a, |vec_type| b, |vec_type| c ) -| |vec_type| **smoothstep** ( float a, float b, |vec_type| c ) +| |vec_type| **smoothstep**\ (\ |vec_type| a, |vec_type| b, |vec_type| c) +| |vec_type| **smoothstep**\ (\ float a, float b, |vec_type| c) + + |componentwise| Performs smooth Hermite interpolation between 0 and 1 when a < c < b. This is useful in cases where a threshold function with a smooth transition is desired. @@ -1268,13 +1289,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_isnan: .. rst-class:: classref-method -|vec_bool_type| **isnan** ( |vec_type| x ) +|vec_bool_type| **isnan**\ (\ |vec_type| x) + + |componentwise| For each element i of the result, returns true if x[i] is positive or negative floating point NaN (Not a Number) and false otherwise. @@ -1292,13 +1313,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_isinf: .. rst-class:: classref-method -|vec_bool_type| **isinf** ( |vec_type| x ) +|vec_bool_type| **isinf**\ (\ |vec_type| x) + + |componentwise| For each element i of the result, returns true if x[i] is positive or negative floating point infinity and false otherwise. @@ -1316,13 +1337,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_floatBitsToInt: .. rst-class:: classref-method -|vec_int_type| **floatBitsToInt** ( |vec_type| x ) +|vec_int_type| **floatBitsToInt**\ (\ |vec_type| x) + + |componentwise| Returns the encoding of the floating-point parameters as int. @@ -1341,13 +1362,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_floatBitsToUint: .. rst-class:: classref-method -|vec_uint_type| **floatBitsToUint** ( |vec_type| x ) +|vec_uint_type| **floatBitsToUint**\ (\ |vec_type| x) + + |componentwise| Returns the encoding of the floating-point parameters as uint. @@ -1366,13 +1387,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_intBitsToFloat: .. rst-class:: classref-method -|vec_type| **intBitsToFloat** ( |vec_int_type| x ) +|vec_type| **intBitsToFloat**\ (\ |vec_int_type| x) + + |componentwise| Converts a bit encoding to a floating-point value. Opposite of `floatBitsToInt<_shader_func_floatBitsToInt>` @@ -1394,13 +1415,13 @@ vec_type pow( |vec_type| x, |vec_type| y) ---- - - .. _shader_func_uintBitsToFloat: .. rst-class:: classref-method -|vec_type| **uintBitsToFloat** ( |vec_uint_type| x ) +|vec_type| **uintBitsToFloat**\ (\ |vec_uint_type| x) + + |componentwise| Converts a bit encoding to a floating-point value. Opposite of `floatBitsToUint<_shader_func_floatBitsToUint>` @@ -1417,7 +1438,8 @@ vec_type pow( |vec_type| x, |vec_type| y) https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/uintBitsToFloat.xhtml -.. rst-class:: classref-item-separator + +.. rst-class:: classref-section-separator ---- @@ -1427,47 +1449,67 @@ vec_type pow( |vec_type| x, |vec_type| y) + + + + + + + + + + + + +.. rst-class:: classref-reftable-group + Geometric Functions -^^^^^^^^^^^^^^^^^^^ - -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`length` ( |vec_type| x ) | Vector length. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`distance` ( |vec_type| a, |vec_type| b ) | Distance between vectors i.e ``length(a - b)``. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`dot` ( |vec_type| a, |vec_type| b ) | Dot product. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| vec3 | :ref:`cross` (vec3 a, vec3 b ) | Cross product. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |vec_type| | :ref:`normalize` ( |vec_type| x ) | Normalize to unit length. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| vec3 | :ref:`reflect` (vec3 I, vec3 N ) | Reflect. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| vec3 | :ref:`refract` (vec3 I, vec3 N, float eta ) | Refract. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |vec_type| | :ref:`faceforward` (|vec_type| N, |vec_type| I, |vec_type| Nref )| If ``dot(Nref, I)`` < 0, return ``N``, otherwise ``-N``. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`matrixCompMult` (|mat_type| x, |mat_type| y ) | Matrix component multiplication. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`outerProduct` ( |vec_type| column, |vec_type| row ) | Matrix outer product. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`transpose` (|mat_type| m ) | Transpose matrix. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| float | :ref:`determinant` (|mat_type| m ) | Matrix determinant. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ -| |mat_type| | :ref:`inverse` (|mat_type| m ) | Inverse matrix. | -+------------+-------------------------------------------------------------------------------------------+----------------------------------------------------------+ +------------------- + +.. table:: + :class: nowrap-col2 + :widths: auto + + +------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------+ + | float | :ref:`length`\ (\ |vec_type| x) | Vector length. | + +------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------+ + | float | :ref:`distance`\ (\ |vec_type| a, |vec_type| b) | Distance between vectors i.e ``length(a - b)``. | + +------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------+ + | float | :ref:`dot`\ (\ |vec_type| a, |vec_type| b) | Dot product. | + +------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------+ + | vec3 | :ref:`cross`\ (\ vec3 a, vec3 b) | Cross product. | + +------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------+ + | |vec_type| | :ref:`normalize`\ (\ |vec_type| x) | Normalize to unit length. | + +------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------+ + | vec3 | :ref:`reflect`\ (\ vec3 I, vec3 N) | Reflect. | + +------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------+ + | vec3 | :ref:`refract`\ (\ vec3 I, vec3 N, float eta) | Refract. | + +------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------+ + | |vec_type| | :ref:`faceforward`\ (\ |vec_type| N, |vec_type| I, |vec_type| Nref) | If ``dot(Nref, I)`` < 0, return ``N``, otherwise ``-N``. | + +------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------+ + | |mat_type| | :ref:`matrixCompMult`\ (\ |mat_type| x, |mat_type| y) | Matrix component multiplication. | + +------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------+ + | |mat_type| | :ref:`outerProduct`\ (\ |vec_type| column, |vec_type| row) | Matrix outer product. | + +------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------+ + | |mat_type| | :ref:`transpose`\ (\ |mat_type| m) | Transpose matrix. | + +------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------+ + | float | :ref:`determinant`\ (\ |mat_type| m) | Matrix determinant. | + +------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------+ + | |mat_type| | :ref:`inverse`\ (\ |mat_type| m) | Inverse matrix. | + +------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------+ -.. rst-class:: classref-section-separator ----------- +.. rst-class:: classref-descriptions-group + +Geometric Function Descriptions +""""""""""""""""""""""""""""""""" .. _shader_func_length: .. rst-class:: classref-method -float **length** ( |vec_type| x ) +float **length**\ (\ |vec_type| x) Returns the length of the vector. ie. ``sqrt(x[0] * x[0] + x[1] * x[1] + ... + x[n] * x[n])`` @@ -1485,14 +1527,11 @@ float **length** ( |vec_type| x ) ---- - - - .. _shader_func_distance: .. rst-class:: classref-method -float **distance** ( |vec_type| a, |vec_type| b ) +float **distance**\ (\ |vec_type| a, |vec_type| b) Returns the distance between the two points a and b. @@ -1514,14 +1553,11 @@ float **distance** ( |vec_type| a, |vec_type| b ) ---- - - - .. _shader_func_dot: .. rst-class:: classref-method -float **dot** ( |vec_type| a, |vec_type| b ) +float **dot**\ (\ |vec_type| a, |vec_type| b) Returns the dot product of two vectors, a and b. i.e., ``a.x * b.x + a.y * b.y + ...`` @@ -1542,21 +1578,18 @@ float **dot** ( |vec_type| a, |vec_type| b ) ---- - - - .. _shader_func_cross: .. rst-class:: classref-method -vec3 **cross** ( vec3 a, vec3 b ) +vec3 **cross**\ (\ vec3 a, vec3 b) Returns the cross product of two vectors. i.e.:: vec2( a.y * b.z - b.y * a.z, a.z * b.x - b.z * a.x, - a.x * b.z - b.x * a.y ) + a.x * b.z - b.x * a.y) :param a: the first vector @@ -1574,14 +1607,11 @@ vec3 **cross** ( vec3 a, vec3 b ) ---- - - - .. _shader_func_normalize: .. rst-class:: classref-method -|vec_type| **normalize** ( |vec_type| x ) +|vec_type| **normalize**\ (\ |vec_type| x) Returns a vector with the same direction as x but with length 1. @@ -1598,14 +1628,11 @@ vec3 **cross** ( vec3 a, vec3 b ) ---- - - - .. _shader_func_reflect: .. rst-class:: classref-method -vec3 **reflect** ( vec3 I, vec3 N ) +vec3 **reflect**\ (\ vec3 I, vec3 N) Calculate the reflection direction for an incident vector. @@ -1630,14 +1657,11 @@ vec3 **reflect** ( vec3 I, vec3 N ) ---- - - - .. _shader_func_refract: .. rst-class:: classref-method -vec3 **refract** ( vec3 I, vec3 N, float eta ) +vec3 **refract**\ (\ vec3 I, vec3 N, float eta) Calculate the refraction direction for an incident vector. @@ -1673,14 +1697,11 @@ vec3 **refract** ( vec3 I, vec3 N, float eta ) ---- - - - .. _shader_func_faceforward: .. rst-class:: classref-method -|vec_type| **faceforward** ( |vec_type| N, |vec_type| I, |vec_type| Nref ) +|vec_type| **faceforward**\ (\ |vec_type| N, |vec_type| I, |vec_type| Nref) Return a vector pointing in the same direction as another. @@ -1706,14 +1727,11 @@ vec3 **refract** ( vec3 I, vec3 N, float eta ) ---- - - - .. _shader_func_matrixCompMult: .. rst-class:: classref-method -|mat_type| **matrixCompMult** ( |mat_type| x, |mat_type| y ) +|mat_type| **matrixCompMult**\ (\ |mat_type| x, |mat_type| y) Perform a component-wise multiplication of two matrices. @@ -1737,14 +1755,11 @@ vec3 **refract** ( vec3 I, vec3 N, float eta ) ---- - - - .. _shader_func_outerProduct: .. rst-class:: classref-method -|mat_type| **outerProduct** ( |vec_type| column, |vec_type| row ) +|mat_type| **outerProduct**\ (\ |vec_type| column, |vec_type| row) Calculate the outer product of a pair of vectors. @@ -1768,14 +1783,11 @@ vec3 **refract** ( vec3 I, vec3 N, float eta ) ---- - - - .. _shader_func_transpose: .. rst-class:: classref-method -|mat_type| **transpose** ( |mat_type| m ) +|mat_type| **transpose**\ (\ |mat_type| m) Calculate the transpose of a matrix. @@ -1792,14 +1804,11 @@ vec3 **refract** ( vec3 I, vec3 N, float eta ) ---- - - - .. _shader_func_determinant: .. rst-class:: classref-method -float **determinant** ( |mat_type| m ) +float **determinant**\ (\ |mat_type| m) Calculate the determinant of a matrix. @@ -1816,14 +1825,11 @@ float **determinant** ( |mat_type| m ) ---- - - - .. _shader_func_inverse: .. rst-class:: classref-method -|mat_type| **inverse** ( |mat_type| m ) +|mat_type| **inverse**\ (\ |mat_type| m) Calculate the inverse of a matrix. @@ -1837,48 +1843,65 @@ float **determinant** ( |mat_type| m ) https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/inverse.xhtml -.. rst-class:: classref-item-separator +.. rst-class:: classref-section-separator ---- + + + + + + + + + +.. rst-class:: classref-reftable-group + Comparison Functions -^^^^^^^^^^^^^^^^^^^^ - -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`lessThan` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on < int/uint/float vectors. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`greaterThan` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on > int/uint/float vectors. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`lessThanEqual` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on <= int/uint/float vectors. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`greaterThanEqual` ( |vec_type| x, |vec_type| y )| Bool vector comparison on >= int/uint/float vectors. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`equal` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on == int/uint/float vectors. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`notEqual` ( |vec_type| x, |vec_type| y ) | Bool vector comparison on != int/uint/float vectors. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| bool | :ref:`any` ( |vec_bool_type| x ) | ``true`` if any component is ``true``, ``false`` otherwise. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| bool | :ref:`all` ( |vec_bool_type| x ) | ``true`` if all components are ``true``, ``false`` otherwise. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ -| |vec_bool_type| | :ref:`not` ( |vec_bool_type| x ) | Invert boolean vector. | -+-----------------+-------------------------------------------------------------------------------------+---------------------------------------------------------------+ +-------------------- + +.. table:: + :class: nowrap-col2 + :widths: auto + + +-----------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------+ + | |vec_bool_type| | :ref:`lessThan`\ (\ |vec_type| x, |vec_type| y) | Bool vector comparison on < int/uint/float vectors. | + +-----------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------+ + | |vec_bool_type| | :ref:`greaterThan`\ (\ |vec_type| x, |vec_type| y) | Bool vector comparison on > int/uint/float vectors. | + +-----------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------+ + | |vec_bool_type| | :ref:`lessThanEqual`\ (\ |vec_type| x, |vec_type| y) | Bool vector comparison on <= int/uint/float vectors. | + +-----------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------+ + | |vec_bool_type| | :ref:`greaterThanEqual`\ (\ |vec_type| x, |vec_type| y) | Bool vector comparison on >= int/uint/float vectors. | + +-----------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------+ + | |vec_bool_type| | :ref:`equal`\ (\ |vec_type| x, |vec_type| y) | Bool vector comparison on == int/uint/float vectors. | + +-----------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------+ + | |vec_bool_type| | :ref:`notEqual`\ (\ |vec_type| x, |vec_type| y) | Bool vector comparison on != int/uint/float vectors. | + +-----------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------+ + | bool | :ref:`any`\ (\ |vec_bool_type| x) | ``true`` if any component is ``true``, ``false`` otherwise. | + +-----------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------+ + | bool | :ref:`all`\ (\ |vec_bool_type| x) | ``true`` if all components are ``true``, ``false`` otherwise. | + +-----------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------+ + | |vec_bool_type| | :ref:`not`\ (\ |vec_bool_type| x) | Invert boolean vector. | + +-----------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------+ -.. rst-class:: classref-section-separator ----- +.. rst-class:: classref-descriptions-group + +Comparison Function Details +""""""""""""""""""""""""""""""" .. _shader_func_lessThan: .. rst-class:: classref-method -|vec_bool_type| **lessThan** ( |vec_type| x, |vec_type| y ) +|vec_bool_type| **lessThan**\ (\ |vec_type| x, |vec_type| y) - Perform a component-wise less-than comparison of two vectors. + Perform a :ref:`component-wise` less-than comparison of two vectors. :param x: the first vector for comparison. @@ -1902,9 +1925,9 @@ Comparison Functions .. rst-class:: classref-method -|vec_bool_type| **greaterThan** ( |vec_type| x, |vec_type| y ) +|vec_bool_type| **greaterThan**\ (\ |vec_type| x, |vec_type| y) - Perform a component-wise greater-than comparison of two vectors. + Perform a :ref:`component-wise` greater-than comparison of two vectors. :param x: the first vector for comparison. @@ -1928,9 +1951,9 @@ Comparison Functions .. rst-class:: classref-method -|vec_bool_type| **lessThanEqual** ( |vec_type| x, |vec_type| y ) +|vec_bool_type| **lessThanEqual**\ (\ |vec_type| x, |vec_type| y) - Perform a component-wise less-than-or-equal comparison of two vectors. + Perform a :ref:`component-wise` less-than-or-equal comparison of two vectors. :param x: the first vector for comparison. @@ -1954,9 +1977,9 @@ Comparison Functions .. rst-class:: classref-method -|vec_bool_type| **greaterThanEqual** ( |vec_type| x, |vec_type| y ) +|vec_bool_type| **greaterThanEqual**\ (\ |vec_type| x, |vec_type| y) - Perform a component-wise greater-than-or-equal comparison of two vectors. + Perform a :ref:`component-wise` greater-than-or-equal comparison of two vectors. :param x: the first vector for comparison. @@ -1980,9 +2003,9 @@ Comparison Functions .. rst-class:: classref-method -|vec_bool_type| **equal** ( |vec_type| x, |vec_type| y ) +|vec_bool_type| **equal**\ (\ |vec_type| x, |vec_type| y) - Perform a component-wise equal-to comparison of two vectors. + Perform a :ref:`component-wise` equal-to comparison of two vectors. :param x: the first vector for comparison. @@ -2006,15 +2029,15 @@ Comparison Functions .. rst-class:: classref-method -|vec_bool_type| **notEqual** ( |vec_type| x, |vec_type| y ) +|vec_bool_type| **notEqual**\ (\ |vec_type| x, |vec_type| y) - Perform a component-wise not-equal-to comparison of two vectors. + Perform a :ref:`component-wise` not-equal-to comparison of two vectors. :param x: the first vector for comparison. :param y: - the first vector for comparison. + the second vector for comparison. :return: a boolean vector in which each element i is computed as ``x[i] != y[i]``. @@ -2032,7 +2055,7 @@ Comparison Functions .. rst-class:: classref-method -bool **any** ( |vec_bool_type| x ) +bool **any**\ (\ |vec_bool_type| x) Check whether any element of a boolean vector is true. @@ -2066,7 +2089,7 @@ bool **any** ( |vec_bool_type| x ) .. rst-class:: classref-method -bool **all** ( |vec_bool_type| x ) +bool **all**\ (\ |vec_bool_type| x) Check whether all elements of a boolean vector are true. @@ -2096,13 +2119,11 @@ bool **all** ( |vec_bool_type| x ) ---- - - .. _shader_func_not: .. rst-class:: classref-method -|vec_bool_type| **not** ( |vec_bool_type| x ) +|vec_bool_type| **not**\ (\ |vec_bool_type| x) Logically invert a boolean vector. @@ -2114,156 +2135,136 @@ bool **all** ( |vec_bool_type| x ) https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/not.xhtml -.. rst-class:: classref-item-separator + +.. rst-class:: classref-section-separator ---- -Texture Functions -^^^^^^^^^^^^^^^^^ - -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| ivec2 | :ref:`textureSize` ( |gsampler2D| s, int lod ) | Get the size of a texture. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| ivec2 | :ref:`textureSize` (samplerCube s, int lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| ivec2 | :ref:`textureSize` (samplerCubeArray s, int lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| ivec3 | :ref:`textureSize` ( |gsampler2DArray| s, int lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| ivec3 | :ref:`textureSize` ( |gsampler3D| s, int lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| vec2 | :ref:`textureQueryLod` ( |gsampler2D| s, vec2 p ) | Compute the level-of-detail that would be used to sample from a | -+--------------+-----------------------------------------------------------------------------------------------------+ texture. | -| vec3 | :ref:`textureQueryLod` ( |gsampler2DArray| s, vec2 p ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec2 | :ref:`textureQueryLod` ( |gsampler3D| s, vec3 p ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec2 | :ref:`textureQueryLod` (samplerCube s, vec3 p ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| int | :ref:`textureQueryLevels` ( |gsampler2D| s ) | Get the number of accessible mipmap levels of a texture. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| int | :ref:`textureQueryLevels` ( |gsampler2DArray| s ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| int | :ref:`textureQueryLevels` ( |gsampler3D| s ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| int | :ref:`textureQueryLevels` (samplerCube s ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`texture` ( |gsampler2D| s, vec2 p [, float bias] ) | Perform a texture read. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`texture` ( |gsampler2DArray| s, vec3 p [, float bias] ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |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] ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |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] ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureProj` ( |gsampler3D| s, vec4 p [, float bias] ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureLod` ( |gsampler2D| s, vec2 p, float lod ) | Perform a texture read at custom mipmap. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureLod` ( |gsampler2DArray| s, vec3 p, float lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureLod` ( |gsampler3D| s, vec3 p, float lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureLod` (samplerCube s, vec3 p, float lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureLod` (samplerCubeArray s, vec4 p, float lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec3 p, float lod ) | Performs a texture read with projection/LOD. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureProjLod` ( |gsampler2D| s, vec4 p, float lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureProjLod` ( |gsampler3D| s, vec4 p, float lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureGrad` ( |gsampler2D| s, vec2 p, vec2 dPdx, vec2 dPdy ) | Performs a texture read with explicit gradients. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureGrad` ( |gsampler2DArray| s, vec3 p, vec2 dPdx, vec2 dPdy ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureGrad` ( |gsampler3D| s, vec3 p, vec2 dPdx, vec2 dPdy ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureGrad` (samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureGrad` (samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy )| Performs a texture read with projection/LOD and with explicit | -+--------------+-----------------------------------------------------------------------------------------------------+ gradients. | -| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy )| | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureProjGrad` ( |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy )| | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`texelFetch` ( |gsampler2D| s, ivec2 p, int lod ) | Fetches a single texel using integer coordinates. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`texelFetch` ( |gsampler2DArray| s, ivec3 p, int lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`texelFetch` ( |gsampler3D| s, ivec3 p, int lod ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |gvec4_type| | :ref:`textureGather` ( |gsampler2D| s, vec2 p [, int comps] ) | Gathers four texels from a texture. | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| |gvec4_type| | :ref:`textureGather` ( |gsampler2DArray| s, vec3 p [, int comps] ) | | -+--------------+-----------------------------------------------------------------------------------------------------+ | -| vec4 | :ref:`textureGather` (samplerCube s, vec3 p [, int comps] ) | | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdx` ( |vec_type| p ) | Derivative with respect to ``x`` window coordinate, | -| | | automatic granularity. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdxCoarse` ( |vec_type| p ) | Derivative with respect to ``x`` window coordinate, | -| | | course granularity. | -| | | | -| | | Not available on ``gl_compatibility`` profile. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdxFine` ( |vec_type| p ) | Derivative with respect to ``x`` window coordinate, | -| | | fine granularity. | -| | | | -| | | Not available on ``gl_compatibility`` profile. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdy` ( |vec_type| p ) | Derivative with respect to ``y`` window coordinate. | -| | | Automatic granularity. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdyCoarse` ( |vec_type| p ) | Derivative with respect to ``y`` window coordinate, | -| | | course granularity. | -| | | | -| | | Not available on ``gl_compatibility`` profile. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`dFdyFine` ( |vec_type| p ) | Derivative with respect to ``y`` window coordinate, | -| | | fine granularity. | -| | | | -| | | Not available on ``gl_compatibility`` profile. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`fwidth` ( |vec_type| p ) | Sum of absolute derivative in ``x`` and ``y``. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`fwidthCoarse` ( |vec_type| p ) | Sum of absolute derivative in ``x`` and ``y``. | -| | | | -| | | Not available on ``gl_compatibility`` profile. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`fwidthFine` ( |vec_type| p ) | Sum of absolute derivative in ``x`` and ``y``. | -| | | | -| | | Not available on ``gl_compatibility`` profile. | -+--------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -.. rst-class:: classref-section-separator ----- +.. rst-class:: classref-reftable-group + +Texture Functions +----------------- + +.. table:: + :class: nowrap-col2 + :widths: auto + + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | | ivec2 | | :ref:`textureSize`\ (\ |gsampler2D| s, int lod) | Get the size of a texture. | + | | ivec2 | | :ref:`textureSize`\ (\ samplerCube s, int lod) | | + | | ivec2 | | :ref:`textureSize`\ (\ samplerCubeArray s, int lod) | | + | | ivec3 | | :ref:`textureSize`\ (\ |gsampler2DArray| s, int lod) | | + | | ivec3 | | :ref:`textureSize`\ (\ |gsampler3D| s, int lod) | | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | | vec2 | | :ref:`textureQueryLod`\ (\ |gsampler2D| s, vec2 p) | Compute the level-of-detail that would be used to sample from a | + | | vec3 | | :ref:`textureQueryLod`\ (\ |gsampler2DArray| s, vec2 p) | texture. | + | | vec2 | | :ref:`textureQueryLod`\ (\ |gsampler3D| s, vec3 p) | | + | | vec2 | | :ref:`textureQueryLod`\ (\ samplerCube s, vec3 p) | | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | | int | | :ref:`textureQueryLevels`\ (\ |gsampler2D| s) | Get the number of accessible mipmap levels of a texture. | + | | int | | :ref:`textureQueryLevels`\ (\ |gsampler2DArray| s) | | + | | int | | :ref:`textureQueryLevels`\ (\ |gsampler3D| s) | | + | | int | | :ref:`textureQueryLevels`\ (\ samplerCube s) | | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | | |gvec4_type| | | :ref:`texture`\ (\ |gsampler2D| s, vec2 p [, float bias] ) | Perform a texture read. | + | | |gvec4_type| | | :ref:`texture`\ (\ |gsampler2DArray| s, vec3 p [, float bias] ) | | + | | |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] ) | | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | | |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] ) | | + | | |gvec4_type| | | :ref:`textureProj`\ (\ |gsampler3D| s, vec4 p [, float bias] ) | | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | | |gvec4_type| | | :ref:`textureLod`\ (\ |gsampler2D| s, vec2 p, float lod) | Perform a texture read at custom mipmap. | + | | |gvec4_type| | | :ref:`textureLod`\ (\ |gsampler2DArray| s, vec3 p, float lod) | | + | | |gvec4_type| | | :ref:`textureLod`\ (\ |gsampler3D| s, vec3 p, float lod) | | + | | vec4 | | :ref:`textureLod`\ (\ samplerCube s, vec3 p, float lod) | | + | | vec4 | | :ref:`textureLod`\ (\ samplerCubeArray s, vec4 p, float lod) | | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | | |gvec4_type| | | :ref:`textureProjLod`\ (\ |gsampler2D| s, vec3 p, float lod) | Performs a texture read with projection/LOD. | + | | |gvec4_type| | | :ref:`textureProjLod`\ (\ |gsampler2D| s, vec4 p, float lod) | | + | | |gvec4_type| | | :ref:`textureProjLod`\ (\ |gsampler3D| s, vec4 p, float lod) | | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | | |gvec4_type| | | :ref:`textureGrad`\ (\ |gsampler2D| s, vec2 p, vec2 dPdx, vec2 dPdy) | Performs a texture read with explicit gradients. | + | | |gvec4_type| | | :ref:`textureGrad`\ (\ |gsampler2DArray| s, vec3 p, vec2 dPdx, vec2 dPdy) | | + | | |gvec4_type| | | :ref:`textureGrad`\ (\ |gsampler3D| s, vec3 p, vec2 dPdx, vec2 dPdy) | | + | | vec4 | | :ref:`textureGrad`\ (\ samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy) | | + | | vec4 | | :ref:`textureGrad`\ (\ samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy) | | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | | |gvec4_type| | | :ref:`textureProjGrad`\ (\ |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy) | Performs a texture read with projection/LOD and with explicit | + | | |gvec4_type| | | :ref:`textureProjGrad`\ (\ |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy) | | + | | |gvec4_type| | | :ref:`textureProjGrad`\ (\ |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy) | | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | | |gvec4_type| | | :ref:`texelFetch`\ (\ |gsampler2D| s, ivec2 p, int lod) | Fetches a single texel using integer coordinates. | + | | |gvec4_type| | | :ref:`texelFetch`\ (\ |gsampler2DArray| s, ivec3 p, int lod) | | + | | |gvec4_type| | | :ref:`texelFetch`\ (\ |gsampler3D| s, ivec3 p, int lod) | | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | | |gvec4_type| | | :ref:`textureGather`\ (\ |gsampler2D| s, vec2 p [, int comps] ) | Gathers four texels from a texture. | + | | |gvec4_type| | | :ref:`textureGather`\ (\ |gsampler2DArray| s, vec3 p [, int comps] ) | | + | | vec4 | | :ref:`textureGather`\ (\ samplerCube s, vec3 p [, int comps] ) | | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | |vec_type| | :ref:`dFdx`\ (\ |vec_type| p) | Derivative with respect to ``x`` window coordinate, | + | | | automatic granularity. | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | |vec_type| | :ref:`dFdxCoarse`\ (\ |vec_type| p) | Derivative with respect to ``x`` window coordinate, | + | | | course granularity. | + | | | | + | | | Not available on ``gl_compatibility`` profile. | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | |vec_type| | :ref:`dFdxFine`\ (\ |vec_type| p) | Derivative with respect to ``x`` window coordinate, | + | | | fine granularity. | + | | | | + | | | Not available on ``gl_compatibility`` profile. | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | |vec_type| | :ref:`dFdy`\ (\ |vec_type| p) | Derivative with respect to ``y`` window coordinate, | + | | | automatic granularity. | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | |vec_type| | :ref:`dFdyCoarse`\ (\ |vec_type| p) | Derivative with respect to ``y`` window coordinate, | + | | | course granularity. | + | | | | + | | | Not available on ``gl_compatibility`` profile. | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | |vec_type| | :ref:`dFdyFine`\ (\ |vec_type| p) | Derivative with respect to ``y`` window coordinate, | + | | | fine granularity. | + | | | | + | | | Not available on ``gl_compatibility`` profile. | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | |vec_type| | :ref:`fwidth`\ (\ |vec_type| p) | Sum of absolute derivative in ``x`` and ``y``. | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | |vec_type| | :ref:`fwidthCoarse`\ (\ |vec_type| p) | Sum of absolute derivative in ``x`` and ``y``. | + | | | | + | | | Not available on ``gl_compatibility`` profile. | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | |vec_type| | :ref:`fwidthFine`\ (\ |vec_type| p) | Sum of absolute derivative in ``x`` and ``y``. | + | | | | + | | | Not available on ``gl_compatibility`` profile. | + +------------------+---------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + + +.. rst-class:: classref-descriptions-group + +Texture Function Descriptions +""""""""""""""""""""""""""""""""""""" + .. _shader_func_textureSize: .. rst-class:: classref-method -| ivec2 **textureSize** ( |gsampler2D| s, int lod ) -| ivec2 **textureSize** ( samplerCube s, int lod ) -| ivec2 **textureSize** ( samplerCubeArray s, int lod ) -| ivec3 **textureSize** ( |gsampler2DArray| s, int lod ) -| ivec3 **textureSize** ( |gsampler3D| s, int lod ) +| ivec2 **textureSize**\ (\ |gsampler2D| s, int lod) +| ivec2 **textureSize**\ (\ samplerCube s, int lod) +| ivec2 **textureSize**\ (\ samplerCubeArray s, int lod) +| ivec3 **textureSize**\ (\ |gsampler2DArray| s, int lod) +| ivec3 **textureSize**\ (\ |gsampler3D| s, int lod) Retrieve the dimensions of a level of a texture. @@ -2295,7 +2296,7 @@ Texture Functions .. rst-class:: classref-method -vec2 **textureQueryLod** ( |gsampler2D| s, vec2 p ) +vec2 **textureQueryLod**\ (\ |gsampler2D| s, vec2 p) Compute the level-of-detail that would be used to sample from a texture. @@ -2324,10 +2325,10 @@ vec2 **textureQueryLod** ( |gsampler2D| s, vec2 p ) .. rst-class:: classref-method -vec2 **textureQueryLod** ( |gsampler2D| s, vec2 p ) -vec2 **textureQueryLod** ( |gsampler2DArray| s, vec2 p ) -vec2 **textureQueryLod** ( |gsampler3D| s, vec3 p ) -vec2 **textureQueryLod** ( samplerCube s, vec3 p ) +vec2 **textureQueryLod**\ (\ |gsampler2D| s, vec2 p) +vec2 **textureQueryLod**\ (\ |gsampler2DArray| s, vec2 p) +vec2 **textureQueryLod**\ (\ |gsampler3D| s, vec3 p) +vec2 **textureQueryLod**\ (\ samplerCube s, vec3 p) .. note:: Available only in the fragment shader. @@ -2361,10 +2362,10 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) .. rst-class:: classref-method -| int **textureQueryLevels** ( |gsampler2D| s ) -| int **textureQueryLevels** ( |gsampler2DArray| s ) -| int **textureQueryLevels** ( |gsampler3D| s ) -| int **textureQueryLevels** ( samplerCube s ) +| int **textureQueryLevels**\ (\ |gsampler2D| s) +| int **textureQueryLevels**\ (\ |gsampler2DArray| s) +| int **textureQueryLevels**\ (\ |gsampler3D| s) +| int **textureQueryLevels**\ (\ samplerCube s) Compute the number of accessible mipmap levels of a texture. @@ -2389,11 +2390,11 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) .. rst-class:: classref-method -| |gvec4_type| **texture** ( |gsampler2D| s, vec2 p [, float bias] ) -| |gvec4_type| **texture** ( |gsampler2DArray| s, vec3 p [, float bias] ) -| |gvec4_type| **texture** ( |gsampler3D| s, vec3 p [, float bias] ) -| vec4 **texture** ( samplerCube s, vec3 p [, float bias] ) -| vec4 **texture** ( samplerCubeArray s, vec4 p [, float bias] ) +| |gvec4_type| **texture**\ (\ |gsampler2D| s, vec2 p [, float bias] ) +| |gvec4_type| **texture**\ (\ |gsampler2DArray| s, vec3 p [, float bias] ) +| |gvec4_type| **texture**\ (\ |gsampler3D| s, vec3 p [, float bias] ) +| | vec4 **texture**\ (\ samplerCube s, vec3 p [, float bias] ) +| | vec4 **texture**\ (\ samplerCubeArray s, vec4 p [, float bias] ) Retrieves texels from a texture. @@ -2430,9 +2431,9 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) .. rst-class:: classref-method -| |gvec4_type| **textureProj** ( |gsampler2D| s, vec3 p [, float bias] ) -| |gvec4_type| **textureProj** ( |gsampler2D| s, vec4 p [, float bias] ) -| |gvec4_type| **textureProj** ( |gsampler3D| s, vec4 p [, float bias] ) +| |gvec4_type| **textureProj**\ (\ |gsampler2D| s, vec3 p [, float bias] ) +| |gvec4_type| **textureProj**\ (\ |gsampler2D| s, vec4 p [, float bias] ) +| |gvec4_type| **textureProj**\ (\ |gsampler3D| s, vec4 p [, float bias] ) Perform a texture lookup with projection. @@ -2465,11 +2466,11 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) .. rst-class:: classref-method -| |gvec4_type| **textureLod** ( |gsampler2D| s, vec2 p, float lod ) -| |gvec4_type| **textureLod** ( |gsampler2DArray| s, vec3 p, float lod ) -| |gvec4_type| **textureLod** ( |gsampler3D| s, vec3 p, float lod ) -| vec4 **textureLod** ( samplerCube s, vec3 p, float lod ) -| vec4 **textureLod** ( samplerCubeArray s, vec4 p, float lod ) +| |gvec4_type| **textureLod**\ (\ |gsampler2D| s, vec2 p, float lod) +| |gvec4_type| **textureLod**\ (\ |gsampler2DArray| s, vec3 p, float lod) +| |gvec4_type| **textureLod**\ (\ |gsampler3D| s, vec3 p, float lod) +| | vec4 **textureLod**\ (\ samplerCube s, vec3 p, float lod) +| | vec4 **textureLod**\ (\ samplerCubeArray s, vec4 p, float lod) Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with an explicit level-of-detail as specified in ``lod``. ``lod`` specifies λbase and sets the @@ -2503,9 +2504,9 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) .. rst-class:: classref-method -|gvec4_type| **textureProjLod** ( |gsampler2D| s, vec3 p, float lod ) -|gvec4_type| **textureProjLod** ( |gsampler2D| s, vec4 p, float lod ) -|gvec4_type| **textureProjLod** ( |gsampler3D| s, vec4 p, float lod ) +|gvec4_type| **textureProjLod**\ (\ |gsampler2D| s, vec3 p, float lod) +|gvec4_type| **textureProjLod**\ (\ |gsampler2D| s, vec4 p, float lod) +|gvec4_type| **textureProjLod**\ (\ |gsampler3D| s, vec4 p, float lod) Performs a texture lookup with projection from an explicitly specified level-of-detail. @@ -2540,11 +2541,11 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) .. rst-class:: classref-method -| |gvec4_type| **textureGrad** ( |gsampler2D| s, vec2 p, vec2 dPdx, vec2 dPdy ) -| |gvec4_type| **textureGrad** ( |gsampler2DArray| s, vec3 p, vec2 dPdx, vec2 dPdy ) -| |gvec4_type| **textureGrad** ( |gsampler3D| s, vec3 p, vec2 dPdx, vec2 dPdy ) -| vec4 **textureGrad** ( samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy ) -| vec4 **textureGrad** ( samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy ) +| |gvec4_type| **textureGrad**\ (\ |gsampler2D| s, vec2 p, vec2 dPdx, vec2 dPdy) +| |gvec4_type| **textureGrad**\ (\ |gsampler2DArray| s, vec3 p, vec2 dPdx, vec2 dPdy) +| |gvec4_type| **textureGrad**\ (\ |gsampler3D| s, vec3 p, vec2 dPdx, vec2 dPdy) +| | vec4 **textureGrad**\ (\ samplerCube s, vec3 p, vec3 dPdx, vec3 dPdy) +| | vec4 **textureGrad**\ (\ samplerCubeArray s, vec3 p, vec3 dPdx, vec3 dPdy) Performs a texture lookup at coordinate ``p`` from the texture bound to sampler with explicit texture coordinate gradiends as specified in ``dPdx`` and ``dPdy``. Set: - ``δs/δx=δp/δx`` for a 1D texture, ``δp.s/δx`` otherwise @@ -2584,9 +2585,9 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) .. rst-class:: classref-method -| |gvec4_type| **textureProjGrad** ( |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy ) -| |gvec4_type| **textureProjGrad** ( |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy ) -| |gvec4_type| **textureProjGrad** ( |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy ) +| |gvec4_type| **textureProjGrad**\ (\ |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy) +| |gvec4_type| **textureProjGrad**\ (\ |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy) +| |gvec4_type| **textureProjGrad**\ (\ |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy) Perform a texture lookup with projection and explicit gradients. @@ -2621,9 +2622,9 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) .. rst-class:: classref-method -| |gvec4_type| **texelFetch** ( |gsampler2D| s, ivec2 p, int lod ) -| |gvec4_type| **texelFetch** ( |gsampler2DArray| s, ivec3 p, int lod ) -| |gvec4_type| **texelFetch** ( |gsampler3D| s, ivec3 p, int lod ) +| |gvec4_type| **texelFetch**\ (\ |gsampler2D| s, ivec2 p, int lod) +| |gvec4_type| **texelFetch**\ (\ |gsampler2DArray| s, ivec3 p, int lod) +| |gvec4_type| **texelFetch**\ (\ |gsampler3D| s, ivec3 p, int lod) Performs a lookup of a single texel from texture coordinate ``p`` in the texture bound to sampler. @@ -2652,9 +2653,9 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) .. rst-class:: classref-method -| |gvec4_type| **textureGather** ( |gsampler2D| s, vec2 p [, int comps] ) -| |gvec4_type| **textureGather** ( |gsampler2DArray| s, vec3 p [, int comps] ) -| vec4 **textureGather** ( samplerCube s, vec3 p [, int comps] ) +| |gvec4_type| **textureGather**\ (\ |gsampler2D| s, vec2 p [, int comps] ) +| |gvec4_type| **textureGather**\ (\ |gsampler2DArray| s, vec3 p [, int comps] ) +| | vec4 **textureGather**\ (\ samplerCube s, vec3 p [, int comps] ) Gathers four texels from a texture. @@ -2690,7 +2691,7 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) .. rst-class:: classref-method -|vec_type| **dFdx** ( |vec_type| p ) +|vec_type| **dFdx**\ (\ |vec_type| p) .. note:: Available only in the fragment shader. @@ -2723,7 +2724,7 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) .. rst-class:: classref-method -|vec_type| **dFdxCoarse** ( |vec_type| p ) +|vec_type| **dFdxCoarse**\ (\ |vec_type| p) .. note:: | Available only in the fragment shader. @@ -2759,7 +2760,7 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) .. rst-class:: classref-method -|vec_type| **dFdxFine** ( |vec_type| p ) +|vec_type| **dFdxFine**\ (\ |vec_type| p) .. note:: | Available only in the fragment shader. @@ -2792,7 +2793,7 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) .. rst-class:: classref-method -|vec_type| **dFdy** ( |vec_type| p ) +|vec_type| **dFdy**\ (\ |vec_type| p) .. note:: Available only in the fragment shader @@ -2824,7 +2825,7 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) .. rst-class:: classref-method -|vec_type| **dFdyCoarse** ( |vec_type| p ) +|vec_type| **dFdyCoarse**\ (\ |vec_type| p) .. note:: | Available only in the fragment shader. @@ -2859,7 +2860,7 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) .. rst-class:: classref-method -|vec_type| **dFdyFine** ( |vec_type| p ) +|vec_type| **dFdyFine**\ (\ |vec_type| p) .. note:: | Available only in the fragment shader. @@ -2892,7 +2893,7 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) .. rst-class:: classref-method -|vec_type| **fwidth** ( |vec_type| p ) +|vec_type| **fwidth**\ (\ |vec_type| p) Return the sum of the absolute value of derivatives in x and y. @@ -2919,7 +2920,7 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) .. rst-class:: classref-method -|vec_type| **fwidthCoarse** ( |vec_type| p ) +|vec_type| **fwidthCoarse**\ (\ |vec_type| p) .. note:: | Available only in the fragment shader. @@ -2950,7 +2951,7 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) .. rst-class:: classref-method -|vec_type| **fwidthFine** ( |vec_type| p ) +|vec_type| **fwidthFine**\ (\ |vec_type| p) .. note:: | Available only in the fragment shader. @@ -2970,52 +2971,62 @@ vec2 **textureQueryLod** ( samplerCube s, vec3 p ) https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/fwidthFine.xhtml -.. rst-class:: classref-item-separator + +.. rst-class:: classref-section-separator ---- + + + + + + + + + +.. rst-class:: classref-reftable-group + Packing/Unpacking Functions -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------- These functions convert floating point numbers into various sized integers and then pack those integers into a single 32bit unsigned integer. The 'unpack' functions perform the opposite operation, returning the original floating point numbers. -+------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packHalf2x16` (vec2 v ) | Convert two 32-bit floats to 16 bit floats and pack them. | -+------+--------------------------------------------------------------+ + -| vec2 | :ref:`unpackHalf2x16` (uint v ) | | -+------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packUnorm2x16` (vec2 v ) | Convert two normalized (range 0..1) 32-bit floats | -+------+--------------------------------------------------------------+ to 16-bit floats and pack them. + -| vec2 | :ref:`unpackUnorm2x16` (uint v )| | -+------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packSnorm2x16` (vec2 v ) | Convert two signed normalized (range -1..1) 32-bit floats | -+------+--------------------------------------------------------------+ to 16-bit floats and pack them. + -| vec2 | :ref:`unpackSnorm2x16` (uint v )| | -+------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packUnorm4x8` (vec4 v ) | Convert four normalized (range 0..1) 32-bit floats | -+------+--------------------------------------------------------------+ into 8-bit floats and pack them. + -| vec4 | :ref:`unpackUnorm4x8` (uint v ) | | -+------+--------------------------------------------------------------+--------------------------------------------------------------+ -| uint | :ref:`packSnorm4x8` (vec4 v ) | Convert four signed normalized (range -1..1) 32-bit floats | -+------+--------------------------------------------------------------+ into 8-bit floats and pack them. + -| vec4 | :ref:`unpackSnorm4x8` (uint v ) | | -+------+--------------------------------------------------------------+--------------------------------------------------------------+ - -.. rst-class:: classref-section-separator - ----- +.. table:: + :class: nowrap-col2 + :widths: auto + + +------------+------------------------------------------------------------------------+--------------------------------------------------------------+ + | | uint | | :ref:`packHalf2x16`\ (\ vec2 v) | Convert two 32-bit floats to 16 bit floats and pack them. | + | | vec2 | | :ref:`unpackHalf2x16`\ (\ uint v) | | + +------------+------------------------------------------------------------------------+--------------------------------------------------------------+ + | | uint | | :ref:`packUnorm2x16`\ (\ vec2 v) | Convert two normalized (range 0..1) 32-bit floats | + | | vec2 | | :ref:`unpackUnorm2x16`\ (\ uint v) | to 16-bit floats and pack them. | + +------------+------------------------------------------------------------------------+--------------------------------------------------------------+ + | | uint | | :ref:`packSnorm2x16`\ (\ vec2 v) | Convert two signed normalized (range -1..1) 32-bit floats | + | | vec2 | | :ref:`unpackSnorm2x16`\ (\ uint v) | to 16-bit floats and pack them. | + +------------+------------------------------------------------------------------------+--------------------------------------------------------------+ + | | uint | | :ref:`packUnorm4x8`\ (\ vec4 v) | Convert four normalized (range 0..1) 32-bit floats | + | | vec4 | | :ref:`unpackUnorm4x8`\ (\ uint v) | into 8-bit floats and pack them. | + +------------+------------------------------------------------------------------------+--------------------------------------------------------------+ + | | uint | | :ref:`packSnorm4x8`\ (\ vec4 v) | Convert four signed normalized (range -1..1) 32-bit floats | + | | vec4 | | :ref:`unpackSnorm4x8`\ (\ uint v) | into 8-bit floats and pack them. | + +------------+------------------------------------------------------------------------+--------------------------------------------------------------+ +.. rst-class:: classref-descriptions-group +Packing/Unpacking Function Descriptions +"""""""""""""""""""""""""""""""""""""""" .. _shader_func_packHalf2x16: .. rst-class:: classref-method -uint **packHalf2x16** ( vec2 v ) +uint **packHalf2x16**\ (\ vec2 v) Convert two 32-bit floating-point quantities to 16-bit floating point quantities and pack them into a single 32-bit integer. @@ -3043,7 +3054,7 @@ uint **packHalf2x16** ( vec2 v ) .. rst-class:: classref-method -vec2 **unpackHalf2x16** ( uint v ) +vec2 **unpackHalf2x16**\ (\ uint v) Inverse of :ref:`packHalf2x16`. @@ -3070,7 +3081,7 @@ vec2 **unpackHalf2x16** ( uint v ) .. rst-class:: classref-method -uint **packUnorm2x16** ( vec2 v ) +uint **packUnorm2x16**\ (\ vec2 v) Pack floating-point values into an unsigned integer. @@ -3102,7 +3113,7 @@ uint **packUnorm2x16** ( vec2 v ) .. rst-class:: classref-method -vec2 **unpackUnorm2x16** ( uint v ) +vec2 **unpackUnorm2x16**\ (\ uint v) Unpack floating-point values from an unsigned integer. @@ -3131,7 +3142,7 @@ vec2 **unpackUnorm2x16** ( uint v ) .. rst-class:: classref-method -uint **packSnorm2x16** ( vec2 v ) +uint **packSnorm2x16**\ (\ vec2 v) Pack floating-point values into an unsigned integer. @@ -3162,7 +3173,7 @@ uint **packSnorm2x16** ( vec2 v ) .. rst-class:: classref-method -vec2 **unpackSnorm2x16** ( uint v ) +vec2 **unpackSnorm2x16**\ (\ uint v) Unpack floating-point values from an unsigned integer. @@ -3191,7 +3202,7 @@ vec2 **unpackSnorm2x16** ( uint v ) .. rst-class:: classref-method -uint **packUnorm4x8** ( vec4 v ) +uint **packUnorm4x8**\ (\ vec4 v) Pack floating-point values into an unsigned integer. @@ -3223,7 +3234,7 @@ uint **packUnorm4x8** ( vec4 v ) .. rst-class:: classref-method -vec4 **unpackUnorm4x8** ( uint v ) +vec4 **unpackUnorm4x8**\ (\ uint v) Unpack floating-point values from an unsigned integer. @@ -3252,7 +3263,7 @@ vec4 **unpackUnorm4x8** ( uint v ) .. rst-class:: classref-method -uint **packSnorm4x8** ( vec4 v ) +uint **packSnorm4x8**\ (\ vec4 v) Pack floating-point values into an unsigned integer. @@ -3284,7 +3295,7 @@ uint **packSnorm4x8** ( vec4 v ) .. rst-class:: classref-method -vec4 **unpackSnorm4x8** ( uint v ) +vec4 **unpackSnorm4x8**\ (\ uint v) Unpack floating-point values from an unsigned integer. @@ -3302,67 +3313,76 @@ vec4 **unpackSnorm4x8** ( uint v ) https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/unpackUnorm.xhtml -.. rst-class:: classref-item-separator + +.. rst-class:: classref-section-separator ---- -Bitwise operations -^^^^^^^^^^^^^^^^^^ - -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`bitfieldExtract` ( |vec_int_type| value, int offset, int bits ) | Extracts a range of bits from an integer. | -| | | | -| |vec_uint_type| | :ref:`bitfieldExtract` ( |vec_uint_type| value, int offset, int bits ) | | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`bitfieldInsert` ( |vec_int_type| base, |vec_int_type| insert, int offset, int bits ) | Insert a range of bits into an integer. | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`bitfieldInsert` (|vec_uint_type| base, |vec_uint_type| insert, int offset, int bits ) | | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`bitfieldReverse` ( |vec_int_type| value ) | Reverse the order of bits in an integer. | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`bitfieldReverse` ( |vec_uint_type| value ) | | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`bitCount` ( |vec_int_type| value ) | Counts the number of 1 bits in an integer. | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`bitCount` ( |vec_uint_type| value ) | | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`findLSB` ( |vec_int_type| value ) | Find the index of the least significant bit set to 1 in an integer. | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`findLSB` ( |vec_uint_type| value ) | | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_int_type| | :ref:`findMSB` ( |vec_int_type| value ) | Find the index of the most significant bit set to 1 in an integer. | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | -| |vec_uint_type| | :ref:`findMSB` ( |vec_uint_type| value ) | | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |void| | :ref:`imulExtended` ( |vec_int_type| x, |vec_int_type| y, out |vec_int_type| msb, out |vec_int_type| lsb ) | Multiplies two 32-bit numbers and produce a 64-bit result. | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+ | -| |void| | :ref:`umulExtended` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| msb, out |vec_uint_type| lsb )| | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_uint_type| | :ref:`uaddCarry` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| carry ) | Adds two unsigned integers and generates carry. | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_uint_type| | :ref:`usubBorrow` (|vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| borrow ) | Subtracts two unsigned integers and generates borrow. | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`ldexp` (|vec_type| x, out |vec_int_type| exp ) | Assemble a floating-point number from a value and exponent. | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -| |vec_type| | :ref:`frexp` (|vec_type| x, out |vec_int_type| exp ) | Splits a floating-point number (``x``) into significand integral | -| | | components | -+-----------------+----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ -.. rst-class:: classref-section-separator ----- + + + + +.. rst-class:: classref-reftable-group + +Bitwise Functions +------------------- + +.. table:: + :class: nowrap-col2 + :widths: auto + + +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | | |vec_int_type| | | :ref:`bitfieldExtract`\ (\ |vec_int_type| value, int offset, int bits) | Extracts a range of bits from an integer. | + | | |vec_uint_type| | | :ref:`bitfieldExtract`\ (\ |vec_uint_type| value, int offset, int bits) | | + +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | | |vec_int_type| | | :ref:`bitfieldInsert`\ (\ |vec_int_type| base, |vec_int_type| insert, int offset, int bits) | Insert a range of bits into an integer. | + | | |vec_uint_type| | | :ref:`bitfieldInsert`\ (\ |vec_uint_type| base, |vec_uint_type| insert, int offset, int bits) | | + +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | | |vec_int_type| | | :ref:`bitfieldReverse`\ (\ |vec_int_type| value) | Reverse the order of bits in an integer. | + | | |vec_uint_type| | | :ref:`bitfieldReverse`\ (\ |vec_uint_type| value) | | + +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | | |vec_int_type| | | :ref:`bitCount`\ (\ |vec_int_type| value) | Counts the number of 1 bits in an integer. | + | | |vec_uint_type| | | :ref:`bitCount`\ (\ |vec_uint_type| value) | | + +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | | |vec_int_type| | | :ref:`findLSB`\ (\ |vec_int_type| value) | Find the index of the least significant bit set to 1 in an integer. | + | | |vec_uint_type| | | :ref:`findLSB`\ (\ |vec_uint_type| value) | | + +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | | |vec_int_type| | | :ref:`findMSB`\ (\ |vec_int_type| value) | Find the index of the most significant bit set to 1 in an integer. | + | | |vec_uint_type| | | :ref:`findMSB`\ (\ |vec_uint_type| value) | | + +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | | |void| | | :ref:`imulExtended`\ (\ |vec_int_type| x, |vec_int_type| y, out |vec_int_type| msb, out |vec_int_type| lsb) | Multiplies two 32-bit numbers and produce a 64-bit result. | + | | |void| | | :ref:`umulExtended`\ (\ |vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| msb, out |vec_uint_type| lsb) | | + +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | |vec_uint_type| | :ref:`uaddCarry`\ (\ |vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| carry) | Adds two unsigned integers and generates carry. | + +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | |vec_uint_type| | :ref:`usubBorrow`\ (\ |vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| borrow) | Subtracts two unsigned integers and generates borrow. | + +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | |vec_type| | :ref:`ldexp`\ (\ |vec_type| x, out |vec_int_type| exp) | Assemble a floating-point number from a value and exponent. | + +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + | |vec_type| | :ref:`frexp`\ (\ |vec_type| x, out |vec_int_type| exp) | Splits a floating-point number (``x``) into significand integral | + | | | components | + +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+ + + +.. rst-class:: classref-descriptions-group + +Bitwise Function Descriptions +""""""""""""""""""""""""""""""" + .. _shader_func_bitfieldExtract: .. rst-class:: classref-method -|vec_int_type| **bitfieldExtract** ( |vec_int_type| value, int offset, int bits ) +|vec_int_type| **bitfieldExtract**\ (\ |vec_int_type| value, int offset, int bits) Eextracts a subset of the bits of value and returns it in the least significant bits of the result. The range of bits extracted is ``[offset, offset + bits - 1]``. @@ -3398,7 +3418,9 @@ Bitwise operations .. rst-class:: classref-method -|vec_uint_type| **bitfieldExtract** ( |vec_uint_type| value, int offset, int bits ) +|vec_uint_type| **bitfieldExtract**\ (\ |vec_uint_type| value, int offset, int bits) + + |componentwise| Eextracts a subset of the bits of value and returns it in the least significant bits of the result. The range of bits extracted is ``[offset, offset + bits - 1]``. @@ -3432,14 +3454,14 @@ Bitwise operations ---- - - .. _shader_func_bitfieldInsert: .. rst-class:: classref-method -| |vec_int_type| **bitfieldInsert** ( |vec_int_type| base, |vec_int_type| insert, int offset, int bits ) -| |vec_uint_type| **bitfieldInsert** ( |vec_uint_type| base, |vec_uint_type| insert, int offset, int bits ) +| |vec_int_type| **bitfieldInsert**\ (\ |vec_int_type| base, |vec_int_type| insert, int offset, int bits) +| |vec_uint_type| **bitfieldInsert**\ (\ |vec_uint_type| base, |vec_uint_type| insert, int offset, int bits) + + |componentwise| Inserts the ``bits`` least significant bits of ``insert`` into ``base`` at offset ``offset``. @@ -3475,14 +3497,14 @@ Bitwise operations ---- - - .. _shader_func_bitfieldReverse: .. rst-class:: classref-method -| |vec_int_type| **bitfieldReverse** ( |vec_int_type| value ) -| |vec_uint_type| **bitfieldReverse** ( |vec_uint_type| value ) +| |vec_int_type| **bitfieldReverse**\ (\ |vec_int_type| value) +| |vec_uint_type| **bitfieldReverse**\ (\ |vec_uint_type| value) + + |componentwise| Reverse the order of bits in an integer. @@ -3501,14 +3523,14 @@ Bitwise operations ---- - - .. _shader_func_bitCount: .. rst-class:: classref-method -| |vec_int_type| **bitCount** ( |vec_int_type| value ) -| |vec_uint_type| **bitCount** ( |vec_uint_type| value ) +| |vec_int_type| **bitCount**\ (\ |vec_int_type| value) +| |vec_uint_type| **bitCount**\ (\ |vec_uint_type| value) + + |componentwise| Counts the number of 1 bits in an integer. @@ -3525,14 +3547,14 @@ Bitwise operations ---- - - .. _shader_func_findLSB: .. rst-class:: classref-method -| |vec_int_type| **findLSB** ( |vec_int_type| value ) -| |vec_uint_type| **findLSB** ( |vec_uint_type| value ) +| |vec_int_type| **findLSB**\ (\ |vec_int_type| value) +| |vec_uint_type| **findLSB**\ (\ |vec_uint_type| value) + + |componentwise| Find the index of the least significant bit set to 1. @@ -3551,14 +3573,14 @@ Bitwise operations ---- - - .. _shader_func_findMSB: .. rst-class:: classref-method -|vec_int_type| **findMSB** ( |vec_int_type| value ) -|vec_uint_type| **findMSB** ( |vec_uint_type| value ) +|vec_int_type| **findMSB**\ (\ |vec_int_type| value) +|vec_uint_type| **findMSB**\ (\ |vec_uint_type| value) + + |componentwise| Find the index of the most significant bit set to 1. @@ -3582,13 +3604,13 @@ Bitwise operations ---- - - .. _shader_func_imulExtended: .. rst-class:: classref-method -|void| **imulExtended** ( |vec_int_type| x, |vec_int_type| y, out |vec_int_type| msb, out |vec_int_type| lsb ) +|void| **imulExtended**\ (\ |vec_int_type| x, |vec_int_type| y, out |vec_int_type| msb, out |vec_int_type| lsb) + + |componentwise| Perform 32-bit by 32-bit signed multiplication to produce a 64-bit result. @@ -3613,13 +3635,13 @@ Bitwise operations ---- - - .. _shader_func_umulExtended: .. rst-class:: classref-method -|void| **umulExtended** ( |vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| msb, out |vec_uint_type| lsb ) +|void| **umulExtended**\ (\ |vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| msb, out |vec_uint_type| lsb) + + |componentwise| Perform 32-bit by 32-bit unsigned multiplication to produce a 64-bit result. @@ -3644,13 +3666,13 @@ Bitwise operations ---- - - .. _shader_func_uaddCarry: .. rst-class:: classref-method -|vec_uint_type| **uaddCarry** ( |vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| carry ) +|vec_uint_type| **uaddCarry**\ (\ |vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| carry) + + |componentwise| Add unsigned integers and generate carry. @@ -3676,13 +3698,13 @@ Bitwise operations ---- - - .. _shader_func_usubBorrow: .. rst-class:: classref-method -|vec_uint_type| **usubBorrow** ( |vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| borrow ) +|vec_uint_type| **usubBorrow**\ (\ |vec_uint_type| x, |vec_uint_type| y, out |vec_uint_type| borrow) + + |componentwise| Subtract unsigned integers and generate borrow. @@ -3705,13 +3727,13 @@ Bitwise operations ---- - - .. _shader_func_ldexp: .. rst-class:: classref-method -|vec_type| **ldexp** ( |vec_type| x, out |vec_int_type| exp ) +|vec_type| **ldexp**\ (\ |vec_type| x, out |vec_int_type| exp) + + |componentwise| Assemble a floating point number from a value and exponent. @@ -3734,13 +3756,13 @@ Bitwise operations ---- - - .. _shader_func_frexp: .. rst-class:: classref-method -|vec_type| **frexp** ( |vec_type| x, out |vec_int_type| exp ) +|vec_type| **frexp**\ (\ |vec_type| x, out |vec_int_type| exp) + + |componentwise| Extracts ``x`` into a floating-point significand in the range [0.5, 1.0) and in integral exponent of two, such that:: @@ -3761,10 +3783,10 @@ Bitwise operations https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/frexp.xhtml -.. rst-class:: classref-item-separator ----- +.. rst-class:: classref-section-separator +---- @@ -3779,3 +3801,4 @@ Bitwise operations .. |gsampler3D| replace:: :abbr:`gsampler3D (Any of: sampler3D, isampler3D, uSampler3D)` .. |mat_type| replace:: :abbr:`mat_type (Any of: mat2, mat3, mat4)` .. |gvec4_type| replace:: :abbr:`gvec4_type (Any of: vec4, ivec4, uvec4)` +.. |componentwise| replace:: :ref:`Component-wise Function`. diff --git a/tutorials/shaders/shader_reference/shading_language.rst b/tutorials/shaders/shader_reference/shading_language.rst index bc6663758fb..5956eeea628 100644 --- a/tutorials/shaders/shader_reference/shading_language.rst +++ b/tutorials/shaders/shader_reference/shading_language.rst @@ -86,7 +86,9 @@ Most GLSL ES 3.0 datatypes are supported: +----------------------+---------------------------------------------------------------------------------+ .. note:: - Most operations on vectors (multiplication, division, etc) are performed component-wise. + + Most operators and functions that accept multiple vectors (multiplication, division, etc) are performed component-wise, meaning the function + is applied to the first value of each vector and then on the second value of each vector, etc. For example, the operation ``vec2(3, 4) * vec2(10, 20)`` would result in ``vec2(3 * 10, 4 * 20)``. or the operation ``min(vec2(3, 4), vec2(1, 8))`` would result in ``vec2(min(3, 1), min(4, 8))``. @@ -510,6 +512,21 @@ is the list of them in precedence order: | 12 (lowest) | logical inclusive OR | **||** | +-------------+------------------------+------------------+ +.. note:: + + Most operators that accept vectors or matrices (multiplication, division, etc) operate component-wise, meaning the function + is applied to the first value of each vector and then on the second value of each vector, etc. + For example, the operation ``vec2(3, 4) * vec2(10, 20)`` would result in ``vec2(3 * 10, 4 * 20)``. + or the operation ``min(vec2(3, 4), vec2(1, 8))`` would result in ``vec2(min(3, 1), min(4, 8))``. + + The `GLSL Language Specification `_ says under section 5.10 Vector and Matrix Operations: + + With a few exceptions, operations are component-wise. Usually, when an operator operates on a + vector or matrix, it is operating independently on each component of the vector or matrix, + in a component-wise fashion. [...] The exceptions are matrix multiplied by vector, + vector multiplied by matrix, and matrix multiplied by matrix. These do not operate component-wise, + but rather perform the correct linear algebraic multiply. + Flow control ------------ From 22d85a04bb727512d4d850cb600ea5a47d94ed77 Mon Sep 17 00:00:00 2001 From: ashbygeek Date: Thu, 19 Sep 2024 15:00:15 -0400 Subject: [PATCH 22/25] Fix note about component-wise operators --- .../shader_reference/shading_language.rst | 87 +++++++++---------- 1 file changed, 42 insertions(+), 45 deletions(-) diff --git a/tutorials/shaders/shader_reference/shading_language.rst b/tutorials/shaders/shader_reference/shading_language.rst index 5956eeea628..7780c91804c 100644 --- a/tutorials/shaders/shader_reference/shading_language.rst +++ b/tutorials/shaders/shader_reference/shading_language.rst @@ -85,21 +85,6 @@ Most GLSL ES 3.0 datatypes are supported: | **samplerCubeArray** | Sampler type for binding Cubemap arrays, which are read as float. | +----------------------+---------------------------------------------------------------------------------+ -.. note:: - - Most operators and functions that accept multiple vectors (multiplication, division, etc) are performed component-wise, meaning the function - is applied to the first value of each vector and then on the second value of each vector, etc. - For example, the operation ``vec2(3, 4) * vec2(10, 20)`` would result in ``vec2(3 * 10, 4 * 20)``. - or the operation ``min(vec2(3, 4), vec2(1, 8))`` would result in ``vec2(min(3, 1), min(4, 8))``. - - The `GLSL Language Specification `_ says under section 5.10 Vector and Matrix Operations: - - With a few exceptions, operations are component-wise. Usually, when an operator operates on a - vector or matrix, it is operating independently on each component of the vector or matrix, - in a component-wise fashion. [...] The exceptions are matrix multiplied by vector, - vector multiplied by matrix, and matrix multiplied by matrix. These do not operate component-wise, - but rather perform the correct linear algebraic multiply. - Comments ~~~~~~~~ @@ -484,40 +469,52 @@ Operators Godot shading language supports the same set of operators as GLSL ES 3.0. Below is the list of them in precedence order: -+-------------+------------------------+------------------+ -| Precedence | Class | Operator | -+-------------+------------------------+------------------+ -| 1 (highest) | parenthetical grouping | **()** | -+-------------+------------------------+------------------+ -| 2 | unary | **+, -, !, ~** | -+-------------+------------------------+------------------+ -| 3 | multiplicative | **/, \*, %** | -+-------------+------------------------+------------------+ -| 4 | additive | **+, -** | -+-------------+------------------------+------------------+ -| 5 | bit-wise shift | **<<, >>** | -+-------------+------------------------+------------------+ -| 6 | relational | **<, >, <=, >=** | -+-------------+------------------------+------------------+ -| 7 | equality | **==, !=** | -+-------------+------------------------+------------------+ -| 8 | bit-wise AND | **&** | -+-------------+------------------------+------------------+ -| 9 | bit-wise exclusive OR | **^** | -+-------------+------------------------+------------------+ -| 10 | bit-wise inclusive OR | **|** | -+-------------+------------------------+------------------+ -| 11 | logical AND | **&&** | -+-------------+------------------------+------------------+ -| 12 (lowest) | logical inclusive OR | **||** | -+-------------+------------------------+------------------+ +.. table:: + :class: nowrap-col3 + :width: auto + + +-------------+------------------------+------------------+ + | Precedence | Class | Operator | + +-------------+------------------------+------------------+ + | 1 (highest) | parenthetical grouping | **()** | + +-------------+------------------------+------------------+ + | 2 | unary | **+, -, !, ~** | + +-------------+------------------------+------------------+ + | 3 | multiplicative | **/, \*, %** | + +-------------+------------------------+------------------+ + | 4 | additive | **+, -** | + +-------------+------------------------+------------------+ + | 5 | bit-wise shift | **<<, >>** | + +-------------+------------------------+------------------+ + | 6 | relational | **<, >, <=, >=** | + +-------------+------------------------+------------------+ + | 7 | equality | **==, !=** | + +-------------+------------------------+------------------+ + | 8 | bit-wise AND | **&** | + +-------------+------------------------+------------------+ + | 9 | bit-wise exclusive OR | **^** | + +-------------+------------------------+------------------+ + | 10 | bit-wise inclusive OR | **|** | + +-------------+------------------------+------------------+ + | 11 | logical AND | **&&** | + +-------------+------------------------+------------------+ + | 12 (lowest) | logical inclusive OR | **||** | + +-------------+------------------------+------------------+ .. note:: Most operators that accept vectors or matrices (multiplication, division, etc) operate component-wise, meaning the function - is applied to the first value of each vector and then on the second value of each vector, etc. - For example, the operation ``vec2(3, 4) * vec2(10, 20)`` would result in ``vec2(3 * 10, 4 * 20)``. - or the operation ``min(vec2(3, 4), vec2(1, 8))`` would result in ``vec2(min(3, 1), min(4, 8))``. + is applied to the first value of each vector and then on the second value of each vector, etc. Some examples: + + +--------------------------------------+-----------------------------------------------------+ + | Operation | Equivalent Scalar Operation | + +======================================+=====================================================+ + | ``vec3(4,5,6) + 2`` | ``vec3(4+2, 5+2, 6+2)`` | + +--------------------------------------+-----------------------------------------------------+ + | ``vec2(3, 4) * vec2(10, 20)`` | ``vec2(3 * 10, 4 * 20)`` | + +--------------------------------------+-----------------------------------------------------+ + | ``mat2(vec2(1,2),vec2(3,4)) + 10`` | ``mat2(vec2(1+10,2+10),vec2(3+10,4+10))`` | + +--------------------------------------+-----------------------------------------------------+ The `GLSL Language Specification `_ says under section 5.10 Vector and Matrix Operations: From 9e39260d709210d37a251bdfd5fc868e352ef04c Mon Sep 17 00:00:00 2001 From: ashbygeek Date: Thu, 19 Sep 2024 15:30:22 -0400 Subject: [PATCH 23/25] Fix a build warning --- tutorials/shaders/shader_reference/shading_language.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/tutorials/shaders/shader_reference/shading_language.rst b/tutorials/shaders/shader_reference/shading_language.rst index 7780c91804c..08f187b1fab 100644 --- a/tutorials/shaders/shader_reference/shading_language.rst +++ b/tutorials/shaders/shader_reference/shading_language.rst @@ -471,7 +471,6 @@ is the list of them in precedence order: .. table:: :class: nowrap-col3 - :width: auto +-------------+------------------------+------------------+ | Precedence | Class | Operator | From 4363a07cc27a537fb210409fbbb2d38efe08b758 Mon Sep 17 00:00:00 2001 From: Daniel Ashby Date: Wed, 25 Sep 2024 15:31:35 -0400 Subject: [PATCH 24/25] Fix GLSL 4.0 mistake Should have stated functions are based on GLSL ES 3.0 (GLSL != GLSL ES) --- .../shader_reference/shader_functions.rst | 32 +++++++++++-------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/tutorials/shaders/shader_reference/shader_functions.rst b/tutorials/shaders/shader_reference/shader_functions.rst index b5831adc683..fcaf0385f21 100644 --- a/tutorials/shaders/shader_reference/shader_functions.rst +++ b/tutorials/shaders/shader_reference/shader_functions.rst @@ -4,7 +4,7 @@ Built-in functions ================== Godot supports a large number of built-in functions, conforming roughly to the -GLSL 4.00 specification. +GLSL ES 3.0 specification. .. note:: The following type aliases only used in documentation to reduce repetitive function declarations. @@ -40,19 +40,23 @@ GLSL 4.00 specification. Many functions that accept one or more vectors or matrices perform the described function on each component of the vector/matrix. Some examples: - +-----------------------------------+-----------------------------------------------------+ - | Operation | Equivalent Scalar Operation | - +===================================+=====================================================+ - | ``sqrt(vec2(4,64))`` | ``vec2(sqrt(4),sqrt(64))`` | - +-----------------------------------+-----------------------------------------------------+ - | ``min(vec2(3,4),1)`` | ``vec2(min(3,1),min(4,1))`` | - +-----------------------------------+-----------------------------------------------------+ - | ``min(vec3(1,2,3),vec3(5,1,3))`` | ``vec3(min(1,5),min(2,1),min(3,3))`` | - +-----------------------------------+-----------------------------------------------------+ - | ``pow(vec3(3,8,5),2)`` | ``vec3(pow(3,2),pow(8,2),pow(5,2))`` | - +-----------------------------------+-----------------------------------------------------+ - | ``pow(vec3(3,8,5),vec3(1,2,4))`` | ``vec3(pow(3,1),pow(8,2),pow(5,4))`` | - +-----------------------------------+-----------------------------------------------------+ + .. table:: + :class: nowrap-col2 nowrap-col1 + :widths: auto + + +---------------------------------------+-----------------------------------------------------+ + | Operation | Equivalent Scalar Operation | + +=======================================+=====================================================+ + | ``sqrt(vec2(4, 64))`` | ``vec2(sqrt(4), sqrt(64))`` | + +---------------------------------------+-----------------------------------------------------+ + | ``min(vec2(3, 4), 1)`` | ``vec2(min(3, 1), min(4, 1))`` | + +---------------------------------------+-----------------------------------------------------+ + | ``min(vec3(1, 2, 3),vec3(5, 1, 3))`` | ``vec3(min(1, 5), min(2, 1), min(3, 3))`` | + +---------------------------------------+-----------------------------------------------------+ + | ``pow(vec3(3, 8, 5 ), 2)`` | ``vec3(pow(3, 2), pow(8, 2), pow(5, 2))`` | + +---------------------------------------+-----------------------------------------------------+ + | ``pow(vec3(3, 8, 5), vec3(1, 2, 4))`` | ``vec3(pow(3, 1), pow(8, 2), pow(5, 4))`` | + +---------------------------------------+-----------------------------------------------------+ The `GLSL Language Specification `_ says under section 5.10 Vector and Matrix Operations: From 220fb2b85988899f5b2676bc61b6b1e5ba49efd6 Mon Sep 17 00:00:00 2001 From: Daniel Ashby Date: Wed, 25 Sep 2024 15:39:15 -0400 Subject: [PATCH 25/25] Fix minor formatting in shading languages --- .../shader_reference/shading_language.rst | 22 +++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/tutorials/shaders/shader_reference/shading_language.rst b/tutorials/shaders/shader_reference/shading_language.rst index 08f187b1fab..c452e19513f 100644 --- a/tutorials/shaders/shader_reference/shading_language.rst +++ b/tutorials/shaders/shader_reference/shading_language.rst @@ -505,15 +505,19 @@ is the list of them in precedence order: Most operators that accept vectors or matrices (multiplication, division, etc) operate component-wise, meaning the function is applied to the first value of each vector and then on the second value of each vector, etc. Some examples: - +--------------------------------------+-----------------------------------------------------+ - | Operation | Equivalent Scalar Operation | - +======================================+=====================================================+ - | ``vec3(4,5,6) + 2`` | ``vec3(4+2, 5+2, 6+2)`` | - +--------------------------------------+-----------------------------------------------------+ - | ``vec2(3, 4) * vec2(10, 20)`` | ``vec2(3 * 10, 4 * 20)`` | - +--------------------------------------+-----------------------------------------------------+ - | ``mat2(vec2(1,2),vec2(3,4)) + 10`` | ``mat2(vec2(1+10,2+10),vec2(3+10,4+10))`` | - +--------------------------------------+-----------------------------------------------------+ + .. table:: + :class: nowrap-col2 nowrap-col1 + :widths: auto + + +---------------------------------------+------------------------------------------------------+ + | Operation | Equivalent Scalar Operation | + +=======================================+======================================================+ + | ``vec3(4, 5, 6) + 2`` | ``vec3(4 + 2, 5 + 2, 6 + 2)`` | + +---------------------------------------+------------------------------------------------------+ + | ``vec2(3, 4) * vec2(10, 20)`` | ``vec2(3 * 10, 4 * 20)`` | + +---------------------------------------+------------------------------------------------------+ + | ``mat2(vec2(1, 2), vec2(3, 4)) + 10`` | ``mat2(vec2(1 + 10, 2 + 10), vec2(3 + 10, 4 + 10))`` | + +---------------------------------------+------------------------------------------------------+ The `GLSL Language Specification `_ says under section 5.10 Vector and Matrix Operations: