summaryrefslogtreecommitdiffstats
path: root/src/gallium
diff options
context:
space:
mode:
authorCorbin Simpson <[email protected]>2010-01-05 08:37:49 -0800
committerCorbin Simpson <[email protected]>2010-01-05 08:37:49 -0800
commit3e18bad36d90255dca6cb519eb7ecfc540c292c1 (patch)
tree1d9d7dc8a24baf21d1758be65f5cf5dadf85e8f1 /src/gallium
parent897cb8950ae14ffe7029b1daf16113ff62ce0dfe (diff)
parent467cccf0a77e225b886711db2b0b929ecf71e411 (diff)
Merge branch 'gallium-docs'
Diffstat (limited to 'src/gallium')
-rw-r--r--src/gallium/docs/Makefile89
-rw-r--r--src/gallium/docs/make.bat113
-rw-r--r--src/gallium/docs/source/conf.py197
-rw-r--r--src/gallium/docs/source/context.rst128
-rw-r--r--src/gallium/docs/source/cso.rst14
-rw-r--r--src/gallium/docs/source/cso/blend.rst14
-rw-r--r--src/gallium/docs/source/cso/dsa.rst58
-rw-r--r--src/gallium/docs/source/cso/rasterizer.rst87
-rw-r--r--src/gallium/docs/source/cso/sampler.rst46
-rw-r--r--src/gallium/docs/source/cso/shader.rst12
-rw-r--r--src/gallium/docs/source/distro.rst141
-rw-r--r--src/gallium/docs/source/glossary.rst10
-rw-r--r--src/gallium/docs/source/index.rst28
-rw-r--r--src/gallium/docs/source/intro.rst9
-rw-r--r--src/gallium/docs/source/screen.rst39
-rw-r--r--src/gallium/docs/source/tgsi.rst1270
16 files changed, 2255 insertions, 0 deletions
diff --git a/src/gallium/docs/Makefile b/src/gallium/docs/Makefile
new file mode 100644
index 00000000000..d4a5be41922
--- /dev/null
+++ b/src/gallium/docs/Makefile
@@ -0,0 +1,89 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ -rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Gallium.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Gallium.qhc"
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+ "run these through (pdf)latex."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
diff --git a/src/gallium/docs/make.bat b/src/gallium/docs/make.bat
new file mode 100644
index 00000000000..6f97e0730a7
--- /dev/null
+++ b/src/gallium/docs/make.bat
@@ -0,0 +1,113 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+set SPHINXBUILD=sphinx-build
+set BUILDDIR=build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
+if NOT "%PAPER%" == "" (
+ set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+ :help
+ echo.Please use `make ^<target^>` where ^<target^> is one of
+ echo. html to make standalone HTML files
+ echo. dirhtml to make HTML files named index.html in directories
+ echo. pickle to make pickle files
+ echo. json to make JSON files
+ echo. htmlhelp to make HTML files and a HTML help project
+ echo. qthelp to make HTML files and a qthelp project
+ echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+ echo. changes to make an overview over all changed/added/deprecated items
+ echo. linkcheck to check all external links for integrity
+ echo. doctest to run all doctests embedded in the documentation if enabled
+ goto end
+)
+
+if "%1" == "clean" (
+ for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+ del /q /s %BUILDDIR%\*
+ goto end
+)
+
+if "%1" == "html" (
+ %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+ goto end
+)
+
+if "%1" == "dirhtml" (
+ %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+ goto end
+)
+
+if "%1" == "pickle" (
+ %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+ echo.
+ echo.Build finished; now you can process the pickle files.
+ goto end
+)
+
+if "%1" == "json" (
+ %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+ echo.
+ echo.Build finished; now you can process the JSON files.
+ goto end
+)
+
+if "%1" == "htmlhelp" (
+ %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+ echo.
+ echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+ goto end
+)
+
+if "%1" == "qthelp" (
+ %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+ echo.
+ echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+ echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Gallium.qhcp
+ echo.To view the help file:
+ echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Gallium.ghc
+ goto end
+)
+
+if "%1" == "latex" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ echo.
+ echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "changes" (
+ %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+ echo.
+ echo.The overview file is in %BUILDDIR%/changes.
+ goto end
+)
+
+if "%1" == "linkcheck" (
+ %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+ echo.
+ echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+ goto end
+)
+
+if "%1" == "doctest" (
+ %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+ echo.
+ echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+ goto end
+)
+
+:end
diff --git a/src/gallium/docs/source/conf.py b/src/gallium/docs/source/conf.py
new file mode 100644
index 00000000000..9b0c86babdb
--- /dev/null
+++ b/src/gallium/docs/source/conf.py
@@ -0,0 +1,197 @@
+# -*- coding: utf-8 -*-
+#
+# Gallium documentation build configuration file, created by
+# sphinx-quickstart on Sun Dec 20 14:09:05 2009.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.append(os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# 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']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Gallium'
+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
+# built documents.
+#
+# The short X.Y version.
+version = '0.3'
+# The full version, including alpha/beta/rc tags.
+release = '0.3'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+exclude_trees = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# The language for highlighting source code.
+highlight_language = 'c'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Galliumdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+ ('index', 'Gallium.tex', u'Gallium Documentation',
+ u'VMWare, X.org, Nouveau', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst
new file mode 100644
index 00000000000..21f5f9111a0
--- /dev/null
+++ b/src/gallium/docs/source/context.rst
@@ -0,0 +1,128 @@
+Context
+=======
+
+The context object represents the purest, most directly accessible, abilities
+of the device's 3D rendering pipeline.
+
+Methods
+-------
+
+CSO State
+^^^^^^^^^
+
+All CSO state is created, bound, and destroyed, with triplets of methods that
+all follow a specific naming scheme. For example, ``create_blend_state``,
+``bind_blend_state``, and ``destroy_blend_state``.
+
+CSO objects handled by the context object:
+
+* :ref:`Blend`: ``*_blend_state``
+* :ref:`Sampler`: These are special; they can be bound to either vertex or
+ fragment samplers, and they are bound in groups.
+ ``bind_fragment_sampler_states``, ``bind_vertex_sampler_states``
+* :ref:`Rasterizer`: ``*_rasterizer_state``
+* :ref:`Depth, Stencil, & Alpha`: ``*_depth_stencil_alpha_state``
+* :ref:`Shader`: These have two sets of methods. ``*_fs_state`` is for
+ fragment shaders, and ``*_vs_state`` is for vertex shaders.
+
+
+Resource Binding State
+^^^^^^^^^^^^^^^^^^^^^^
+
+This state describes how resources in various flavours (textures,
+buffers, surfaces) are bound to the driver.
+
+
+* ``set_constant_buffer``
+* ``set_framebuffer_state``
+* ``set_fragment_sampler_textures``
+* ``set_vertex_sampler_textures``
+* ``set_vertex_buffers``
+
+
+Non-CSO State
+^^^^^^^^^^^^^
+
+These pieces of state are too small, variable, and/or trivial to have CSO
+objects. They all follow simple, one-method binding calls, e.g.
+``set_edgeflags``.
+
+* ``set_edgeflags``
+* ``set_blend_color``
+* ``set_clip_state``
+* ``set_polygon_stipple``
+* ``set_scissor_state``
+* ``set_viewport_state``
+* ``set_vertex_elements``
+
+
+Clearing
+^^^^^^^^
+
+``clear`` initializes some or all of the surfaces currently bound to
+the framebuffer to particular RGBA, depth, or stencil values.
+
+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.
+
+
+Drawing
+^^^^^^^
+
+``draw_arrays``
+
+``draw_elements``
+
+``draw_range_elements``
+
+
+Queries
+^^^^^^^
+
+Queries gather some statistic from the 3D pipeline over one or more
+draws. Queries may be nested, though no state tracker currently
+exercises this.
+
+Queries can be created with ``create_query`` and deleted with
+``destroy_query``. To enable a query, use ``begin_query``, and when finished,
+use ``end_query`` to stop the query. Finally, ``get_query_result`` is used
+to retrieve the results.
+
+Flushing
+^^^^^^^^
+
+``flush``
+
+
+Resource Busy Queries
+^^^^^^^^^^^^^^^^^^^^^
+
+``is_texture_referenced``
+
+``is_buffer_referenced``
+
+
+
+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 operate directly on ``pipe_surface`` 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.
+
+``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.
+
+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.
+
diff --git a/src/gallium/docs/source/cso.rst b/src/gallium/docs/source/cso.rst
new file mode 100644
index 00000000000..dab1ee50f39
--- /dev/null
+++ b/src/gallium/docs/source/cso.rst
@@ -0,0 +1,14 @@
+CSO
+===
+
+CSO, Constant State Objects, are a core part of Gallium's API.
+
+CSO work on the principle of reusable state; they are created by filling
+out a state object with the desired properties, then passing that object
+to a context. The context returns an opaque context-specific handle which
+can be bound at any time for the desired effect.
+
+.. toctree::
+ :glob:
+
+ cso/*
diff --git a/src/gallium/docs/source/cso/blend.rst b/src/gallium/docs/source/cso/blend.rst
new file mode 100644
index 00000000000..fd9e4a1e2d5
--- /dev/null
+++ b/src/gallium/docs/source/cso/blend.rst
@@ -0,0 +1,14 @@
+.. _blend:
+
+Blend
+=====
+
+This state controls blending of the final fragments into the target rendering
+buffers.
+
+XXX it is unresolved what behavior should result if blend_enable is off.
+
+Members
+-------
+
+XXX undocumented members
diff --git a/src/gallium/docs/source/cso/dsa.rst b/src/gallium/docs/source/cso/dsa.rst
new file mode 100644
index 00000000000..12abaa9d6fe
--- /dev/null
+++ b/src/gallium/docs/source/cso/dsa.rst
@@ -0,0 +1,58 @@
+.. _depth,stencil,&alpha:
+
+Depth, Stencil, & Alpha
+=======================
+
+These three states control the depth, stencil, and alpha tests, used to
+discard fragments that have passed through the fragment shader.
+
+Traditionally, these three tests have been clumped together in hardware, so
+they are all stored in one structure.
+
+During actual execution, the order of operations done on fragments is always:
+
+* Stencil
+* Depth
+* Alpha
+
+Depth Members
+-------------
+
+enabled
+ Whether the depth test is enabled.
+writemask
+ Whether the depth buffer receives depth writes.
+func
+ The depth test function. One of PIPE_FUNC.
+
+Stencil Members
+---------------
+
+XXX document valuemask, writemask
+
+enabled
+ Whether the stencil test is enabled. For the second stencil, whether the
+ two-sided stencil is enabled.
+func
+ The stencil test function. One of PIPE_FUNC.
+ref_value
+ Stencil test reference value; used for certain functions.
+fail_op
+ The operation to carry out if the stencil test fails. One of
+ PIPE_STENCIL_OP.
+zfail_op
+ The operation to carry out if the stencil test passes but the depth test
+ fails. One of PIPE_STENCIL_OP.
+zpass_op
+ The operation to carry out if the stencil test and depth test both pass.
+ One of PIPE_STENCIL_OP.
+
+Alpha Members
+-------------
+
+enabled
+ Whether the alpha test is enabled.
+func
+ The alpha test function. One of PIPE_FUNC.
+ref_value
+ Alpha test reference value; used for certain functions.
diff --git a/src/gallium/docs/source/cso/rasterizer.rst b/src/gallium/docs/source/cso/rasterizer.rst
new file mode 100644
index 00000000000..afb58ea375f
--- /dev/null
+++ b/src/gallium/docs/source/cso/rasterizer.rst
@@ -0,0 +1,87 @@
+.. _rasterizer:
+
+Rasterizer
+==========
+
+The rasterizer is the main chunk of state controlling how vertices are
+interpolated into fragments.
+
+Members
+-------
+
+XXX undocumented light_twoside, front_winding, cull_mode, fill_cw, fill_ccw, offset_cw, offset_ccw
+XXX moar undocumented poly_smooth, line_stipple_factor, line_last_pixel, offset_units, offset_scale
+XXX sprite_coord_mode
+
+flatshade
+ If set, the provoking vertex of each polygon is used to determine the
+ color of the entire polygon. If not set, the color fragments will be
+ interpolated from each vertex's color.
+scissor
+ Whether the scissor test is enabled.
+poly_stipple_enable
+ Whether polygon stippling is enabled.
+point_smooth
+ Whether points should be smoothed. Point smoothing turns rectangular
+ points into circles or ovals.
+point_sprite
+ Whether point sprites are enabled.
+point_size_per_vertex
+ Whether vertices have a point size element.
+multisample
+ Whether :ref:`MSAA` is enabled.
+line_smooth
+ Whether lines should be smoothed. Line smoothing is simply anti-aliasing.
+line_stipple_enable
+ Whether line stippling is enabled.
+line_stipple_pattern
+ 16-bit bitfield of on/off flags, used to pattern the line stipple.
+bypass_vs_clip_and_viewport
+ Whether the entire TCL pipeline should be bypassed. This implies that
+ vertices are pre-transformed for the viewport, and will not be run
+ through the vertex shader. Note that implementations may still clip away
+ vertices that are not in the viewport.
+flatshade_first
+ Whether the first vertex should be the provoking vertex, for most
+ primitives. If not set, the last vertex is the provoking vertex.
+gl_rasterization_rules
+ Whether the rasterizer should use (0.5, 0.5) pixel centers. When not set,
+ the rasterizer will use (0, 0) for pixel centers.
+line_width
+ The width of lines.
+point_size
+ The size of points, if not specified per-vertex.
+point_size_min
+ The minimum size of points.
+point_size_max
+ The maximum size of points.
+
+Notes
+-----
+
+flatshade
+^^^^^^^^^
+
+The actual interpolated shading algorithm is obviously
+implementation-dependent, but will usually be Gourard for most hardware.
+
+bypass_vs_clip_and_viewport
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When set, this implies that vertices are pre-transformed for the viewport, and
+will not be run through the vertex shader. Note that implementations may still
+clip away vertices that are not visible.
+
+flatshade_first
+^^^^^^^^^^^^^^^
+
+There are several important exceptions to the specification of this rule.
+
+* ``PIPE_PRIMITIVE_POLYGON``: The provoking vertex is always the first
+ vertex. If the caller wishes to change the provoking vertex, they merely
+ need to rotate the vertices themselves.
+* ``PIPE_PRIMITIVE_QUAD``, ``PIPE_PRIMITIVE_QUAD_STRIP``: This option has no
+ effect; the provoking vertex is always the last vertex.
+* ``PIPE_PRIMITIVE_TRIANGLE_FAN``: When set, the provoking vertex is the
+ second vertex, not the first. This permits each segment of the fan to have
+ a different color.
diff --git a/src/gallium/docs/source/cso/sampler.rst b/src/gallium/docs/source/cso/sampler.rst
new file mode 100644
index 00000000000..e3f1757f57a
--- /dev/null
+++ b/src/gallium/docs/source/cso/sampler.rst
@@ -0,0 +1,46 @@
+.. _sampler:
+
+Sampler
+=======
+
+Texture units have many options for selecting texels from loaded textures;
+this state controls an individual texture unit's texel-sampling settings.
+
+Texture coordinates are always treated as four-dimensional, and referred to
+with the traditional (S, T, R, Q) notation.
+
+Members
+-------
+
+XXX undocumented compare_mode, compare_func
+
+wrap_s
+ How to wrap the S coordinate. One of PIPE_TEX_WRAP.
+wrap_t
+ How to wrap the T coordinate. One of PIPE_TEX_WRAP.
+wrap_r
+ How to wrap the R coordinate. One of PIPE_TEX_WRAP.
+min_img_filter
+ The filter to use when minifying texels. One of PIPE_TEX_FILTER.
+min_mip_filter
+ The filter to use when minifying mipmapped textures. One of
+ PIPE_TEX_FILTER.
+mag_img_filter
+ The filter to use when magnifying texels. One of PIPE_TEX_FILTER.
+normalized_coords
+ Whether the texture coordinates are normalized. If normalized, they will
+ always be in [0, 1]. If not, they will be in the range of each dimension
+ of the loaded texture.
+prefilter
+ XXX From the Doxy, "weird sampling state exposed by some APIs." Refine.
+lod_bias
+ The bias to apply to the level of detail.
+min_lod
+ Minimum level of detail, used to clamp LoD after bias.
+max_lod
+ Maximum level of detail, used to clamp LoD after bias.
+border_color
+ RGBA color used for out-of-bounds coordinates.
+max_anisotropy
+ Maximum filtering to apply anisotropically to textures. Setting this to
+ 1.0 effectively disables anisotropic filtering.
diff --git a/src/gallium/docs/source/cso/shader.rst b/src/gallium/docs/source/cso/shader.rst
new file mode 100644
index 00000000000..0ee42c87876
--- /dev/null
+++ b/src/gallium/docs/source/cso/shader.rst
@@ -0,0 +1,12 @@
+.. _shader:
+
+Shader
+======
+
+One of the two types of shaders supported by Gallium.
+
+Members
+-------
+
+tokens
+ A list of tgsi_tokens.
diff --git a/src/gallium/docs/source/distro.rst b/src/gallium/docs/source/distro.rst
new file mode 100644
index 00000000000..33e846e33d2
--- /dev/null
+++ b/src/gallium/docs/source/distro.rst
@@ -0,0 +1,141 @@
+Distribution
+============
+
+Along with the interface definitions, the following drivers, state trackers,
+and auxiliary modules are shipped in the standard Gallium distribution.
+
+Drivers
+-------
+
+Cell
+^^^^
+
+Failover
+^^^^^^^^
+
+Deprecated.
+
+Intel i915
+^^^^^^^^^^
+
+Intel i965
+^^^^^^^^^^
+
+Highly experimental.
+
+Identity
+^^^^^^^^
+
+Wrapper driver.
+
+LLVM Softpipe
+^^^^^^^^^^^^^
+
+nVidia nv04
+^^^^^^^^^^^
+
+Deprecated.
+
+nVidia nv10
+^^^^^^^^^^^
+
+Deprecated.
+
+nVidia nv20
+^^^^^^^^^^^
+
+Deprecated.
+
+nVidia nv30
+^^^^^^^^^^^
+
+nVidia nv40
+^^^^^^^^^^^
+
+nVidia nv50
+^^^^^^^^^^^
+
+VMWare SVGA
+^^^^^^^^^^^
+
+ATI r300
+^^^^^^^^
+
+AMD/ATI r600
+^^^^^^^^^^^^
+
+Highly experimental.
+
+Softpipe
+^^^^^^^^
+
+Reference software rasterizer.
+
+Trace
+^^^^^
+
+Wrapper driver.
+
+State Trackers
+--------------
+
+Direct Rendering Infrastructure
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+EGL
+^^^
+
+GLX
+^^^
+
+MesaGL
+^^^^^^
+
+Python
+^^^^^^
+
+OpenVG
+^^^^^^
+
+WGL
+^^^
+
+Xorg XFree86 DDX
+^^^^^^^^^^^^^^^^
+
+Auxiliary
+---------
+
+CSO Cache
+^^^^^^^^^
+
+Draw
+^^^^
+
+Gallivm
+^^^^^^^
+
+Indices
+^^^^^^^
+
+Pipe Buffer Manager
+^^^^^^^^^^^^^^^^^^^
+
+Remote Debugger
+^^^^^^^^^^^^^^^
+
+Runtime Assembly Emission
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Surface Context Tracker
+^^^^^^^^^^^^^^^^^^^^^^^
+
+TGSI
+^^^^
+
+Translate
+^^^^^^^^^
+
+Util
+^^^^
+
diff --git a/src/gallium/docs/source/glossary.rst b/src/gallium/docs/source/glossary.rst
new file mode 100644
index 00000000000..6a9110ce786
--- /dev/null
+++ b/src/gallium/docs/source/glossary.rst
@@ -0,0 +1,10 @@
+Glossary
+========
+
+.. glossary::
+ :sorted:
+
+ MSAA
+ Multi-Sampled Anti-Aliasing. A basic anti-aliasing technique that takes
+ multiple samples of the depth buffer, and uses this information to
+ smooth the edges of polygons.
diff --git a/src/gallium/docs/source/index.rst b/src/gallium/docs/source/index.rst
new file mode 100644
index 00000000000..54bc883fced
--- /dev/null
+++ b/src/gallium/docs/source/index.rst
@@ -0,0 +1,28 @@
+.. Gallium documentation master file, created by
+ sphinx-quickstart on Sun Dec 20 14:09:05 2009.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to Gallium's documentation!
+===================================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ intro
+ tgsi
+ screen
+ context
+ cso
+ distro
+ glossary
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
diff --git a/src/gallium/docs/source/intro.rst b/src/gallium/docs/source/intro.rst
new file mode 100644
index 00000000000..1ea103840a2
--- /dev/null
+++ b/src/gallium/docs/source/intro.rst
@@ -0,0 +1,9 @@
+Introduction
+============
+
+What is Gallium?
+----------------
+
+Gallium is essentially an API for writing graphics drivers in a largely
+device-agnostic fashion. It provides several objects which encapsulate the
+core services of graphics hardware in a straightforward manner.
diff --git a/src/gallium/docs/source/screen.rst b/src/gallium/docs/source/screen.rst
new file mode 100644
index 00000000000..9631e6967ef
--- /dev/null
+++ b/src/gallium/docs/source/screen.rst
@@ -0,0 +1,39 @@
+Screen
+======
+
+A screen is an object representing the context-independent part of a device.
+
+Methods
+-------
+
+XXX moar; got bored
+
+get_name
+^^^^^^^^
+
+Returns an identifying name for the screen.
+
+get_vendor
+^^^^^^^^^^
+
+Returns the screen vendor.
+
+get_param
+^^^^^^^^^
+
+Get an integer/boolean screen parameter.
+
+get_paramf
+^^^^^^^^^^
+
+Get a floating-point screen parameter.
+
+is_format_supported
+^^^^^^^^^^^^^^^^^^^
+
+See if a format can be used in a specific manner.
+
+texture_create
+^^^^^^^^^^^^^^
+
+Given a template of texture setup, create a BO-backed texture.
diff --git a/src/gallium/docs/source/tgsi.rst b/src/gallium/docs/source/tgsi.rst
new file mode 100644
index 00000000000..ebee4902b05
--- /dev/null
+++ b/src/gallium/docs/source/tgsi.rst
@@ -0,0 +1,1270 @@
+TGSI
+====
+
+TGSI, Tungsten Graphics Shader Infrastructure, is an intermediate language
+for describing shaders. Since Gallium is inherently shaderful, shaders are
+an important part of the API. TGSI is the only intermediate representation
+used by all drivers.
+
+Instruction Set
+---------------
+
+From GL_NV_vertex_program
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+ARL - Address Register Load
+
+.. math::
+
+ dst.x = \lfloor src.x\rfloor
+
+ dst.y = \lfloor src.y\rfloor
+
+ dst.z = \lfloor src.z\rfloor
+
+ dst.w = \lfloor src.w\rfloor
+
+
+MOV - Move
+
+.. math::
+
+ dst.x = src.x
+
+ dst.y = src.y
+
+ dst.z = src.z
+
+ dst.w = src.w
+
+
+LIT - Light Coefficients
+
+.. math::
+
+ dst.x = 1
+
+ dst.y = max(src.x, 0)
+
+ dst.z = (src.x > 0) ? max(src.y, 0)^{clamp(src.w, -128, 128))} : 0
+
+ dst.w = 1
+
+
+RCP - Reciprocal
+
+.. math::
+
+ dst.x = \frac{1}{src.x}
+
+ dst.y = \frac{1}{src.x}
+
+ dst.z = \frac{1}{src.x}
+
+ dst.w = \frac{1}{src.x}
+
+
+RSQ - Reciprocal Square Root
+
+.. math::
+
+ dst.x = \frac{1}{\sqrt{|src.x|}}
+
+ dst.y = \frac{1}{\sqrt{|src.x|}}
+
+ dst.z = \frac{1}{\sqrt{|src.x|}}
+
+ dst.w = \frac{1}{\sqrt{|src.x|}}
+
+
+EXP - Approximate Exponential Base 2
+
+.. math::
+
+ dst.x = 2^{\lfloor src.x\rfloor}
+
+ dst.y = src.x - \lfloor src.x\rfloor
+
+ dst.z = 2^{src.x}
+
+ dst.w = 1
+
+
+LOG - Approximate Logarithm Base 2
+
+.. math::
+
+ dst.x = \lfloor\log_2{|src.x|}\rfloor
+
+ dst.y = \frac{|src.x|}{2^{\lfloor\log_2{|src.x|}\rfloor}}
+
+ dst.z = \log_2{|src.x|}
+
+ dst.w = 1
+
+
+MUL - Multiply
+
+.. math::
+
+ dst.x = src0.x \times src1.x
+
+ dst.y = src0.y \times src1.y
+
+ dst.z = src0.z \times src1.z
+
+ dst.w = src0.w \times src1.w
+
+
+ADD - Add
+
+.. math::
+
+ dst.x = src0.x + src1.x
+
+ dst.y = src0.y + src1.y
+
+ dst.z = src0.z + src1.z
+
+ dst.w = src0.w + src1.w
+
+
+DP3 - 3-component Dot Product
+
+.. math::
+
+ dst.x = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z
+
+ dst.y = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z
+
+ dst.z = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z
+
+ dst.w = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z
+
+
+DP4 - 4-component Dot Product
+
+.. math::
+
+ dst.x = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src0.w \times src1.w
+
+ dst.y = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src0.w \times src1.w
+
+ dst.z = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src0.w \times src1.w
+
+ dst.w = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src0.w \times src1.w
+
+
+DST - Distance Vector
+
+.. math::
+
+ dst.x = 1
+
+ dst.y = src0.y \times src1.y
+
+ dst.z = src0.z
+
+ dst.w = src1.w
+
+
+MIN - Minimum
+
+.. math::
+
+ dst.x = min(src0.x, src1.x)
+
+ dst.y = min(src0.y, src1.y)
+
+ dst.z = min(src0.z, src1.z)
+
+ dst.w = min(src0.w, src1.w)
+
+
+MAX - Maximum
+
+.. math::
+
+ dst.x = max(src0.x, src1.x)
+
+ dst.y = max(src0.y, src1.y)
+
+ dst.z = max(src0.z, src1.z)
+
+ dst.w = max(src0.w, src1.w)
+
+
+SLT - Set On Less Than
+
+.. math::
+
+ dst.x = (src0.x < src1.x) ? 1 : 0
+
+ dst.y = (src0.y < src1.y) ? 1 : 0
+
+ dst.z = (src0.z < src1.z) ? 1 : 0
+
+ dst.w = (src0.w < src1.w) ? 1 : 0
+
+
+SGE - Set On Greater Equal Than
+
+.. math::
+
+ dst.x = (src0.x >= src1.x) ? 1 : 0
+
+ dst.y = (src0.y >= src1.y) ? 1 : 0
+
+ dst.z = (src0.z >= src1.z) ? 1 : 0
+
+ dst.w = (src0.w >= src1.w) ? 1 : 0
+
+
+MAD - Multiply And Add
+
+.. math::
+
+ dst.x = src0.x \times src1.x + src2.x
+
+ dst.y = src0.y \times src1.y + src2.y
+
+ dst.z = src0.z \times src1.z + src2.z
+
+ dst.w = src0.w \times src1.w + src2.w
+
+
+SUB - Subtract
+
+.. math::
+
+ dst.x = src0.x - src1.x
+
+ dst.y = src0.y - src1.y
+
+ dst.z = src0.z - src1.z
+
+ dst.w = src0.w - src1.w
+
+
+LRP - Linear Interpolate
+
+.. math::
+
+ dst.x = src0.x \times src1.x + (1 - src0.x) \times src2.x
+
+ dst.y = src0.y \times src1.y + (1 - src0.y) \times src2.y
+
+ dst.z = src0.z \times src1.z + (1 - src0.z) \times src2.z
+
+ dst.w = src0.w \times src1.w + (1 - src0.w) \times src2.w
+
+
+CND - Condition
+
+.. math::
+
+ dst.x = (src2.x > 0.5) ? src0.x : src1.x
+
+ dst.y = (src2.y > 0.5) ? src0.y : src1.y
+
+ dst.z = (src2.z > 0.5) ? src0.z : src1.z
+
+ dst.w = (src2.w > 0.5) ? src0.w : src1.w
+
+
+DP2A - 2-component Dot Product And Add
+
+.. math::
+
+ dst.x = src0.x \times src1.x + src0.y \times src1.y + src2.x
+
+ dst.y = src0.x \times src1.x + src0.y \times src1.y + src2.x
+
+ dst.z = src0.x \times src1.x + src0.y \times src1.y + src2.x
+
+ dst.w = src0.x \times src1.x + src0.y \times src1.y + src2.x
+
+
+FRAC - Fraction
+
+.. math::
+
+ dst.x = src.x - \lfloor src.x\rfloor
+
+ dst.y = src.y - \lfloor src.y\rfloor
+
+ dst.z = src.z - \lfloor src.z\rfloor
+
+ dst.w = src.w - \lfloor src.w\rfloor
+
+
+CLAMP - Clamp
+
+.. math::
+
+ dst.x = clamp(src0.x, src1.x, src2.x)
+
+ dst.y = clamp(src0.y, src1.y, src2.y)
+
+ dst.z = clamp(src0.z, src1.z, src2.z)
+
+ dst.w = clamp(src0.w, src1.w, src2.w)
+
+
+FLR - Floor
+
+This is identical to ARL.
+
+.. math::
+
+ dst.x = \lfloor src.x\rfloor
+
+ dst.y = \lfloor src.y\rfloor
+
+ dst.z = \lfloor src.z\rfloor
+
+ dst.w = \lfloor src.w\rfloor
+
+
+ROUND - Round
+
+.. math::
+
+ dst.x = round(src.x)
+
+ dst.y = round(src.y)
+
+ dst.z = round(src.z)
+
+ dst.w = round(src.w)
+
+
+EX2 - Exponential Base 2
+
+.. math::
+
+ dst.x = 2^{src.x}
+
+ dst.y = 2^{src.x}
+
+ dst.z = 2^{src.x}
+
+ dst.w = 2^{src.x}
+
+
+LG2 - Logarithm Base 2
+
+.. math::
+
+ dst.x = \log_2{src.x}
+
+ dst.y = \log_2{src.x}
+
+ dst.z = \log_2{src.x}
+
+ dst.w = \log_2{src.x}
+
+
+POW - Power
+
+.. math::
+
+ dst.x = src0.x^{src1.x}
+
+ dst.y = src0.x^{src1.x}
+
+ dst.z = src0.x^{src1.x}
+
+ dst.w = src0.x^{src1.x}
+
+XPD - Cross Product
+
+.. math::
+
+ dst.x = src0.y \times src1.z - src1.y \times src0.z
+
+ dst.y = src0.z \times src1.x - src1.z \times src0.x
+
+ dst.z = src0.x \times src1.y - src1.x \times src0.y
+
+ dst.w = 1
+
+
+ABS - Absolute
+
+.. math::
+
+ dst.x = |src.x|
+
+ dst.y = |src.y|
+
+ dst.z = |src.z|
+
+ dst.w = |src.w|
+
+
+RCC - Reciprocal Clamped
+
+XXX cleanup on aisle three
+
+.. math::
+
+ dst.x = (1 / src.x) > 0 ? clamp(1 / src.x, 5.42101e-020, 1.884467e+019) : clamp(1 / src.x, -1.884467e+019, -5.42101e-020)
+
+ dst.y = (1 / src.x) > 0 ? clamp(1 / src.x, 5.42101e-020, 1.884467e+019) : clamp(1 / src.x, -1.884467e+019, -5.42101e-020)
+
+ dst.z = (1 / src.x) > 0 ? clamp(1 / src.x, 5.42101e-020, 1.884467e+019) : clamp(1 / src.x, -1.884467e+019, -5.42101e-020)
+
+ dst.w = (1 / src.x) > 0 ? clamp(1 / src.x, 5.42101e-020, 1.884467e+019) : clamp(1 / src.x, -1.884467e+019, -5.42101e-020)
+
+
+DPH - Homogeneous Dot Product
+
+.. math::
+
+ dst.x = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src1.w
+
+ dst.y = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src1.w
+
+ dst.z = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src1.w
+
+ dst.w = src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z + src1.w
+
+
+COS - Cosine
+
+.. math::
+
+ dst.x = \cos{src.x}
+
+ dst.y = \cos{src.x}
+
+ dst.z = \cos{src.x}
+
+ dst.w = \cos{src.x}
+
+
+DDX - Derivative Relative To X
+
+.. math::
+
+ dst.x = partialx(src.x)
+
+ dst.y = partialx(src.y)
+
+ dst.z = partialx(src.z)
+
+ dst.w = partialx(src.w)
+
+
+DDY - Derivative Relative To Y
+
+.. math::
+
+ dst.x = partialy(src.x)
+
+ dst.y = partialy(src.y)
+
+ dst.z = partialy(src.z)
+
+ dst.w = partialy(src.w)
+
+
+KILP - Predicated Discard
+
+ discard
+
+
+PK2H - Pack Two 16-bit Floats
+
+ TBD
+
+
+PK2US - Pack Two Unsigned 16-bit Scalars
+
+ TBD
+
+
+PK4B - Pack Four Signed 8-bit Scalars
+
+ TBD
+
+
+PK4UB - Pack Four Unsigned 8-bit Scalars
+
+ TBD
+
+
+RFL - Reflection Vector
+
+.. math::
+
+ dst.x = 2 \times (src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z) / (src0.x \times src0.x + src0.y \times src0.y + src0.z \times src0.z) \times src0.x - src1.x
+
+ dst.y = 2 \times (src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z) / (src0.x \times src0.x + src0.y \times src0.y + src0.z \times src0.z) \times src0.y - src1.y
+
+ dst.z = 2 \times (src0.x \times src1.x + src0.y \times src1.y + src0.z \times src1.z) / (src0.x \times src0.x + src0.y \times src0.y + src0.z \times src0.z) \times src0.z - src1.z
+
+ dst.w = 1
+
+Considered for removal.
+
+
+SEQ - Set On Equal
+
+.. math::
+
+ dst.x = (src0.x == src1.x) ? 1 : 0
+ dst.y = (src0.y == src1.y) ? 1 : 0
+ dst.z = (src0.z == src1.z) ? 1 : 0
+ dst.w = (src0.w == src1.w) ? 1 : 0
+
+
+SFL - Set On False
+
+.. math::
+
+ dst.x = 0
+ dst.y = 0
+ dst.z = 0
+ dst.w = 0
+
+Considered for removal.
+
+SGT - Set On Greater Than
+
+.. math::
+
+ dst.x = (src0.x > src1.x) ? 1 : 0
+ dst.y = (src0.y > src1.y) ? 1 : 0
+ dst.z = (src0.z > src1.z) ? 1 : 0
+ dst.w = (src0.w > src1.w) ? 1 : 0
+
+
+SIN - Sine
+
+.. math::
+
+ dst.x = \sin{src.x}
+
+ dst.y = \sin{src.x}
+
+ dst.z = \sin{src.x}
+
+ dst.w = \sin{src.x}
+
+
+SLE - Set On Less Equal Than
+
+.. math::
+
+ dst.x = (src0.x <= src1.x) ? 1 : 0
+ dst.y = (src0.y <= src1.y) ? 1 : 0
+ dst.z = (src0.z <= src1.z) ? 1 : 0
+ dst.w = (src0.w <= src1.w) ? 1 : 0
+
+
+SNE - Set On Not Equal
+
+.. math::
+
+ dst.x = (src0.x != src1.x) ? 1 : 0
+ dst.y = (src0.y != src1.y) ? 1 : 0
+ dst.z = (src0.z != src1.z) ? 1 : 0
+ dst.w = (src0.w != src1.w) ? 1 : 0
+
+
+STR - Set On True
+
+.. math::
+
+ dst.x = 1
+ dst.y = 1
+ dst.z = 1
+ dst.w = 1
+
+
+TEX - Texture Lookup
+
+ TBD
+
+
+TXD - Texture Lookup with Derivatives
+
+ TBD
+
+
+TXP - Projective Texture Lookup
+
+ TBD
+
+
+UP2H - Unpack Two 16-Bit Floats
+
+ TBD
+
+ Considered for removal.
+
+UP2US - Unpack Two Unsigned 16-Bit Scalars
+
+ TBD
+
+ Considered for removal.
+
+UP4B - Unpack Four Signed 8-Bit Values
+
+ TBD
+
+ Considered for removal.
+
+UP4UB - Unpack Four Unsigned 8-Bit Scalars
+
+ TBD
+
+ Considered for removal.
+
+X2D - 2D Coordinate Transformation
+
+.. math::
+
+ dst.x = src0.x + src1.x \times src2.x + src1.y \times src2.y
+ dst.y = src0.y + src1.x \times src2.z + src1.y \times src2.w
+ dst.z = src0.x + src1.x \times src2.x + src1.y \times src2.y
+ dst.w = src0.y + src1.x \times src2.z + src1.y \times src2.w
+
+Considered for removal.
+
+
+From GL_NV_vertex_program2
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+ARA - Address Register Add
+
+ TBD
+
+ Considered for removal.
+
+ARR - Address Register Load With Round
+
+.. math::
+
+ dst.x = round(src.x)
+
+ dst.y = round(src.y)
+
+ dst.z = round(src.z)
+
+ dst.w = round(src.w)
+
+
+BRA - Branch
+
+ pc = target
+
+ Considered for removal.
+
+CAL - Subroutine Call
+
+ push(pc)
+ pc = target
+
+
+RET - Subroutine Call Return
+
+ pc = pop()
+
+ Potential restrictions:
+ * Only occurs at end of function.
+
+SSG - Set Sign
+
+.. math::
+
+ dst.x = (src.x > 0) ? 1 : (src.x < 0) ? -1 : 0
+
+ dst.y = (src.y > 0) ? 1 : (src.y < 0) ? -1 : 0
+
+ dst.z = (src.z > 0) ? 1 : (src.z < 0) ? -1 : 0
+
+ dst.w = (src.w > 0) ? 1 : (src.w < 0) ? -1 : 0
+
+
+CMP - Compare
+
+.. math::
+
+ dst.x = (src0.x < 0) ? src1.x : src2.x
+
+ dst.y = (src0.y < 0) ? src1.y : src2.y
+
+ dst.z = (src0.z < 0) ? src1.z : src2.z
+
+ dst.w = (src0.w < 0) ? src1.w : src2.w
+
+
+KIL - Conditional Discard
+
+.. math::
+
+ if (src.x < 0 || src.y < 0 || src.z < 0 || src.w < 0)
+ discard
+ endif
+
+
+SCS - Sine Cosine
+
+.. math::
+
+ dst.x = \cos{src.x}
+
+ dst.y = \sin{src.x}
+
+ dst.z = 0
+
+ dst.y = 1
+
+
+TXB - Texture Lookup With Bias
+
+ TBD
+
+
+NRM - 3-component Vector Normalise
+
+.. math::
+
+ dst.x = src.x / (src.x \times src.x + src.y \times src.y + src.z \times src.z)
+
+ dst.y = src.y / (src.x \times src.x + src.y \times src.y + src.z \times src.z)
+
+ dst.z = src.z / (src.x \times src.x + src.y \times src.y + src.z \times src.z)
+
+ dst.w = 1
+
+
+DIV - Divide
+
+.. math::
+
+ dst.x = \frac{src0.x}{src1.x}
+
+ dst.y = \frac{src0.y}{src1.y}
+
+ dst.z = \frac{src0.z}{src1.z}
+
+ dst.w = \frac{src0.w}{src1.w}
+
+
+DP2 - 2-component Dot Product
+
+.. math::
+
+ dst.x = src0.x \times src1.x + src0.y \times src1.y
+
+ dst.y = src0.x \times src1.x + src0.y \times src1.y
+
+ dst.z = src0.x \times src1.x + src0.y \times src1.y
+
+ dst.w = src0.x \times src1.x + src0.y \times src1.y
+
+
+TXL - Texture Lookup With LOD
+
+ TBD
+
+
+BRK - Break
+
+ TBD
+
+
+IF - If
+
+ TBD
+
+
+BGNFOR - Begin a For-Loop
+
+ dst.x = floor(src.x)
+ dst.y = floor(src.y)
+ dst.z = floor(src.z)
+
+ if (dst.y <= 0)
+ pc = [matching ENDFOR] + 1
+ endif
+
+ Note: The destination must be a loop register.
+ The source must be a constant register.
+
+ Considered for cleanup / removal.
+
+
+REP - Repeat
+
+ TBD
+
+
+ELSE - Else
+
+ TBD
+
+
+ENDIF - End If
+
+ TBD
+
+
+ENDFOR - End a For-Loop
+
+ dst.x = dst.x + dst.z
+ dst.y = dst.y - 1.0
+
+ if (dst.y > 0)
+ pc = [matching BGNFOR instruction] + 1
+ endif
+
+ Note: The destination must be a loop register.
+
+ Considered for cleanup / removal.
+
+ENDREP - End Repeat
+
+ TBD
+
+
+PUSHA - Push Address Register On Stack
+
+ push(src.x)
+ push(src.y)
+ push(src.z)
+ push(src.w)
+
+ Considered for cleanup / removal.
+
+POPA - Pop Address Register From Stack
+
+ dst.w = pop()
+ dst.z = pop()
+ dst.y = pop()
+ dst.x = pop()
+
+ Considered for cleanup / removal.
+
+
+From GL_NV_gpu_program4
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Support for these opcodes indicated by a special pipe capability bit (TBD).
+
+CEIL - Ceiling
+
+.. math::
+
+ dst.x = \lceil src.x\rceil
+
+ dst.y = \lceil src.y\rceil
+
+ dst.z = \lceil src.z\rceil
+
+ dst.w = \lceil src.w\rceil
+
+
+I2F - Integer To Float
+
+.. math::
+
+ dst.x = (float) src.x
+
+ dst.y = (float) src.y
+
+ dst.z = (float) src.z
+
+ dst.w = (float) src.w
+
+
+NOT - Bitwise Not
+
+.. math::
+
+ dst.x = ~src.x
+
+ dst.y = ~src.y
+
+ dst.z = ~src.z
+
+ dst.w = ~src.w
+
+
+TRUNC - Truncate
+
+.. math::
+
+ dst.x = trunc(src.x)
+
+ dst.y = trunc(src.y)
+
+ dst.z = trunc(src.z)
+
+ dst.w = trunc(src.w)
+
+
+SHL - Shift Left
+
+.. math::
+
+ dst.x = src0.x << src1.x
+
+ dst.y = src0.y << src1.x
+
+ dst.z = src0.z << src1.x
+
+ dst.w = src0.w << src1.x
+
+
+SHR - Shift Right
+
+.. math::
+
+ dst.x = src0.x >> src1.x
+
+ dst.y = src0.y >> src1.x
+
+ dst.z = src0.z >> src1.x
+
+ dst.w = src0.w >> src1.x
+
+
+AND - Bitwise And
+
+.. math::
+
+ dst.x = src0.x & src1.x
+
+ dst.y = src0.y & src1.y
+
+ dst.z = src0.z & src1.z
+
+ dst.w = src0.w & src1.w
+
+
+OR - Bitwise Or
+
+.. math::
+
+ dst.x = src0.x | src1.x
+
+ dst.y = src0.y | src1.y
+
+ dst.z = src0.z | src1.z
+
+ dst.w = src0.w | src1.w
+
+
+MOD - Modulus
+
+.. math::
+
+ dst.x = src0.x \bmod src1.x
+
+ dst.y = src0.y \bmod src1.y
+
+ dst.z = src0.z \bmod src1.z
+
+ dst.w = src0.w \bmod src1.w
+
+
+XOR - Bitwise Xor
+
+.. math::
+
+ dst.x = src0.x ^ src1.x
+
+ dst.y = src0.y ^ src1.y
+
+ dst.z = src0.z ^ src1.z
+
+ dst.w = src0.w ^ src1.w
+
+
+SAD - Sum Of Absolute Differences
+
+.. math::
+
+ dst.x = |src0.x - src1.x| + src2.x
+
+ dst.y = |src0.y - src1.y| + src2.y
+
+ dst.z = |src0.z - src1.z| + src2.z
+
+ dst.w = |src0.w - src1.w| + src2.w
+
+
+TXF - Texel Fetch
+
+ TBD
+
+
+TXQ - Texture Size Query
+
+ TBD
+
+
+CONT - Continue
+
+ TBD
+
+
+From GL_NV_geometry_program4
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+EMIT - Emit
+
+ TBD
+
+
+ENDPRIM - End Primitive
+
+ TBD
+
+
+From GLSL
+^^^^^^^^^^
+
+
+BGNLOOP - Begin a Loop
+
+ TBD
+
+
+BGNSUB - Begin Subroutine
+
+ TBD
+
+
+ENDLOOP - End a Loop
+
+ TBD
+
+
+ENDSUB - End Subroutine
+
+ TBD
+
+
+NOP - No Operation
+
+ Do nothing.
+
+
+NRM4 - 4-component Vector Normalise
+
+.. math::
+
+ dst.x = \frac{src.x}{src.x \times src.x + src.y \times src.y + src.z \times src.z + src.w \times src.w}
+
+ dst.y = \frac{src.y}{src.x \times src.x + src.y \times src.y + src.z \times src.z + src.w \times src.w}
+
+ dst.z = \frac{src.z}{src.x \times src.x + src.y \times src.y + src.z \times src.z + src.w \times src.w}
+
+ dst.w = \frac{src.w}{src.x \times src.x + src.y \times src.y + src.z \times src.z + src.w \times src.w}
+
+
+ps_2_x
+^^^^^^^^^^^^
+
+
+CALLNZ - Subroutine Call If Not Zero
+
+ TBD
+
+
+IFC - If
+
+ TBD
+
+
+BREAKC - Break Conditional
+
+ TBD
+
+
+Explanation of symbols used
+------------------------------
+
+
+Functions
+^^^^^^^^^^^^^^
+
+
+ :math:`|x|` Absolute value of `x`.
+
+ :math:`\lceil x \rceil` Ceiling of `x`.
+
+ clamp(x,y,z) Clamp x between y and z.
+ (x < y) ? y : (x > z) ? z : x
+
+ :math:`\lfloor x\rfloor` Floor of `x`.
+
+ :math:`\log_2{x}` Logarithm of `x`, base 2.
+
+ max(x,y) Maximum of x and y.
+ (x > y) ? x : y
+
+ min(x,y) Minimum of x and y.
+ (x < y) ? x : y
+
+ partialx(x) Derivative of x relative to fragment's X.
+
+ partialy(x) Derivative of x relative to fragment's Y.
+
+ pop() Pop from stack.
+
+ :math:`x^y` `x` to the power `y`.
+
+ push(x) Push x on stack.
+
+ round(x) Round x.
+
+ trunc(x) Truncate x, i.e. drop the fraction bits.
+
+
+Keywords
+^^^^^^^^^^^^^
+
+
+ discard Discard fragment.
+
+ dst First destination register.
+
+ dst0 First destination register.
+
+ pc Program counter.
+
+ src First source register.
+
+ src0 First source register.
+
+ src1 Second source register.
+
+ src2 Third source register.
+
+ target Label of target instruction.
+
+
+Other tokens
+---------------
+
+
+Declaration Semantic
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+ Follows Declaration token if Semantic bit is set.
+
+ Since its purpose is to link a shader with other stages of the pipeline,
+ it is valid to follow only those Declaration tokens that declare a register
+ either in INPUT or OUTPUT file.
+
+ SemanticName field contains the semantic name of the register being declared.
+ There is no default value.
+
+ SemanticIndex is an optional subscript that can be used to distinguish
+ different register declarations with the same semantic name. The default value
+ is 0.
+
+ The meanings of the individual semantic names are explained in the following
+ sections.
+
+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 ---
+
+XXX --- wait a minute. Should position be in [0,1] for x and y?
+
+XXX additionally, is there a way to configure the perspective divide? it's
+accelerated on most chipsets AFAIK...
+
+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.
+
+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.
+
+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.
+
+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 ``(p, n, x, f)`` format, where ``p`` is the point size, ``n`` is the minimum
+size, ``x`` is the maximum size, and ``f`` is the fade threshold.
+
+XXX this is arb_vp. is this what we actually do? should double-check...
+
+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.
+
+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.
+
+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.
+
+TGSI_SEMANTIC_EDGEFLAG
+""""""""""""""""""""""
+
+XXX no clue