From d06914a1bd2e4523e1a3ce21d163b57f46d0c7fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sat, 19 Oct 2019 00:59:52 +0200 Subject: [PATCH] doc: hint that Optional is a safer NoCreate. --- doc/opengl-wrapping.dox | 9 +++++++++ src/Magnum/GL/AbstractShaderProgram.h | 2 ++ src/Magnum/GL/Buffer.h | 2 ++ src/Magnum/GL/BufferImage.h | 7 +++++++ src/Magnum/GL/BufferTexture.h | 2 ++ src/Magnum/GL/CubeMapTexture.h | 2 ++ src/Magnum/GL/CubeMapTextureArray.h | 2 ++ src/Magnum/GL/Framebuffer.h | 2 ++ src/Magnum/GL/Mesh.h | 2 ++ src/Magnum/GL/MultisampleTexture.h | 2 ++ src/Magnum/GL/PrimitiveQuery.h | 2 ++ src/Magnum/GL/RectangleTexture.h | 2 ++ src/Magnum/GL/Renderbuffer.h | 2 ++ src/Magnum/GL/SampleQuery.h | 2 ++ src/Magnum/GL/Texture.h | 2 ++ src/Magnum/GL/TextureArray.h | 2 ++ src/Magnum/GL/TimeQuery.h | 2 ++ src/Magnum/GL/TransformFeedback.h | 2 ++ src/Magnum/Shaders/DistanceFieldVector.h | 2 ++ src/Magnum/Shaders/Flat.h | 2 ++ src/Magnum/Shaders/MeshVisualizer.h | 2 ++ src/Magnum/Shaders/Phong.h | 2 ++ src/Magnum/Shaders/Vector.h | 2 ++ src/Magnum/Shaders/VertexColor.h | 2 ++ src/Magnum/Tags.h | 6 +++++- 25 files changed, 65 insertions(+), 1 deletion(-) diff --git a/doc/opengl-wrapping.dox b/doc/opengl-wrapping.dox index 7ae7a8076..8b0812637 100644 --- a/doc/opengl-wrapping.dox +++ b/doc/opengl-wrapping.dox @@ -60,6 +60,15 @@ you know you would overwrite it later with another object: @snippet MagnumGL.cpp opengl-wrapping-nocreate + + +@m_class{m-note m-warning} + +@par + Note that calling anything on objects created this way is not defined (and + not checked or guarded in any way) and may result in crashes. If you want delayed object creation with safety checks (however with some extra + memory overhead), wrap the objects in an @ref Corrade::Containers::Optional. + If you need to preserve the underlying OpenGL object after destruction, you can call @cpp release() @ce. It returns ID of the underlying object, the instance is then equivalent to moved-from state and you are responsible for proper diff --git a/src/Magnum/GL/AbstractShaderProgram.h b/src/Magnum/GL/AbstractShaderProgram.h index 9f7289052..2218d5667 100644 --- a/src/Magnum/GL/AbstractShaderProgram.h +++ b/src/Magnum/GL/AbstractShaderProgram.h @@ -650,6 +650,8 @@ class MAGNUM_GL_EXPORT AbstractShaderProgram: public AbstractObject { * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. * @see @ref AbstractShaderProgram() */ explicit AbstractShaderProgram(NoCreateT) noexcept; diff --git a/src/Magnum/GL/Buffer.h b/src/Magnum/GL/Buffer.h index 2c9ae547b..d9b7610e2 100644 --- a/src/Magnum/GL/Buffer.h +++ b/src/Magnum/GL/Buffer.h @@ -778,6 +778,8 @@ class MAGNUM_GL_EXPORT Buffer: public AbstractObject { * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. * @see @ref Buffer(TargetHint), @ref wrap() */ explicit Buffer(NoCreateT) noexcept; diff --git a/src/Magnum/GL/BufferImage.h b/src/Magnum/GL/BufferImage.h index 615ad66ee..c1d01af57 100644 --- a/src/Magnum/GL/BufferImage.h +++ b/src/Magnum/GL/BufferImage.h @@ -245,6 +245,8 @@ template class BufferImage { * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. * @see @ref BufferImage(), @ref Buffer::wrap() */ explicit BufferImage(NoCreateT) noexcept; @@ -561,6 +563,11 @@ template class CompressedBufferImage { * The constructed instance is equivalent to moved-from state. Useful * in cases where you will overwrite the instance later anyway. Move * another object over it to make it useful. + * + * This function can be safely used for constructing (and later + * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. * @see @ref CompressedBufferImage(), @ref Buffer::wrap() */ explicit CompressedBufferImage(NoCreateT) noexcept; diff --git a/src/Magnum/GL/BufferTexture.h b/src/Magnum/GL/BufferTexture.h index 793e56b42..b7187e15b 100644 --- a/src/Magnum/GL/BufferTexture.h +++ b/src/Magnum/GL/BufferTexture.h @@ -140,6 +140,8 @@ class MAGNUM_GL_EXPORT BufferTexture: public AbstractTexture { * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. * @see @ref BufferTexture(), @ref wrap() */ explicit BufferTexture(NoCreateT) noexcept: AbstractTexture{NoCreate, GL_TEXTURE_BUFFER} {} diff --git a/src/Magnum/GL/CubeMapTexture.h b/src/Magnum/GL/CubeMapTexture.h index a596374ed..a6e6268e1 100644 --- a/src/Magnum/GL/CubeMapTexture.h +++ b/src/Magnum/GL/CubeMapTexture.h @@ -164,6 +164,8 @@ class MAGNUM_GL_EXPORT CubeMapTexture: public AbstractTexture { * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. * @see @ref CubeMapTexture(), @ref wrap() */ explicit CubeMapTexture(NoCreateT) noexcept: AbstractTexture{NoCreate, GL_TEXTURE_CUBE_MAP} {} diff --git a/src/Magnum/GL/CubeMapTextureArray.h b/src/Magnum/GL/CubeMapTextureArray.h index 62fbb367f..91d51a592 100644 --- a/src/Magnum/GL/CubeMapTextureArray.h +++ b/src/Magnum/GL/CubeMapTextureArray.h @@ -151,6 +151,8 @@ class MAGNUM_GL_EXPORT CubeMapTextureArray: public AbstractTexture { * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. * @see @ref CubeMapTextureArray(), @ref wrap() */ explicit CubeMapTextureArray(NoCreateT) noexcept: AbstractTexture{NoCreate, GL_TEXTURE_CUBE_MAP_ARRAY} {} diff --git a/src/Magnum/GL/Framebuffer.h b/src/Magnum/GL/Framebuffer.h index 526e12cb2..26b3ee2f8 100644 --- a/src/Magnum/GL/Framebuffer.h +++ b/src/Magnum/GL/Framebuffer.h @@ -379,6 +379,8 @@ class MAGNUM_GL_EXPORT Framebuffer: public AbstractFramebuffer, public AbstractO * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. * @see @ref Framebuffer(const Range2Di&), @ref wrap() */ explicit Framebuffer(NoCreateT) noexcept: AbstractFramebuffer{{}, {}, {}} {} diff --git a/src/Magnum/GL/Mesh.h b/src/Magnum/GL/Mesh.h index db0382491..966849b95 100644 --- a/src/Magnum/GL/Mesh.h +++ b/src/Magnum/GL/Mesh.h @@ -396,6 +396,8 @@ class MAGNUM_GL_EXPORT Mesh: public AbstractObject { * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. * @see @ref Mesh(MeshPrimitive), @ref wrap() */ explicit Mesh(NoCreateT) noexcept; diff --git a/src/Magnum/GL/MultisampleTexture.h b/src/Magnum/GL/MultisampleTexture.h index d754948d3..c972d382f 100644 --- a/src/Magnum/GL/MultisampleTexture.h +++ b/src/Magnum/GL/MultisampleTexture.h @@ -159,6 +159,8 @@ template class MultisampleTexture: public AbstractTextur * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. * @see @ref MultisampleTexture(), @ref wrap() */ explicit MultisampleTexture(NoCreateT) noexcept: AbstractTexture{NoCreate, Implementation::multisampleTextureTarget()} {} diff --git a/src/Magnum/GL/PrimitiveQuery.h b/src/Magnum/GL/PrimitiveQuery.h index d6515bc97..85cd79368 100644 --- a/src/Magnum/GL/PrimitiveQuery.h +++ b/src/Magnum/GL/PrimitiveQuery.h @@ -147,6 +147,8 @@ class MAGNUM_GL_EXPORT PrimitiveQuery: public AbstractQuery { * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. * @see @ref PrimitiveQuery(Target), @ref wrap() */ explicit PrimitiveQuery(NoCreateT) noexcept: AbstractQuery{NoCreate, GLenum(Target::TransformFeedbackPrimitivesWritten)} {} diff --git a/src/Magnum/GL/RectangleTexture.h b/src/Magnum/GL/RectangleTexture.h index 2fa210155..19d395664 100644 --- a/src/Magnum/GL/RectangleTexture.h +++ b/src/Magnum/GL/RectangleTexture.h @@ -133,6 +133,8 @@ class MAGNUM_GL_EXPORT RectangleTexture: public AbstractTexture { * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. * @see @ref RectangleTexture(), @ref wrap() */ explicit RectangleTexture(NoCreateT) noexcept: AbstractTexture{NoCreate, GL_TEXTURE_RECTANGLE} {} diff --git a/src/Magnum/GL/Renderbuffer.h b/src/Magnum/GL/Renderbuffer.h index 600478956..58fc3b0f4 100644 --- a/src/Magnum/GL/Renderbuffer.h +++ b/src/Magnum/GL/Renderbuffer.h @@ -126,6 +126,8 @@ class MAGNUM_GL_EXPORT Renderbuffer: public AbstractObject { * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. * @see @ref Renderbuffer(), @ref wrap() */ explicit Renderbuffer(NoCreateT) noexcept: _id{0}, _flags{ObjectFlag::DeleteOnDestruction} {} diff --git a/src/Magnum/GL/SampleQuery.h b/src/Magnum/GL/SampleQuery.h index bd0d2b4d8..412b99bb4 100644 --- a/src/Magnum/GL/SampleQuery.h +++ b/src/Magnum/GL/SampleQuery.h @@ -204,6 +204,8 @@ class SampleQuery: public AbstractQuery { * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. * @see @ref SampleQuery(Target), @ref wrap() */ explicit SampleQuery(NoCreateT) noexcept: AbstractQuery{NoCreate, GLenum(Target::AnySamplesPassed)} {} diff --git a/src/Magnum/GL/Texture.h b/src/Magnum/GL/Texture.h index a0ab5ac13..bde332a98 100644 --- a/src/Magnum/GL/Texture.h +++ b/src/Magnum/GL/Texture.h @@ -185,6 +185,8 @@ template class Texture: public AbstractTexture { * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. * @see @ref Texture(), @ref wrap() */ explicit Texture(NoCreateT) noexcept: AbstractTexture{NoCreate, Implementation::textureTarget()} {} diff --git a/src/Magnum/GL/TextureArray.h b/src/Magnum/GL/TextureArray.h index 9e895261b..029955c71 100644 --- a/src/Magnum/GL/TextureArray.h +++ b/src/Magnum/GL/TextureArray.h @@ -169,6 +169,8 @@ template class TextureArray: public AbstractTexture { * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. * @see @ref TextureArray(), @ref wrap() */ explicit TextureArray(NoCreateT) noexcept: AbstractTexture{NoCreate, Implementation::textureArrayTarget()} {} diff --git a/src/Magnum/GL/TimeQuery.h b/src/Magnum/GL/TimeQuery.h index 483cea675..ae868f836 100644 --- a/src/Magnum/GL/TimeQuery.h +++ b/src/Magnum/GL/TimeQuery.h @@ -123,6 +123,8 @@ class TimeQuery: public AbstractQuery { * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. * @see @ref TimeQuery(Target), @ref wrap() */ explicit TimeQuery(NoCreateT) noexcept: AbstractQuery{NoCreate, GLenum(Target::TimeElapsed)} {} diff --git a/src/Magnum/GL/TransformFeedback.h b/src/Magnum/GL/TransformFeedback.h index 14a641e27..ab07f6d14 100644 --- a/src/Magnum/GL/TransformFeedback.h +++ b/src/Magnum/GL/TransformFeedback.h @@ -200,6 +200,8 @@ class MAGNUM_GL_EXPORT TransformFeedback: public AbstractObject { * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. * @see @ref TransformFeedback(), @ref wrap() */ explicit TransformFeedback(NoCreateT) noexcept: _id{0}, _flags{ObjectFlag::DeleteOnDestruction} {} diff --git a/src/Magnum/Shaders/DistanceFieldVector.h b/src/Magnum/Shaders/DistanceFieldVector.h index 175ae9357..aef619637 100644 --- a/src/Magnum/Shaders/DistanceFieldVector.h +++ b/src/Magnum/Shaders/DistanceFieldVector.h @@ -78,6 +78,8 @@ template class MAGNUM_SHADERS_EXPORT DistanceFieldVector * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. */ explicit DistanceFieldVector(NoCreateT) noexcept /** @todoc remove workaround when doxygen is sane */ diff --git a/src/Magnum/Shaders/Flat.h b/src/Magnum/Shaders/Flat.h index bf5278f2f..ac7101da1 100644 --- a/src/Magnum/Shaders/Flat.h +++ b/src/Magnum/Shaders/Flat.h @@ -251,6 +251,8 @@ template class MAGNUM_SHADERS_EXPORT Flat: public GL::Ab * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. */ explicit Flat(NoCreateT) noexcept: GL::AbstractShaderProgram{NoCreate} {} diff --git a/src/Magnum/Shaders/MeshVisualizer.h b/src/Magnum/Shaders/MeshVisualizer.h index 42d96f842..5af656268 100644 --- a/src/Magnum/Shaders/MeshVisualizer.h +++ b/src/Magnum/Shaders/MeshVisualizer.h @@ -179,6 +179,8 @@ class MAGNUM_SHADERS_EXPORT MeshVisualizer: public GL::AbstractShaderProgram { * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. */ explicit MeshVisualizer(NoCreateT) noexcept: GL::AbstractShaderProgram{NoCreate} {} diff --git a/src/Magnum/Shaders/Phong.h b/src/Magnum/Shaders/Phong.h index 242b79ae1..517ade0af 100644 --- a/src/Magnum/Shaders/Phong.h +++ b/src/Magnum/Shaders/Phong.h @@ -279,6 +279,8 @@ class MAGNUM_SHADERS_EXPORT Phong: public GL::AbstractShaderProgram { * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. */ explicit Phong(NoCreateT) noexcept: GL::AbstractShaderProgram{NoCreate} {} diff --git a/src/Magnum/Shaders/Vector.h b/src/Magnum/Shaders/Vector.h index 714259d7d..cd63656f1 100644 --- a/src/Magnum/Shaders/Vector.h +++ b/src/Magnum/Shaders/Vector.h @@ -74,6 +74,8 @@ template class MAGNUM_SHADERS_EXPORT Vector: public Abst * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. */ explicit Vector(NoCreateT) noexcept /** @todoc remove workaround when doxygen is sane */ diff --git a/src/Magnum/Shaders/VertexColor.h b/src/Magnum/Shaders/VertexColor.h index 7834b7985..c43340cf8 100644 --- a/src/Magnum/Shaders/VertexColor.h +++ b/src/Magnum/Shaders/VertexColor.h @@ -119,6 +119,8 @@ template class MAGNUM_SHADERS_EXPORT VertexColor: public * * This function can be safely used for constructing (and later * destructing) objects even without any OpenGL context being active. + * However note that this is a low-level and a potentially dangerous + * API, see the documentation of @ref NoCreate for alternatives. */ explicit VertexColor(NoCreateT) noexcept: AbstractShaderProgram{NoCreate} {} diff --git a/src/Magnum/Tags.h b/src/Magnum/Tags.h index 29170eb33..6954d28b5 100644 --- a/src/Magnum/Tags.h +++ b/src/Magnum/Tags.h @@ -51,7 +51,11 @@ struct NoCreateT { /** @brief No creation tag -Use for construction without creating the underlying OpenGL object. +Use for construction without creating the underlying OpenGL object. Note that +calling anything on objects created this way is not defined (and not checked or +guarded in any way) and may result in crashes. If you want delayed object +creation with safety checks (however with some extra memory overhead), wrap +the objects in an @ref Corrade::Containers::Optional. */ constexpr NoCreateT NoCreate{NoCreateT::Init{}};