radeonsi: merge uses_persp_opcode_interp_sample/uses_linear_opcode_interp_sample

[mesa.git] / docs / dispatch.rst

diff --git a/docs/dispatch.rst b/docs/dispatch.rst
index c7b0af37636146993d5c2f13ce5fa9e4fb27dacc..6b808597310ffd16e5e1e4eac1b667da67f5927f 100644 (file)
--- a/docs/dispatch.rst
+++ b/docs/dispatch.rst
@@ -5,7 +5,7 @@ Several factors combine to make efficient dispatch of OpenGL functions
 fairly complicated. This document attempts to explain some of the issues
 and introduce the reader to Mesa's implementation. Readers already
 familiar with the issues around GL dispatch can safely skip ahead to the
-`overview of Mesa's implementation <#overview>`__.
+:ref:`overview of Mesa's implementation <overview>`.
 
 1. Complexity of GL Dispatch
 ----------------------------
@@ -64,7 +64,8 @@ conceptually simple:
 This can be implemented in just a few lines of C code. The file
 ``src/mesa/glapi/glapitemp.h`` contains code very similar to this.
 
-::
+.. code-block:: c
+   :caption: Sample dispatch function
 
    void glVertex3f(GLfloat x, GLfloat y, GLfloat z)
    {
@@ -73,8 +74,6 @@ This can be implemented in just a few lines of C code. The file
        (*dispatch->Vertex3f)(x, y, z);
    }
 
-Sample dispatch function
-
 The problem with this simple implementation is the large amount of
 overhead that it adds to every GL function call.
 
@@ -118,14 +117,13 @@ resulting implementation of ``GET_DISPATCH`` is slightly more complex,
 but it avoids the expensive ``pthread_getspecific`` call in the common
 case.
 
-::
+.. code-block:: c
+   :caption: Improved ``GET_DISPATCH`` Implementation
 
    #define GET_DISPATCH() \
        (_glapi_Dispatch != NULL) \
            ? _glapi_Dispatch : pthread_getspecific(&_glapi_Dispatch_key)
 
-Improved ``GET_DISPATCH`` Implementation
-
 3.2. ELF TLS
 ~~~~~~~~~~~~
 
@@ -142,15 +140,14 @@ with direct rendering drivers that use either interface. Once the
 pointer is properly declared, ``GET_DISPACH`` becomes a simple variable
 reference.
 
-::
+.. code-block:: c
+   :caption: TLS ``GET_DISPATCH`` Implementation
 
    extern __thread struct _glapi_table *_glapi_tls_Dispatch
        __attribute__((tls_model("initial-exec")));
 
    #define GET_DISPATCH() _glapi_tls_Dispatch
 
-TLS ``GET_DISPATCH`` Implementation
-
 Use of this path is controlled by the preprocessor define
 ``USE_ELF_TLS``. Any platform capable of using ELF TLS should use this
 as the default dispatch method.
@@ -165,7 +162,7 @@ dispatch routines are very short, and it is trivial to create optimal
 assembly language versions. The amount of optimization provided by using
 assembly stubs varies from platform to platform and application to
 application. However, by using the assembly stubs, many platforms can
-use an additional space optimization (see `below <#fixedsize>`__).
+use an additional space optimization (see :ref:`below <fixedsize>`).
 
 The biggest hurdle to creating assembly stubs is handling the various
 ways that the dispatch table pointer can be accessed. There are four
@@ -198,12 +195,11 @@ the assembly source file different implementations of the macro are
 selected based on the defined preprocessor variables. The assembly code
 then consists of a series of invocations of the macros such as:
 
-::
+.. code-block:: c
+   :caption: SPARC Assembly Implementation of ``glColor3fv``
 
    GL_STUB(Color3fv, _gloffset_Color3fv)
 
-SPARC Assembly Implementation of ``glColor3fv``
-
 The benefit of this technique is that changes to the calling pattern
 (i.e., addition of a new dispatch table pointer access method) require
 fewer changed lines in the assembly code.
@@ -223,8 +219,8 @@ implementation of each function. This makes the assembly file
 considerably larger (e.g., 29,332 lines for ``glapi_x86-64.S`` versus
 1,155 lines for ``glapi_x86.S``) and causes simple changes to the
 function implementation to generate many lines of diffs. Since the
-assembly files are typically generated by scripts (see
-`below <#autogen>`__), this isn't a significant problem.
+assembly files are typically generated by scripts, this isn't a
+significant problem.
 
 Once a new assembly file is created, it must be inserted in the build
 system. There are two steps to this. The file must first be added to