Commit 392c0833 authored by Erik Faye-Lund 's avatar Erik Faye-Lund

docs: add more more code-tags

It's easier to read function-names, file-names and other
"machine"-related strings if they are formatted in a monospace font. So
let's mark these up with code-tags.
Signed-off-by: Erik Faye-Lund 's avatarErik Faye-Lund <erik.faye-lund@collabora.com>
Reviewed-by: default avatarEmil Velikov <emil.velikov@collabora.com>
Reviewed-by: Eric Engestrom's avatarEric Engestrom <eric.engestrom@intel.com>
parent 0ee36696
...@@ -48,16 +48,16 @@ start-up because of an extension string buffer-overflow problem. ...@@ -48,16 +48,16 @@ start-up because of an extension string buffer-overflow problem.
<p> <p>
The problem is a modern OpenGL driver will return a very long string The problem is a modern OpenGL driver will return a very long string
for the glGetString(GL_EXTENSIONS) query and if the application for the <code>glGetString(GL_EXTENSIONS)</code> query and if the application
naively copies the string into a fixed-size buffer it can overflow the naively copies the string into a fixed-size buffer it can overflow the
buffer and crash the application. buffer and crash the application.
</p> </p>
<p> <p>
The work-around is to set the MESA_EXTENSION_MAX_YEAR environment variable The work-around is to set the <code>MESA_EXTENSION_MAX_YEAR</code>
to the approximate release year of the game. environment variable to the approximate release year of the game.
This will cause the glGetString(GL_EXTENSIONS) query to only report extensions This will cause the <code>glGetString(GL_EXTENSIONS)</code> query to only report
older than the given year. extensions older than the given year.
</p> </p>
<p> <p>
......
...@@ -120,10 +120,11 @@ the opening brace goes on the next line by itself (see above.) ...@@ -120,10 +120,11 @@ the opening brace goes on the next line by itself (see above.)
_mesa_foo_bar() - an internal non-static Mesa function _mesa_foo_bar() - an internal non-static Mesa function
</pre> </pre>
<li>Constants, macros and enum names are ALL_UPPERCASE, with _ between <li>Constants, macros and enum names are <code>ALL_UPPERCASE</code>, with _
words. between words.
<li>Mesa usually uses camel case for local variables (Ex: "localVarname") <li>Mesa usually uses camel case for local variables (Ex:
while gallium typically uses underscores (Ex: "local_var_name"). <code>localVarname</code>) while gallium typically uses underscores (Ex:
<code>local_var_name</code>).
<li>Global variables are almost never used because Mesa should be thread-safe. <li>Global variables are almost never used because Mesa should be thread-safe.
<li>Booleans. Places that are not directly visible to the GL API <li>Booleans. Places that are not directly visible to the GL API
...@@ -131,8 +132,9 @@ should prefer the use of <code>bool</code>, <code>true</code>, and ...@@ -131,8 +132,9 @@ should prefer the use of <code>bool</code>, <code>true</code>, and
<code>false</code> over <code>GLboolean</code>, <code>GL_TRUE</code>, and <code>false</code> over <code>GLboolean</code>, <code>GL_TRUE</code>, and
<code>GL_FALSE</code>. In C code, this may mean that <code>GL_FALSE</code>. In C code, this may mean that
<code>#include &lt;stdbool.h&gt;</code> needs to be added. The <code>#include &lt;stdbool.h&gt;</code> needs to be added. The
<code>try_emit_</code>* methods in src/mesa/program/ir_to_mesa.cpp and <code>try_emit_</code>* methods in <code>src/mesa/program/ir_to_mesa.cpp</code>
src/mesa/state_tracker/st_glsl_to_tgsi.cpp can serve as examples. and <code>src/mesa/state_tracker/st_glsl_to_tgsi.cpp</code> can serve as
examples.
</ul> </ul>
......
...@@ -20,9 +20,9 @@ ...@@ -20,9 +20,9 @@
Normally Mesa (and OpenGL) records but does not notify the user of Normally Mesa (and OpenGL) records but does not notify the user of
errors. It is up to the application to call errors. It is up to the application to call
<code>glGetError</code> to check for errors. Mesa supports an <code>glGetError</code> to check for errors. Mesa supports an
environment variable, MESA_DEBUG, to help with debugging. If environment variable, <code>MESA_DEBUG</code>, to help with debugging. If
MESA_DEBUG is defined, a message will be printed to stdout whenever <code>MESA_DEBUG</code> is defined, a message will be printed to stdout
an error occurs. whenever an error occurs.
</p> </p>
<p> <p>
...@@ -30,12 +30,12 @@ ...@@ -30,12 +30,12 @@
(<code>--buildtype debug</code> for meson, <code>build=debug</code> for scons). (<code>--buildtype debug</code> for meson, <code>build=debug</code> for scons).
</p> </p>
<p> <p>
In your debugger you can set a breakpoint in _mesa_error() to trap Mesa In your debugger you can set a breakpoint in <code>_mesa_error()</code> to trap
errors. Mesa errors.
</p> </p>
<p> <p>
There is a display list printing/debugging facility. See the end of There is a display list printing/debugging facility. See the end of
src/dlist.c for details. <code>src/dlist.c</code> for details.
</p> </p>
</div> </div>
......
...@@ -29,8 +29,8 @@ To add a new GL extension to Mesa you have to do at least the following. ...@@ -29,8 +29,8 @@ To add a new GL extension to Mesa you have to do at least the following.
<ul> <ul>
<li> <li>
If glext.h doesn't define the extension, edit include/GL/gl.h and add If <code>glext.h</code> doesn't define the extension, edit
code like this: <code>include/GL/gl.h</code> and add code like this:
<pre> <pre>
#ifndef GL_EXT_the_extension_name #ifndef GL_EXT_the_extension_name
#define GL_EXT_the_extension_name 1 #define GL_EXT_the_extension_name 1
...@@ -41,18 +41,18 @@ To add a new GL extension to Mesa you have to do at least the following. ...@@ -41,18 +41,18 @@ To add a new GL extension to Mesa you have to do at least the following.
</pre> </pre>
</li> </li>
<li> <li>
In the src/mapi/glapi/gen/ directory, add the new extension functions and In the <code>src/mapi/glapi/gen/</code> directory, add the new extension
enums to the gl_API.xml file. functions and enums to the <code>gl_API.xml</code> file.
Then, a bunch of source files must be regenerated by executing the Then, a bunch of source files must be regenerated by executing the
corresponding Python scripts. corresponding Python scripts.
</li> </li>
<li> <li>
Add a new entry to the <code>gl_extensions</code> struct in mtypes.h Add a new entry to the <code>gl_extensions</code> struct in
if the extension requires driver capabilities not already exposed by <code>mtypes.h</code> if the extension requires driver capabilities not
another extension. already exposed by another extension.
</li> </li>
<li> <li>
Add a new entry to the src/mesa/main/extensions_table.h file. Add a new entry to the <code>src/mesa/main/extensions_table.h</code> file.
</li> </li>
<li> <li>
From this point, the best way to proceed is to find another extension, From this point, the best way to proceed is to find another extension,
...@@ -65,13 +65,13 @@ To add a new GL extension to Mesa you have to do at least the following. ...@@ -65,13 +65,13 @@ To add a new GL extension to Mesa you have to do at least the following.
</li> </li>
<li> <li>
To determine if the new extension is active in the current context, To determine if the new extension is active in the current context,
use the auto-generated _mesa_has_##name_str() function defined in use the auto-generated <code>_mesa_has_##name_str()</code> function
src/mesa/main/extensions.h. defined in <code>src/mesa/main/extensions.h</code>.
</li> </li>
<li> <li>
The dispatch tests check_table.cpp and dispatch_sanity.cpp The dispatch tests check_table.cpp and <code>dispatch_sanity.cpp</code>
should be updated with details about the new extensions functions. These should be updated with details about the new extensions functions. These
tests are run using 'meson test' tests are run using <code>meson test</code>.
</li> </li>
</ul> </ul>
......
...@@ -291,34 +291,34 @@ If you need a deeper you can modify the parameters to ...@@ -291,34 +291,34 @@ If you need a deeper you can modify the parameters to
<h3>3.3 Why Isn't depth buffering working at all?</h3> <h3>3.3 Why Isn't depth buffering working at all?</h3>
<p> <p>
Be sure you're requesting a depth buffered-visual. If you set the MESA_DEBUG Be sure you're requesting a depth buffered-visual. If you set the
environment variable it will warn you about trying to enable depth testing <code>MESA_DEBUG</code> environment variable it will warn you about trying
when you don't have a depth buffer. to enable depth testing when you don't have a depth buffer.
</p> </p>
<p>Specifically, make sure <code>glutInitDisplayMode</code> is being called <p>Specifically, make sure <code>glutInitDisplayMode</code> is being called
with <code>GLUT_DEPTH</code> or <code>glXChooseVisual</code> is being with <code>GLUT_DEPTH</code> or <code>glXChooseVisual</code> is being
called with a non-zero value for GLX_DEPTH_SIZE. called with a non-zero value for <code>GLX_DEPTH_SIZE</code>.
</p> </p>
<p>This discussion applies to stencil buffers, accumulation buffers and <p>This discussion applies to stencil buffers, accumulation buffers and
alpha channels too. alpha channels too.
</p> </p>
<h3>3.4 Why does glGetString() always return NULL?</h3> <h3>3.4 Why does <code>glGetString()</code> always return <code>NULL</code>?</h3>
<p> <p>
Be sure you have an active/current OpenGL rendering context before Be sure you have an active/current OpenGL rendering context before
calling glGetString. calling <code>glGetString</code>.
</p> </p>
<h3>3.5 GL_POINTS and GL_LINES don't touch the right pixels</h3> <h3>3.5 <code>GL_POINTS</code> and <code>GL_LINES</code> don't touch the
right pixels</h3>
<p> <p>
If you're trying to draw a filled region by using GL_POINTS or GL_LINES If you're trying to draw a filled region by using <code>GL_POINTS</code> or
and seeing holes or gaps it's because of a float-to-int rounding problem. <code>GL_LINES</code> and seeing holes or gaps it's because of a float-to-int
But this is not a bug. rounding problem. But this is not a bug. See Appendix H of the OpenGL
See Appendix H of the OpenGL Programming Guide - "OpenGL Correctness Tips". Programming Guide - "OpenGL Correctness Tips". Basically, applying a
Basically, applying a translation of (0.375, 0.375, 0.0) to your coordinates translation of (0.375, 0.375, 0.0) to your coordinates will fix the problem.
will fix the problem.
</p> </p>
<br> <br>
...@@ -365,7 +365,8 @@ the archives) is a good way to get information. ...@@ -365,7 +365,8 @@ the archives) is a good way to get information.
</p> </p>
<h3>4.3 Why isn't GL_EXT_texture_compression_s3tc implemented in Mesa?</h3> <h3>4.3 Why isn't <code>GL_EXT_texture_compression_s3tc</code> implemented in
Mesa?</h3>
<p> <p>
Oh but it is! Prior to 2nd October 2017, the Mesa project did not include s3tc Oh but it is! Prior to 2nd October 2017, the Mesa project did not include s3tc
support due to intellectual property (IP) and/or patent issues around the s3tc support due to intellectual property (IP) and/or patent issues around the s3tc
......
...@@ -48,7 +48,8 @@ You can find some further To-do lists here: ...@@ -48,7 +48,8 @@ You can find some further To-do lists here:
</p> </p>
<ul> <ul>
<li><a href="https://gitlab.freedesktop.org/mesa/mesa/blob/master/docs/features.txt"> <li><a href="https://gitlab.freedesktop.org/mesa/mesa/blob/master/docs/features.txt">
<b>features.txt</b></a> - Status of OpenGL 3.x / 4.x features in Mesa.</li> <code>features.txt</code></a> - Status of OpenGL 3.x / 4.x features in
Mesa.</li>
</ul> </ul>
<p> <p>
...@@ -56,9 +57,9 @@ You can find some further To-do lists here: ...@@ -56,9 +57,9 @@ You can find some further To-do lists here:
</p> </p>
<ul> <ul>
<li><a href="https://dri.freedesktop.org/wiki/R600ToDo"> <li><a href="https://dri.freedesktop.org/wiki/R600ToDo">
<b>r600g</b></a> - Driver for ATI/AMD R600 - Northern Island.</li> <code>r600g</code></a> - Driver for ATI/AMD R600 - Northern Island.</li>
<li><a href="https://dri.freedesktop.org/wiki/R300ToDo"> <li><a href="https://dri.freedesktop.org/wiki/R300ToDo">
<b>r300g</b></a> - Driver for ATI R300 - R500.</li> <code>r300g</code></a> - Driver for ATI R300 - R500.</li>
</ul> </ul>
<p> <p>
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment