diff options
Diffstat (limited to 'src/gallium/docs')
| -rw-r--r-- | src/gallium/docs/d3d11ddi.txt | 30 | ||||
| -rw-r--r-- | src/gallium/docs/source/conf.py | 6 | ||||
| -rw-r--r-- | src/gallium/docs/source/context.rst | 55 | ||||
| -rw-r--r-- | src/gallium/docs/source/cso/rasterizer.rst | 39 | ||||
| -rw-r--r-- | src/gallium/docs/source/debugging.rst | 101 | ||||
| -rw-r--r-- | src/gallium/docs/source/distro.rst | 9 | ||||
| -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/index.rst | 1 |
9 files changed, 193 insertions, 96 deletions
diff --git a/src/gallium/docs/d3d11ddi.txt b/src/gallium/docs/d3d11ddi.txt index 0954c2926d..f8155c828b 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 @@ -271,31 +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 -> 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) @@ -332,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 diff --git a/src/gallium/docs/source/conf.py b/src/gallium/docs/source/conf.py index ccc84405c4..0846e7d0ec 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 4e35a4c408..f241411a00 100644 --- a/src/gallium/docs/source/context.rst +++ b/src/gallium/docs/source/context.rst @@ -45,6 +45,7 @@ buffers, surfaces) are bound to the driver. * ``set_vertex_buffers`` +* ``set_index_buffer`` Non-CSO State ^^^^^^^^^^^^^ @@ -132,50 +133,26 @@ this surface need not be bound to the framebuffer. Drawing ^^^^^^^ -``draw_arrays`` draws a specified primitive. +``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_arrays_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_elements`` draws a specified primitive using an optional -index buffer. +Every instance with instanceID in the range between ``start_instance`` and +``start_instance``+``instance_count``-1, inclusive, will be drawn. -This command is equivalent to calling ``draw_elements_instanced`` -with ``startInstance`` set to 0 and ``instanceCount`` set to 1. +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_range_elements`` +``index_bias`` is a value added to every vertex index before fetching vertex +attributes. It does not affect ``min_index`` and ``max_index``. -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. - -``draw_arrays_instanced`` draws multiple instances of the same primitive. - -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 diff --git a/src/gallium/docs/source/cso/rasterizer.rst b/src/gallium/docs/source/cso/rasterizer.rst index ad1612f93e..ee3419ccfc 100644 --- a/src/gallium/docs/source/cso/rasterizer.rst +++ b/src/gallium/docs/source/cso/rasterizer.rst @@ -126,11 +126,15 @@ 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. +are zero, point sprites are effectively disabled. + +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. + +If enabled, the four vertices of the resulting quad will be assigned +texture coordinates, according to sprite_coord_mode. sprite_coord_mode ^^^^^^^^^^^^^^^^^ @@ -141,20 +145,23 @@ 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. +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:: diff --git a/src/gallium/docs/source/debugging.rst b/src/gallium/docs/source/debugging.rst new file mode 100644 index 0000000000..42bda5aee9 --- /dev/null +++ b/src/gallium/docs/source/debugging.rst @@ -0,0 +1,101 @@ +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_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 6ba5a056f4..70d75b51e6 100644 --- a/src/gallium/docs/source/distro.rst +++ b/src/gallium/docs/source/distro.rst @@ -51,10 +51,10 @@ nVidia nv50 Driver for the nVidia nv50 family of GPUs. -VMWare SVGA +VMware SVGA ^^^^^^^^^^^ -Driver for VMWare virtualized guest operating system graphics processing. +Driver for VMware virtualized guest operating system graphics processing. ATI r300 ^^^^^^^^ @@ -74,6 +74,11 @@ Trace 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. + State Trackers -------------- diff --git a/src/gallium/docs/source/exts/formatting.py b/src/gallium/docs/source/exts/formatting.py new file mode 100644 index 0000000000..14865f3603 --- /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 e92cd5c4d1..0000000000 --- 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/index.rst b/src/gallium/docs/source/index.rst index 54bc883fce..6c19842dac 100644 --- a/src/gallium/docs/source/index.rst +++ b/src/gallium/docs/source/index.rst @@ -12,6 +12,7 @@ Contents: :maxdepth: 2 intro + debugging tgsi screen context |