diff options
Diffstat (limited to 'src/gallium/docs/source')
| -rw-r--r-- | src/gallium/docs/source/context.rst | 4 | ||||
| -rw-r--r-- | src/gallium/docs/source/distro.rst | 54 | ||||
| -rw-r--r-- | src/gallium/docs/source/glossary.rst | 4 | ||||
| -rw-r--r-- | src/gallium/docs/source/screen.rst | 12 | ||||
| -rw-r--r-- | src/gallium/docs/source/tgsi.rst | 136 |
5 files changed, 150 insertions, 60 deletions
diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst index 0242dedbf3..4e35a4c408 100644 --- a/src/gallium/docs/source/context.rst +++ b/src/gallium/docs/source/context.rst @@ -1,3 +1,5 @@ +.. _context: + Context ======= @@ -120,7 +122,7 @@ will be cleared. color value. While it is only possible to clear one surface at a time (which can include several layers), this surface need not be bound to the framebuffer. -``clear_depth_stencil``clears a single depth, stencil or depth/stencil surface +``clear_depth_stencil`` clears a single depth, stencil or depth/stencil surface with the specified depth and stencil values (for combined depth/stencil buffers, is is also possible to only clear one or the other part). While it is only possible to clear one surface at a time (which can include several layers), diff --git a/src/gallium/docs/source/distro.rst b/src/gallium/docs/source/distro.rst index 100afe3397..6ba5a056f4 100644 --- a/src/gallium/docs/source/distro.rst +++ b/src/gallium/docs/source/distro.rst @@ -10,69 +10,100 @@ Drivers Cell ^^^^ +Simple driver for the IBM Cell architecture. Runs faster than :ref:`softpipe` +on Cell-based machines. + Failover ^^^^^^^^ -Deprecated. +Broken and deprecated. Intel i915 ^^^^^^^^^^ +Driver for Intel i915 and i945 chipsets. + Intel i965 ^^^^^^^^^^ -Highly experimental. +Highly experimental driver for Intel i965 chipsets. Identity ^^^^^^^^ -Wrapper driver. +Wrapper driver. The identity driver is a simple skeleton that passes through +all of its :ref:`Context` and :ref:`Screen` methods to an underlying Context +and Screen, and as such, it is an excellent starting point for new drivers. LLVM Softpipe ^^^^^^^^^^^^^ -nVidia nv30 -^^^^^^^^^^^ +A version of :ref:`softpipe` that uses the Low-Level Virtual Machine to +dynamically generate optimized rasterizing pipelines. -nVidia nv40 +nVidia nvfx ^^^^^^^^^^^ +Driver for the nVidia nv30 and nv40 families of GPUs. + nVidia nv50 ^^^^^^^^^^^ +Driver for the nVidia nv50 family of GPUs. + VMWare SVGA ^^^^^^^^^^^ +Driver for VMWare virtualized guest operating system graphics processing. + ATI r300 ^^^^^^^^ -Testing-quality. +Driver for the ATI/AMD r300, r400, and r500 families of GPUs. + +.. _softpipe: Softpipe ^^^^^^^^ -Reference software rasterizer. +Reference software rasterizer. Slow but accurate. Trace ^^^^^ -Wrapper driver. +Wrapper driver. Trace dumps an XML record of the calls made to the +:ref:`Context` and :ref:`Screen` objects that it wraps. State Trackers -------------- +.. _dri: + Direct Rendering Infrastructure ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Tracker that implements the client-side DRI protocol, for providing direct +acceleration services to X11 servers with the DRI extension. Supports DRI1 +and DRI2. Only GL is supported. + +.. _egl: + EGL ^^^ +Tracker for the Khronos EGL standard, used to set up GL and GLES contexts +without extra knowledge of the underlying windowing system. + GLX ^^^ MesaGL ^^^^^^ +Tracker implementing a GL state machine. Not usable as a standalone tracker; +Mesa should be built with another state tracker, such as :ref:`DRI` or +:ref:`EGL`. + Python ^^^^^^ @@ -82,9 +113,12 @@ OpenVG WGL ^^^ -Xorg XFree86 DDX +Xorg/XFree86 DDX ^^^^^^^^^^^^^^^^ +Tracker for XFree86 and Xorg X11 servers. Provides device-dependent +modesetting and acceleration as a DDX driver. + Auxiliary --------- diff --git a/src/gallium/docs/source/glossary.rst b/src/gallium/docs/source/glossary.rst index 0696cb5d27..acde56eafc 100644 --- a/src/gallium/docs/source/glossary.rst +++ b/src/gallium/docs/source/glossary.rst @@ -21,3 +21,7 @@ Glossary LOD Level of Detail. Also spelled "LoD." The value that determines when the switches between mipmaps occur during texture sampling. + + GLSL + GL Shading Language. The official, common high-level shader language used + in GL 2.0 and above. diff --git a/src/gallium/docs/source/screen.rst b/src/gallium/docs/source/screen.rst index 48d9d570b6..e3ef49c862 100644 --- a/src/gallium/docs/source/screen.rst +++ b/src/gallium/docs/source/screen.rst @@ -36,7 +36,9 @@ The integer capabilities: bound. * ``OCCLUSION_QUERY``: Whether occlusion queries are available. * ``TIMER_QUERY``: Whether timer queries are available. -* ``TEXTURE_SHADOW_MAP``: XXX +* ``TEXTURE_SHADOW_MAP``: indicates whether the fragment shader hardware + can do the depth texture / Z comparison operation in TEX instructions + for shadow testing. * ``MAX_TEXTURE_2D_LEVELS``: The maximum number of mipmap levels available for a 2D texture. * ``MAX_TEXTURE_3D_LEVELS``: The maximum number of mipmap levels available @@ -55,7 +57,13 @@ The integer capabilities: from color blend equations, in :ref:`Blend` state. * ``SM3``: Whether the vertex shader and fragment shader support equivalent opcodes to the Shader Model 3 specification. XXX oh god this is horrible -* ``MAX_PREDICATE_REGISTERS``: XXX +* ``MAX_PREDICATE_REGISTERS``: indicates the number of predicate registers + available. Predicate register may be set as a side-effect of ALU + instructions to indicate less than, greater than or equal to zero. + Later instructions can use a predicate register to control writing to + each channel of destination registers. NOTE: predicate registers have + not been fully implemented in Gallium at this time. See the + GL_NV_fragment_program extension for more info (look for "condition codes"). * ``MAX_COMBINED_SAMPLERS``: The total number of samplers accessible from the vertex and fragment shader, inclusive. * ``MAX_CONST_BUFFERS``: Maximum number of constant buffers that can be bound diff --git a/src/gallium/docs/source/tgsi.rst b/src/gallium/docs/source/tgsi.rst index 411dce856a..205e7b8539 100644 --- a/src/gallium/docs/source/tgsi.rst +++ b/src/gallium/docs/source/tgsi.rst @@ -26,9 +26,11 @@ each of the components of *dst*. When this happens, the result is said to be Instruction Set --------------- -From GL_NV_vertex_program +Core ISA ^^^^^^^^^^^^^^^^^^^^^^^^^ +These opcodes are guaranteed to be available regardless of the driver being +used. .. opcode:: ARL - Address Register Load @@ -637,10 +639,6 @@ This instruction replicates its result. Considered for removal. -From GL_NV_vertex_program2 -^^^^^^^^^^^^^^^^^^^^^^^^^^ - - .. opcode:: ARA - Address Register Add TBD @@ -827,11 +825,14 @@ This instruction replicates its result. Considered for removal. -From GL_NV_gpu_program4 +Compute ISA ^^^^^^^^^^^^^^^^^^^^^^^^ +These opcodes are primarily provided for special-use computational shaders. Support for these opcodes indicated by a special pipe capability bit (TBD). +XXX so let's discuss it, yeah? + .. opcode:: CEIL - Ceiling .. math:: @@ -989,10 +990,17 @@ Support for these opcodes indicated by a special pipe capability bit (TBD). TBD +.. note:: + + Support for CONT is determined by a special capability bit, + ``TGSI_CONT_SUPPORTED``. See :ref:`Screen` for more information. -From GL_NV_geometry_program4 + +Geometry ISA ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +These opcodes are only supported in geometry shaders; they have no meaning +in any other type of shader. .. opcode:: EMIT - Emit @@ -1004,9 +1012,11 @@ From GL_NV_geometry_program4 TBD -From GLSL +GLSL ISA ^^^^^^^^^^ +These opcodes are part of :term:`GLSL`'s opcode set. Support for these +opcodes is determined by a special capability bit, ``GLSL``. .. opcode:: BGNLOOP - Begin a Loop @@ -1045,6 +1055,7 @@ This instruction replicates its result. ps_2_x ^^^^^^^^^^^^ +XXX wait what .. opcode:: CALLNZ - Subroutine Call If Not Zero @@ -1062,10 +1073,15 @@ ps_2_x .. _doubleopcodes: -Double Opcodes +Double ISA ^^^^^^^^^^^^^^^ -.. opcode:: DADD - Add Double +The double-precision opcodes reinterpret four-component vectors into +two-component vectors with doubled precision in each component. + +Support for these opcodes is XXX undecided. :T + +.. opcode:: DADD - Add .. math:: @@ -1074,7 +1090,7 @@ Double Opcodes dst.zw = src0.zw + src1.zw -.. opcode:: DDIV - Divide Double +.. opcode:: DDIV - Divide .. math:: @@ -1082,7 +1098,7 @@ Double Opcodes dst.zw = src0.zw / src1.zw -.. opcode:: DSEQ - Set Double on Equal +.. opcode:: DSEQ - Set on Equal .. math:: @@ -1090,7 +1106,7 @@ Double Opcodes dst.zw = src0.zw == src1.zw ? 1.0F : 0.0F -.. opcode:: DSLT - Set Double on Less than +.. opcode:: DSLT - Set on Less than .. math:: @@ -1098,7 +1114,7 @@ Double Opcodes dst.zw = src0.zw < src1.zw ? 1.0F : 0.0F -.. opcode:: DFRAC - Double Fraction +.. opcode:: DFRAC - Fraction .. math:: @@ -1107,23 +1123,33 @@ Double Opcodes dst.zw = src.zw - \lfloor src.zw\rfloor -.. opcode:: DFRACEXP - Convert Double Number to Fractional and Integral Components +.. opcode:: DFRACEXP - Convert Number to Fractional and Integral Components + +Like the ``frexp()`` routine in many math libraries, this opcode stores the +exponent of its source to ``dst0``, and the significand to ``dst1``, such that +:math:`dst1 \times 2^{dst0} = src` . .. math:: - dst0.xy = frexp(src.xy, dst1.xy) + dst0.xy = exp(src.xy) + + dst1.xy = frac(src.xy) - dst0.zw = frexp(src.zw, dst1.zw) + dst0.zw = exp(src.zw) -.. opcode:: DLDEXP - Multiple Double Number by Integral Power of 2 + dst1.zw = frac(src.zw) + +.. opcode:: DLDEXP - Multiply Number by Integral Power of 2 + +This opcode is the inverse of :opcode:`DFRACEXP`. .. math:: - dst.xy = ldexp(src0.xy, src1.xy) + dst.xy = src0.xy \times 2^{src1.xy} - dst.zw = ldexp(src0.zw, src1.zw) + dst.zw = src0.zw \times 2^{src1.zw} -.. opcode:: DMIN - Minimum Double +.. opcode:: DMIN - Minimum .. math:: @@ -1131,7 +1157,7 @@ Double Opcodes dst.zw = min(src0.zw, src1.zw) -.. opcode:: DMAX - Maximum Double +.. opcode:: DMAX - Maximum .. math:: @@ -1139,7 +1165,7 @@ Double Opcodes dst.zw = max(src0.zw, src1.zw) -.. opcode:: DMUL - Multiply Double +.. opcode:: DMUL - Multiply .. math:: @@ -1148,7 +1174,7 @@ Double Opcodes dst.zw = src0.zw \times src1.zw -.. opcode:: DMAD - Multiply And Add Doubles +.. opcode:: DMAD - Multiply And Add .. math:: @@ -1157,7 +1183,7 @@ Double Opcodes dst.zw = src0.zw \times src1.zw + src2.zw -.. opcode:: DRCP - Reciprocal Double +.. opcode:: DRCP - Reciprocal .. math:: @@ -1165,7 +1191,7 @@ Double Opcodes dst.zw = \frac{1}{src.zw} -.. opcode:: DSQRT - Square root double +.. opcode:: DSQRT - Square Root .. math:: @@ -1280,38 +1306,46 @@ Declaration Semantic TGSI_SEMANTIC_POSITION """""""""""""""""""""" -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. - -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. +For vertex shaders, TGSI_SEMANTIC_POSITION indicates the vertex shader +output register which contains the homogeneous vertex position in the clip +space coordinate system. After clipping, the X, Y and Z components of the +vertex will be divided by the W value to get normalized device coordinates. -XXX additionally, is there a way to configure the perspective divide? it's -accelerated on most chipsets AFAIK... +For fragment shaders, TGSI_SEMANTIC_POSITION is used to indicate that +fragment shader input contains the fragment's window position. The X +component starts at zero and always increases from left to right. +The Y component starts at zero and always increases but Y=0 may either +indicate the top of the window or the bottom depending on the fragment +coordinate origin convention (see TGSI_PROPERTY_FS_COORD_ORIGIN). +The Z coordinate ranges from 0 to 1 to represent depth from the front +to the back of the Z buffer. The W component contains the reciprocol +of the interpolated vertex position W component. -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)``. -XXX usually? can we solidify that? TGSI_SEMANTIC_COLOR """"""""""""""""""" -Colors are used to, well, color the primitives. Colors are always in -``(r, g, b, a)`` format. +For vertex shader outputs or fragment shader inputs/outputs, this +label indicates that the resister contains an R,G,B,A color. + +Several shader inputs/outputs may contain colors so the semantic index +is used to distinguish them. For example, color[0] may be the diffuse +color while color[1] may be the specular color. + +This label is needed so that the flat/smooth shading can be applied +to the right interpolants during rasterization. + -If alpha is not specified, it defaults to 1. TGSI_SEMANTIC_BCOLOR """""""""""""""""""" 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. +and COLOR and BCOLOR end up occupying the same slots in the fragment shader, +so all BCOLORs effectively become regular COLORs in the fragment shader. + TGSI_SEMANTIC_FOG """"""""""""""""" @@ -1363,7 +1397,15 @@ back-facing. TGSI_SEMANTIC_EDGEFLAG """""""""""""""""""""" -XXX no clue +For vertex shaders, this sematic label indicates that an input or +output is a boolean edge flag. The register layout is [F, x, x, x] +where F is 0.0 or 1.0 and x = don't care. Normally, the vertex shader +simply copies the edge flag input to the edgeflag output. + +Edge flags are used to control which lines or points are actually +drawn when the polygon mode converts triangles/quads/polygons into +points or lines. + Properties @@ -1420,9 +1462,9 @@ well. +--------------------+--------------+--------------------+--------------+ | Texture Components | Gallium | OpenGL | Direct3D 9 | +====================+==============+====================+==============+ -| R | XXX TBD | (r, 0, 0, 1) | (r, 1, 1, 1) | +| R | (r, 0, 0, 1) | (r, 0, 0, 1) | (r, 1, 1, 1) | +--------------------+--------------+--------------------+--------------+ -| RG | XXX TBD | (r, g, 0, 1) | (r, g, 1, 1) | +| RG | (r, g, 0, 1) | (r, g, 0, 1) | (r, g, 1, 1) | +--------------------+--------------+--------------------+--------------+ | RGB | (r, g, b, 1) | (r, g, b, 1) | (r, g, b, 1) | +--------------------+--------------+--------------------+--------------+ |