From 0446c2919c71323bcdda509a4274785aa6d78c22 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Wed, 22 Feb 2023 18:12:40 +0100 Subject: [PATCH] doc: refresh Developers Guide re GL feature additions. Amazing how much I can forget after a while. Better write that all down. --- doc/developers.dox | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-) diff --git a/doc/developers.dox b/doc/developers.dox index d75fd5ad1..d60cab1e2 100644 --- a/doc/developers.dox +++ b/doc/developers.dox @@ -678,11 +678,19 @@ unless it doesn't affect public API at all. @section developers-gl-functionality Checklist for adding / removing GL functionality -1. Check if given desktop functionality has equivalent in ES or WebGL, add - missing extensions if needed (see @ref developers-gl-extensions) +1. Check if given desktop functionality has equivalent in ES or WebGL: + - check for similarly named APIs in `MagnumExternal/OpenGL/GLES2/flextGL.h` + and others + - if not there or if there only in a core version and not an extension, + the extension may not be included --- check the cached `spec/gl.xml` + file inside the flextGL clone + - for WebGL it might also be ANGLE-only, look for it in + https://chromium.googlesource.com/angle/angle/+/refs/heads/main/extensions + - add missing extensions as described in @ref developers-gl-extensions 2. Check if there's a DSA / non-DSA way to do the thing. Omit the non-DSA way - if all drivers that support given functionality support DSA as well and - there's no corresponding non-DSA functionality in ES or WebGL. + if all drivers that support given functionality support DSA as well (i.e., + the functionality was not introduced before DSA became core) and there's no + corresponding non-DSA functionality in ES or WebGL. 3. If the functionality uses different entry points / defines on desktop and ES / WebGL platforms, use @cpp #ifdef MAGNUM_TARGET_GLES @ce, @cpp #ifdef MAGNUM_TARGET_GLES2 @ce and @cpp #ifdef MAGNUM_TARGET_WEBGL @ce @@ -692,6 +700,9 @@ unless it doesn't affect public API at all. separate code paths: - new private and `MAGNUM_LOCAL` `thingImplementation*()` functions, each implementing one code path, preferably @cpp static @ce + - ideally make the signature in a way that makes it possible to just + call the GL API directly via a function pointer and have + `thingImplementation*()` only for fallbackse - a `thingImplementation` (member) function pointer in `src/Magnum/Implementation/SomeState.h` that gets populated in `src/Magnum/GL/Implementation/SomeState.cpp` based on extension / version availability @@ -715,17 +726,19 @@ unless it doesn't affect public API at all. etc., use @c \@fn_gl_keyword{} etc. to expose them in search if desired (see @ref coding-style-documentation-commands-ref) - list version / extension requirements using @c \@requires_glXY etc. - (see @ref coding-style-documentation-commands-requires) + (see @ref coding-style-documentation-commands-requires), check how + similar requirements are listed elsewhere and try to match that 8. Add the function or limit query to the mapping table in `doc/opengl-mapping.dox`, possibly to multiple places 9. Update relevant extension support in tables in `doc/opengl-support.dox` 10. Mention the new stuff in `doc/changelog.dox` 11. @ref building-doc "Build documentation": - - run [doxygen.py](http://mcss.mosra.cz/doxygen/) on `Doxyfile-mcss` - and verify there are no new warnings + - run [doxygen.py](https://mcss.mosra.cz/documentation/doxygen/) on + `Doxyfile-mcss` and verify there are no new warnings - eyeball the relevant docs and fix suspicious things + - make sure links to GL APIs and extensions are working 12. Build and test for relevant platforms locally (as the public CI can't test - GL things yet) + GL things in full, only the ES subset) 13. Push to a temporary branch (e.g., `next`) 14. Iterate until the CIs are green 15. Merge to `master`