From 2100c5a11aaf6fdb1c65079dfc5e1f89f408bb44 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Tue, 19 Oct 2021 20:29:30 +0200 Subject: [PATCH] GL: further clarify caveats with temporary allocations for multidraw. --- src/Magnum/GL/AbstractShaderProgram.h | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/src/Magnum/GL/AbstractShaderProgram.h b/src/Magnum/GL/AbstractShaderProgram.h index f73a60ffc..2413ed922 100644 --- a/src/Magnum/GL/AbstractShaderProgram.h +++ b/src/Magnum/GL/AbstractShaderProgram.h @@ -866,13 +866,26 @@ class MAGNUM_GL_EXPORT AbstractShaderProgram: public AbstractObject { * * If @p counts, @p vertexOffsets and @p indexOffsets are contiguous * views, they get passed directly to the underlying GL functions, - * otherwise a temporary contiguous copy is allocated. On - * @ref CORRADE_TARGET_32BIT "64-bit builds" the @p indexOffsets - * additionally have to be 64-bit in order to avoid a copy because the - * @fn_gl{MultiDrawElements} / - * @fn_gl_keyword{MultiDrawElementsBaseVertex} functions accept them as - * pointers, see the @ref draw(Mesh&, const Containers::StridedArrayView1D&, const Containers::StridedArrayView1D&, const Containers::StridedArrayView1D&) - * overload below. + * otherwise a temporary contiguous copy is allocated. There are the + * folllowing special cases, however: + * + * - On @ref CORRADE_TARGET_32BIT "64-bit builds" the + * @p indexOffsets additionally have to be 64-bit in order to + * avoid a copy because the @fn_gl{MultiDrawElements} / + * @fn_gl_keyword{MultiDrawElementsBaseVertex} functions accept + * them as pointers, see the @ref draw(Mesh&, const Containers::StridedArrayView1D&, const Containers::StridedArrayView1D&, const Containers::StridedArrayView1D&) + * overload below. + * - If the @p mesh is indexed, @p vertexOffsets are not empty and + * the platform is WebGL or OpenGL ES with + * @gl_extension{OES,draw_elements_base_vertex} / + * @gl_extension{EXT,draw_elements_base_vertex} supported but + * @gl_extension{EXT,multi_draw_arrays} not, the function has to + * delegate to @ref draw(Mesh&, const Containers::StridedArrayView1D&, const Containers::StridedArrayView1D&, const Containers::StridedArrayView1D&, const Containers::StridedArrayView1D&, const Containers::StridedArrayView1D&) + * and allocate trivial instance counts and offsets. To avoid this + * extra allocation, use the overload directly if the + * @m_class{m-doc-external} [ANGLE_base_vertex_base_instance](https://chromium.googlesource.com/angle/angle/+/refs/heads/main/extensions/ANGLE_base_vertex_base_instance.txt) + * OpenGL ES or @webgl_extension{WEBGL,multi_draw_instanced_base_vertex_base_instance} + * WebGL extension is supported. * * @see @ref draw(MeshView&), @fn_gl{UseProgram}, * @fn_gl_keyword{EnableVertexAttribArray}, @fn_gl{BindBuffer},