Primitives: clarify how primitives look.

src/Magnum/Primitives/Axis.h

@@ -37,10 +37,11 @@ namespace Magnum { namespace Primitives {
 /**
 @brief 2D axis
 
-Two color-coded arrows for visualizing orientation (XY is RG).
+Two color-coded arrows for visualizing orientation (XY is RG), going from
-@ref MeshPrimitive::Lines with @ref MeshIndexType::UnsignedShort indices,
+@cpp 0.0f @ce to @cpp 1.0f @ce on the X and Y axis. @ref MeshPrimitive::Lines
-interleaved @ref VertexFormat::Vector2 positions and @ref VertexFormat::Vector3
+with @ref MeshIndexType::UnsignedShort indices, interleaved
-colors. The returned instance references data stored in constant memory.
+@ref VertexFormat::Vector2 positions and @ref VertexFormat::Vector3 colors. The
+returned instance references data stored in constant memory.
 
 @image html primitives-axis2d.png width=256px
 
@@ -51,7 +52,8 @@ MAGNUM_PRIMITIVES_EXPORT Trade::MeshData axis2D();
 /**
 @brief 3D axis
 
-Three color-coded arrows for visualizing orientation (XYZ is RGB).
+Three color-coded arrows for visualizing orientation (XYZ is RGB), going from
+@cpp 0.0f @ce to @cpp 1.0f @ce on the X, Y and Z axis.
 @ref MeshPrimitive::Lines with @ref MeshIndexType::UnsignedShort indices,
 interleaved @ref VertexFormat::Vector3 positions and @ref VertexFormat::Vector3
 colors. The returned instance references data stored in constant memory.

src/Magnum/Primitives/Capsule.h

@@ -45,9 +45,10 @@ namespace Magnum { namespace Primitives {
     equal to @cpp 1 @ce.
 @param halfLength    Half the length of cylinder part
 
-Cylinder of radius @cpp 1.0f @ce along Y axis with hemispheres instead of caps.
+Cylinder of radius @cpp 1.0f @ce along the Y axis, centered at origin, with
-@ref MeshPrimitive::Lines with @ref MeshIndexType::UnsignedInt indices and
+hemispheres instead of caps. @ref MeshPrimitive::Lines with
-@ref VertexFormat::Vector2 positions.
+@ref MeshIndexType::UnsignedInt indices and @ref VertexFormat::Vector2
+positions.
 
 @image html primitives-capsule2dwireframe.png width=256px
 
@@ -96,12 +97,13 @@ CORRADE_ENUMSET_OPERATORS(CapsuleFlags)
 @param flags            Flags
 @m_since_latest
 
-Cylinder of radius @cpp 1.0f @ce along Y axis with hemispheres instead of caps.
+Cylinder of radius @cpp 1.0f @ce along the Y axis, centered at origin, with
-@ref MeshPrimitive::Triangles with @ref MeshIndexType::UnsignedInt indices,
+hemispheres instead of caps. @ref MeshPrimitive::Triangles with
-interleaved @ref VertexFormat::Vector3 positions, @ref VertexFormat::Vector3
+@ref MeshIndexType::UnsignedInt indices, interleaved @ref VertexFormat::Vector3
-normals, optional @ref VertexFormat::Vector4 tangents and optional
+positions, @ref VertexFormat::Vector3 normals, optional
-@ref VertexFormat::Vector2 texture coordinates. If texture coordinates are
+@ref VertexFormat::Vector4 tangents and optional @ref VertexFormat::Vector2
-generated, vertices of one segment are duplicated for texture wrapping.
+texture coordinates. If texture coordinates are generated, vertices of one
+segment are duplicated for texture wrapping.
 
 @image html primitives-capsule3dsolid.png width=256px
 
@@ -143,9 +145,10 @@ CORRADE_IGNORE_DEPRECATED_POP
     @cpp 4 @ce and multiple of @cpp 4 @ce.
 @param halfLength       Half the length of cylinder part
 
-Cylinder of radius @cpp 1.0f @ce along Y axis with hemispheres instead of caps.
+Cylinder of radius @cpp 1.0f @ce along the Y axis, centered at origin, with
-@ref MeshPrimitive::Lines with @ref MeshIndexType::UnsignedInt indices and
+hemispheres instead of caps. @ref MeshPrimitive::Lines with
-@ref VertexFormat::Vector3 positions.
+@ref MeshIndexType::UnsignedInt indices and @ref VertexFormat::Vector3
+positions.
 
 @image html primitives-capsule3dwireframe.png width=256px
 

src/Magnum/Primitives/Circle.h

@@ -75,9 +75,10 @@ enum class CORRADE_DEPRECATED_ENUM("use Circle2DFlags or Circle3DFlags instead")
 @param flags        Flags
 @m_since_latest
 
-Circle with radius @cpp 1.0f @ce. @ref MeshPrimitive::TriangleFan with
+Circle with radius @cpp 1.0f @ce, centered at origin.
-@ref MeshIndexType::UnsignedInt indices, interleaved @ref VertexFormat::Vector2
+@ref MeshPrimitive::TriangleFan with @ref MeshIndexType::UnsignedInt indices,
-positions and optional @ref VertexFormat::Vector2 texture coordinates.
+interleaved @ref VertexFormat::Vector2 positions and optional
+@ref VertexFormat::Vector2 texture coordinates.
 
 @image html primitives-circle2dsolid.png width=256px
 
@@ -102,8 +103,8 @@ CORRADE_IGNORE_DEPRECATED_POP
 @param segments         Number of segments. Must be greater or equal to
     @cpp 3 @ce.
 
-Circle with radius @cpp 1.0f @ce. Non-indexed @ref MeshPrimitive::LineLoop with
+Circle with radius @cpp 1.0f @ce, centered at origin. Non-indexed
-@ref VertexFormat::Vector2 positions.
+@ref MeshPrimitive::LineLoop with @ref VertexFormat::Vector2 positions.
 
 @image html primitives-circle2dwireframe.png width=256px
 
@@ -146,11 +147,11 @@ CORRADE_ENUMSET_OPERATORS(Circle3DFlags)
 @param flags        Flags
 @m_since_latest
 
-Circle on the XY plane with radius @cpp 1.0f @ce. Non-indexed
+Circle on the XY plane with radius @cpp 1.0f @ce, centered at origin.
-@ref MeshPrimitive::TriangleFan with interleaved @ref VertexFormat::Vector3
+Non-indexed @ref MeshPrimitive::TriangleFan with interleaved
-positions, @ref VertexFormat::Vector3 normals in positive Z direction, optional
+@ref VertexFormat::Vector3 positions, @ref VertexFormat::Vector3 normals in
-@ref VertexFormat::Vector4 tangents and optional @ref VertexFormat::Vector2
+positive Z direction, optional @ref VertexFormat::Vector4 tangents and optional
-texture coordinates.
+@ref VertexFormat::Vector2 texture coordinates.
 
 @image html primitives-circle3dsolid.png width=256px
 
@@ -174,7 +175,9 @@ CORRADE_IGNORE_DEPRECATED_POP
 @brief Wireframe 3D circle
 @param segments  Number of segments. Must be greater or equal to @cpp 3 @ce.
 
-Circle on the XY plane with radius @cpp 1.0f @ce. Non-indexed @ref MeshPrimitive::LineLoop with @ref VertexFormat::Vector2 positions.
+Circle on the XY plane with radius @cpp 1.0f @ce, centered at origin.
+Non-indexed @ref MeshPrimitive::LineLoop with @ref VertexFormat::Vector2
+positions.
 
 @image html primitives-circle3dwireframe.png width=256px
 

src/Magnum/Primitives/Cone.h

@@ -88,13 +88,13 @@ CORRADE_ENUMSET_OPERATORS(ConeFlags)
 @param halfLength   Half the cone length
 @param flags        Flags
 
-Cone along Y axis of radius @cpp 1.0f @ce. @ref MeshPrimitive::Triangles with
+Cone of radius @cpp 1.0f @ce along the Y axis, centered at origin.
-@ref MeshIndexType::UnsignedInt indices, interleaved @ref VertexFormat::Vector3
+@ref MeshPrimitive::Triangles with @ref MeshIndexType::UnsignedInt indices,
-positions, @ref VertexFormat::Vector3 normals, optional
+interleaved @ref VertexFormat::Vector3 positions, @ref VertexFormat::Vector3
-@ref VertexFormat::Vector4 tangents and optional @ref VertexFormat::Vector2
+normals, optional @ref VertexFormat::Vector4 tangents and optional
-texture coordinates. Note that in order to have properly smooth normals over
+@ref VertexFormat::Vector2 texture coordinates. Note that in order to have
-the whole area, the tip consists of @cpp segments*2 @ce vertices instead of
+properly smooth normals over the whole area, the tip consists of
-just one.
+@cpp segments*2 @ce vertices instead of just one.
 
 @image html primitives-conesolid.png width=256px
 
@@ -112,9 +112,9 @@ MAGNUM_PRIMITIVES_EXPORT Trade::MeshData coneSolid(UnsignedInt rings, UnsignedIn
     @cpp 4 @ce and multiple of @cpp 4 @ce.
 @param halfLength   Half the cone length
 
-Cone along Y axis of radius @cpp 1.0f @ce. @ref MeshPrimitive::Lines with
+Cone of radius @cpp 1.0f @ce along the Y axis, centered at origin.
-@ref MeshIndexType::UnsignedInt indices and @ref VertexFormat::Vector3
+@ref MeshPrimitive::Lines with @ref MeshIndexType::UnsignedInt indices and
-positions.
+@ref VertexFormat::Vector3 positions.
 
 @image html primitives-conewireframe.png width=256px
 

src/Magnum/Primitives/Crosshair.h

@@ -37,9 +37,9 @@ namespace Magnum { namespace Primitives {
 /**
 @brief 2D crosshair
 
-2x2 crosshair (two crossed lines). Non-indexed @ref MeshPrimitive::Lines with
+2x2 crosshair (two crossed lines), centered at origin. Non-indexed
-@ref VertexFormat::Vector2 positions. The returned instance references data
+@ref MeshPrimitive::Lines with @ref VertexFormat::Vector2 positions. The
-stored in constant memory.
+returned instance references data astored in constant memory.
 
 @image html primitives-crosshair2d.png width=256px
 
@@ -50,9 +50,9 @@ MAGNUM_PRIMITIVES_EXPORT Trade::MeshData crosshair2D();
 /**
 @brief 3D crosshair
 
-2x2x2 crosshair (three crossed lines). Non-indexed @ref MeshPrimitive::Lines
+2x2x2 crosshair (three crossed lines), centered at origin. Non-indexed
-with @ref VertexFormat::Vector3 positions. The returned instance references
+@ref MeshPrimitive::Lines with @ref VertexFormat::Vector3 positions. The
-data stored in constant memory.
+returned instance references data stored in constant memory.
 
 @image html primitives-crosshair3d.png width=256px
 

src/Magnum/Primitives/Cube.h

@@ -37,10 +37,10 @@ namespace Magnum { namespace Primitives {
 /**
 @brief Solid 3D cube
 
-@ref MeshPrimitive::Triangles with @ref MeshIndexType::UnsignedShort indices,
+2x2x2 cube, centered at origin. @ref MeshPrimitive::Triangles with
-interleaved @ref VertexFormat::Vector3 positions and flat
+@ref MeshIndexType::UnsignedShort indices, interleaved
-@ref VertexFormat::Vector3 normals. The returned instance references data
+@ref VertexFormat::Vector3 positions and flat @ref VertexFormat::Vector3
-stored in constant memory.
+normals. The returned instance references data stored in constant memory.
 
 @image html primitives-cubesolid.png width=256px
 
@@ -51,9 +51,10 @@ MAGNUM_PRIMITIVES_EXPORT Trade::MeshData cubeSolid();
 /**
 @brief Solid 3D cube as a single strip
 
-Non-indexed @ref MeshPrimitive::TriangleStrip with @ref VertexFormat::Vector3
+2x2x2 cube, centered at origin. Non-indexed @ref MeshPrimitive::TriangleStrip
-positions. The returned instance references data stored in constant memory. No
+with @ref VertexFormat::Vector3 positions. The returned instance references
-normals or anything else --- use @ref cubeSolid() instead if you need these.
+data stored in constant memory. No normals or anything else --- use
+@ref cubeSolid() instead if you need these.
 
 @image html primitives-cubesolid.png width=256px
 
@@ -64,9 +65,9 @@ MAGNUM_PRIMITIVES_EXPORT Trade::MeshData cubeSolidStrip();
 /**
 @brief Wireframe 3D cube
 
-@ref MeshPrimitive::Lines with @ref MeshIndexType::UnsignedShort indices and
+2x2x2 cube, centered at origin. @ref MeshPrimitive::Lines with
-@ref VertexFormat::Vector3 positions. The returned instance references data
+@ref MeshIndexType::UnsignedShort indices and @ref VertexFormat::Vector3
-stored in constant memory.
+positions. The returned instance references data stored in constant memory.
 
 @image html primitives-cubewireframe.png width=256px
 

src/Magnum/Primitives/Cylinder.h

@@ -87,10 +87,10 @@ CORRADE_ENUMSET_OPERATORS(CylinderFlags)
 @param halfLength   Half the cylinder length
 @param flags        Flags
 
-Cylinder along Y axis of radius @cpp 1.0f @ce. @ref MeshPrimitive::Triangles
+Cylinder of radius @cpp 1.0f @ce along the Y axis, centered at origin.
-with @ref MeshIndexType::UnsignedInt indices, interleaved
+@ref MeshPrimitive::Triangles with @ref MeshIndexType::UnsignedInt indices,
-@ref VertexFormat::Vector3 positions, @ref VertexFormat::Vector3 normals,
+interleaved @ref VertexFormat::Vector3 positions, @ref VertexFormat::Vector3
-optional @ref VertexFormat::Vector4 tangents, optional
+normals, optional @ref VertexFormat::Vector4 tangents, optional
 @ref VertexFormat::Vector2 texture coordinates and optional capped ends. If
 texture coordinates are generated, vertices of one segment are duplicated for
 texture wrapping.
@@ -113,9 +113,9 @@ MAGNUM_PRIMITIVES_EXPORT Trade::MeshData cylinderSolid(UnsignedInt rings, Unsign
     @cpp 4 @ce and multiple of @cpp 4 @ce.
 @param halfLength   Half the cylinder length
 
-Cylinder along Y axis of radius @cpp 1.0f @ce. @ref MeshPrimitive::Lines with
+Cylinder of radius @cpp 1.0f @ce along the Y axis, centerd at origin.
-@ref MeshIndexType::UnsignedInt indices and @ref VertexFormat::Vector3
+@ref MeshPrimitive::Lines with @ref MeshIndexType::UnsignedInt indices and
-positions.
+@ref VertexFormat::Vector3 positions.
 
 @image html primitives-cylinderwireframe.png width=256px
 

src/Magnum/Primitives/Gradient.h

@@ -38,11 +38,11 @@ namespace Magnum { namespace Primitives {
 /**
 @brief 2D square with a gradient
 
-2x2 square with vertex colors. Non-indexed @ref MeshPrimitive::TriangleStrip
+2x2 square with vertex colors, centered at origin. Non-indexed
-with interleaved @ref VertexFormat::Vector2 positions and
+@ref MeshPrimitive::TriangleStrip with interleaved @ref VertexFormat::Vector2
-@ref VertexFormat::Vector4 colors. Vertex colors correspond to the gradient
+positions and @ref VertexFormat::Vector4 colors. Vertex colors correspond to
-defined by the endpoints @p a and @p b, linearly interpolated from @p colorA to
+the gradient defined by the endpoints @p a and @p b, linearly interpolated from
-@p colorB.
+@p colorA to @p colorB.
 
 @image html primitives-gradient2d.png width=256px
 
@@ -80,9 +80,9 @@ MAGNUM_PRIMITIVES_EXPORT Trade::MeshData gradient2DVertical(const Color4& colorB
 /**
 @brief 3D plane with a gradient
 
-2x2 plane with vertex colors. Non-indexed @ref MeshPrimitive::TriangleStrip on
+2x2 square on the XY plane with vertex colors, centered at origin. Non-indexed
-the XY plane with interleaved @ref VertexFormat::Vector3 positions,
+@ref MeshPrimitive::TriangleStrip with interleaved @ref VertexFormat::Vector3
-@ref VertexFormat::Vector3 normals in positive Z direction and
+positions, @ref VertexFormat::Vector3 normals in positive Z direction and
 @ref VertexFormat::Vector4 colors. Vertex colors correspond to the gradient
 defined by the endpoints @p a and @p b, linearly interpolated from @p colorA to
 @p colorB.

src/Magnum/Primitives/Grid.h

@@ -94,9 +94,9 @@ CORRADE_ENUMSET_OPERATORS(GridFlags)
 /**
 @brief Solid 3D grid
 
-2x2 grid in the XY plane with normals in positive Z direction.
+2x2 grid on the XY plane with normals in positive Z direction, centered at
-@ref MeshPrimitive::Triangles with @ref MeshIndexType::UnsignedInt indices,
+origin. @ref MeshPrimitive::Triangles with @ref MeshIndexType::UnsignedInt
-interleaved @ref VertexFormat::Vector3 positions, optional
+indices, interleaved @ref VertexFormat::Vector3 positions, optional
 @ref VertexFormat::Vector3 normals, optional @ref VertexFormat::Vector4
 tangents and optional @ref VertexFormat::Vector2 texture coordinates.
 
@@ -114,7 +114,7 @@ MAGNUM_PRIMITIVES_EXPORT Trade::MeshData grid3DSolid(const Vector2i& subdivision
 /**
 @brief Wireframe 3D grid
 
-2x2 grid in the XY plane. @ref MeshPrimitive::Lines with
+2x2 grid on the XY plane, centered at origin. @ref MeshPrimitive::Lines with
 @ref MeshIndexType::UnsignedInt indices and @ref VertexFormat::Vector3
 positions.
 

src/Magnum/Primitives/Icosphere.h

@@ -38,9 +38,10 @@ namespace Magnum { namespace Primitives {
 @brief Solid 3D icosphere
 @param subdivisions      Number of subdivisions
 
-Sphere with radius @cpp 1.0f @ce. @ref MeshPrimitive::Triangles with
+Sphere of radius @cpp 1.0f @ce, centered at origin.
-@ref MeshIndexType::UnsignedInt indices, interleaved @ref VertexFormat::Vector3
+@ref MeshPrimitive::Triangles with @ref MeshIndexType::UnsignedInt indices,
-positions and @ref VertexFormat::Vector3 normals.
+interleaved @ref VertexFormat::Vector3 positions and @ref VertexFormat::Vector3
+normals.
 
 @image html primitives-icospheresolid.png width=256px
 

src/Magnum/Primitives/Plane.h

@@ -84,11 +84,12 @@ enum class CORRADE_DEPRECATED_ENUM("use PlaneFlags instead") PlaneTextureCoords:
 @param flags        Flags
 @m_since_latest
 
-2x2 plane. Non-indexed @ref MeshPrimitive::TriangleStrip on the XY plane with
+2x2 square on the XY plane, centered at origin. Non-indexed
-@ref VertexFormat::Vector3 positions, @ref VertexFormat::Vector3 normals in
+@ref MeshPrimitive::TriangleStrip with @ref VertexFormat::Vector3 positions,
-positive Z direction, optional @ref VertexFormat::Vector4 tangents and optional
+@ref VertexFormat::Vector3 normals in positive Z direction, optional
-@ref VertexFormat::Vector2 texture coordinates. The returned instance may
+@ref VertexFormat::Vector4 tangents and optional @ref VertexFormat::Vector2
-reference data stored in constant memory.
+texture coordinates. The returned instance may reference data stored in
+constant memory.
 
 @image html primitives-planesolid.png width=256px
 
@@ -115,9 +116,9 @@ CORRADE_IGNORE_DEPRECATED_POP
 /**
 @brief Wireframe 3D plane
 
-2x2 plane. Non-indexed @ref MeshPrimitive::LineLoop on the XY plane with
+2x2 square on the XY plane, centered at origin. Non-indexed
-@ref VertexFormat::Vector3 positions. The returned instance references data
+@ref MeshPrimitive::LineLoop on the XY plane with @ref VertexFormat::Vector3
-stored in constant memory.
+positions. The returned instance references data stored in constant memory.
 
 @image html primitives-planewireframe.png width=256px
 

src/Magnum/Primitives/Square.h

@@ -76,10 +76,10 @@ enum class CORRADE_DEPRECATED_ENUM("use SquareFlags instead") SquareTextureCoord
 @param flags        Flags
 @m_since_latest
 
-2x2 square. Non-indexed @ref MeshPrimitive::TriangleStrip with interleaved
+2x2 square, centered at origin. Non-indexed @ref MeshPrimitive::TriangleStrip
-@ref VertexFormat::Vector2 positions and optional @ref VertexFormat::Vector2
+with interleaved @ref VertexFormat::Vector2 positions and optional
-texture coordinates. The returned instance references data stored in constant
+@ref VertexFormat::Vector2 texture coordinates. The returned instance
-memory.
+references data stored in constant memory.
 
 @image html primitives-squaresolid.png width=256px
 
@@ -101,7 +101,7 @@ CORRADE_IGNORE_DEPRECATED_POP
 /**
 @brief Wireframe 2D square
 
-2x2 square. Non-indexed @ref MeshPrimitive::LineLoop with
+2x2 square, centered at origin. Non-indexed @ref MeshPrimitive::LineLoop with
 @ref VertexFormat::Vector2 positions. The returned instance references data
 stored in constant memory.
 

src/Magnum/Primitives/UVSphere.h

@@ -74,12 +74,12 @@ CORRADE_ENUMSET_OPERATORS(UVSphereFlags)
 @param flags            Flags
 @m_since_latest
 
-Sphere with radius @cpp 1.0f @ce. @ref MeshPrimitive::Triangles with
+Sphere of radius @cpp 1.0f @ce, centered at origin.
-@ref MeshIndexType::UnsignedInt indices, interleaved @ref VertexFormat::Vector3
+@ref MeshPrimitive::Triangles with @ref MeshIndexType::UnsignedInt indices,
-positions, @ref VertexFormat::Vector3 normals, optional
+interleaved @ref VertexFormat::Vector3 positions, @ref VertexFormat::Vector3
-@ref VertexFormat::Vector4 tangents and @ref VertexFormat::Vector2 texture
+normals, optional @ref VertexFormat::Vector4 tangents and
-coordinates. If texture coordinates are generated, vertices of one segment are
+@ref VertexFormat::Vector2 texture coordinates. If texture coordinates are
-duplicated for texture wrapping.
+generated, vertices of one segment are duplicated for texture wrapping.
 
 @image html primitives-uvspheresolid.png width=256px
 
@@ -114,8 +114,8 @@ CORRADE_IGNORE_DEPRECATED_POP
 @param segments         Number of (line) segments. Must be larger or equal to
     @cpp 4 @ce and multiple of @cpp 4 @ce.
 
-Sphere with radius @cpp 1.0f @ce. @ref MeshPrimitive::Lines with
+Sphere of radius @cpp 1.0f @ce, centered at origin. @ref MeshPrimitive::Lines
-@ref MeshIndexType::UnsignedInt indices and @ref VertexFormat::Vector3
+with @ref MeshIndexType::UnsignedInt indices and @ref VertexFormat::Vector3
 positions.
 
 @image html primitives-uvspherewireframe.png width=256px