← Back to branch summary

~ubuntu-branches/ubuntu/natty/mesa/natty-proposed

« back to all changes in this revision

Viewing changes to src/gallium/docs/source/tgsi.rst

  • Committer: Bazaar Package Importer
  • Author(s): Robert Hooker, Robert Hooker, Christopher James Halse Rogers
  • Date: 2010-09-14 08:55:40 UTC
  • mfrom: (1.2.28 upstream)
  • Revision ID: james.westby@ubuntu.com-20100914085540-m4fpl0hdjlfd4jgz
Tags: 7.9~git20100909-0ubuntu1
https://launchpad.net/bugs/631413
https://launchpad.net/bugs/628930
https://launchpad.net/bugs/628727
https://launchpad.net/bugs/596292
https://launchpad.net/bugs/599741
https://launchpad.net/bugs/630315
https://launchpad.net/bugs/613694
https://launchpad.net/bugs/599741
https://launchpad.net/bugs/578619
https://launchpad.net/bugs/626943
https://launchpad.net/bugs/610541
https://launchpad.net/bugs/601052
[ Robert Hooker ]
* New upstream git snapshot up to commit 94118fe2d4b1e5 (LP: #631413)
* New features include ATI HD5xxx series support in r600, and a vastly
  improved glsl compiler.
* Remove pre-generated .pc's, use the ones generated at build time
  instead.
* Remove all references to mesa-utils now that its no longer shipped
  with the mesa source.
* Disable the experimental ARB_fragment_shader option by default on
  i915, it exposes incomplete functionality that breaks KDE compositing
  among other things. It can be enabled via driconf still. (LP: #628930).

[ Christopher James Halse Rogers ]
* debian/patches/04_osmesa_version.diff:
  - Refresh for new upstream
* Bugs fixed in this release:
  - Fixes severe rendering corruption in Unity on radeon (LP: #628727,
    LP: #596292, LP: #599741, LP: #630315, LP: #613694, LP: #599741).
  - Also fixes rendering in gnome-shell (LP: #578619).
  - Flickering in OpenGL apps on radeon (LP: #626943, LP: #610541).
  - Provides preliminary support for new intel chips (LP: #601052).
* debian/rules:
  - Update configure flags to match upstream reshuffling.
  - Explicitly remove gallium DRI drivers that we don't want to ship.
* Update debian/gbp.conf for this Maverick-specific packaging
* libegl1-mesa-dri-x11,kms: There are no longer separate kms or x11 drivers
  for EGL, libegl1-mesa-drivers now contains a single driver that provides
  both backends.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/gallium/docs/source/tgsi.rst
26
26
Instruction Set
27
27
---------------
28
28
 
29
 
From GL_NV_vertex_program
 
29
Core ISA
30
30
^^^^^^^^^^^^^^^^^^^^^^^^^
31
31
 
 
32
These opcodes are guaranteed to be available regardless of the driver being
 
33
used.
32
34
 
33
35
.. opcode:: ARL - Address Register Load
34
36
 
287
289
  dst.w = src0.x \times src1.x + src0.y \times src1.y + src2.x
288
290
 
289
291
 
290
 
.. opcode:: FRAC - Fraction
 
292
.. opcode:: FRC - Fraction
291
293
 
292
294
.. math::
293
295
 
637
639
   Considered for removal.
638
640
 
639
641
 
640
 
From GL_NV_vertex_program2
641
 
^^^^^^^^^^^^^^^^^^^^^^^^^^
642
 
 
643
 
 
644
642
.. opcode:: ARA - Address Register Add
645
643
 
646
644
  TBD
786
784
  TBD
787
785
 
788
786
 
789
 
.. opcode:: BGNFOR - Begin a For-Loop
790
 
 
791
 
  dst.x = floor(src.x)
792
 
  dst.y = floor(src.y)
793
 
  dst.z = floor(src.z)
794
 
 
795
 
  if (dst.y <= 0)
796
 
    pc = [matching ENDFOR] + 1
797
 
  endif
798
 
 
799
 
  Note: The destination must be a loop register.
800
 
        The source must be a constant register.
801
 
 
802
 
.. note::
803
 
 
804
 
   Considered for cleanup.
805
 
 
806
 
.. note::
807
 
 
808
 
   Considered for removal.
809
 
 
810
 
 
811
 
.. opcode:: REP - Repeat
812
 
 
813
 
  TBD
814
 
 
815
 
 
816
787
.. opcode:: ELSE - Else
817
788
 
818
789
  TBD
823
794
  TBD
824
795
 
825
796
 
826
 
.. opcode:: ENDFOR - End a For-Loop
827
 
 
828
 
  dst.x = dst.x + dst.z
829
 
  dst.y = dst.y - 1.0
830
 
 
831
 
  if (dst.y > 0)
832
 
    pc = [matching BGNFOR instruction] + 1
833
 
  endif
834
 
 
835
 
  Note: The destination must be a loop register.
836
 
 
837
 
.. note::
838
 
 
839
 
   Considered for cleanup.
840
 
 
841
 
.. note::
842
 
 
843
 
   Considered for removal.
844
 
 
845
 
.. opcode:: ENDREP - End Repeat
846
 
 
847
 
  TBD
848
 
 
849
 
 
850
797
.. opcode:: PUSHA - Push Address Register On Stack
851
798
 
852
799
  push(src.x)
878
825
   Considered for removal.
879
826
 
880
827
 
881
 
From GL_NV_gpu_program4
 
828
Compute ISA
882
829
^^^^^^^^^^^^^^^^^^^^^^^^
883
830
 
 
831
These opcodes are primarily provided for special-use computational shaders.
884
832
Support for these opcodes indicated by a special pipe capability bit (TBD).
885
833
 
 
834
XXX so let's discuss it, yeah?
 
835
 
886
836
.. opcode:: CEIL - Ceiling
887
837
 
888
838
.. math::
1040
990
 
1041
991
  TBD
1042
992
 
1043
 
 
1044
 
From GL_NV_geometry_program4
 
993
.. note::
 
994
 
 
995
   Support for CONT is determined by a special capability bit,
 
996
   ``TGSI_CONT_SUPPORTED``. See :ref:`Screen` for more information.
 
997
 
 
998
 
 
999
Geometry ISA
1045
1000
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1046
1001
 
 
1002
These opcodes are only supported in geometry shaders; they have no meaning
 
1003
in any other type of shader.
1047
1004
 
1048
1005
.. opcode:: EMIT - Emit
1049
1006
 
1055
1012
  TBD
1056
1013
 
1057
1014
 
1058
 
From GLSL
 
1015
GLSL ISA
1059
1016
^^^^^^^^^^
1060
1017
 
 
1018
These opcodes are part of :term:`GLSL`'s opcode set. Support for these
 
1019
opcodes is determined by a special capability bit, ``GLSL``.
1061
1020
 
1062
1021
.. opcode:: BGNLOOP - Begin a Loop
1063
1022
 
1096
1055
ps_2_x
1097
1056
^^^^^^^^^^^^
1098
1057
 
 
1058
XXX wait what
1099
1059
 
1100
1060
.. opcode:: CALLNZ - Subroutine Call If Not Zero
1101
1061
 
1113
1073
 
1114
1074
.. _doubleopcodes:
1115
1075
 
1116
 
Double Opcodes
 
1076
Double ISA
1117
1077
^^^^^^^^^^^^^^^
1118
1078
 
1119
 
.. opcode:: DADD - Add Double
 
1079
The double-precision opcodes reinterpret four-component vectors into
 
1080
two-component vectors with doubled precision in each component.
 
1081
 
 
1082
Support for these opcodes is XXX undecided. :T
 
1083
 
 
1084
.. opcode:: DADD - Add
1120
1085
 
1121
1086
.. math::
1122
1087
 
1125
1090
  dst.zw = src0.zw + src1.zw
1126
1091
 
1127
1092
 
1128
 
.. opcode:: DDIV - Divide Double
 
1093
.. opcode:: DDIV - Divide
1129
1094
 
1130
1095
.. math::
1131
1096
 
1133
1098
 
1134
1099
  dst.zw = src0.zw / src1.zw
1135
1100
 
1136
 
.. opcode:: DSEQ - Set Double on Equal
 
1101
.. opcode:: DSEQ - Set on Equal
1137
1102
 
1138
1103
.. math::
1139
1104
 
1141
1106
 
1142
1107
  dst.zw = src0.zw == src1.zw ? 1.0F : 0.0F
1143
1108
 
1144
 
.. opcode:: DSLT - Set Double on Less than
 
1109
.. opcode:: DSLT - Set on Less than
1145
1110
 
1146
1111
.. math::
1147
1112
 
1149
1114
 
1150
1115
  dst.zw = src0.zw < src1.zw ? 1.0F : 0.0F
1151
1116
 
1152
 
.. opcode:: DFRAC - Double Fraction
 
1117
.. opcode:: DFRAC - Fraction
1153
1118
 
1154
1119
.. math::
1155
1120
 
1158
1123
  dst.zw = src.zw - \lfloor src.zw\rfloor
1159
1124
 
1160
1125
 
1161
 
.. opcode:: DFRACEXP - Convert Double Number to Fractional and Integral Components
1162
 
 
1163
 
.. math::
1164
 
 
1165
 
  dst0.xy = frexp(src.xy, dst1.xy)
1166
 
 
1167
 
  dst0.zw = frexp(src.zw, dst1.zw)
1168
 
 
1169
 
.. opcode:: DLDEXP - Multiple Double Number by Integral Power of 2
1170
 
 
1171
 
.. math::
1172
 
 
1173
 
  dst.xy = ldexp(src0.xy, src1.xy)
1174
 
 
1175
 
  dst.zw = ldexp(src0.zw, src1.zw)
1176
 
 
1177
 
.. opcode:: DMIN - Minimum Double
 
1126
.. opcode:: DFRACEXP - Convert Number to Fractional and Integral Components
 
1127
 
 
1128
Like the ``frexp()`` routine in many math libraries, this opcode stores the
 
1129
exponent of its source to ``dst0``, and the significand to ``dst1``, such that
 
1130
:math:`dst1 \times 2^{dst0} = src` .
 
1131
 
 
1132
.. math::
 
1133
 
 
1134
  dst0.xy = exp(src.xy)
 
1135
 
 
1136
  dst1.xy = frac(src.xy)
 
1137
 
 
1138
  dst0.zw = exp(src.zw)
 
1139
 
 
1140
  dst1.zw = frac(src.zw)
 
1141
 
 
1142
.. opcode:: DLDEXP - Multiply Number by Integral Power of 2
 
1143
 
 
1144
This opcode is the inverse of :opcode:`DFRACEXP`.
 
1145
 
 
1146
.. math::
 
1147
 
 
1148
  dst.xy = src0.xy \times 2^{src1.xy}
 
1149
 
 
1150
  dst.zw = src0.zw \times 2^{src1.zw}
 
1151
 
 
1152
.. opcode:: DMIN - Minimum
1178
1153
 
1179
1154
.. math::
1180
1155
 
1182
1157
 
1183
1158
  dst.zw = min(src0.zw, src1.zw)
1184
1159
 
1185
 
.. opcode:: DMAX - Maximum Double
 
1160
.. opcode:: DMAX - Maximum
1186
1161
 
1187
1162
.. math::
1188
1163
 
1190
1165
 
1191
1166
  dst.zw = max(src0.zw, src1.zw)
1192
1167
 
1193
 
.. opcode:: DMUL - Multiply Double
 
1168
.. opcode:: DMUL - Multiply
1194
1169
 
1195
1170
.. math::
1196
1171
 
1199
1174
  dst.zw = src0.zw \times src1.zw
1200
1175
 
1201
1176
 
1202
 
.. opcode:: DMAD - Multiply And Add Doubles
 
1177
.. opcode:: DMAD - Multiply And Add
1203
1178
 
1204
1179
.. math::
1205
1180
 
1208
1183
  dst.zw = src0.zw \times src1.zw + src2.zw
1209
1184
 
1210
1185
 
1211
 
.. opcode:: DRCP - Reciprocal Double
 
1186
.. opcode:: DRCP - Reciprocal
1212
1187
 
1213
1188
.. math::
1214
1189
 
1216
1191
 
1217
1192
   dst.zw = \frac{1}{src.zw}
1218
1193
 
1219
 
.. opcode:: DSQRT - Square root double
 
1194
.. opcode:: DSQRT - Square Root
1220
1195
 
1221
1196
.. math::
1222
1197
 
1311
1286
Declaration Semantic
1312
1287
^^^^^^^^^^^^^^^^^^^^^^^^
1313
1288
 
 
1289
  Vertex and fragment shader input and output registers may be labeled
 
1290
  with semantic information consisting of a name and index.
1314
1291
 
1315
1292
  Follows Declaration token if Semantic bit is set.
1316
1293
 
1331
1308
TGSI_SEMANTIC_POSITION
1332
1309
""""""""""""""""""""""
1333
1310
 
1334
 
Position, sometimes known as HPOS or WPOS for historical reasons, is the
1335
 
location of the vertex in space, in ``(x, y, z, w)`` format. ``x``, ``y``, and ``z``
1336
 
are the Cartesian coordinates, and ``w`` is the homogenous coordinate and used
1337
 
for the perspective divide, if enabled.
1338
 
 
1339
 
As a vertex shader output, position should be scaled to the viewport. When
1340
 
used in fragment shaders, position will be in window coordinates. The convention
1341
 
used depends on the FS_COORD_ORIGIN and FS_COORD_PIXEL_CENTER properties.
1342
 
 
1343
 
XXX additionally, is there a way to configure the perspective divide? it's
1344
 
accelerated on most chipsets AFAIK...
1345
 
 
1346
 
Position, if not specified, usually defaults to ``(0, 0, 0, 1)``, and can
1347
 
be partially specified as ``(x, y, 0, 1)`` or ``(x, y, z, 1)``.
1348
 
 
1349
 
XXX usually? can we solidify that?
 
1311
For vertex shaders, TGSI_SEMANTIC_POSITION indicates the vertex shader
 
1312
output register which contains the homogeneous vertex position in the clip
 
1313
space coordinate system.  After clipping, the X, Y and Z components of the
 
1314
vertex will be divided by the W value to get normalized device coordinates.
 
1315
 
 
1316
For fragment shaders, TGSI_SEMANTIC_POSITION is used to indicate that
 
1317
fragment shader input contains the fragment's window position.  The X
 
1318
component starts at zero and always increases from left to right.
 
1319
The Y component starts at zero and always increases but Y=0 may either
 
1320
indicate the top of the window or the bottom depending on the fragment
 
1321
coordinate origin convention (see TGSI_PROPERTY_FS_COORD_ORIGIN).
 
1322
The Z coordinate ranges from 0 to 1 to represent depth from the front
 
1323
to the back of the Z buffer.  The W component contains the reciprocol
 
1324
of the interpolated vertex position W component.
 
1325
 
 
1326
Fragment shaders may also declare an output register with
 
1327
TGSI_SEMANTIC_POSITION.  Only the Z component is writable.  This allows
 
1328
the fragment shader to change the fragment's Z position.
 
1329
 
 
1330
 
1350
1331
 
1351
1332
TGSI_SEMANTIC_COLOR
1352
1333
"""""""""""""""""""
1353
1334
 
1354
 
Colors are used to, well, color the primitives. Colors are always in
1355
 
``(r, g, b, a)`` format.
1356
 
 
1357
 
If alpha is not specified, it defaults to 1.
 
1335
For vertex shader outputs or fragment shader inputs/outputs, this
 
1336
label indicates that the resister contains an R,G,B,A color.
 
1337
 
 
1338
Several shader inputs/outputs may contain colors so the semantic index
 
1339
is used to distinguish them.  For example, color[0] may be the diffuse
 
1340
color while color[1] may be the specular color.
 
1341
 
 
1342
This label is needed so that the flat/smooth shading can be applied
 
1343
to the right interpolants during rasterization.
 
1344
 
 
1345
 
1358
1346
 
1359
1347
TGSI_SEMANTIC_BCOLOR
1360
1348
""""""""""""""""""""
1361
1349
 
1362
1350
Back-facing colors are only used for back-facing polygons, and are only valid
1363
1351
in vertex shader outputs. After rasterization, all polygons are front-facing
1364
 
and COLOR and BCOLOR end up occupying the same slots in the fragment, so
1365
 
all BCOLORs effectively become regular COLORs in the fragment shader.
 
1352
and COLOR and BCOLOR end up occupying the same slots in the fragment shader,
 
1353
so all BCOLORs effectively become regular COLORs in the fragment shader.
 
1354
 
1366
1355
 
1367
1356
TGSI_SEMANTIC_FOG
1368
1357
"""""""""""""""""
1369
1358
 
1370
 
The fog coordinate historically has been used to replace the depth coordinate
1371
 
for generation of fog in dedicated fog blocks. Gallium, however, does not use
1372
 
dedicated fog acceleration, placing it entirely in the fragment shader
1373
 
instead.
1374
 
 
1375
 
The fog coordinate should be written in ``(f, 0, 0, 1)`` format. Only the first
1376
 
component matters when writing from the vertex shader; the driver will ensure
1377
 
that the coordinate is in this format when used as a fragment shader input.
 
1359
Vertex shader inputs and outputs and fragment shader inputs may be
 
1360
labeled with TGSI_SEMANTIC_FOG to indicate that the register contains
 
1361
a fog coordinate in the form (F, 0, 0, 1).  Typically, the fragment
 
1362
shader will use the fog coordinate to compute a fog blend factor which
 
1363
is used to blend the normal fragment color with a constant fog color.
 
1364
 
 
1365
Only the first component matters when writing from the vertex shader;
 
1366
the driver will ensure that the coordinate is in this format when used
 
1367
as a fragment shader input.
 
1368
 
1378
1369
 
1379
1370
TGSI_SEMANTIC_PSIZE
1380
1371
"""""""""""""""""""
1381
1372
 
1382
 
PSIZE, or point size, is used to specify point sizes per-vertex. It should
1383
 
be in ``(s, 0, 0, 1)`` format, where ``s`` is the (possibly clamped) point size.
1384
 
Only the first component matters when writing from the vertex shader.
 
1373
Vertex shader input and output registers may be labeled with
 
1374
TGIS_SEMANTIC_PSIZE to indicate that the register contains a point size
 
1375
in the form (S, 0, 0, 1).  The point size controls the width or diameter
 
1376
of points for rasterization.  This label cannot be used in fragment
 
1377
shaders.
1385
1378
 
1386
1379
When using this semantic, be sure to set the appropriate state in the
1387
1380
:ref:`rasterizer` first.
1388
1381
 
 
1382
 
1389
1383
TGSI_SEMANTIC_GENERIC
1390
1384
"""""""""""""""""""""
1391
1385
 
1392
 
Generic semantics are nearly always used for texture coordinate attributes,
1393
 
in ``(s, t, r, q)`` format. ``t`` and ``r`` may be unused for certain kinds
1394
 
of lookups, and ``q`` is the level-of-detail bias for biased sampling.
 
1386
All vertex/fragment shader inputs/outputs not labeled with any other
 
1387
semantic label can be considered to be generic attributes.  Typical
 
1388
uses of generic inputs/outputs are texcoords and user-defined values.
1395
1389
 
1396
 
These attributes are called "generic" because they may be used for anything
1397
 
else, including parameters, texture generation information, or anything that
1398
 
can be stored inside a four-component vector.
1399
1390
 
1400
1391
TGSI_SEMANTIC_NORMAL
1401
1392
""""""""""""""""""""
1402
1393
 
1403
 
Vertex normal; could be used to implement per-pixel lighting for legacy APIs
1404
 
that allow mixing fixed-function and programmable stages.
 
1394
Indicates that a vertex shader input is a normal vector.  This is
 
1395
typically only used for legacy graphics APIs.
 
1396
 
1405
1397
 
1406
1398
TGSI_SEMANTIC_FACE
1407
1399
""""""""""""""""""
1408
1400
 
1409
 
FACE is the facing bit, to store the facing information for the fragment
1410
 
shader. ``(f, 0, 0, 1)`` is the format. The first component will be positive
1411
 
when the fragment is front-facing, and negative when the component is
1412
 
back-facing.
 
1401
This label applies to fragment shader inputs only and indicates that
 
1402
the register contains front/back-face information of the form (F, 0,
 
1403
0, 1).  The first component will be positive when the fragment belongs
 
1404
to a front-facing polygon, and negative when the fragment belongs to a
 
1405
back-facing polygon.
 
1406
 
1413
1407
 
1414
1408
TGSI_SEMANTIC_EDGEFLAG
1415
1409
""""""""""""""""""""""
1416
1410
 
1417
 
XXX no clue
 
1411
For vertex shaders, this sematic label indicates that an input or
 
1412
output is a boolean edge flag.  The register layout is [F, x, x, x]
 
1413
where F is 0.0 or 1.0 and x = don't care.  Normally, the vertex shader
 
1414
simply copies the edge flag input to the edgeflag output.
 
1415
 
 
1416
Edge flags are used to control which lines or points are actually
 
1417
drawn when the polygon mode converts triangles/quads/polygons into
 
1418
points or lines.
 
1419
 
1418
1420
 
1419
1421
 
1420
1422
Properties
1471
1473
+--------------------+--------------+--------------------+--------------+
1472
1474
| Texture Components | Gallium      | OpenGL             | Direct3D 9   |
1473
1475
+====================+==============+====================+==============+
1474
 
| R                  | XXX TBD      | (r, 0, 0, 1)       | (r, 1, 1, 1) |
 
1476
| R                  | (r, 0, 0, 1) | (r, 0, 0, 1)       | (r, 1, 1, 1) |
1475
1477
+--------------------+--------------+--------------------+--------------+
1476
 
| RG                 | XXX TBD      | (r, g, 0, 1)       | (r, g, 1, 1) |
 
1478
| RG                 | (r, g, 0, 1) | (r, g, 0, 1)       | (r, g, 1, 1) |
1477
1479
+--------------------+--------------+--------------------+--------------+
1478
1480
| RGB                | (r, g, b, 1) | (r, g, b, 1)       | (r, g, b, 1) |
1479
1481
+--------------------+--------------+--------------------+--------------+