From 392c083377fca82ebfbdc559a6a0c6933df422db Mon Sep 17 00:00:00 2001 From: Erik Faye-Lund Date: Tue, 28 May 2019 13:14:03 +0200 Subject: [PATCH] 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 Reviewed-by: Emil Velikov Reviewed-by: Eric Engestrom --- docs/application-issues.html | 10 +++++----- docs/codingstyle.html | 14 ++++++++------ docs/debugging.html | 12 ++++++------ docs/devinfo.html | 24 ++++++++++++------------ docs/faq.html | 29 +++++++++++++++-------------- docs/helpwanted.html | 7 ++++--- 6 files changed, 50 insertions(+), 46 deletions(-) diff --git a/docs/application-issues.html b/docs/application-issues.html index 7407137..c4ac9d9 100644 --- a/docs/application-issues.html +++ b/docs/application-issues.html @@ -48,16 +48,16 @@ start-up because of an extension string buffer-overflow problem.

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 glGetString(GL_EXTENSIONS) query and if the application naively copies the string into a fixed-size buffer it can overflow the buffer and crash the application.

-The work-around is to set the MESA_EXTENSION_MAX_YEAR environment variable -to the approximate release year of the game. -This will cause the glGetString(GL_EXTENSIONS) query to only report extensions -older than the given year. +The work-around is to set the MESA_EXTENSION_MAX_YEAR +environment variable to the approximate release year of the game. +This will cause the glGetString(GL_EXTENSIONS) query to only report +extensions older than the given year.

diff --git a/docs/codingstyle.html b/docs/codingstyle.html index e8832e7..aa1e09c 100644 --- a/docs/codingstyle.html +++ b/docs/codingstyle.html @@ -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 -

  • Constants, macros and enum names are ALL_UPPERCASE, with _ between -words. -
  • Mesa usually uses camel case for local variables (Ex: "localVarname") -while gallium typically uses underscores (Ex: "local_var_name"). +
  • Constants, macros and enum names are ALL_UPPERCASE, with _ +between words. +
  • Mesa usually uses camel case for local variables (Ex: +localVarname) while gallium typically uses underscores (Ex: +local_var_name).
  • Global variables are almost never used because Mesa should be thread-safe.
  • Booleans. Places that are not directly visible to the GL API @@ -131,8 +132,9 @@ should prefer the use of bool, true, and false over GLboolean, GL_TRUE, and GL_FALSE. In C code, this may mean that #include <stdbool.h> needs to be added. The -try_emit_* methods in src/mesa/program/ir_to_mesa.cpp and -src/mesa/state_tracker/st_glsl_to_tgsi.cpp can serve as examples. +try_emit_* methods in src/mesa/program/ir_to_mesa.cpp +and src/mesa/state_tracker/st_glsl_to_tgsi.cpp can serve as +examples. diff --git a/docs/debugging.html b/docs/debugging.html index bd21e5c..c6f69fe 100644 --- a/docs/debugging.html +++ b/docs/debugging.html @@ -20,9 +20,9 @@ Normally Mesa (and OpenGL) records but does not notify the user of errors. It is up to the application to call glGetError to check for errors. Mesa supports an - environment variable, MESA_DEBUG, to help with debugging. If - MESA_DEBUG is defined, a message will be printed to stdout whenever - an error occurs. + environment variable, MESA_DEBUG, to help with debugging. If + MESA_DEBUG is defined, a message will be printed to stdout + whenever an error occurs.

    @@ -30,12 +30,12 @@ (--buildtype debug for meson, build=debug for scons).

    - In your debugger you can set a breakpoint in _mesa_error() to trap Mesa - errors. + In your debugger you can set a breakpoint in _mesa_error() to trap + Mesa errors.

    There is a display list printing/debugging facility. See the end of - src/dlist.c for details. + src/dlist.c for details.

    diff --git a/docs/devinfo.html b/docs/devinfo.html index 07d154b..a636e37 100644 --- a/docs/devinfo.html +++ b/docs/devinfo.html @@ -29,8 +29,8 @@ To add a new GL extension to Mesa you have to do at least the following.
    • - If glext.h doesn't define the extension, edit include/GL/gl.h and add - code like this: + If glext.h doesn't define the extension, edit + include/GL/gl.h and add code like this: 
            #ifndef GL_EXT_the_extension_name
      #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.
    • - In the src/mapi/glapi/gen/ directory, add the new extension functions and - enums to the gl_API.xml file. + In the src/mapi/glapi/gen/ directory, add the new extension + functions and enums to the gl_API.xml file. Then, a bunch of source files must be regenerated by executing the corresponding Python scripts.
    • - Add a new entry to the gl_extensions struct in mtypes.h - if the extension requires driver capabilities not already exposed by - another extension. + Add a new entry to the gl_extensions struct in + mtypes.h if the extension requires driver capabilities not + already exposed by another extension.
    • - Add a new entry to the src/mesa/main/extensions_table.h file. + Add a new entry to the src/mesa/main/extensions_table.h file.
    • 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.
    • To determine if the new extension is active in the current context, - use the auto-generated _mesa_has_##name_str() function defined in - src/mesa/main/extensions.h. + use the auto-generated _mesa_has_##name_str() function + defined in src/mesa/main/extensions.h.
    • - The dispatch tests check_table.cpp and dispatch_sanity.cpp + The dispatch tests check_table.cpp and dispatch_sanity.cpp should be updated with details about the new extensions functions. These - tests are run using 'meson test' + tests are run using meson test.
    diff --git a/docs/faq.html b/docs/faq.html index a85c69c..183bd4e 100644 --- a/docs/faq.html +++ b/docs/faq.html @@ -291,34 +291,34 @@ If you need a deeper you can modify the parameters to

    3.3 Why Isn't depth buffering working at all?

    -Be sure you're requesting a depth buffered-visual. If you set the MESA_DEBUG -environment variable it will warn you about trying to enable depth testing -when you don't have a depth buffer. +Be sure you're requesting a depth buffered-visual. If you set the +MESA_DEBUG environment variable it will warn you about trying +to enable depth testing when you don't have a depth buffer.

    Specifically, make sure glutInitDisplayMode is being called with GLUT_DEPTH or glXChooseVisual is being -called with a non-zero value for GLX_DEPTH_SIZE. +called with a non-zero value for GLX_DEPTH_SIZE.

    This discussion applies to stencil buffers, accumulation buffers and alpha channels too.

    -

    3.4 Why does glGetString() always return NULL?

    +

    3.4 Why does glGetString() always return NULL?

    Be sure you have an active/current OpenGL rendering context before -calling glGetString. +calling glGetString.

    -

    3.5 GL_POINTS and GL_LINES don't touch the right pixels

    +

    3.5 GL_POINTS and GL_LINES don't touch the +right pixels

    -If you're trying to draw a filled region by using GL_POINTS or GL_LINES -and seeing holes or gaps it's because of a float-to-int rounding problem. -But this is not a bug. -See Appendix H of the OpenGL Programming Guide - "OpenGL Correctness Tips". -Basically, applying a translation of (0.375, 0.375, 0.0) to your coordinates -will fix the problem. +If you're trying to draw a filled region by using GL_POINTS or +GL_LINES and seeing holes or gaps it's because of a float-to-int +rounding problem. But this is not a bug. See Appendix H of the OpenGL +Programming Guide - "OpenGL Correctness Tips". Basically, applying a +translation of (0.375, 0.375, 0.0) to your coordinates will fix the problem.


    @@ -365,7 +365,8 @@ the archives) is a good way to get information.

    -

    4.3 Why isn't GL_EXT_texture_compression_s3tc implemented in Mesa?

    +

    4.3 Why isn't GL_EXT_texture_compression_s3tc implemented in +Mesa?

    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 diff --git a/docs/helpwanted.html b/docs/helpwanted.html index 4425590..5e0684b 100644 --- a/docs/helpwanted.html +++ b/docs/helpwanted.html @@ -48,7 +48,8 @@ You can find some further To-do lists here:

    • - features.txt - Status of OpenGL 3.x / 4.x features in Mesa.
      • + features.txt - Status of OpenGL 3.x / 4.x features in + Mesa.

    @@ -56,9 +57,9 @@ You can find some further To-do lists here:

    • - r600g - Driver for ATI/AMD R600 - Northern Island.
      • + r600g - Driver for ATI/AMD R600 - Northern Island.
    • - r300g - Driver for ATI R300 - R500.
      • + r300g - Driver for ATI R300 - R500.

    -- 2.7.4