TGSI
====
-TGSI, Tungsten Graphics Shader Instructions, is an intermediate language
+TGSI, Tungsten Graphics Shader Infrastructure, is an intermediate language
for describing shaders. Since Gallium is inherently shaderful, shaders are
an important part of the API. TGSI is the only intermediate representation
used by all drivers.
+Basics
+------
-TGSI Instruction Specification
-==============================
+All TGSI instructions, known as *opcodes*, operate on arbitrary-precision
+floating-point four-component vectors. An opcode may have up to one
+destination register, known as *dst*, and between zero and three source
+registers, called *src0* through *src2*, or simply *src* if there is only
+one.
+Some instructions, like :opcode:`I2F`, permit re-interpretation of vector
+components as integers. Other instructions permit using registers as
+two-component vectors with double precision; see :ref:`Double Opcodes`.
-1 Instruction Set Operations
-=============================
+When an instruction has a scalar result, the result is usually copied into
+each of the components of *dst*. When this happens, the result is said to be
+*replicated* to *dst*. :opcode:`RCP` is one such instruction.
+Instruction Set
+---------------
-1.1 GL_NV_vertex_program
--------------------------
+From GL_NV_vertex_program
+^^^^^^^^^^^^^^^^^^^^^^^^^
-1.1.1 ARL - Address Register Load
+.. opcode:: ARL - Address Register Load
- dst.x = floor(src.x)
- dst.y = floor(src.y)
- dst.z = floor(src.z)
- dst.w = floor(src.w)
+.. math::
+
+ dst.x = \lfloor src.x\rfloor
+
+ dst.y = \lfloor src.y\rfloor
+ dst.z = \lfloor src.z\rfloor
-1.1.2 MOV - Move
+ dst.w = \lfloor src.w\rfloor
+
+
+.. opcode:: MOV - Move
+
+.. math::
dst.x = src.x
+
dst.y = src.y
+
dst.z = src.z
+
dst.w = src.w
-1.1.3 LIT - Light Coefficients
+.. opcode:: LIT - Light Coefficients
+
+.. math::
+
+ dst.x = 1
+
+ dst.y = max(src.x, 0)
+
+ dst.z = (src.x > 0) ? max(src.y, 0)^{clamp(src.w, -128, 128))} : 0
+
+ dst.w = 1
+
+
+.. opcode:: RCP - Reciprocal
- dst.x = 1.0
- dst.y = max(src.x, 0.0)
- dst.z = (src.x > 0.0) ? pow(max(src.y, 0.0), clamp(src.w, -128.0, 128.0)) : 0.0
- dst.w = 1.0
+This instruction replicates its result.
+.. math::
-1.1.4 RCP - Reciprocal
+ dst = \frac{1}{src.x}
- dst.x = 1.0 / src.x
- dst.y = 1.0 / src.x
- dst.z = 1.0 / src.x
- dst.w = 1.0 / src.x
+.. opcode:: RSQ - Reciprocal Square Root
-1.1.5 RSQ - Reciprocal Square Root
+This instruction replicates its result.
- dst.x = 1.0 / sqrt(abs(src.x))
- dst.y = 1.0 / sqrt(abs(src.x))
- dst.z = 1.0 / sqrt(abs(src.x))
- dst.w = 1.0 / sqrt(abs(src.x))
+.. math::
+ dst = \frac{1}{\sqrt{|src.x|}}
-1.1.6 EXP - Approximate Exponential Base 2
- dst.x = pow(2.0, floor(src.x))
- dst.y = src.x - floor(src.x)
- dst.z = pow(2.0, src.x)
- dst.w = 1.0
+.. opcode:: EXP - Approximate Exponential Base 2
+.. math::
-1.1.7 LOG - Approximate Logarithm Base 2
+ dst.x = 2^{\lfloor src.x\rfloor}
- dst.x = floor(lg2(abs(src.x)))
- dst.y = abs(src.x) / pow(2.0, floor(lg2(abs(src.x))))
- dst.z = lg2(abs(src.x))
- dst.w = 1.0
+ dst.y = src.x - \lfloor src.x\rfloor
+ dst.z = 2^{src.x}
-1.1.8 MUL - Multiply
+ dst.w = 1
- dst.x = src0.x * src1.x
- dst.y = src0.y * src1.y
- dst.z = src0.z * src1.z
- dst.w = src0.w * src1.w
+.. opcode:: LOG - Approximate Logarithm Base 2
-1.1.9 ADD - Add
+.. math::
+
+ dst.x = \lfloor\log_2{|src.x|}\rfloor
+
+ dst.y = \frac{|src.x|}{2^{\lfloor\log_2{|src.x|}\rfloor}}
+
+ dst.z = \log_2{|src.x|}
+
+ dst.w = 1
+
+
+.. opcode:: MUL - Multiply
+
+.. math::
+
+ dst.x = src0.x \times src1.x
+
+ dst.y = src0.y \times src1.y
+
+ dst.z = src0.z \times src1.z
+
+ dst.w = src0.w \times src1.w
+
+
+.. opcode:: ADD - Add
+
+.. math::
dst.x = src0.x + src1.x
+
dst.y = src0.y + src1.y
+
dst.z = src0.z + src1.z
+
dst.w = src0.w + src1.w
-1.1.10 DP3 - 3-component Dot Product
+.. opcode:: DP3 - 3-component Dot Product
- dst.x = src0.x * src1.x + src0.y * src1.y + src0.z * src1.z
- dst.y = src0.x * src1.x + src0.y * src1.y + src0.z * src1.z
- dst.z = src0.x * src1.x + src0.y * src1.y + src0.z * src1.z
- dst.w = src0.x * src1.x + src0.y * src1.y + src0.z * src1.z
+This instruction replicates its result.
+.. math::
-1.1.11 DP4 - 4-component Dot Product
+ dst = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z
- dst.x = src0.x * src1.x + src0.y * src1.y + src0.z * src1.z + src0.w * src1.w
- dst.y = src0.x * src1.x + src0.y * src1.y + src0.z * src1.z + src0.w * src1.w
- dst.z = src0.x * src1.x + src0.y * src1.y + src0.z * src1.z + src0.w * src1.w
- dst.w = src0.x * src1.x + src0.y * src1.y + src0.z * src1.z + src0.w * src1.w
+.. opcode:: DP4 - 4-component Dot Product
-1.1.12 DST - Distance Vector
+This instruction replicates its result.
+
+.. math::
+
+ dst = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src0.w \times src1.w
+
+
+.. opcode:: DST - Distance Vector
+
+.. math::
+
+ dst.x = 1
+
+ dst.y = src0.y \times src1.y
- dst.x = 1.0
- dst.y = src0.y * src1.y
dst.z = src0.z
+
dst.w = src1.w
-1.1.13 MIN - Minimum
+.. opcode:: MIN - Minimum
+
+.. math::
dst.x = min(src0.x, src1.x)
+
dst.y = min(src0.y, src1.y)
+
dst.z = min(src0.z, src1.z)
+
dst.w = min(src0.w, src1.w)
-1.1.14 MAX - Maximum
+.. opcode:: MAX - Maximum
+
+.. math::
dst.x = max(src0.x, src1.x)
+
dst.y = max(src0.y, src1.y)
+
dst.z = max(src0.z, src1.z)
+
dst.w = max(src0.w, src1.w)
-1.1.15 SLT - Set On Less Than
+.. opcode:: SLT - Set On Less Than
+
+.. math::
+
+ dst.x = (src0.x < src1.x) ? 1 : 0
- dst.x = (src0.x < src1.x) ? 1.0 : 0.0
- dst.y = (src0.y < src1.y) ? 1.0 : 0.0
- dst.z = (src0.z < src1.z) ? 1.0 : 0.0
- dst.w = (src0.w < src1.w) ? 1.0 : 0.0
+ dst.y = (src0.y < src1.y) ? 1 : 0
+ dst.z = (src0.z < src1.z) ? 1 : 0
-1.1.16 SGE - Set On Greater Equal Than
+ dst.w = (src0.w < src1.w) ? 1 : 0
- dst.x = (src0.x >= src1.x) ? 1.0 : 0.0
- dst.y = (src0.y >= src1.y) ? 1.0 : 0.0
- dst.z = (src0.z >= src1.z) ? 1.0 : 0.0
- dst.w = (src0.w >= src1.w) ? 1.0 : 0.0
+.. opcode:: SGE - Set On Greater Equal Than
-1.1.17 MAD - Multiply And Add
+.. math::
- dst.x = src0.x * src1.x + src2.x
- dst.y = src0.y * src1.y + src2.y
- dst.z = src0.z * src1.z + src2.z
- dst.w = src0.w * src1.w + src2.w
+ dst.x = (src0.x >= src1.x) ? 1 : 0
+ dst.y = (src0.y >= src1.y) ? 1 : 0
-1.2 GL_ATI_fragment_shader
----------------------------
+ dst.z = (src0.z >= src1.z) ? 1 : 0
+ dst.w = (src0.w >= src1.w) ? 1 : 0
-1.2.1 SUB - Subtract
+
+.. opcode:: MAD - Multiply And Add
+
+.. math::
+
+ dst.x = src0.x \times src1.x + src2.x
+
+ dst.y = src0.y \times src1.y + src2.y
+
+ dst.z = src0.z \times src1.z + src2.z
+
+ dst.w = src0.w \times src1.w + src2.w
+
+
+.. opcode:: SUB - Subtract
+
+.. math::
dst.x = src0.x - src1.x
+
dst.y = src0.y - src1.y
+
dst.z = src0.z - src1.z
- dst.w = src0.w - src1.w
+ dst.w = src0.w - src1.w
-1.2.2 DOT3 - 3-component Dot Product
- Alias for DP3.
+.. opcode:: LRP - Linear Interpolate
+.. math::
-1.2.3 DOT4 - 4-component Dot Product
+ dst.x = src0.x \times src1.x + (1 - src0.x) \times src2.x
- Alias for DP4.
+ dst.y = src0.y \times src1.y + (1 - src0.y) \times src2.y
+ dst.z = src0.z \times src1.z + (1 - src0.z) \times src2.z
-1.2.4 LERP - Linear Interpolate
+ dst.w = src0.w \times src1.w + (1 - src0.w) \times src2.w
- dst.x = src0.x * (src1.x - src2.x) + src2.x
- dst.y = src0.y * (src1.y - src2.y) + src2.y
- dst.z = src0.z * (src1.z - src2.z) + src2.z
- dst.w = src0.w * (src1.w - src2.w) + src2.w
+.. opcode:: CND - Condition
-1.2.5 CND - Condition
+.. math::
dst.x = (src2.x > 0.5) ? src0.x : src1.x
+
dst.y = (src2.y > 0.5) ? src0.y : src1.y
+
dst.z = (src2.z > 0.5) ? src0.z : src1.z
- dst.w = (src2.w > 0.5) ? src0.w : src1.w
+ dst.w = (src2.w > 0.5) ? src0.w : src1.w
-1.2.6 CND0 - Condition Zero
- Removed. Use (CMP src2, src1, src0) instead.
+.. opcode:: DP2A - 2-component Dot Product And Add
-1.2.7 DOT2ADD - 2-component Dot Product And Add
+.. math::
- dst.x = src0.x * src1.x + src0.y * src1.y + src2.x
- dst.y = src0.x * src1.x + src0.y * src1.y + src2.x
- dst.z = src0.x * src1.x + src0.y * src1.y + src2.x
- dst.w = src0.x * src1.x + src0.y * src1.y + src2.x
+ dst.x = src0.x \times src1.x + src0.y \times src1.y + src2.x
+ dst.y = src0.x \times src1.x + src0.y \times src1.y + src2.x
-1.3 GL_EXT_vertex_shader
--------------------------
+ dst.z = src0.x \times src1.x + src0.y \times src1.y + src2.x
+ dst.w = src0.x \times src1.x + src0.y \times src1.y + src2.x
-1.3.1 INDEX - Array Lookup
- Considered for removal from language.
+.. opcode:: FRAC - Fraction
+.. math::
-1.3.2 NEGATE - Negate
+ dst.x = src.x - \lfloor src.x\rfloor
- Considered for removal from language.
+ dst.y = src.y - \lfloor src.y\rfloor
+ dst.z = src.z - \lfloor src.z\rfloor
-1.3.3 MADD - Multiply And Add
+ dst.w = src.w - \lfloor src.w\rfloor
- Alias for MAD.
+.. opcode:: CLAMP - Clamp
-1.3.4 FRAC - Fraction
+.. math::
- dst.x = src.x - floor(src.x)
- dst.y = src.y - floor(src.y)
- dst.z = src.z - floor(src.z)
- dst.w = src.w - floor(src.w)
+ dst.x = clamp(src0.x, src1.x, src2.x)
+ dst.y = clamp(src0.y, src1.y, src2.y)
-1.3.5 SETGE - Set On Greater Equal
+ dst.z = clamp(src0.z, src1.z, src2.z)
- Alias for SGE.
+ dst.w = clamp(src0.w, src1.w, src2.w)
-1.3.6 SETLT - Set On Less Than
+.. opcode:: FLR - Floor
- Alias for SLT.
+This is identical to :opcode:`ARL`.
+.. math::
-1.3.7 CLAMP - Clamp
+ dst.x = \lfloor src.x\rfloor
- dst.x = clamp(src0.x, src1.x, src2.x)
- dst.y = clamp(src0.y, src1.y, src2.y)
- dst.z = clamp(src0.z, src1.z, src2.z)
- dst.w = clamp(src0.w, src1.w, src2.w)
+ dst.y = \lfloor src.y\rfloor
+ dst.z = \lfloor src.z\rfloor
-1.3.8 FLOOR - Floor
+ dst.w = \lfloor src.w\rfloor
- dst.x = floor(src.x)
- dst.y = floor(src.y)
- dst.z = floor(src.z)
- dst.w = floor(src.w)
+.. opcode:: ROUND - Round
-1.3.9 ROUND - Round
+.. math::
dst.x = round(src.x)
+
dst.y = round(src.y)
+
dst.z = round(src.z)
+
dst.w = round(src.w)
-1.3.10 EXPBASE2 - Exponential Base 2
+.. opcode:: EX2 - Exponential Base 2
+
+This instruction replicates its result.
+
+.. math::
+
+ dst = 2^{src.x}
+
- dst.x = pow(2.0, src.x)
- dst.y = pow(2.0, src.x)
- dst.z = pow(2.0, src.x)
- dst.w = pow(2.0, src.x)
+.. opcode:: LG2 - Logarithm Base 2
+This instruction replicates its result.
-1.3.11 LOGBASE2 - Logarithm Base 2
+.. math::
- dst.x = lg2(src.x)
- dst.y = lg2(src.x)
- dst.z = lg2(src.x)
- dst.w = lg2(src.x)
+ dst = \log_2{src.x}
-1.3.12 POWER - Power
+.. opcode:: POW - Power
- dst.x = pow(src0.x, src1.x)
- dst.y = pow(src0.x, src1.x)
- dst.z = pow(src0.x, src1.x)
- dst.w = pow(src0.x, src1.x)
+This instruction replicates its result.
+.. math::
-1.3.13 RECIP - Reciprocal
+ dst = src0.x^{src1.x}
- Alias for RCP.
+.. opcode:: XPD - Cross Product
+.. math::
-1.3.14 RECIPSQRT - Reciprocal Square Root
+ dst.x = src0.y \times src1.z - src1.y \times src0.z
- Alias for RSQ.
+ dst.y = src0.z \times src1.x - src1.z \times src0.x
+ dst.z = src0.x \times src1.y - src1.x \times src0.y
-1.3.15 CROSSPRODUCT - Cross Product
+ dst.w = 1
- dst.x = src0.y * src1.z - src1.y * src0.z
- dst.y = src0.z * src1.x - src1.z * src0.x
- dst.z = src0.x * src1.y - src1.x * src0.y
- dst.w = 1.0
+.. opcode:: ABS - Absolute
-1.3.16 MULTIPLYMATRIX - Multiply Matrix
+.. math::
- Considered for removal from language.
+ dst.x = |src.x|
+ dst.y = |src.y|
-1.4 GL_NV_vertex_program1_1
-----------------------------
+ dst.z = |src.z|
+ dst.w = |src.w|
-1.4.1 ABS - Absolute
- dst.x = abs(src.x)
- dst.y = abs(src.y)
- dst.z = abs(src.z)
- dst.w = abs(src.w)
+.. opcode:: RCC - Reciprocal Clamped
+This instruction replicates its result.
-1.4.2 RCC - Reciprocal Clamped
+XXX cleanup on aisle three
- dst.x = (1.0 / src.x) > 0.0 ? clamp(1.0 / src.x, 5.42101e-020, 1.884467e+019) : clamp(1.0 / src.x, -1.884467e+019, -5.42101e-020)
- dst.y = (1.0 / src.x) > 0.0 ? clamp(1.0 / src.x, 5.42101e-020, 1.884467e+019) : clamp(1.0 / src.x, -1.884467e+019, -5.42101e-020)
- dst.z = (1.0 / src.x) > 0.0 ? clamp(1.0 / src.x, 5.42101e-020, 1.884467e+019) : clamp(1.0 / src.x, -1.884467e+019, -5.42101e-020)
- dst.w = (1.0 / src.x) > 0.0 ? clamp(1.0 / src.x, 5.42101e-020, 1.884467e+019) : clamp(1.0 / src.x, -1.884467e+019, -5.42101e-020)
+.. math::
+ dst = (1 / src.x) > 0 ? clamp(1 / src.x, 5.42101e-020, 1.884467e+019) : clamp(1 / src.x, -1.884467e+019, -5.42101e-020)
-1.4.3 DPH - Homogeneous Dot Product
- dst.x = src0.x * src1.x + src0.y * src1.y + src0.z * src1.z + src1.w
- dst.y = src0.x * src1.x + src0.y * src1.y + src0.z * src1.z + src1.w
- dst.z = src0.x * src1.x + src0.y * src1.y + src0.z * src1.z + src1.w
- dst.w = src0.x * src1.x + src0.y * src1.y + src0.z * src1.z + src1.w
+.. opcode:: DPH - Homogeneous Dot Product
+This instruction replicates its result.
-1.5 GL_NV_fragment_program
----------------------------
+.. math::
+ dst = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src1.w
-1.5.1 COS - Cosine
- dst.x = cos(src.x)
- dst.y = cos(src.x)
- dst.z = cos(src.x)
- dst.w = cos(src.w)
+.. opcode:: COS - Cosine
+This instruction replicates its result.
-1.5.2 DDX - Derivative Relative To X
+.. math::
+
+ dst = \cos{src.x}
+
+
+.. opcode:: DDX - Derivative Relative To X
+
+.. math::
dst.x = partialx(src.x)
+
dst.y = partialx(src.y)
+
dst.z = partialx(src.z)
+
dst.w = partialx(src.w)
-1.5.3 DDY - Derivative Relative To Y
+.. opcode:: DDY - Derivative Relative To Y
+
+.. math::
dst.x = partialy(src.x)
+
dst.y = partialy(src.y)
+
dst.z = partialy(src.z)
+
dst.w = partialy(src.w)
-1.5.4 EX2 - Exponential Base 2
+.. opcode:: KILP - Predicated Discard
- Alias for EXPBASE2.
+ discard
-1.5.5 FLR - Floor
+.. opcode:: PK2H - Pack Two 16-bit Floats
- Alias for FLOOR.
+ TBD
-1.5.6 FRC - Fraction
+.. opcode:: PK2US - Pack Two Unsigned 16-bit Scalars
- Alias for FRAC.
+ TBD
-1.5.7 KILP - Predicated Discard
+.. opcode:: PK4B - Pack Four Signed 8-bit Scalars
- discard
+ TBD
-1.5.8 LG2 - Logarithm Base 2
+.. opcode:: PK4UB - Pack Four Unsigned 8-bit Scalars
- Alias for LOGBASE2.
+ TBD
-1.5.9 LRP - Linear Interpolate
+.. opcode:: RFL - Reflection Vector
- Alias for LERP.
+.. math::
+ dst.x = 2 \times (src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z) / (src0.x \times src0.x + src0.y \times src0.y + src0.z \times src0.z) \times src0.x - src1.x
-1.5.10 PK2H - Pack Two 16-bit Floats
+ dst.y = 2 \times (src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z) / (src0.x \times src0.x + src0.y \times src0.y + src0.z \times src0.z) \times src0.y - src1.y
- TBD
+ dst.z = 2 \times (src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z) / (src0.x \times src0.x + src0.y \times src0.y + src0.z \times src0.z) \times src0.z - src1.z
+ dst.w = 1
-1.5.11 PK2US - Pack Two Unsigned 16-bit Scalars
+.. note::
- TBD
+ Considered for removal.
-1.5.12 PK4B - Pack Four Signed 8-bit Scalars
+.. opcode:: SEQ - Set On Equal
- TBD
+.. math::
+ dst.x = (src0.x == src1.x) ? 1 : 0
-1.5.13 PK4UB - Pack Four Unsigned 8-bit Scalars
+ dst.y = (src0.y == src1.y) ? 1 : 0
- TBD
+ dst.z = (src0.z == src1.z) ? 1 : 0
+
+ dst.w = (src0.w == src1.w) ? 1 : 0
+
+
+.. opcode:: SFL - Set On False
+
+This instruction replicates its result.
+
+.. math::
+ dst = 0
-1.5.14 POW - Power
+.. note::
- Alias for POWER.
+ Considered for removal.
-1.5.15 RFL - Reflection Vector
+.. opcode:: SGT - Set On Greater Than
- dst.x = 2.0 * (src0.x * src1.x + src0.y * src1.y + src0.z * src1.z) / (src0.x * src0.x + src0.y * src0.y + src0.z * src0.z) * src0.x - src1.x
- dst.y = 2.0 * (src0.x * src1.x + src0.y * src1.y + src0.z * src1.z) / (src0.x * src0.x + src0.y * src0.y + src0.z * src0.z) * src0.y - src1.y
- dst.z = 2.0 * (src0.x * src1.x + src0.y * src1.y + src0.z * src1.z) / (src0.x * src0.x + src0.y * src0.y + src0.z * src0.z) * src0.z - src1.z
- dst.w = 1.0
+.. math::
+ dst.x = (src0.x > src1.x) ? 1 : 0
-1.5.16 SEQ - Set On Equal
+ dst.y = (src0.y > src1.y) ? 1 : 0
- dst.x = (src0.x == src1.x) ? 1.0 : 0.0
- dst.y = (src0.y == src1.y) ? 1.0 : 0.0
- dst.z = (src0.z == src1.z) ? 1.0 : 0.0
- dst.w = (src0.w == src1.w) ? 1.0 : 0.0
+ dst.z = (src0.z > src1.z) ? 1 : 0
+ dst.w = (src0.w > src1.w) ? 1 : 0
-1.5.17 SFL - Set On False
- dst.x = 0.0
- dst.y = 0.0
- dst.z = 0.0
- dst.w = 0.0
+.. opcode:: SIN - Sine
+This instruction replicates its result.
-1.5.18 SGT - Set On Greater Than
+.. math::
- dst.x = (src0.x > src1.x) ? 1.0 : 0.0
- dst.y = (src0.y > src1.y) ? 1.0 : 0.0
- dst.z = (src0.z > src1.z) ? 1.0 : 0.0
- dst.w = (src0.w > src1.w) ? 1.0 : 0.0
+ dst = \sin{src.x}
-1.5.19 SIN - Sine
+.. opcode:: SLE - Set On Less Equal Than
- dst.x = sin(src.x)
- dst.y = sin(src.x)
- dst.z = sin(src.x)
- dst.w = sin(src.w)
+.. math::
+ dst.x = (src0.x <= src1.x) ? 1 : 0
-1.5.20 SLE - Set On Less Equal Than
+ dst.y = (src0.y <= src1.y) ? 1 : 0
- dst.x = (src0.x <= src1.x) ? 1.0 : 0.0
- dst.y = (src0.y <= src1.y) ? 1.0 : 0.0
- dst.z = (src0.z <= src1.z) ? 1.0 : 0.0
- dst.w = (src0.w <= src1.w) ? 1.0 : 0.0
+ dst.z = (src0.z <= src1.z) ? 1 : 0
+ dst.w = (src0.w <= src1.w) ? 1 : 0
-1.5.21 SNE - Set On Not Equal
- dst.x = (src0.x != src1.x) ? 1.0 : 0.0
- dst.y = (src0.y != src1.y) ? 1.0 : 0.0
- dst.z = (src0.z != src1.z) ? 1.0 : 0.0
- dst.w = (src0.w != src1.w) ? 1.0 : 0.0
+.. opcode:: SNE - Set On Not Equal
+.. math::
-1.5.22 STR - Set On True
+ dst.x = (src0.x != src1.x) ? 1 : 0
- dst.x = 1.0
- dst.y = 1.0
- dst.z = 1.0
- dst.w = 1.0
+ dst.y = (src0.y != src1.y) ? 1 : 0
+ dst.z = (src0.z != src1.z) ? 1 : 0
-1.5.23 TEX - Texture Lookup
+ dst.w = (src0.w != src1.w) ? 1 : 0
+
+
+.. opcode:: STR - Set On True
+
+This instruction replicates its result.
+
+.. math::
+
+ dst = 1
+
+
+.. opcode:: TEX - Texture Lookup
TBD
-1.5.24 TXD - Texture Lookup with Derivatives
+.. opcode:: TXD - Texture Lookup with Derivatives
TBD
-1.5.25 TXP - Projective Texture Lookup
+.. opcode:: TXP - Projective Texture Lookup
TBD
-1.5.26 UP2H - Unpack Two 16-Bit Floats
+.. opcode:: UP2H - Unpack Two 16-Bit Floats
TBD
+.. note::
+
+ Considered for removal.
-1.5.27 UP2US - Unpack Two Unsigned 16-Bit Scalars
+.. opcode:: UP2US - Unpack Two Unsigned 16-Bit Scalars
TBD
+.. note::
-1.5.28 UP4B - Unpack Four Signed 8-Bit Values
+ Considered for removal.
+
+.. opcode:: UP4B - Unpack Four Signed 8-Bit Values
TBD
+.. note::
+
+ Considered for removal.
-1.5.29 UP4UB - Unpack Four Unsigned 8-Bit Scalars
+.. opcode:: UP4UB - Unpack Four Unsigned 8-Bit Scalars
TBD
+.. note::
+
+ Considered for removal.
+
+.. opcode:: X2D - 2D Coordinate Transformation
+
+.. math::
+
+ dst.x = src0.x + src1.x \times src2.x + src1.y \times src2.y
+
+ dst.y = src0.y + src1.x \times src2.z + src1.y \times src2.w
+
+ dst.z = src0.x + src1.x \times src2.x + src1.y \times src2.y
+
+ dst.w = src0.y + src1.x \times src2.z + src1.y \times src2.w
-1.5.30 X2D - 2D Coordinate Transformation
+.. note::
- dst.x = src0.x + src1.x * src2.x + src1.y * src2.y
- dst.y = src0.y + src1.x * src2.z + src1.y * src2.w
- dst.z = src0.x + src1.x * src2.x + src1.y * src2.y
- dst.w = src0.y + src1.x * src2.z + src1.y * src2.w
+ Considered for removal.
-1.6 GL_NV_vertex_program2
---------------------------
+From GL_NV_vertex_program2
+^^^^^^^^^^^^^^^^^^^^^^^^^^
-1.6.1 ARA - Address Register Add
+.. opcode:: ARA - Address Register Add
TBD
+.. note::
-1.6.2 ARR - Address Register Load With Round
+ Considered for removal.
+
+.. opcode:: ARR - Address Register Load With Round
+
+.. math::
dst.x = round(src.x)
+
dst.y = round(src.y)
+
dst.z = round(src.z)
+
dst.w = round(src.w)
-1.6.3 BRA - Branch
+.. opcode:: BRA - Branch
pc = target
+.. note::
+
+ Considered for removal.
-1.6.4 CAL - Subroutine Call
+.. opcode:: CAL - Subroutine Call
push(pc)
pc = target
-1.6.5 RET - Subroutine Call Return
+.. opcode:: RET - Subroutine Call Return
pc = pop()
+ Potential restrictions:
+ * Only occurs at end of function.
-1.6.6 SSG - Set Sign
+.. opcode:: SSG - Set Sign
- dst.x = (src.x > 0.0) ? 1.0 : (src.x < 0.0) ? -1.0 : 0.0
- dst.y = (src.y > 0.0) ? 1.0 : (src.y < 0.0) ? -1.0 : 0.0
- dst.z = (src.z > 0.0) ? 1.0 : (src.z < 0.0) ? -1.0 : 0.0
- dst.w = (src.w > 0.0) ? 1.0 : (src.w < 0.0) ? -1.0 : 0.0
+.. math::
+ dst.x = (src.x > 0) ? 1 : (src.x < 0) ? -1 : 0
-1.7 GL_ARB_vertex_program
---------------------------
+ dst.y = (src.y > 0) ? 1 : (src.y < 0) ? -1 : 0
+ dst.z = (src.z > 0) ? 1 : (src.z < 0) ? -1 : 0
-1.7.1 SWZ - Extended Swizzle
-
- dst.x = src.x
- dst.y = src.y
- dst.z = src.z
- dst.w = src.w
+ dst.w = (src.w > 0) ? 1 : (src.w < 0) ? -1 : 0
-1.7.2 XPD - Cross Product
+.. opcode:: CMP - Compare
- Alias for CROSSPRODUCT.
+.. math::
+ dst.x = (src0.x < 0) ? src1.x : src2.x
-1.8 GL_ARB_fragment_program
-----------------------------
+ dst.y = (src0.y < 0) ? src1.y : src2.y
+ dst.z = (src0.z < 0) ? src1.z : src2.z
-1.8.1 CMP - Compare
+ dst.w = (src0.w < 0) ? src1.w : src2.w
- dst.x = (src0.x < 0.0) ? src1.x : src2.x
- dst.y = (src0.y < 0.0) ? src1.y : src2.y
- dst.z = (src0.z < 0.0) ? src1.z : src2.z
- dst.w = (src0.w < 0.0) ? src1.w : src2.w
+.. opcode:: KIL - Conditional Discard
-1.8.2 KIL - Conditional Discard
+.. math::
- if (src.x < 0.0 || src.y < 0.0 || src.z < 0.0 || src.w < 0.0)
+ if (src.x < 0 || src.y < 0 || src.z < 0 || src.w < 0)
discard
endif
-1.8.3 SCS - Sine Cosine
+.. opcode:: SCS - Sine Cosine
+
+.. math::
+
+ dst.x = \cos{src.x}
- dst.x = cos(src.x)
- dst.y = sin(src.x)
- dst.z = 0.0
- dst.y = 1.0
+ dst.y = \sin{src.x}
+ dst.z = 0
-1.8.4 TXB - Texture Lookup With Bias
+ dst.y = 1
+
+
+.. opcode:: TXB - Texture Lookup With Bias
TBD
-1.9 GL_NV_fragment_program2
-----------------------------
+.. opcode:: NRM - 3-component Vector Normalise
+
+.. math::
+
+ dst.x = src.x / (src.x \times src.x + src.y \times src.y + src.z \times src.z)
+ dst.y = src.y / (src.x \times src.x + src.y \times src.y + src.z \times src.z)
-1.9.1 NRM - 3-component Vector Normalise
+ dst.z = src.z / (src.x \times src.x + src.y \times src.y + src.z \times src.z)
- dst.x = src.x / (src.x * src.x + src.y * src.y + src.z * src.z)
- dst.y = src.y / (src.x * src.x + src.y * src.y + src.z * src.z)
- dst.z = src.z / (src.x * src.x + src.y * src.y + src.z * src.z)
- dst.w = 1.0
+ dst.w = 1
-1.9.2 DIV - Divide
+.. opcode:: DIV - Divide
- dst.x = src0.x / src1.x
- dst.y = src0.y / src1.y
- dst.z = src0.z / src1.z
- dst.w = src0.w / src1.w
+.. math::
+ dst.x = \frac{src0.x}{src1.x}
-1.9.3 DP2 - 2-component Dot Product
+ dst.y = \frac{src0.y}{src1.y}
- dst.x = src0.x * src1.x + src0.y * src1.y
- dst.y = src0.x * src1.x + src0.y * src1.y
- dst.z = src0.x * src1.x + src0.y * src1.y
- dst.w = src0.x * src1.x + src0.y * src1.y
+ dst.z = \frac{src0.z}{src1.z}
+ dst.w = \frac{src0.w}{src1.w}
-1.9.4 DP2A - 2-component Dot Product And Add
- Alias for DOT2ADD.
+.. opcode:: DP2 - 2-component Dot Product
+This instruction replicates its result.
-1.9.5 TXL - Texture Lookup With LOD
+.. math::
+
+ dst = src0.x \times src1.x + src0.y \times src1.y
+
+
+.. opcode:: TXL - Texture Lookup With LOD
TBD
-1.9.6 BRK - Break
+.. opcode:: BRK - Break
TBD
-1.9.7 IF - If
+.. opcode:: IF - If
TBD
-1.9.8 BGNFOR - Begin a For-Loop
+.. opcode:: BGNFOR - Begin a For-Loop
dst.x = floor(src.x)
dst.y = floor(src.y)
Note: The destination must be a loop register.
The source must be a constant register.
+.. note::
+
+ Considered for cleanup.
+
+.. note::
-1.9.9 REP - Repeat
+ Considered for removal.
+
+
+.. opcode:: REP - Repeat
TBD
-1.9.10 ELSE - Else
+.. opcode:: ELSE - Else
TBD
-1.9.11 ENDIF - End If
+.. opcode:: ENDIF - End If
TBD
-1.9.12 ENDFOR - End a For-Loop
+.. opcode:: ENDFOR - End a For-Loop
dst.x = dst.x + dst.z
dst.y = dst.y - 1.0
Note: The destination must be a loop register.
+.. note::
-1.9.13 ENDREP - End Repeat
+ Considered for cleanup.
- TBD
+.. note::
+ Considered for removal.
-1.10 GL_NV_vertex_program3
----------------------------
+.. opcode:: ENDREP - End Repeat
+ TBD
-1.10.1 PUSHA - Push Address Register On Stack
+
+.. opcode:: PUSHA - Push Address Register On Stack
push(src.x)
push(src.y)
push(src.z)
push(src.w)
+.. note::
+
+ Considered for cleanup.
+
+.. note::
-1.10.2 POPA - Pop Address Register From Stack
+ Considered for removal.
+
+.. opcode:: POPA - Pop Address Register From Stack
dst.w = pop()
dst.z = pop()
dst.y = pop()
dst.x = pop()
+.. note::
+
+ Considered for cleanup.
+
+.. note::
+
+ Considered for removal.
+
+
+From GL_NV_gpu_program4
+^^^^^^^^^^^^^^^^^^^^^^^^
-1.11 GL_NV_gpu_program4
-------------------------
+Support for these opcodes indicated by a special pipe capability bit (TBD).
+.. opcode:: CEIL - Ceiling
-1.11.1 CEIL - Ceiling
+.. math::
- dst.x = ceil(src.x)
- dst.y = ceil(src.y)
- dst.z = ceil(src.z)
- dst.w = ceil(src.w)
+ dst.x = \lceil src.x\rceil
+ dst.y = \lceil src.y\rceil
-1.11.2 I2F - Integer To Float
+ dst.z = \lceil src.z\rceil
+
+ dst.w = \lceil src.w\rceil
+
+
+.. opcode:: I2F - Integer To Float
+
+.. math::
dst.x = (float) src.x
+
dst.y = (float) src.y
+
dst.z = (float) src.z
+
dst.w = (float) src.w
-1.11.3 NOT - Bitwise Not
+.. opcode:: NOT - Bitwise Not
+
+.. math::
dst.x = ~src.x
+
dst.y = ~src.y
+
dst.z = ~src.z
+
dst.w = ~src.w
-1.11.4 TRUNC - Truncate
+.. opcode:: TRUNC - Truncate
+
+.. math::
dst.x = trunc(src.x)
+
dst.y = trunc(src.y)
+
dst.z = trunc(src.z)
+
dst.w = trunc(src.w)
-1.11.5 SHL - Shift Left
+.. opcode:: SHL - Shift Left
+
+.. math::
dst.x = src0.x << src1.x
+
dst.y = src0.y << src1.x
+
dst.z = src0.z << src1.x
+
dst.w = src0.w << src1.x
-1.11.6 SHR - Shift Right
+.. opcode:: SHR - Shift Right
+
+.. math::
dst.x = src0.x >> src1.x
+
dst.y = src0.y >> src1.x
+
dst.z = src0.z >> src1.x
+
dst.w = src0.w >> src1.x
-1.11.7 AND - Bitwise And
+.. opcode:: AND - Bitwise And
+
+.. math::
dst.x = src0.x & src1.x
+
dst.y = src0.y & src1.y
+
dst.z = src0.z & src1.z
+
dst.w = src0.w & src1.w
-1.11.8 OR - Bitwise Or
+.. opcode:: OR - Bitwise Or
+
+.. math::
dst.x = src0.x | src1.x
+
dst.y = src0.y | src1.y
+
dst.z = src0.z | src1.z
+
dst.w = src0.w | src1.w
-1.11.9 MOD - Modulus
+.. opcode:: MOD - Modulus
+
+.. math::
+
+ dst.x = src0.x \bmod src1.x
+
+ dst.y = src0.y \bmod src1.y
+
+ dst.z = src0.z \bmod src1.z
+
+ dst.w = src0.w \bmod src1.w
+
+
+.. opcode:: XOR - Bitwise Xor
+
+.. math::
+
+ dst.x = src0.x \oplus src1.x
+
+ dst.y = src0.y \oplus src1.y
+
+ dst.z = src0.z \oplus src1.z
+
+ dst.w = src0.w \oplus src1.w
- dst.x = src0.x % src1.x
- dst.y = src0.y % src1.y
- dst.z = src0.z % src1.z
- dst.w = src0.w % src1.w
+.. opcode:: SAD - Sum Of Absolute Differences
-1.11.10 XOR - Bitwise Xor
+.. math::
- dst.x = src0.x ^ src1.x
- dst.y = src0.y ^ src1.y
- dst.z = src0.z ^ src1.z
- dst.w = src0.w ^ src1.w
+ dst.x = |src0.x - src1.x| + src2.x
+ dst.y = |src0.y - src1.y| + src2.y
-1.11.11 SAD - Sum Of Absolute Differences
+ dst.z = |src0.z - src1.z| + src2.z
- dst.x = abs(src0.x - src1.x) + src2.x
- dst.y = abs(src0.y - src1.y) + src2.y
- dst.z = abs(src0.z - src1.z) + src2.z
- dst.w = abs(src0.w - src1.w) + src2.w
+ dst.w = |src0.w - src1.w| + src2.w
-1.11.12 TXF - Texel Fetch
+.. opcode:: TXF - Texel Fetch
TBD
-1.11.13 TXQ - Texture Size Query
+.. opcode:: TXQ - Texture Size Query
TBD
-1.11.14 CONT - Continue
+.. opcode:: CONT - Continue
TBD
-1.12 GL_NV_geometry_program4
------------------------------
+From GL_NV_geometry_program4
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-1.12.1 EMIT - Emit
+.. opcode:: EMIT - Emit
TBD
-1.12.2 ENDPRIM - End Primitive
+.. opcode:: ENDPRIM - End Primitive
TBD
-1.13 GLSL
-----------
+From GLSL
+^^^^^^^^^^
-1.13.1 BGNLOOP - Begin a Loop
+.. opcode:: BGNLOOP - Begin a Loop
TBD
-1.13.2 BGNSUB - Begin Subroutine
+.. opcode:: BGNSUB - Begin Subroutine
TBD
-1.13.3 ENDLOOP - End a Loop
+.. opcode:: ENDLOOP - End a Loop
TBD
-1.13.4 ENDSUB - End Subroutine
+.. opcode:: ENDSUB - End Subroutine
TBD
-1.13.5 INT - Truncate
+.. opcode:: NOP - No Operation
- Alias for TRUNC.
+ Do nothing.
-1.13.6 NOISE1 - 1D Noise
+.. opcode:: NRM4 - 4-component Vector Normalise
+
+This instruction replicates its result.
+
+.. math::
+
+ dst = \frac{src.x}{src.x \times src.x + src.y \times src.y + src.z \times src.z + src.w \times src.w}
- TBD
+ps_2_x
+^^^^^^^^^^^^
-1.13.7 NOISE2 - 2D Noise
+
+.. opcode:: CALLNZ - Subroutine Call If Not Zero
TBD
-1.13.8 NOISE3 - 3D Noise
+.. opcode:: IFC - If
TBD
-1.13.9 NOISE4 - 4D Noise
+.. opcode:: BREAKC - Break Conditional
TBD
+.. _doubleopcodes:
-1.13.10 NOP - No Operation
+Double Opcodes
+^^^^^^^^^^^^^^^
- Do nothing.
+.. opcode:: DADD - Add Double
+.. math::
-1.14 ps_1_1
-------------
+ dst.xy = src0.xy + src1.xy
+ dst.zw = src0.zw + src1.zw
-1.14.1 TEXKILL - Conditional Discard
- Alias for KIL.
+.. opcode:: DDIV - Divide Double
+.. math::
-1.15 ps_1_4
-------------
+ dst.xy = src0.xy / src1.xy
+ dst.zw = src0.zw / src1.zw
-1.15.1 TEXLD - Texture Lookup
+.. opcode:: DSEQ - Set Double on Equal
- Alias for TEX.
+.. math::
+ dst.xy = src0.xy == src1.xy ? 1.0F : 0.0F
-1.16 ps_2_0
-------------
+ dst.zw = src0.zw == src1.zw ? 1.0F : 0.0F
+.. opcode:: DSLT - Set Double on Less than
-1.16.1 M4X4 - Multiply Matrix
+.. math::
- Alias for MULTIPLYMATRIX.
+ dst.xy = src0.xy < src1.xy ? 1.0F : 0.0F
+ dst.zw = src0.zw < src1.zw ? 1.0F : 0.0F
-1.16.2 M4X3 - Multiply Matrix
+.. opcode:: DFRAC - Double Fraction
- Considered for removal from language.
+.. math::
+ dst.xy = src.xy - \lfloor src.xy\rfloor
-1.16.3 M3X4 - Multiply Matrix
+ dst.zw = src.zw - \lfloor src.zw\rfloor
- Considered for removal from language.
+.. opcode:: DFRACEXP - Convert Double Number to Fractional and Integral Components
-1.16.4 M3X3 - Multiply Matrix
+.. math::
- Considered for removal from language.
+ dst0.xy = frexp(src.xy, dst1.xy)
+ dst0.zw = frexp(src.zw, dst1.zw)
-1.16.5 M3X2 - Multiply Matrix
+.. opcode:: DLDEXP - Multiple Double Number by Integral Power of 2
- Considered for removal from language.
+.. math::
+ dst.xy = ldexp(src0.xy, src1.xy)
-1.16.6 CRS - Cross Product
+ dst.zw = ldexp(src0.zw, src1.zw)
- Alias for XPD.
+.. opcode:: DMIN - Minimum Double
+.. math::
-1.16.7 NRM4 - 4-component Vector Normalise
+ dst.xy = min(src0.xy, src1.xy)
- dst.x = src.x / (src.x * src.x + src.y * src.y + src.z * src.z + src.w * src.w)
- dst.y = src.y / (src.x * src.x + src.y * src.y + src.z * src.z + src.w * src.w)
- dst.z = src.z / (src.x * src.x + src.y * src.y + src.z * src.z + src.w * src.w)
- dst.w = src.w / (src.x * src.x + src.y * src.y + src.z * src.z + src.w * src.w)
+ dst.zw = min(src0.zw, src1.zw)
+.. opcode:: DMAX - Maximum Double
-1.16.8 SINCOS - Sine Cosine
+.. math::
- Alias for SCS.
+ dst.xy = max(src0.xy, src1.xy)
+ dst.zw = max(src0.zw, src1.zw)
-1.16.9 TEXLDB - Texture Lookup With Bias
+.. opcode:: DMUL - Multiply Double
- Alias for TXB.
+.. math::
+ dst.xy = src0.xy \times src1.xy
-1.16.10 DP2ADD - 2-component Dot Product And Add
+ dst.zw = src0.zw \times src1.zw
- Alias for DP2A.
+.. opcode:: DMAD - Multiply And Add Doubles
-1.17 ps_2_x
-------------
+.. math::
+ dst.xy = src0.xy \times src1.xy + src2.xy
-1.17.1 CALL - Subroutine Call
+ dst.zw = src0.zw \times src1.zw + src2.zw
- Alias for CAL.
+.. opcode:: DRCP - Reciprocal Double
-1.17.2 CALLNZ - Subroutine Call If Not Zero
+.. math::
- TBD
+ dst.xy = \frac{1}{src.xy}
+ dst.zw = \frac{1}{src.zw}
-1.17.3 IFC - If
+.. opcode:: DSQRT - Square root double
- TBD
+.. math::
+ dst.xy = \sqrt{src.xy}
-1.17.4 BREAK - Break
+ dst.zw = \sqrt{src.zw}
- Alias for BRK.
+Explanation of symbols used
+------------------------------
-1.17.5 BREAKC - Break Conditional
- TBD
+Functions
+^^^^^^^^^^^^^^
-1.17.6 DSX - Derivative Relative To X
+ :math:`|x|` Absolute value of `x`.
- Alias for DDX.
+ :math:`\lceil x \rceil` Ceiling of `x`.
+ clamp(x,y,z) Clamp x between y and z.
+ (x < y) ? y : (x > z) ? z : x
-1.17.7 DSY - Derivative Relative To Y
+ :math:`\lfloor x\rfloor` Floor of `x`.
- Alias for DDY.
+ :math:`\log_2{x}` Logarithm of `x`, base 2.
+ max(x,y) Maximum of x and y.
+ (x > y) ? x : y
-1.17.8 TEXLDD - Texture Lookup with Derivatives
+ min(x,y) Minimum of x and y.
+ (x < y) ? x : y
- Alias for TXD.
+ partialx(x) Derivative of x relative to fragment's X.
+ partialy(x) Derivative of x relative to fragment's Y.
-1.18 vs_1_1
-------------
+ pop() Pop from stack.
+ :math:`x^y` `x` to the power `y`.
-1.18.1 EXPP - Approximate Exponential Base 2
+ push(x) Push x on stack.
- Use EXP. See also 1.19.3.
+ round(x) Round x.
+ trunc(x) Truncate x, i.e. drop the fraction bits.
-1.18.2 LOGP - Logarithm Base 2
- Use LOG. See also 1.19.4.
+Keywords
+^^^^^^^^^^^^^
-1.19 vs_2_0
-------------
+ discard Discard fragment.
+ pc Program counter.
-1.19.1 SGN - Set Sign
+ target Label of target instruction.
- Alias for SSG.
+Other tokens
+---------------
-1.19.2 MOVA - Move Address Register
- Alias for ARR.
+Declaration
+^^^^^^^^^^^
-1.19.3 EXPP - Approximate Exponential Base 2
+Declares a register that is will be referenced as an operand in Instruction
+tokens.
- Use EX2.
+File field contains register file that is being declared and is one
+of TGSI_FILE.
+UsageMask field specifies which of the register components can be accessed
+and is one of TGSI_WRITEMASK.
-1.19.4 LOGP - Logarithm Base 2
+Interpolate field is only valid for fragment shader INPUT register files.
+It specifes the way input is being interpolated by the rasteriser and is one
+of TGSI_INTERPOLATE.
- Use LG2.
+If Dimension flag is set to 1, a Declaration Dimension token follows.
+If Semantic flag is set to 1, a Declaration Semantic token follows.
-2 Explanation of symbols used
-==============================
+CylindricalWrap bitfield is only valid for fragment shader INPUT register
+files. It specifies which register components should be subject to cylindrical
+wrapping when interpolating by the rasteriser. If TGSI_CYLINDRICAL_WRAP_X
+is set to 1, the X component should be interpolated according to cylindrical
+wrapping rules.
-2.1 Functions
---------------
+Declaration Semantic
+^^^^^^^^^^^^^^^^^^^^^^^^
- abs(x) Absolute value of x.
- '|x|'
- (x < 0.0) ? -x : x
+ Follows Declaration token if Semantic bit is set.
- ceil(x) Ceiling of x.
+ Since its purpose is to link a shader with other stages of the pipeline,
+ it is valid to follow only those Declaration tokens that declare a register
+ either in INPUT or OUTPUT file.
- clamp(x,y,z) Clamp x between y and z.
- (x < y) ? y : (x > z) ? z : x
+ SemanticName field contains the semantic name of the register being declared.
+ There is no default value.
- cos(x) Cosine of x.
+ SemanticIndex is an optional subscript that can be used to distinguish
+ different register declarations with the same semantic name. The default value
+ is 0.
- floor(x) Floor of x.
+ The meanings of the individual semantic names are explained in the following
+ sections.
- lg2(x) Logarithm base 2 of x.
+TGSI_SEMANTIC_POSITION
+""""""""""""""""""""""
- max(x,y) Maximum of x and y.
- (x > y) ? x : y
+Position, sometimes known as HPOS or WPOS for historical reasons, is the
+location of the vertex in space, in ``(x, y, z, w)`` format. ``x``, ``y``, and ``z``
+are the Cartesian coordinates, and ``w`` is the homogenous coordinate and used
+for the perspective divide, if enabled.
- min(x,y) Minimum of x and y.
- (x < y) ? x : y
+As a vertex shader output, position should be scaled to the viewport. When
+used in fragment shaders, position will be in window coordinates. The convention
+used depends on the FS_COORD_ORIGIN and FS_COORD_PIXEL_CENTER properties.
- partialx(x) Derivative of x relative to fragment's X.
+XXX additionally, is there a way to configure the perspective divide? it's
+accelerated on most chipsets AFAIK...
- partialy(x) Derivative of x relative to fragment's Y.
+Position, if not specified, usually defaults to ``(0, 0, 0, 1)``, and can
+be partially specified as ``(x, y, 0, 1)`` or ``(x, y, z, 1)``.
- pop() Pop from stack.
+XXX usually? can we solidify that?
- pow(x,y) Raise x to power of y.
+TGSI_SEMANTIC_COLOR
+"""""""""""""""""""
- push(x) Push x on stack.
+Colors are used to, well, color the primitives. Colors are always in
+``(r, g, b, a)`` format.
- round(x) Round x.
+If alpha is not specified, it defaults to 1.
- sin(x) Sine of x.
+TGSI_SEMANTIC_BCOLOR
+""""""""""""""""""""
- sqrt(x) Square root of x.
+Back-facing colors are only used for back-facing polygons, and are only valid
+in vertex shader outputs. After rasterization, all polygons are front-facing
+and COLOR and BCOLOR end up occupying the same slots in the fragment, so
+all BCOLORs effectively become regular COLORs in the fragment shader.
- trunc(x) Truncate x.
+TGSI_SEMANTIC_FOG
+"""""""""""""""""
+The fog coordinate historically has been used to replace the depth coordinate
+for generation of fog in dedicated fog blocks. Gallium, however, does not use
+dedicated fog acceleration, placing it entirely in the fragment shader
+instead.
-2.2 Keywords
--------------
+The fog coordinate should be written in ``(f, 0, 0, 1)`` format. Only the first
+component matters when writing from the vertex shader; the driver will ensure
+that the coordinate is in this format when used as a fragment shader input.
+TGSI_SEMANTIC_PSIZE
+"""""""""""""""""""
- discard Discard fragment.
+PSIZE, or point size, is used to specify point sizes per-vertex. It should
+be in ``(s, 0, 0, 1)`` format, where ``s`` is the (possibly clamped) point size.
+Only the first component matters when writing from the vertex shader.
- dst First destination register.
+When using this semantic, be sure to set the appropriate state in the
+:ref:`rasterizer` first.
- dst0 First destination register.
+TGSI_SEMANTIC_GENERIC
+"""""""""""""""""""""
- pc Program counter.
+Generic semantics are nearly always used for texture coordinate attributes,
+in ``(s, t, r, q)`` format. ``t`` and ``r`` may be unused for certain kinds
+of lookups, and ``q`` is the level-of-detail bias for biased sampling.
- src First source register.
+These attributes are called "generic" because they may be used for anything
+else, including parameters, texture generation information, or anything that
+can be stored inside a four-component vector.
- src0 First source register.
+TGSI_SEMANTIC_NORMAL
+""""""""""""""""""""
- src1 Second source register.
+Vertex normal; could be used to implement per-pixel lighting for legacy APIs
+that allow mixing fixed-function and programmable stages.
- src2 Third source register.
+TGSI_SEMANTIC_FACE
+""""""""""""""""""
- target Label of target instruction.
+FACE is the facing bit, to store the facing information for the fragment
+shader. ``(f, 0, 0, 1)`` is the format. The first component will be positive
+when the fragment is front-facing, and negative when the component is
+back-facing.
+TGSI_SEMANTIC_EDGEFLAG
+""""""""""""""""""""""
-3 Other tokens
-===============
+XXX no clue
-3.1 Declaration Semantic
--------------------------
+Properties
+^^^^^^^^^^^^^^^^^^^^^^^^
- Follows Declaration token if Semantic bit is set.
+ Properties are general directives that apply to the whole TGSI program.
- Since its purpose is to link a shader with other stages of the pipeline,
- it is valid to follow only those Declaration tokens that declare a register
- either in INPUT or OUTPUT file.
+FS_COORD_ORIGIN
+"""""""""""""""
- SemanticName field contains the semantic name of the register being declared.
- There is no default value.
+Specifies the fragment shader TGSI_SEMANTIC_POSITION coordinate origin.
+The default value is UPPER_LEFT.
+
+If UPPER_LEFT, the position will be (0,0) at the upper left corner and
+increase downward and rightward.
+If LOWER_LEFT, the position will be (0,0) at the lower left corner and
+increase upward and rightward.
+
+OpenGL defaults to LOWER_LEFT, and is configurable with the
+GL_ARB_fragment_coord_conventions extension.
+
+DirectX 9/10 use UPPER_LEFT.
+
+FS_COORD_PIXEL_CENTER
+"""""""""""""""""""""
+
+Specifies the fragment shader TGSI_SEMANTIC_POSITION pixel center convention.
+The default value is HALF_INTEGER.
+
+If HALF_INTEGER, the fractionary part of the position will be 0.5
+If INTEGER, the fractionary part of the position will be 0.0
+
+Note that this does not affect the set of fragments generated by
+rasterization, which is instead controlled by gl_rasterization_rules in the
+rasterizer.
+
+OpenGL defaults to HALF_INTEGER, and is configurable with the
+GL_ARB_fragment_coord_conventions extension.
+
+DirectX 9 uses INTEGER.
+DirectX 10 uses HALF_INTEGER.
- SemanticIndex is an optional subscript that can be used to distinguish
- different register declarations with the same semantic name. The default value
- is 0.
- The meanings of the individual semantic names are explained in the following
- sections.
+Texture Sampling and Texture Formats
+------------------------------------
-3.1.1 FACE
+This table shows how texture image components are returned as (x,y,z,w) tuples
+by TGSI texture instructions, such as :opcode:`TEX`, :opcode:`TXD`, and
+:opcode:`TXP`. For reference, OpenGL and Direct3D conventions are shown as
+well.
- Valid only in a fragment shader INPUT declaration.
++--------------------+--------------+--------------------+--------------+
+| Texture Components | Gallium | OpenGL | Direct3D 9 |
++====================+==============+====================+==============+
+| R | XXX TBD | (r, 0, 0, 1) | (r, 1, 1, 1) |
++--------------------+--------------+--------------------+--------------+
+| RG | XXX TBD | (r, g, 0, 1) | (r, g, 1, 1) |
++--------------------+--------------+--------------------+--------------+
+| RGB | (r, g, b, 1) | (r, g, b, 1) | (r, g, b, 1) |
++--------------------+--------------+--------------------+--------------+
+| RGBA | (r, g, b, a) | (r, g, b, a) | (r, g, b, a) |
++--------------------+--------------+--------------------+--------------+
+| A | (0, 0, 0, a) | (0, 0, 0, a) | (0, 0, 0, a) |
++--------------------+--------------+--------------------+--------------+
+| L | (l, l, l, 1) | (l, l, l, 1) | (l, l, l, 1) |
++--------------------+--------------+--------------------+--------------+
+| LA | (l, l, l, a) | (l, l, l, a) | (l, l, l, a) |
++--------------------+--------------+--------------------+--------------+
+| I | (i, i, i, i) | (i, i, i, i) | N/A |
++--------------------+--------------+--------------------+--------------+
+| UV | XXX TBD | (0, 0, 0, 1) | (u, v, 1, 1) |
+| | | [#envmap-bumpmap]_ | |
++--------------------+--------------+--------------------+--------------+
+| Z | XXX TBD | (z, z, z, 1) | (0, z, 0, 1) |
+| | | [#depth-tex-mode]_ | |
++--------------------+--------------+--------------------+--------------+
- FACE.x is negative when the primitive is back facing. FACE.x is positive
- when the primitive is front facing.
+.. [#envmap-bumpmap] http://www.opengl.org/registry/specs/ATI/envmap_bumpmap.txt
+.. [#depth-tex-mode] the default is (z, z, z, 1) but may also be (0, 0, 0, z)
+ or (z, z, z, z) depending on the value of GL_DEPTH_TEXTURE_MODE.
projects / mesa.git / blobdiff