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
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`

Loading…
Cancel
Save