Browse Source

doc: refresh Developers Guide re GL feature additions.

Amazing how much I can forget after a while. Better write that all down.
pull/601/head
Vladimír Vondruš 3 years ago
parent
commit
0446c2919c
  1. 29
      doc/developers.dox

29
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 @section developers-gl-functionality Checklist for adding / removing GL functionality
1. Check if given desktop functionality has equivalent in ES or WebGL, add 1. Check if given desktop functionality has equivalent in ES or WebGL:
missing extensions if needed (see @ref developers-gl-extensions) - 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 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 if all drivers that support given functionality support DSA as well (i.e.,
there's no corresponding non-DSA functionality in ES or WebGL. 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 3. If the functionality uses different entry points / defines on desktop and
ES / WebGL platforms, use @cpp #ifdef MAGNUM_TARGET_GLES @ce, ES / WebGL platforms, use @cpp #ifdef MAGNUM_TARGET_GLES @ce,
@cpp #ifdef MAGNUM_TARGET_GLES2 @ce and @cpp #ifdef MAGNUM_TARGET_WEBGL @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: separate code paths:
- new private and `MAGNUM_LOCAL` `thingImplementation*()` functions, each - new private and `MAGNUM_LOCAL` `thingImplementation*()` functions, each
implementing one code path, preferably @cpp static @ce 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` - a `thingImplementation` (member) function pointer in `src/Magnum/Implementation/SomeState.h`
that gets populated in `src/Magnum/GL/Implementation/SomeState.cpp` that gets populated in `src/Magnum/GL/Implementation/SomeState.cpp`
based on extension / version availability 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 etc., use @c \@fn_gl_keyword{} etc. to expose them in search if
desired (see @ref coding-style-documentation-commands-ref) desired (see @ref coding-style-documentation-commands-ref)
- list version / extension requirements using @c \@requires_glXY etc. - 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`, 8. Add the function or limit query to the mapping table in `doc/opengl-mapping.dox`,
possibly to multiple places possibly to multiple places
9. Update relevant extension support in tables in `doc/opengl-support.dox` 9. Update relevant extension support in tables in `doc/opengl-support.dox`
10. Mention the new stuff in `doc/changelog.dox` 10. Mention the new stuff in `doc/changelog.dox`
11. @ref building-doc "Build documentation": 11. @ref building-doc "Build documentation":
- run [doxygen.py](http://mcss.mosra.cz/doxygen/) on `Doxyfile-mcss` - run [doxygen.py](https://mcss.mosra.cz/documentation/doxygen/) on
and verify there are no new warnings `Doxyfile-mcss` and verify there are no new warnings
- eyeball the relevant docs and fix suspicious things - 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 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`) 13. Push to a temporary branch (e.g., `next`)
14. Iterate until the CIs are green 14. Iterate until the CIs are green
15. Merge to `master` 15. Merge to `master`

Loading…
Cancel
Save