diff options
Diffstat (limited to 'src/gallium/docs')
| -rw-r--r-- | src/gallium/docs/d3d11ddi.txt | 59 | ||||
| -rw-r--r-- | src/gallium/docs/source/conf.py | 6 | ||||
| -rw-r--r-- | src/gallium/docs/source/context.rst | 153 | ||||
| -rw-r--r-- | src/gallium/docs/source/cso/blend.rst | 67 | ||||
| -rw-r--r-- | src/gallium/docs/source/cso/rasterizer.rst | 172 | ||||
| -rw-r--r-- | src/gallium/docs/source/cso/velems.rst | 41 | ||||
| -rw-r--r-- | src/gallium/docs/source/debugging.rst | 105 | ||||
| -rw-r--r-- | src/gallium/docs/source/distro.rst | 70 | ||||
| -rw-r--r-- | src/gallium/docs/source/exts/formatting.py | 31 | ||||
| -rw-r--r-- | src/gallium/docs/source/exts/tgsi.py | 17 | ||||
| -rw-r--r-- | src/gallium/docs/source/glossary.rst | 4 | ||||
| -rw-r--r-- | src/gallium/docs/source/index.rst | 2 | ||||
| -rw-r--r-- | src/gallium/docs/source/pipeline.txt | 128 | ||||
| -rw-r--r-- | src/gallium/docs/source/resources.rst | 195 | ||||
| -rw-r--r-- | src/gallium/docs/source/screen.rst | 38 | ||||
| -rw-r--r-- | src/gallium/docs/source/tgsi.rst | 195 |
16 files changed, 998 insertions, 285 deletions
diff --git a/src/gallium/docs/d3d11ddi.txt b/src/gallium/docs/d3d11ddi.txt index 8f2509ce035..f8155c828b1 100644 --- a/src/gallium/docs/d3d11ddi.txt +++ b/src/gallium/docs/d3d11ddi.txt @@ -66,9 +66,6 @@ Unordered access view: view supporting random read/write access (usually from co clear + Gallium supports clearing both render targets and depth/stencil with a single call -draw_range_elements - + Gallium supports indexed draw with explicit range - fence_signalled fence_finish + D3D10/D3D11 don't appear to support explicit fencing; queries can often substitute though, and flushing is supported @@ -79,7 +76,7 @@ set_clip_state set_polygon_stipple + Gallium supports polygon stipple -surface_fill +clearRT/clearDS + Gallium supports subrectangle fills of surfaces, D3D10 only supports full clears of views * DirectX 10/11 DDI functions and Gallium equivalents @@ -114,11 +111,10 @@ CheckDeferredContextHandleSizes (D3D11 only) CheckFormatSupport -> screen->is_format_supported ! Gallium passes usages to this function, D3D11 returns them - Gallium does not differentiate between blendable and non-blendable render targets - - Gallium lacks multisampled-texture and multisampled-render-target usages + ! Gallium includes sample count directly, D3D11 uses additional query CheckMultisampleQualityLevels - * could merge this with is_format_supported - - Gallium lacks multisampling support + ! is merged with is_format_supported CommandListExecute (D3D11 only) - Gallium does not support command lists @@ -139,7 +135,6 @@ ClearUnorderedAccessViewUint (D3D11 only) CreateBlendState (extended in D3D10.1) -> create_blend_state # D3D10 does not support per-RT blend modes (but per-RT blending), only D3D10.1 does - - Gallium lacks alpha-to-coverage + Gallium supports logic ops + Gallium supports dithering + Gallium supports using the broadcast alpha component of the blend constant color @@ -179,7 +174,7 @@ CreateElementLayout -> create_vertex_elements_state ! D3D11 has an extra flag (InputSlotClass) that is the same as instance_divisor == 0 CreateGeometryShader -> create_gs_state -CreateGeometryShaderWithStreamOutput -> create_gs_state +CreateGeometryShaderWithStreamOutput -> create_gs_state + create_stream_output_state CreatePixelShader -> create_fs_state CreateVertexShader -> create_vs_state > bytecode is different (see D3d10tokenizedprogramformat.hpp) @@ -198,7 +193,6 @@ CreateQuery -> create_query CreateRasterizerState - Gallium lacks clamping of polygon offset depth biases - Gallium lacks support to disable depth clipping - - Gallium lacks multisampling + Gallium, like OpenGL, supports PIPE_POLYGON_MODE_POINT + Gallium, like OpenGL, supports per-face polygon fill modes + Gallium, like OpenGL, supports culling everything @@ -223,12 +217,10 @@ CreateResource -> texture_create or buffer_create # Note that hardware often has the implicit rule, so the D3D11 interface seems to make little sense # Also, the D3D11 API does not allow the user to specify mipmap sizes, so this really seems a dubious decision on Microsoft's part - D3D11 supports specifying initial data to write in the resource - - Gallium lacks support for stream output buffer usage - Gallium does not support unordered access buffers ! D3D11 specifies mapping flags (i.e. read/write/discard);:it's unclear what they are used for here - D3D11 supports odd things in the D3D10_DDI_RESOURCE_MISC_FLAG enum (D3D10_DDI_RESOURCE_MISC_DISCARD_ON_PRESENT, D3D11_DDI_RESOURCE_MISC_BUFFER_ALLOW_RAW_VIEWS, D3D11_DDI_RESOURCE_MISC_BUFFER_STRUCTURED) - Gallium does not support indirect draw call parameter buffers - - Gallium lacks multisampling - Gallium lacks array textures ! D3D11 supports specifying hardware modes and other stuff here for scanout resources + Gallium allows specifying minimum buffer alignment @@ -276,32 +268,27 @@ Dispatch (D3D11 only) DispatchIndirect (D3D11 only) - Gallium does not support compute shaders -Draw -> draw_arrays +Draw -> draw_vbo ! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better -DrawAuto - - Gallium lacks stream out and DrawAuto +DrawAuto -> draw_auto -DrawIndexed -> draw_elements +DrawIndexed -> draw_vbo ! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better - * may want to add a separate set_index_buffer - - Gallium lacks base vertex for indexed draw calls - + D3D11 lacks draw_range_elements functionality, which is required for OpenGL + + D3D11 lacks explicit range, which is required for OpenGL -DrawIndexedInstanced -> draw_elements_instanced +DrawIndexedInstanced -> draw_vbo ! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better - * may want to add a separate set_index_buffer - - Gallium lacks base vertex for indexed draw calls -DrawIndexedInstancedIndirect (D3D11 only) -> call draw_elements_instanced multiple times in software - # this allows to use an hardware buffer to specify the parameters for multiple draw_elements_instanced calls +DrawIndexedInstancedIndirect (D3D11 only) + # this allows to use an hardware buffer to specify the parameters for multiple draw_vbo calls - Gallium does not support draw call parameter buffers and indirect draw -DrawInstanced -> draw_arrays_instanced +DrawInstanced -> draw_vbo ! D3D11 sets primitive modes separately with IaSetTopology: it's not obvious which is better -DrawInstancedIndirect (D3D11 only) -> call draw_arrays_instanced multiple times in software - # this allows to use an hardware buffer to specify the parameters for multiple draw_arrays_instanced calls +DrawInstancedIndirect (D3D11 only) + # this allows to use an hardware buffer to specify the parameters for multiple draw_vbo calls - Gallium does not support draw call parameter buffers and indirect draws DsSetConstantBuffers (D3D11 only) @@ -338,10 +325,9 @@ HsSetShaderResources (D3D11 only) HsSetShaderWithIfaces (D3D11 only) - Gallium does not support hull shaders -IaSetIndexBuffer - ! Gallium passes this to the draw_elements or draw_elements_instanced calls +IaSetIndexBuffer -> set_index_buffer + Gallium supports 8-bit indices - ! the D3D11 interface allows index-size-unaligned byte offsets into index buffers; it's not clear whether they actually work + # the D3D11 interface allows index-size-unaligned byte offsets into the index buffer; most drivers will abort with an assertion IaSetInputLayout -> bind_vertex_elements_state @@ -400,7 +386,7 @@ ResourceCopy ResourceCopyRegion ResourceConvert (D3D10.1+ only) ResourceConvertRegion (D3D10.1+ only) - -> surface_copy + -> resource_copy_region - Gallium does not support hardware buffer copies - Gallium does not support copying 3D texture subregions in a single call @@ -410,8 +396,7 @@ ResourceIsStagingBusy -> is_texture_referenced, is_buffer_referenced ResourceReadAfterWriteHazard ! Gallium specifies hides this, except for the render and texture caches -ResourceResolveSubresource - - Gallium does not support multisample sample resolution +ResourceResolveSubresource -> resource_resolve ResourceMap ResourceUnmap @@ -433,9 +418,8 @@ StagingResourceUnmap ResourceUpdateSubresourceUP -> transfer functionality, transfer_inline_write in gallium-resources DefaultConstantBufferUpdateSubresourceUP -> transfer functionality, transfer_inline_write in gallium-resources -SetBlendState -> bind_blend_state and set_blend_color - ! D3D11 fuses bind_blend_state and set_blend_color in a single function - - Gallium lacks the sample mask +SetBlendState -> bind_blend_state, set_blend_color and set_sample_mask + ! D3D11 fuses bind_blend_state, set_blend_color and set_sample_mask in a single function SetDepthStencilState -> bind_depth_stencil_alpha_state and set_stencil_ref ! D3D11 fuses bind_depth_stencil_alpha_state and set_stencil_ref in a single function @@ -474,8 +458,7 @@ SetViewports ShaderResourceViewReadAfterWriteHazard -> flush(PIPE_FLUSH_RENDER_CACHE) - Gallium does not support specifying this per-render-target/view -SoSetTargets - - Gallium does not support stream out +SoSetTargets -> set_stream_output_buffers VsSetConstantBuffers -> for(i = StartBuffer; i < NumBuffers; ++i) set_constant_buffer(PIPE_SHADER_VERTEX, i, phBuffers[i]) * may want to split into fragment/vertex-specific versions diff --git a/src/gallium/docs/source/conf.py b/src/gallium/docs/source/conf.py index ccc84405c41..0846e7d0ece 100644 --- a/src/gallium/docs/source/conf.py +++ b/src/gallium/docs/source/conf.py @@ -22,7 +22,7 @@ sys.path.append(os.path.abspath('exts')) # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.pngmath', 'tgsi'] +extensions = ['sphinx.ext.pngmath', 'formatting'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -38,7 +38,7 @@ master_doc = 'index' # General information about the project. project = u'Gallium' -copyright = u'2009, VMWare, X.org, Nouveau' +copyright = u'2009, VMware, X.org, Nouveau' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -176,7 +176,7 @@ htmlhelp_basename = 'Galliumdoc' # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('index', 'Gallium.tex', u'Gallium Documentation', - u'VMWare, X.org, Nouveau', 'manual'), + u'VMware, X.org, Nouveau', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst index c82e681a254..5342fc25dc1 100644 --- a/src/gallium/docs/source/context.rst +++ b/src/gallium/docs/source/context.rst @@ -1,3 +1,5 @@ +.. _context: + Context ======= @@ -43,6 +45,7 @@ buffers, surfaces) are bound to the driver. * ``set_vertex_buffers`` +* ``set_index_buffer`` Non-CSO State ^^^^^^^^^^^^^ @@ -54,12 +57,15 @@ objects. They all follow simple, one-method binding calls, e.g. * ``set_stencil_ref`` sets the stencil front and back reference values which are used as comparison values in stencil test. * ``set_blend_color`` +* ``set_sample_mask`` * ``set_clip_state`` * ``set_polygon_stipple`` * ``set_scissor_state`` sets the bounds for the scissor test, which culls pixels before blending to render targets. If the :ref:`Rasterizer` does not have the scissor test enabled, then the scissor bounds never need to - be set since they will not be used. + be set since they will not be used. Note that scissor xmin and ymin are + inclusive, but xmax and ymax are exclusive. The inclusive ranges in x + and y would be [xmin..xmax-1] and [ymin..ymax-1]. * ``set_viewport_state`` @@ -101,63 +107,54 @@ the LOD range the texture is going to be constrained to. Clearing ^^^^^^^^ +Clear is one of the most difficult concepts to nail down to a single +interface (due to both different requirements from APIs and also driver/hw +specific differences). + ``clear`` initializes some or all of the surfaces currently bound to the framebuffer to particular RGBA, depth, or stencil values. +Currently, this does not take into account color or stencil write masks (as +used by GL), and always clears the whole surfaces (no scissoring as used by +GL clear or explicit rectangles like d3d9 uses). It can, however, also clear +only depth or stencil in a combined depth/stencil surface, if the driver +supports PIPE_CAP_DEPTHSTENCIL_CLEAR_SEPARATE. +If a surface includes several layers/slices (XXX: not yet...) then all layers +will be cleared. -Clear is one of the most difficult concepts to nail down to a single -interface and it seems likely that we will want to add additional -clear paths, for instance clearing surfaces not bound to the -framebuffer, or read-modify-write clears such as depth-only or -stencil-only clears of packed depth-stencil buffers. +``clear_render_target`` clears a single color rendertarget with the specified +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 +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), +this surface need not be bound to the framebuffer. Drawing ^^^^^^^ -``draw_arrays`` draws a specified primitive. - -This command is equivalent to calling ``draw_arrays_instanced`` -with ``startInstance`` set to 0 and ``instanceCount`` set to 1. - -``draw_elements`` draws a specified primitive using an optional -index buffer. +``draw_vbo`` draws a specified primitive. The primitive mode and other +properties are described by ``pipe_draw_info``. -This command is equivalent to calling ``draw_elements_instanced`` -with ``startInstance`` set to 0 and ``instanceCount`` set to 1. +The ``mode``, ``start``, and ``count`` fields of ``pipe_draw_info`` specify the +the mode of the primitive and the vertices to be fetched, in the range between +``start`` to ``start``+``count``-1, inclusive. -``draw_range_elements`` +Every instance with instanceID in the range between ``start_instance`` and +``start_instance``+``instance_count``-1, inclusive, will be drawn. -XXX: this is (probably) a temporary entrypoint, as the range -information should be available from the vertex_buffer state. -Using this to quickly evaluate a specialized path in the draw -module. +All vertex indices must fall inside the range given by ``min_index`` and +``max_index``. In case non-indexed draw, ``min_index`` should be set to +``start`` and ``max_index`` should be set to ``start``+``count``-1. -``draw_arrays_instanced`` draws multiple instances of the same primitive. +``index_bias`` is a value added to every vertex index before fetching vertex +attributes. It does not affect ``min_index`` and ``max_index``. -This command is equivalent to calling ``draw_elements_instanced`` -with ``indexBuffer`` set to NULL and ``indexSize`` set to 0. - -``draw_elements_instanced`` draws multiple instances of the same primitive -using an optional index buffer. - -For instanceID in the range between ``startInstance`` -and ``startInstance``+``instanceCount``-1, inclusive, draw a primitive -specified by ``mode`` and sequential numbers in the range between ``start`` -and ``start``+``count``-1, inclusive. - -If ``indexBuffer`` is not NULL, it specifies an index buffer with index -byte size of ``indexSize``. The sequential numbers are used to lookup -the index buffer and the resulting indices in turn are used to fetch -vertex attributes. - -If ``indexBuffer`` is NULL, the sequential numbers are used directly -as indices to fetch vertex attributes. - -``indexBias`` is a value which is added to every index read from the index -buffer before fetching vertex attributes. - -``minIndex`` and ``maxIndex`` describe minimum and maximum index contained in -the index buffer. +If there is an index buffer bound, and ``indexed`` field is true, all vertex +indices will be looked up in the index buffer. ``min_index``, ``max_index``, +and ``index_bias`` apply after index lookup. If a given vertex element has ``instance_divisor`` set to 0, it is said it contains per-vertex data and effective vertex attribute address needs @@ -200,9 +197,16 @@ returned). Otherwise, if the ``wait`` parameter is FALSE, the call will not block and the return value will be TRUE if the query has completed or FALSE otherwise. -A common type of query is the occlusion query which counts the number of -fragments/pixels which are written to the framebuffer (and not culled by -Z/stencil/alpha testing or shader KILL instructions). +The most common type of query is the occlusion query, +``PIPE_QUERY_OCCLUSION_COUNTER``, which counts the number of fragments which +are written to the framebuffer without being culled by +:ref:`Depth, Stencil, & Alpha` testing or shader KILL instructions. + +Another type of query, ``PIPE_QUERY_TIME_ELAPSED``, returns the amount of +time, in nanoseconds, the context takes to perform operations. + +Gallium does not guarantee the availability of any query types; one must +always check the capabilities of the :ref:`Screen` first. Conditional Rendering @@ -252,24 +256,45 @@ Resource Busy Queries Blitting ^^^^^^^^ -These methods emulate classic blitter controls. They are not guaranteed to be -available; if they are set to NULL, then they are not present. +These methods emulate classic blitter controls. -These methods operate directly on ``pipe_surface`` objects, and stand +These methods operate directly on ``pipe_resource`` objects, and stand apart from any 3D state in the context. Blitting functionality may be moved to a separate abstraction at some point in the future. -``surface_fill`` performs a fill operation on a section of a surface. +``resource_copy_region`` blits a region of a subresource of a resource to a +region of another subresource of a resource, provided that both resources have +the same format, or compatible formats, i.e., formats for which copying the +bytes from the source resource unmodified to the destination resource will +achieve the same effect of a textured quad blitter. The source and destination +may be the same resource, but overlapping blits are not permitted. -``surface_copy`` blits a region of a surface to a region of another surface, -provided that both surfaces are the same format. The source and destination -may be the same surface, and overlapping blits are permitted. +``resource_resolve`` resolves a multisampled resource into a non-multisampled +one. Formats and dimensions must match. This function must be present if a driver +supports multisampling. The interfaces to these calls are likely to change to make it easier for a driver to batch multiple blits with the same source and destination. +Stream Output +^^^^^^^^^^^^^ + +Stream output, also known as transform feedback allows writing the results of the +vertex pipeline (after the geometry shader or vertex shader if no geometry shader +is present) to be written to a buffer created with a ``PIPE_BIND_STREAM_OUTPUT`` +flag. + +First a stream output state needs to be created with the +``create_stream_output_state`` call. It specific the details of what's being written, +to which buffer and with what kind of a writemask. + +Then target buffers needs to be set with the call to ``set_stream_output_buffers`` +which sets the buffers and the offsets from the start of those buffer to where +the data will be written to. + + Transfers ^^^^^^^^^ @@ -284,11 +309,6 @@ data to be written to the resource at this point. The returned map points to the start of the mapped range according to the box region, not the beginning of the resource. -.. _transfer_flush_region: -``transfer_flush_region`` If a transfer was created with TRANFER_FLUSH_EXPLICIT, -only the region specified is guaranteed to be written to. This is relative to -the mapped range, not the beginning of the resource. - ``transfer_unmap`` remove the memory mapping for the transfer object. Any pointers into the map should be considered invalid and discarded. @@ -296,6 +316,16 @@ Any pointers into the map should be considered invalid and discarded. Basically get_transfer, transfer_map, data write, transfer_unmap, and transfer_destroy all in one. +.. _transfer_flush_region: + +transfer_flush_region +%%%%%%%%%%%%%%%%%%%%% + +If a transfer was created with ``FLUSH_EXPLICIT``, it will not automatically +be flushed on write or unmap. Flushes must be requested with +``transfer_flush_region``. Flush ranges are relative to the mapped range, not +the beginning of the resource. + .. _pipe_transfer: PIPE_TRANSFER @@ -315,5 +345,4 @@ These flags control the behavior of a transfer object. operations pending on the resource are undefined. Cannot be used with ``READ``. * ``FLUSH_EXPLICIT``: Written ranges will be notified later with - :ref:`transfer_flush_region`. Cannot be used with - ``READ``. + :ref:`transfer_flush_region`. Cannot be used with ``READ``. diff --git a/src/gallium/docs/source/cso/blend.rst b/src/gallium/docs/source/cso/blend.rst index c74396284cc..7bde10c1245 100644 --- a/src/gallium/docs/source/cso/blend.rst +++ b/src/gallium/docs/source/cso/blend.rst @@ -14,21 +14,74 @@ in other modern and legacy drawing APIs. XXX blurb about dual-source blends +Logical Operations +------------------ + +Logical operations, also known as logicops, lops, or rops, are supported. +Only two-operand logicops are available. When logicops are enabled, all other +blend state is ignored, including per-render-target state, so logicops are +performed on all render targets. + +.. warning:: + The blend_enable flag is ignored for all render targets when logical + operations are enabled. + +For a source component `s` and destination component `d`, the logical +operations are defined as taking the bits of each channel of each component, +and performing one of the following operations per-channel: + +* ``CLEAR``: 0 +* ``NOR``: :math:`\lnot(s \lor d)` +* ``AND_INVERTED``: :math:`\lnot s \land d` +* ``COPY_INVERTED``: :math:`\lnot s` +* ``AND_REVERSE``: :math:`s \land \lnot d` +* ``INVERT``: :math:`\lnot d` +* ``XOR``: :math:`s \oplus d` +* ``NAND``: :math:`\lnot(s \land d)` +* ``AND``: :math:`s \land d` +* ``EQUIV``: :math:`\lnot(s \oplus d)` +* ``NOOP``: :math:`d` +* ``OR_INVERTED``: :math:`\lnot s \lor d` +* ``COPY``: :math:`s` +* ``OR_REVERSE``: :math:`s \lor \lnot d` +* ``OR``: :math:`s \lor d` +* ``SET``: 1 + +.. note:: + The logical operation names and definitions match those of the OpenGL API, + and are similar to the ROP2 and ROP3 definitions of GDI. This is + intentional, to ease transitions to Gallium. + Members ------- +These members affect all render targets. + +dither +%%%%%% + +Whether dithering is enabled. + +.. note:: + Dithering is completely implementation-dependent. It may be ignored by + drivers for any reason, and some render targets may always or never be + dithered depending on their format or usage flags. + +logicop_enable +%%%%%%%%%%%%%% + +Whether the blender should perform a logicop instead of blending. + +logicop_func +%%%%%%%%%%%% + +The logicop to use. One of ``PIPE_LOGICOP``. + independent_blend_enable If enabled, blend state is different for each render target, and for each render target set in the respective member of the rt array. If disabled, blend state is the same for all render targets, and only the first member of the rt array contains valid data. -logicop_enable - Enables logic ops. Cannot be enabled at the same time as blending, and - is always the same for all render targets. -logicop_func - The logic operation to use if logic ops are enabled. One of PIPE_LOGICOP. -dither - Whether dithering is enabled. Note: Dithering is implementation-dependent. rt Contains the per-rendertarget blend state. diff --git a/src/gallium/docs/source/cso/rasterizer.rst b/src/gallium/docs/source/cso/rasterizer.rst index 56a601a8d06..d547055096f 100644 --- a/src/gallium/docs/source/cso/rasterizer.rst +++ b/src/gallium/docs/source/cso/rasterizer.rst @@ -46,87 +46,61 @@ There are several important exceptions to the specification of this rule. second vertex, not the first. This permits each segment of the fan to have a different color. -Points ------- - -sprite_coord_enable -^^^^^^^^^^^^^^^^^^^ - -Specifies if a texture unit has its texture coordinates replaced or not. This -is a packed bitfield containing the enable for all texcoords -- if all bits -are zero, point sprites are effectively disabled. If any bit is set, then -point_smooth and point_quad_rasterization are ignored; point smoothing is -disabled and points are always rasterized as quads. If enabled, the four -vertices of the resulting quad will be assigned texture coordinates, -according to sprite_coord_mode. - -sprite_coord_mode -^^^^^^^^^^^^^^^^^ - -Specifies how the value for each shader output should be computed when drawing -point sprites. For PIPE_SPRITE_COORD_LOWER_LEFT, the lower-left vertex will -have coordinates (0,0,0,1). For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left -vertex will have coordinates (0,0,0,1). -This state is used by :ref:`Draw` to generate texcoords. - -.. note:: - - When geometry shaders are available, a special geometry shader could be - used instead of this functionality, to convert incoming points into quads - with the proper texture coordinates. - -point_quad_rasterization -^^^^^^^^^^^^^^^^^^^^^^^^ - -Determines if points should be rasterized as quads or points. Certain APIs, -like Direct3D, always use quad rasterization for points, regardless of -whether point sprites are enabled or not. If this state is enabled, point -smoothing and antialiasing are disabled. If it is disabled, point sprite -coordinates are not generated. - -.. note:: +Polygons +-------- - Some renderers always internally translate points into quads; this state - still affects those renderers by overriding other rasterization state. - -Other Members +light_twoside ^^^^^^^^^^^^^ -light_twoside - If set, there are per-vertex back-facing colors. :ref:`Draw` - uses this state along with the front/back information to set the - final vertex colors prior to rasterization. +If set, there are per-vertex back-facing colors. The hardware +(perhaps assisted by :ref:`Draw`) should be set up to use this state +along with the front/back information to set the final vertex colors +prior to rasterization. + +The frontface vertex shader color output is marked with TGSI semantic +COLOR[0], and backface COLOR[1]. -front_winding - Indicates the window order of front-facing polygons, either - PIPE_WINDING_CW or PIPE_WINDING_CCW +front_ccw + Indicates whether the window order of front-facing polygons is + counter-clockwise (TRUE) or clockwise (FALSE). cull_mode - Indicates which polygons to cull, either PIPE_WINDING_NONE (cull no - polygons), PIPE_WINDING_CW (cull clockwise-winding polygons), - PIPE_WINDING_CCW (cull counter clockwise-winding polygons), or - PIPE_WINDING_BOTH (cull all polygons). - -fill_cw - Indicates how to fill clockwise polygons, either PIPE_POLYGON_MODE_FILL, - PIPE_POLYGON_MODE_LINE or PIPE_POLYGON_MODE_POINT. -fill_ccw - Indicates how to fill counter clockwise polygons, either - PIPE_POLYGON_MODE_FILL, PIPE_POLYGON_MODE_LINE or PIPE_POLYGON_MODE_POINT. + Indicates which faces of polygons to cull, either PIPE_FACE_NONE + (cull no polygons), PIPE_FACE_FRONT (cull front-facing polygons), + PIPE_FACE_BACK (cull back-facing polygons), or + PIPE_FACE_FRONT_AND_BACK (cull all polygons). + +fill_front + Indicates how to fill front-facing polygons, either + PIPE_POLYGON_MODE_FILL, PIPE_POLYGON_MODE_LINE or + PIPE_POLYGON_MODE_POINT. +fill_back + Indicates how to fill back-facing polygons, either + PIPE_POLYGON_MODE_FILL, PIPE_POLYGON_MODE_LINE or + PIPE_POLYGON_MODE_POINT. poly_stipple_enable Whether polygon stippling is enabled. poly_smooth Controls OpenGL-style polygon smoothing/antialiasing -offset_cw - If set, clockwise polygons will have polygon offset factors applied -offset_ccw - If set, counter clockwise polygons will have polygon offset factors applied + +offset_point + If set, point-filled polygons will have polygon offset factors applied +offset_line + If set, line-filled polygons will have polygon offset factors applied +offset_tri + If set, filled polygons will have polygon offset factors applied + offset_units Specifies the polygon offset bias offset_scale Specifies the polygon offset scale + + +Lines +----- + line_width The width of lines. line_smooth @@ -143,14 +117,80 @@ line_last_pixel omits the last pixel to avoid double-drawing pixels at the ends of lines when drawing connected lines. + +Points +------ + +sprite_coord_enable +^^^^^^^^^^^^^^^^^^^ + +Controls automatic texture coordinate generation for rendering sprite points. + +When bit k in the sprite_coord_enable bitfield is set, then generic +input k to the fragment shader will get an automatically computed +texture coordinate. + +The texture coordinate will be of the form (s, t, 0, 1) where s varies +from 0 to 1 from left to right while t varies from 0 to 1 according to +the state of 'sprite_coord_mode' (see below). + +If any bit is set, then point_smooth MUST be disabled (there are no +round sprites) and point_quad_rasterization MUST be true (sprites are +always rasterized as quads). Any mismatch between these states should +be considered a bug in the state-tracker. + +This feature is implemented in the :ref:`Draw` module but may also be +implemented natively by GPUs or implemented with a geometry shader. + + +sprite_coord_mode +^^^^^^^^^^^^^^^^^ + +Specifies how the value for each shader output should be computed when drawing +point sprites. For PIPE_SPRITE_COORD_LOWER_LEFT, the lower-left vertex will +have coordinates (0,0,0,1). For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left +vertex will have coordinates (0,0,0,1). +This state is used by :ref:`Draw` to generate texcoords. + + +point_quad_rasterization +^^^^^^^^^^^^^^^^^^^^^^^^ + +Determines if points should be rasterized according to quad or point +rasterization rules. + +OpenGL actually has quite different rasterization rules for points and +point sprites - hence this indicates if points should be rasterized as +points or according to point sprite (which decomposes them into quads, +basically) rules. + +Additionally Direct3D will always use quad rasterization rules for +points, regardless of whether point sprites are enabled or not. + +If this state is enabled, point smoothing and antialiasing are +disabled. If it is disabled, point sprite coordinates are not +generated. + +.. note:: + + Some renderers always internally translate points into quads; this state + still affects those renderers by overriding other rasterization state. + point_smooth Whether points should be smoothed. Point smoothing turns rectangular points into circles or ovals. point_size_per_vertex - Whether vertices have a point size element. + Whether the vertex shader is expected to have a point size output. + Undefined behaviour is permitted if there is disagreement between + this flag and the actual bound shader. point_size The size of points, if not specified per-vertex. + + +Other Members +------------- + scissor Whether the scissor test is enabled. diff --git a/src/gallium/docs/source/cso/velems.rst b/src/gallium/docs/source/cso/velems.rst index 92cde014fb8..978ad4a2434 100644 --- a/src/gallium/docs/source/cso/velems.rst +++ b/src/gallium/docs/source/cso/velems.rst @@ -3,9 +3,44 @@ Vertex Elements =============== -This state controls format etc. of the input attributes contained -in the pipe_vertex_buffer(s). There's one pipe_vertex_element array member -for each input attribute. +This state controls the format of the input attributes contained in +pipe_vertex_buffers. There is one pipe_vertex_element array member for each +input attribute. + +Input Formats +------------- + +Gallium supports a diverse range of formats for vertex data. Drivers are +guaranteed to support 32-bit floating-point vectors of one to four components. +Additionally, they may support the following formats: + +* Integers, signed or unsigned, normalized or non-normalized, 8, 16, or 32 + bits wide +* Floating-point, 16, 32, or 64 bits wide + +At this time, support for varied vertex data formats is limited by driver +deficiencies. It is planned to support a single uniform set of formats for all +Gallium drivers at some point. + +Rather than attempt to specify every small nuance of behavior, Gallium uses a +very simple set of rules for padding out unspecified components. If an input +uses less than four components, it will be padded out with the constant vector +``(0, 0, 0, 1)``. + +Fog, point size, the facing bit, and edgeflags, all are in the standard format +of ``(x, 0, 0, 1)``, and so only the first component of those inputs is used. + +Position +%%%%%%%% + +Vertex position may be specified with two to four components. Using less than +two components is not allowed. + +Colors +%%%%%% + +Colors, both front- and back-facing, may omit the alpha component, only using +three components. Using less than three components is not allowed. Members ------- diff --git a/src/gallium/docs/source/debugging.rst b/src/gallium/docs/source/debugging.rst new file mode 100644 index 00000000000..e081cbf74e1 --- /dev/null +++ b/src/gallium/docs/source/debugging.rst @@ -0,0 +1,105 @@ +Debugging +========= + +Debugging utilities in gallium. + +Debug Variables +^^^^^^^^^^^^^^^ + +All drivers respond to a set of common debug environment variables, as well as +some driver-specific variables. Set them as normal environment variables for +the platform or operating system you are running. For example, for Linux this +can be done by typing "export var=value" into a console and then running the +program from that console. + +Common +"""""" + +.. envvar:: GALLIUM_PRINT_OPTIONS <bool> (false) + +This option controls if the debug variables should be printed to stderr. This +is probably the most useful variable, since it allows you to find which +variables a driver uses. + +.. envvar:: GALLIUM_GALAHAD <bool> (false) + +Controls if the :ref:`galahad` sanity checker module should be used. + +.. envvar:: GALLIUM_RBUG <bool> (false) + +Controls if the :ref:`rbug` should be used. + +.. envvar:: GALLIUM_TRACE <string> ("") + +If set, this variable will cause the :ref:`Trace` output to be written to the +specified file. Paths may be relative or absolute; relative paths are relative +to the working directory. For example, setting it to "trace.xml" will cause +the trace to be written to a file of the same name in the working directory. + +.. envvar:: GALLIUM_DUMP_CPU <bool> (false) + +Dump information about the current CPU that the driver is running on. + +.. envvar:: TGSI_PRINT_SANITY <bool> (false) + +Gallium has a built-in shader sanity checker. This option controls whether +the shader sanity checker prints its warnings and errors to stderr. + +.. envvar:: DRAW_USE_LLVM <bool> (false) + +Whether the :ref:`Draw` module will attempt to use LLVM for vertex and geometry shaders. + + +State tracker-specific +"""""""""""""""""""""" + +.. envvar:: ST_DEBUG <flags> (0x0) + +Debug :ref:`flags` for the GL state tracker. + + +Driver-specific +""""""""""""""" + +.. envvar:: I915_DEBUG <flags> (0x0) + +Debug :ref:`flags` for the i915 driver. + +.. envvar:: I915_NO_HW <bool> (false) + +Stop the i915 driver from submitting commands to the hardware. + +.. envvar:: I915_DUMP_CMD <bool> (false) + +Dump all commands going to the hardware. + +.. envvar:: LP_DEBUG <flags> (0x0) + +Debug :ref:`flags` for the llvmpipe driver. + +.. envvar:: LP_NUM_THREADS <int> (number of CPUs) + +Number of threads that the llvmpipe driver should use. + + +.. _flags: + +Flags +""""" + +The variables of type "flags" all take a string with comma-separated flags to +enable different debugging for different parts of the drivers or state +tracker. If set to "help", the driver will print a list of flags which the +variable accepts. Order does not matter. + + +.. _rbug: + +Remote Debugger +^^^^^^^^^^^^^^^ + +The remote debugger, commonly known as rbug, allows for runtime inspections of +:ref:`Context`, :ref:`Screen`, :ref:`Resource` and :ref:`Shader` objects; and +pausing and stepping of :ref:`Draw` calls. Is used with rbug-gui which is +hosted outside of the main mesa repository. rbug is can be used over a network +connection, so the debugger does not need to be on the same machine. diff --git a/src/gallium/docs/source/distro.rst b/src/gallium/docs/source/distro.rst index 100afe33972..08c8eab890a 100644 --- a/src/gallium/docs/source/distro.rst +++ b/src/gallium/docs/source/distro.rst @@ -10,69 +10,114 @@ 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 ^^^^^^^^^^^ -VMWare SVGA +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. + +Rbug +^^^^ + +Wrapper driver. :ref:`rbug` driver used with stand alone rbug-gui. + +.. _galahad: + +Galahad +^^^^^^^ + +Wrapper driver. Sanity checker for the internal gallium state. Normally +a driver should n't have to sanity check the input it gets from a state +tracker. Any wrong state received should be perceived as a state tracker bug. 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 +127,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/exts/formatting.py b/src/gallium/docs/source/exts/formatting.py new file mode 100644 index 00000000000..14865f36033 --- /dev/null +++ b/src/gallium/docs/source/exts/formatting.py @@ -0,0 +1,31 @@ +# formatting.py +# Sphinx extension providing formatting for Gallium-specific data +# (c) Corbin Simpson 2010 +# Public domain to the extent permitted; contact author for special licensing + +import docutils.nodes +import sphinx.addnodes + +def parse_envvar(env, sig, signode): + envvar, t, default = sig.split(" ", 2) + envvar = envvar.strip().upper() + t = " Type: %s" % t.strip(" <>").lower() + default = " Default: %s" % default.strip(" ()") + signode += sphinx.addnodes.desc_name(envvar, envvar) + signode += sphinx.addnodes.desc_type(t, t) + signode += sphinx.addnodes.desc_annotation(default, default) + return envvar + +def parse_opcode(env, sig, signode): + opcode, desc = sig.split("-", 1) + opcode = opcode.strip().upper() + desc = " (%s)" % desc.strip() + signode += sphinx.addnodes.desc_name(opcode, opcode) + signode += sphinx.addnodes.desc_annotation(desc, desc) + return opcode + +def setup(app): + app.add_description_unit("envvar", "envvar", "%s (environment variable)", + parse_envvar) + app.add_description_unit("opcode", "opcode", "%s (TGSI opcode)", + parse_opcode) diff --git a/src/gallium/docs/source/exts/tgsi.py b/src/gallium/docs/source/exts/tgsi.py deleted file mode 100644 index e92cd5c4d1b..00000000000 --- a/src/gallium/docs/source/exts/tgsi.py +++ /dev/null @@ -1,17 +0,0 @@ -# tgsi.py -# Sphinx extension providing formatting for TGSI opcodes -# (c) Corbin Simpson 2010 - -import docutils.nodes -import sphinx.addnodes - -def parse_opcode(env, sig, signode): - opcode, desc = sig.split("-", 1) - opcode = opcode.strip().upper() - desc = " (%s)" % desc.strip() - signode += sphinx.addnodes.desc_name(opcode, opcode) - signode += sphinx.addnodes.desc_annotation(desc, desc) - return opcode - -def setup(app): - app.add_description_unit("opcode", "opcode", "%s (TGSI opcode)", parse_opcode) diff --git a/src/gallium/docs/source/glossary.rst b/src/gallium/docs/source/glossary.rst index 0696cb5d277..acde56eafc4 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/index.rst b/src/gallium/docs/source/index.rst index 54bc883fced..2a73e3ab59d 100644 --- a/src/gallium/docs/source/index.rst +++ b/src/gallium/docs/source/index.rst @@ -12,8 +12,10 @@ Contents: :maxdepth: 2 intro + debugging tgsi screen + resources context cso distro diff --git a/src/gallium/docs/source/pipeline.txt b/src/gallium/docs/source/pipeline.txt new file mode 100644 index 00000000000..fd1fbe9c76f --- /dev/null +++ b/src/gallium/docs/source/pipeline.txt @@ -0,0 +1,128 @@ +XXX this could be converted/formatted for Sphinx someday. +XXX do not use tabs in this file. + + + + position ] + primary/secondary colors ] + generics (normals, ] + texcoords, fog) ] User vertices / arrays + point size ] + edge flag ] + primitive ID } System-generated values + vertex ID } + | | | + V V V + +-------------------+ + | Vertex shader | + +-------------------+ + | | | + V V V + position + clip distance + generics + front/back & primary/secondary colors + point size + edge flag + primitive ID + | | | + V V V + +------------------------+ + | Geometry shader | + | (consume vertex ID) | + | (may change prim type) | + +------------------------+ + | | | + V V V + [...] + fb layer + | | | + V V V + +--------------------------+ + | Clipper | + | (consume clip distances) | + +--------------------------+ + | | | + V V V + +-------------------+ + | Polygon Culling | + +-------------------+ + | | | + V V V + +-----------------------+ + | Choose front or | + | back face color | + | (consume other color) | + +-----------------------+ + | | | + V V V + [...] + primary/secondary colors only + | | | + V V V + +-------------------+ + | Polygon Offset | + +-------------------+ + | | | + V V V + +----------------------+ + | Unfilled polygons | + | (consume edge flags) | + | (change prim type) | + +----------------------+ + | | | + V V V + position + generics + primary/secondary colors + point size + primitive ID + fb layer + | | | + V V V + +---------------------------------+ + | Optional Draw module helpers | + | * Polygon Stipple | + | * Line Stipple | + | * Line AA/smooth (as tris) | + | * Wide lines (as tris) | + | * Wide points/sprites (as tris) | + | * Point AA/smooth (as tris) | + | (NOTE: these stages may emit | + | new/extra generic attributes | + | such as texcoords) | + +---------------------------------+ + | | | + V V V + position ] + generics (+ new/extra ones) ] + primary/secondary colors ] Software rast vertices + point size ] + primitive ID ] + fb layer ] + | | | + V V V + +---------------------+ + | Triangle/Line/Point | + | Rasterization | + +---------------------+ + | | | + V V V + generic attribs + primary/secondary colors + primitive ID + fragment win coord pos } System-generated values + front/back face flag } + | | | + V V V + +-------------------+ + | Fragment shader | + +-------------------+ + | | | + V V V + zero or more colors + zero or one Z value + + +NOTE: The instance ID is not shown. It can be imagined to be a global variable +accessible to all shader stages. diff --git a/src/gallium/docs/source/resources.rst b/src/gallium/docs/source/resources.rst new file mode 100644 index 00000000000..c8a5766821b --- /dev/null +++ b/src/gallium/docs/source/resources.rst @@ -0,0 +1,195 @@ +Resources and derived objects +============================= + +Resources represent objects that hold data: textures and buffers. + +They are mostly modelled after the resources in Direct3D 10/11, but with a +different transfer/update mechanism, and more features for OpenGL support. + +Resources can be used in several ways, and it is required to specify all planned uses through an appropriate set of bind flags. + +TODO: write much more on resources + +Transfers +--------- + +Transfers are the mechanism used to access resources with the CPU. + +OpenGL: OpenGL supports mapping buffers and has inline transfer functions for both buffers and textures + +D3D11: D3D11 lacks transfers, but has special resource types that are mappable to the CPU address space + +TODO: write much more on transfers + +Resource targets +---------------- + +Resource targets determine the type of a resource. + +Note that drivers may not actually have the restrictions listed regarding +coordinate normalization and wrap modes, and in fact efficient OpenCL +support will probably require drivers that don't have any of them, which +will probably be advertised with an appropriate cap. + +TODO: document all targets. Note that both 3D and cube have restrictions +that depend on the hardware generation. + +TODO: can buffers have a non-R8 format? + +PIPE_BUFFER +^^^^^^^^^^^ + +Buffer resource: can be used as a vertex, index, constant buffer (appropriate bind flags must be requested). + +They can be bound to stream output if supported. +TODO: what about the restrictions lifted by the several later GL transform feedback extensions? How does one advertise that in Gallium? + +They can be also be bound to a shader stage as usual. +TODO: are all drivers supposed to support this? how does this work exactly? are there size limits? + +They can be also be bound to the framebuffer as usual. +TODO: are all drivers supposed to support this? how does this work exactly? are there size limits? +TODO: is there any chance of supporting GL pixel buffer object acceleration with this? + +- depth0 must be 1 +- last_level must be 0 +- TODO: what about normalization? +- TODO: wrap modes/other sampling state? +- TODO: are arbitrary formats supported? in which cases? + +OpenGL: vertex buffers in GL 1.5 or GL_ARB_vertex_buffer_object + +- Binding to stream out requires GL 3.0 or GL_NV_transform_feedback +- Binding as constant buffers requires GL 3.1 or GL_ARB_uniform_buffer_object +- Binding to a sampling stage requires GL 3.1 or GL_ARB_texture_buffer_object +- TODO: can they be bound to an FBO? + +D3D11: buffer resources +- Binding to a render target requires D3D_FEATURE_LEVEL_10_0 + +PIPE_TEXTURE_1D +^^^^^^^^^^^^^^^ +1D surface accessed with normalized coordinates. + +UNIMPLEMENTED: 1D texture arrays not supported + +- If PIPE_CAP_NPOT_TEXTURES is not supported, + width must be a power of two +- height0 must be 1 +- depth0 must be 1 +- Mipmaps can be used +- Must use normalized coordinates + +OpenGL: GL_TEXTURE_1D in GL 1.0 + +- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or GL_ARB_texture_non_power_of_two + +D3D11: 1D textures in D3D_FEATURE_LEVEL_10_0 + +PIPE_TEXTURE_RECT +^^^^^^^^^^^^^^^^^ +2D surface with OpenGL GL_TEXTURE_RECTANGLE semantics. + +- depth0 must be 1 +- last_level must be 0 +- Must use unnormalized coordinates +- Must use a clamp wrap mode + +OpenGL: GL_TEXTURE_RECTANGLE in GL 3.1 or GL_ARB_texture_rectangle or GL_NV_texture_rectangle + +OpenCL: can create OpenCL images based on this, that can then be sampled arbitrarily + +D3D11: not supported (only PIPE_TEXTURE_2D with normalized coordinates is supported) + +PIPE_TEXTURE_2D +^^^^^^^^^^^^^^^ +2D surface accessed with normalized coordinates. + +UNIMPLEMENTED: 2D texture arrays not supported + +- If PIPE_CAP_NPOT_TEXTURES is not supported, + width and height must be powers of two +- depth0 must be 1 +- Mipmaps can be used +- Must use normalized coordinates +- No special restrictions on wrap modes + +OpenGL: GL_TEXTURE_2D in GL 1.0 + +- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or GL_ARB_texture_non_power_of_two + +OpenCL: can create OpenCL images based on this, that can then be sampled arbitrarily + +D3D11: 2D textures + +- PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_9_3 + +PIPE_TEXTURE_3D +^^^^^^^^^^^^^^^ + +3-dimensional array of texels. +Mipmap dimensions are reduced in all 3 coordinates. + +- If PIPE_CAP_NPOT_TEXTURES is not supported, + width, height and depth must be powers of two +- Must use normalized coordinates + +OpenGL: GL_TEXTURE_3D in GL 1.2 or GL_EXT_texture3D + +- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or GL_ARB_texture_non_power_of_two + +D3D11: 3D textures + +- PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_10_0 + +PIPE_TEXTURE_CUBE +^^^^^^^^^^^^^^^^^ + +Cube maps consist of 6 2D faces. +The 6 surfaces form an imaginary cube, and sampling happens by mapping an +input 3-vector to the point of the cube surface in that direction. + +Sampling may be optionally seamless, resulting in filtering taking samples +from multiple surfaces near to the edge. +UNIMPLEMENTED: seamless cube map sampling not supported + +UNIMPLEMENTED: cube map arrays not supported + +- Width and height must be equal +- If PIPE_CAP_NPOT_TEXTURES is not supported, + width and height must be powers of two +- Must use normalized coordinates + +OpenGL: GL_TEXTURE_CUBE_MAP in GL 1.3 or EXT_texture_cube_map + +- PIPE_CAP_NPOT_TEXTURES is equivalent to GL 2.0 or GL_ARB_texture_non_power_of_two +- Seamless cube maps require GL 3.2 or GL_ARB_seamless_cube_map or GL_AMD_seamless_cubemap_per_texture +- Cube map arrays require GL 4.0 or GL_ARB_texture_cube_map_array + +D3D11: 2D array textures with the D3D11_RESOURCE_MISC_TEXTURECUBE flag + +- PIPE_CAP_NPOT_TEXTURES is equivalent to D3D_FEATURE_LEVEL_10_0 +- Cube map arrays require D3D_FEATURE_LEVEL_10_1 +- TODO: are (non)seamless cube maps supported in D3D11? how? + +Surfaces +-------- + +Surfaces are views of a resource that can be bound as a framebuffer to serve as the render target or depth buffer. + +TODO: write much more on surfaces + +OpenGL: FBOs are collections of surfaces in GL 3.0 or GL_ARB_framebuffer_object + +D3D11: render target views and depth/stencil views + +Sampler views +------------- + +Sampler views are views of a resource that can be bound to a pipeline stage to be sampled from shaders. + +TODO: write much more on sampler views + +OpenGL: texture objects are actually sampler view and resource in a single unit + +D3D11: shader resource views diff --git a/src/gallium/docs/source/screen.rst b/src/gallium/docs/source/screen.rst index c5815f8939c..e3ef49c862c 100644 --- a/src/gallium/docs/source/screen.rst +++ b/src/gallium/docs/source/screen.rst @@ -1,3 +1,5 @@ +.. _screen: + Screen ====== @@ -33,7 +35,10 @@ The integer capabilities: * ``MAX_RENDER_TARGETS``: The maximum number of render targets that may be bound. * ``OCCLUSION_QUERY``: Whether occlusion queries are available. -* ``TEXTURE_SHADOW_MAP``: XXX +* ``TIMER_QUERY``: Whether timer queries are available. +* ``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 @@ -52,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 @@ -101,6 +112,22 @@ The floating-point capabilities: * ``GUARD_BAND_LEFT``, ``GUARD_BAND_TOP``, ``GUARD_BAND_RIGHT``, ``GUARD_BAND_BOTTOM``: XXX +Fragment shader limits: + +* ``PIPE_CAP_MAX_FS_INSTRUCTIONS``: The maximum number of instructions. +* ``PIPE_CAP_MAX_FS_ALU_INSTRUCTIONS``: The maximum number of arithmetic instructions. +* ``PIPE_CAP_MAX_FS_TEX_INSTRUCTIONS``: The maximum number of texture instructions. +* ``PIPE_CAP_MAX_FS_TEX_INDIRECTIONS``: The maximum number of texture indirections. +* ``PIPE_CAP_MAX_FS_CONTROL_FLOW_DEPTH``: The maximum nested control flow depth. +* ``PIPE_CAP_MAX_FS_INPUTS``: The maximum number of input registers. +* ``PIPE_CAP_MAX_FS_CONSTS``: The maximum number of constants. +* ``PIPE_CAP_MAX_FS_TEMPS``: The maximum number of temporary registers. +* ``PIPE_CAP_MAX_FS_ADDRS``: The maximum number of address registers. +* ``PIPE_CAP_MAX_FS_PREDS``: The maximum number of predicate registers. + +Vertex shader limits: + +* ``PIPE_CAP_MAX_VS_*``: Identical to ``PIPE_CAP_MAX_FS_*``. .. _pipe_bind: @@ -128,9 +155,6 @@ resources might be created and handled quite differently. * ``PIPE_BIND_VERTEX_BUFFER``: A vertex buffer. * ``PIPE_BIND_INDEX_BUFFER``: An vertex index/element buffer. * ``PIPE_BIND_CONSTANT_BUFFER``: A buffer of shader constants. -* ``PIPE_BIND_BLIT_SOURCE``: A blit source, as given to surface_copy. -* ``PIPE_BIND_BLIT_DESTINATION``: A blit destination, as given to surface_copy - and surface_fill. * ``PIPE_BIND_TRANSFER_WRITE``: A transfer object which will be written to. * ``PIPE_BIND_TRANSFER_READ``: A transfer object which will be read from. * ``PIPE_BIND_CUSTOM``: @@ -217,13 +241,15 @@ Determine if a resource in the given format can be used in a specific manner. **target** one of the PIPE_TEXTURE_x flags +**sample_count** the number of samples. 0 and 1 mean no multisampling, +the maximum allowed legal value is 32. + **bindings** is a bitmask of :ref:`PIPE_BIND` flags. **geom_flags** is a bitmask of PIPE_TEXTURE_GEOM_x flags. Returns TRUE if all usages can be satisfied. - .. _resource_create: resource_create diff --git a/src/gallium/docs/source/tgsi.rst b/src/gallium/docs/source/tgsi.rst index e2c8602da02..9e02d43ab74 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 @@ -287,7 +289,7 @@ This instruction replicates its result. dst.w = src0.x \times src1.x + src0.y \times src1.y + src2.x -.. opcode:: FRAC - Fraction +.. opcode:: FRC - Fraction .. math:: @@ -637,10 +639,6 @@ This instruction replicates its result. Considered for removal. -From GL_NV_vertex_program2 -^^^^^^^^^^^^^^^^^^^^^^^^^^ - - .. opcode:: ARA - Address Register Add TBD @@ -680,8 +678,6 @@ From GL_NV_vertex_program2 pc = pop() - Potential restrictions: - * Only occurs at end of function. .. opcode:: SSG - Set Sign @@ -728,7 +724,7 @@ From GL_NV_vertex_program2 dst.z = 0 - dst.y = 1 + dst.w = 1 .. opcode:: TXB - Texture Lookup With Bias @@ -827,11 +823,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 +988,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 +1010,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 +1053,7 @@ This instruction replicates its result. ps_2_x ^^^^^^^^^^^^ +XXX wait what .. opcode:: CALLNZ - Subroutine Call If Not Zero @@ -1062,10 +1071,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 +1088,7 @@ Double Opcodes dst.zw = src0.zw + src1.zw -.. opcode:: DDIV - Divide Double +.. opcode:: DDIV - Divide .. math:: @@ -1082,7 +1096,7 @@ Double Opcodes dst.zw = src0.zw / src1.zw -.. opcode:: DSEQ - Set Double on Equal +.. opcode:: DSEQ - Set on Equal .. math:: @@ -1090,7 +1104,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 +1112,7 @@ Double Opcodes dst.zw = src0.zw < src1.zw ? 1.0F : 0.0F -.. opcode:: DFRAC - Double Fraction +.. opcode:: DFRAC - Fraction .. math:: @@ -1107,23 +1121,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 = exp(src.zw) - dst0.zw = frexp(src.zw, dst1.zw) + dst1.zw = frac(src.zw) -.. opcode:: DLDEXP - Multiple Double Number by Integral Power of 2 +.. 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 +1155,7 @@ Double Opcodes dst.zw = min(src0.zw, src1.zw) -.. opcode:: DMAX - Maximum Double +.. opcode:: DMAX - Maximum .. math:: @@ -1139,7 +1163,7 @@ Double Opcodes dst.zw = max(src0.zw, src1.zw) -.. opcode:: DMUL - Multiply Double +.. opcode:: DMUL - Multiply .. math:: @@ -1148,7 +1172,7 @@ Double Opcodes dst.zw = src0.zw \times src1.zw -.. opcode:: DMAD - Multiply And Add Doubles +.. opcode:: DMAD - Multiply And Add .. math:: @@ -1157,7 +1181,7 @@ Double Opcodes dst.zw = src0.zw \times src1.zw + src2.zw -.. opcode:: DRCP - Reciprocal Double +.. opcode:: DRCP - Reciprocal .. math:: @@ -1165,7 +1189,7 @@ Double Opcodes dst.zw = \frac{1}{src.zw} -.. opcode:: DSQRT - Square root double +.. opcode:: DSQRT - Square Root .. math:: @@ -1260,6 +1284,8 @@ wrapping rules. Declaration Semantic ^^^^^^^^^^^^^^^^^^^^^^^^ + Vertex and fragment shader input and output registers may be labeled + with semantic information consisting of a name and index. Follows Declaration token if Semantic bit is set. @@ -1280,90 +1306,115 @@ 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. +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. -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 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. -XXX additionally, is there a way to configure the perspective divide? it's -accelerated on most chipsets AFAIK... +Fragment shaders may also declare an output register with +TGSI_SEMANTIC_POSITION. Only the Z component is writable. This allows +the fragment shader to change the fragment's Z position. -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 """"""""""""""""" -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. +Vertex shader inputs and outputs and fragment shader inputs may be +labeled with TGSI_SEMANTIC_FOG to indicate that the register contains +a fog coordinate in the form (F, 0, 0, 1). Typically, the fragment +shader will use the fog coordinate to compute a fog blend factor which +is used to blend the normal fragment color with a constant fog color. + +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. -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 """"""""""""""""""" -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. +Vertex shader input and output registers may be labeled with +TGIS_SEMANTIC_PSIZE to indicate that the register contains a point size +in the form (S, 0, 0, 1). The point size controls the width or diameter +of points for rasterization. This label cannot be used in fragment +shaders. When using this semantic, be sure to set the appropriate state in the :ref:`rasterizer` first. + TGSI_SEMANTIC_GENERIC """"""""""""""""""""" -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. +All vertex/fragment shader inputs/outputs not labeled with any other +semantic label can be considered to be generic attributes. Typical +uses of generic inputs/outputs are texcoords and user-defined values. -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. TGSI_SEMANTIC_NORMAL """""""""""""""""""" -Vertex normal; could be used to implement per-pixel lighting for legacy APIs -that allow mixing fixed-function and programmable stages. +Indicates that a vertex shader input is a normal vector. This is +typically only used for legacy graphics APIs. + TGSI_SEMANTIC_FACE """""""""""""""""" -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. +This label applies to fragment shader inputs only and indicates that +the register contains front/back-face information of the form (F, 0, +0, 1). The first component will be positive when the fragment belongs +to a front-facing polygon, and negative when the fragment belongs to a +back-facing polygon. + 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 +1471,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) | +--------------------+--------------+--------------------+--------------+ |