1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
4 <meta http-equiv=
"content-type" content=
"text/html; charset=utf-8">
5 <title>Coding Style
</title>
6 <link rel=
"stylesheet" type=
"text/css" href=
"mesa.css">
11 <h1>The Mesa
3D Graphics Library
</h1>
14 <iframe src=
"contents.html"></iframe>
20 Mesa is over
20 years old and the coding style has evolved over time.
21 Some old parts use a style that's a bit out of date.
23 Different sections of mesa can use different coding style as set in the local
24 EditorConfig (.editorconfig) and/or Emacs (.dir-locals.el) file.
26 Alternatively the following is applicable.
28 If the guidelines below don't cover something, try following the format of
29 existing, neighboring code.
33 Basic formatting guidelines
37 <li>3-space indentation, no tabs.
38 <li>Limit lines to
78 or fewer characters. The idea is to prevent line
39 wrapping in
80-column editors and terminals. There are exceptions, such
40 as if you're defining a large, static table of information.
41 <li>Opening braces go on the same line as the if/for/while statement.
51 <li>Put a space before/after operators. For example,
<tt>a = b + c;
</tt>
52 and not
<tt>a=b+c;
</tt>
54 <li>This GNU indent command generally does the right thing for formatting:
56 indent -br -i3 -npcs --no-tabs infile.c -o outfile.c
59 <li>Use comments wherever you think it would be helpful for other developers.
60 Several specific cases and style examples follow. Note that we roughly
61 follow
<a href=
"https://www.stack.nl/~dimitri/doxygen/">Doxygen
</a> conventions.
66 /* null-out pointer to prevent dangling reference below */
71 bufferObj = NULL; /* prevent dangling reference below */
75 /* If this is a new buffer object id, or one which was generated but
76 * never used before, allocate a buffer object now.
79 We try to quote the OpenGL specification where prudent:
81 /* Page
38 of the PDF of the OpenGL ES
3.0 spec says:
83 *
"An INVALID_OPERATION error is generated for any of the following
86 * * <length> is zero."
88 * Additionally, page
94 of the PDF of the OpenGL
4.5 core spec
89 * (
30.10.2014) also says this, so it's no longer allowed for desktop GL,
93 Function comment example:
96 * Create and initialize a new buffer object. Called via the
97 * ctx-
>Driver.CreateObject() driver callback function.
98 * \param name integer name of the object
99 * \param type one of GL_FOO, GL_BAR, etc.
100 * \return pointer to new object or NULL if error
103 _mesa_create_object(GLuint name, GLenum type)
109 <li>Put the function return type and qualifiers on one line and the function
110 name and parameters on the next, as seen above. This makes it easy to use
111 <code>grep ^function_name dir/*
</code> to find function definitions. Also,
112 the opening brace goes on the next line by itself (see above.)
114 <li>Function names follow various conventions depending on the type of function:
116 glFooBar() - a public GL entry point (in glapi_dispatch.c)
117 _mesa_FooBar() - the internal immediate mode function
118 save_FooBar() - retained mode (display list) function in dlist.c
119 foo_bar() - a static (private) function
120 _mesa_foo_bar() - an internal non-static Mesa function
123 <li>Constants, macros and enum names are ALL_UPPERCASE, with _ between
125 <li>Mesa usually uses camel case for local variables (Ex:
"localVarname")
126 while gallium typically uses underscores (Ex:
"local_var_name").
127 <li>Global variables are almost never used because Mesa should be thread-safe.
129 <li>Booleans. Places that are not directly visible to the GL API
130 should prefer the use of
<tt>bool
</tt>,
<tt>true
</tt>, and
131 <tt>false
</tt> over
<tt>GLboolean
</tt>,
<tt>GL_TRUE
</tt>, and
132 <tt>GL_FALSE
</tt>. In C code, this may mean that
133 <tt>#include
<stdbool.h
></tt> needs to be added. The
134 <tt>try_emit_
</tt>* methods in src/mesa/program/ir_to_mesa.cpp and
135 src/mesa/state_tracker/st_glsl_to_tgsi.cpp can serve as examples.