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 The Mesa
3D Graphics Library
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,
<code>a = b + c;
</code>
52 and not
<code>a=b+c;
</code>
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
60 <p>Use comments wherever you think it would be helpful for other developers.
61 Several specific cases and style examples follow. Note that we roughly
62 follow
<a href=
"http://www.doxygen.nl">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
<code>ALL_UPPERCASE
</code>, with _
125 <li>Mesa usually uses camel case for local variables (Ex:
126 <code>localVarname
</code>) while gallium typically uses underscores (Ex:
127 <code>local_var_name
</code>).
128 <li>Global variables are almost never used because Mesa should be thread-safe.
130 <li>Booleans. Places that are not directly visible to the GL API
131 should prefer the use of
<code>bool
</code>,
<code>true
</code>, and
132 <code>false
</code> over
<code>GLboolean
</code>,
<code>GL_TRUE
</code>, and
133 <code>GL_FALSE
</code>. In C code, this may mean that
134 <code>#include
<stdbool.h
></code> needs to be added. The
135 <code>try_emit_*
</code> methods in
<code>src/mesa/program/ir_to_mesa.cpp
</code>
136 and
<code>src/mesa/state_tracker/st_glsl_to_tgsi.cpp
</code> can serve as