-Mesa is over 20 years old and the coding style has evolved over time. -Some old parts use a style that's a bit out of date. -If the guidelines below don't cover something, try following the format of -existing, neighboring code. -
- --Basic formatting guidelines -
- -
- if (condition) {
- foo;
- } else {
- bar;
- }
-
-
-- indent -br -i3 -npcs --no-tabs infile.c -o outfile.c -- -
- /* null-out pointer to prevent dangling reference below */ - bufferObj = NULL; --Or, -
- bufferObj = NULL; /* prevent dangling reference below */ --Multi-line comment: -
- /* If this is a new buffer object id, or one which was generated but - * never used before, allocate a buffer object now. - */ --We try to quote the OpenGL specification where prudent: -
- /* Page 38 of the PDF of the OpenGL ES 3.0 spec says: - * - * "An INVALID_OPERATION error is generated for any of the following - * conditions: - * - * *-Function comment example: -is zero." - * - * Additionally, page 94 of the PDF of the OpenGL 4.5 core spec - * (30.10.2014) also says this, so it's no longer allowed for desktop GL, - * either. - */ -
- /**
- * Create and initialize a new buffer object. Called via the
- * ctx->Driver.CreateObject() driver callback function.
- * \param name integer name of the object
- * \param type one of GL_FOO, GL_BAR, etc.
- * \return pointer to new object or NULL if error
- */
- struct gl_object *
- _mesa_create_object(GLuint name, GLenum type)
- {
- /* function body */
- }
-
-
-grep ^function_name dir/* to find function definitions. Also,
-the opening brace goes on the next line by itself (see above.)
-
-- glFooBar() - a public GL entry point (in glapi_dispatch.c) - _mesa_FooBar() - the internal immediate mode function - save_FooBar() - retained mode (display list) function in dlist.c - foo_bar() - a static (private) function - _mesa_foo_bar() - an internal non-static Mesa function -- -
-The basic guidelines for submitting patches are: -
- -git bisect.)
-git send-email.
--The basic rules for patch formatting are: -
- -- mesa: Add support for querying GL_VERTEX_ATTRIB_ARRAY_LONG - - gallium: add PIPE_CAP_DEVICE_RESET_STATUS_QUERY - - i965: Fix missing type in local variable declaration. --
- i965: Remove end-of-thread SEND alignment code. - - This was present in Eric's initial implementation of the compaction code - for Sandybridge (commit 077d01b6). There is no documentation saying this - is necessary, and removing it causes no regressions in piglit on any - platform. --
- Bugzilla: https://bugs.freedesktop.org/show_bug.cgi?id=89689 --
- st/mesa: add ARB_texture_stencil8 support (v4) - - if we support stencil texturing, enable texture_stencil8 - there is no requirement to support native S8 for this, - the texture can be converted to x24s8 fine. - - v2: fold fixes from Marek in: - a) put S8 last in the list - b) fix renderable to always test for d/s renderable - fixup the texture case to use a stencil only format - for picking the format for the texture view. - v3: hit fallback for getteximage - v4: put s8 back in front, it shouldn't get picked now (Ilia) --
- Tested-by: Joe Hacker <jhacker@foo.com> --
- Reviewed-by: Joe Hacker <jhacker@foo.com> - Acked-by: Joe Hacker <jhacker@foo.com> --
-It should go without saying that patches must be tested. In general, -do whatever testing is prudent. -
- --You should always run the Mesa test suite before submitting patches. -The test suite can be run using the 'make check' command. All tests -must pass before patches will be accepted, this may mean you have -to update the tests themselves. -
- --Whenever possible and applicable, test the patch with -Piglit to -check for regressions. -
- - --Patches should be sent to the Mesa mailing list for review. -When submitting a patch make sure to use git send-email rather than attaching -patches to emails. Sending patches as attachments prevents people from being -able to provide in-line review comments. -
- --When submitting follow-up patches you can use --in-reply-to to make v2, v3, -etc patches show up as replies to the originals. This usually works well -when you're sending out updates to individual patches (as opposed to -re-sending the whole series). Using --in-reply-to makes -it harder for reviewers to accidentally review old patches. -
- --When submitting follow-up patches you should also login to -patchwork and change the -state of your old patches to Superseded. -
- --When you've reviewed a patch on the mailing list, please be unambiguous -about your review. That is, state either -
- Reviewed-by: Joe Hacker <jhacker@foo.com> --or -
- Acked-by: Joe Hacker <jhacker@foo.com> --Rather than saying just "LGTM" or "Seems OK". - - -
-If small changes are suggested, it's OK to say something like: -
- With the above fixes, Reviewed-by: Joe Hacker <jhacker@foo.com> --which tells the patch author that the patch can be committed, as long -as the issues are resolved first. - - - -
-If you want a commit to be applied to a stable branch, -you should add an appropriate note to the commit message. -
- --Here are some examples of such a note: -
-git cherry-pick -x <commit>. The -x option is
-important so that the picked patch references the comit ID of the original
-patch.
-
-The stable-release manager may at times need to force-push changes to the
-stable branches, for example, to drop a previously-picked patch that was later
-identified as causing a regression). These force-pushes may cause changes to
-be lost from the stable branch if developers push things directly. Consider
-yourself warned.
-
-The stable-release manager is also given broad discretion in rejecting patches
-that have been nominated for the stable branch. The most basic rule is that
-the stable branch is for bug fixes only, (no new features, no
-regressions). Here is a non-exhaustive list of some reasons that a patch may
-be rejected:
-
--These are the instructions for making a new Mesa release. -
- --Use git to get the latest Mesa files from the git repository, from whatever -branch is relevant. This document uses the convention X.Y.Z for the release -being created, which should be created from a branch named X.Y. -
- --The release manager should, at the very least, test the code by compiling it, -installing it, and running the latest piglit to ensure that no piglit tests -have regressed since the previous release. -
- --The release manager should do this testing with at least one hardware driver, -(say, whatever is contained in the local development machine), as well as on -both Gallium and non-Gallium software drivers. The software testing can be -performed by running piglit with the following environment-variable set: -
- --LIBGL_ALWAYS_SOFTWARE=1 -- -And Gallium vs. non-Gallium software drivers can be obtained by using the -following configure flags on separate builds: - -
---with-dri-drivers=swrast ---with-gallium-drivers=swrast -- -
-Note: If both options are given in one build, both swrast_dri.so drivers will -be compiled, but only one will be installed. The following command can be used -to ensure the correct driver is being tested: -
- --LIBGL_ALWAYS_SOFTWARE=1 glxinfo | grep "renderer string" -- -If any regressions are found in this testing with piglit, stop here, and do -not perform a release until regressions are fixed. - -
-Increment the version contained in the file VERSION at Mesa's top-level, then -commit this change. -
- --Create a new file docs/relnotes/X.Y.Z.html, (follow the style of the previous -release notes). Note that the sha256sums section of the release notes should -be empty at this point. -
- --Two scripts are available to help generate portions of the release notes: - -
- ./bin/bugzilla_mesa.sh - ./bin/shortlog_mesa.sh -- -
-The first script identifies commits that reference bugzilla bugs and obtains -the descriptions of those bugs from bugzilla. The second script generates a -log of all commits. In both cases, HTML-formatted lists are printed to stdout -to be included in the release notes. -
- --Commit these changes -
- --From inside the Mesa directory: -
- ./autogen.sh - make -j1 tarballs -- -
-After the tarballs are created, the sha256 checksums for the files will -be computed and printed. These will be used in a step below. -
- --It's important at this point to also verify that the constructed tar file -actually builds: -
- -- tar xjf MesaLib-X.Y.Z.tar.bz2 - cd Mesa-X.Y.Z - ./configure --enable-gallium-llvm - make -j6 - make install -- -
-Some touch testing should also be performed at this point, (run glxgears or -more involved OpenGL programs against the installed Mesa). -
- --Create detached GPG signatures for each of the archive files created above: -
- -- gpg --sign --detach MesaLib-X.Y.Z.tar.gz - gpg --sign --detach MesaLib-X.Y.Z.tar.bz2 - gpg --sign --detach MesaLib-X.Y.Z.zip -- -
-Tag the commit used for the build: -
- -- git tag -s mesa-X.Y.X -m "Mesa X.Y.Z release" -- -
-Note: It would be nice to investigate and fix the issue that causes the -tarballs target to fail with multiple build process, such as with "-j4". It -would also be nice to incorporate all of the above commands into a single -makefile target. And instead of a custom "tarballs" target, we should -incorporate things into the standard "make dist" and "make distcheck" targets. -
- --Edit docs/relnotes/X.Y.Z.html to add the sha256sums printed as part of "make -tarballs" in the previous step. Commit this change. -
- --This is the first step that cannot easily be undone. The release is going -forward from this point: -
- -- git push origin X.Y --tags -- -
-The following commands can be used to copy the release archive files and -signatures to the freedesktop.org server: -
- -- scp MesaLib-X.Y.Z* people.freedesktop.org: - ssh people.freedesktop.org - cd /srv/ftp.freedesktop.org/pub/mesa - mkdir X.Y.Z - cd X.Y.Z - mv ~/MesaLib-X.Y.Z* . -- -
-Something like the following steps will do the trick: -
- -- cp docs/relnotes/X.Y.Z.html /tmp - git checkout master - cp /tmp/X.Y.Z.html docs/relnotes - git add docs/relnotes/X.Y.Z.html -- -
-Also, edit docs/relnotes.html to add a link to the new release notes, and edit -docs/index.html to add a news entry. Then commit and push: -
- -- git commit -a -m "docs: Import X.Y.Z release notes, add news item." - git push origin -- -
-NOTE: The recent release managers have not been performing this step -themselves, but leaving this to Brian Paul, (who has access to the -sourceforge.net hosting for mesa3d.org). Brian is more than willing to grant -the permission necessary to future release managers to do this step on their -own. -
- -
-Update the web site by copying the docs/ directory's files to
-/home/users/b/br/brianp/mesa-www/htdocs/ with:
-
-
-sftp USERNAME,mesa3d@web.sourceforge.net
-
-
-Make an announcement on the mailing lists: - -mesa-dev@lists.freedesktop.org, -and -mesa-announce@lists.freedesktop.org - -Follow the template of previously-sent release announcements. The following -command can be used to generate the log of changes to be included in the -release announcement: - -
- git shortlog mesa-X.Y.Z-1..mesa-X.Y.Z -- - -
To add a new GL extension to Mesa you have to do at least the following. +
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
@@ -677,16 +41,18 @@ To add a new GL extension to Mesa you have to do at least the following.
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.
gl_extensions struct in mtypes.h
+ Add a new entry to the gl_extensions struct in
+ mtypes.h if the extension requires driver capabilities not
+ already exposed by another extension.
extensions.c file.
+ Add a new entry to the src/mesa/main/extensions_table.h file.
get.c, enable.c and attrib.c
+ will most likely require new code.
+_mesa_has_##name_str() function
+ defined in src/mesa/main/extensions.h.
check_table.cpp and
+ dispatch_sanity.cpp should be updated with details about
+ the new extensions functions. These tests are run using
+ meson test.