doc: hint that Optional is a safer NoCreate.

doc/opengl-wrapping.dox

@@ -60,6 +60,15 @@ you know you would overwrite it later with another object:
 
 @snippet MagnumGL.cpp opengl-wrapping-nocreate
 
+<b></b>
+
+@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

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;

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;

src/Magnum/GL/BufferImage.h

@@ -245,6 +245,8 @@ template<UnsignedInt dimensions> 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<UnsignedInt dimensions> 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;

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} {}

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} {}

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} {}

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{{}, {}, {}} {}

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;

src/Magnum/GL/MultisampleTexture.h

@@ -159,6 +159,8 @@ template<UnsignedInt dimensions> 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<dimensions>()} {}

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)} {}

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} {}

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} {}

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)} {}

src/Magnum/GL/Texture.h

@@ -185,6 +185,8 @@ template<UnsignedInt dimensions> 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<dimensions>()} {}

src/Magnum/GL/TextureArray.h

@@ -169,6 +169,8 @@ template<UnsignedInt dimensions> 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<dimensions>()} {}

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)} {}

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} {}

src/Magnum/Shaders/DistanceFieldVector.h

@@ -78,6 +78,8 @@ template<UnsignedInt dimensions> 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 */

src/Magnum/Shaders/Flat.h

@@ -251,6 +251,8 @@ template<UnsignedInt dimensions> 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} {}
 

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} {}
 

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} {}
 

src/Magnum/Shaders/Vector.h

@@ -74,6 +74,8 @@ template<UnsignedInt dimensions> 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 */

src/Magnum/Shaders/VertexColor.h

@@ -119,6 +119,8 @@ template<UnsignedInt dimensions> 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} {}
 

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{}};