Primitives: a better line primitive.

doc/changelog.dox

@@ -124,6 +124,13 @@ See also:
     @ref Platform::AndroidApplication. This also makes the default framebuffer
     parameters consistent across the implementations.
 
+@subsubsection changelog-latest-new-primitives Primitives library
+
+-   New @ref Primitives::line2D(const Vector2&, const Vector2&) and
+    @ref Primitives::line3D(const Vector3&, const Vector3&) overloads for
+    easier creation of arbitrary lines, as transforming the line identities is
+    not worth the mental overhead
+
 @subsubsection changelog-latest-new-scenegraph SceneGraph library
 
 -   New @ref SceneGraph::TranslationRotationScalingTransformation2D and

doc/snippets/CMakeLists.txt

@@ -112,6 +112,14 @@ if(WITH_DEBUGTOOLS AND Corrade_TestSuite_FOUND AND NOT CORRADE_TARGET_IOS)
     set_target_properties(debugtools-compareimage PROPERTIES FOLDER "Magnum/doc/snippets")
 endif()
 
+if(WITH_PRIMITIVES)
+    add_library(snippets-MagnumPrimitives STATIC
+        MagnumPrimitives.cpp)
+    target_link_libraries(snippets-MagnumPrimitives PRIVATE MagnumPrimitives)
+    set_target_properties(snippets-MagnumPrimitives
+        PROPERTIES FOLDER "Magnum/doc/snippets")
+endif()
+
 if(WITH_SCENEGRAPH)
     add_library(snippets-MagnumSceneGraph STATIC
         MagnumSceneGraph.cpp)

doc/snippets/MagnumPrimitives.cpp

@@ -0,0 +1,45 @@
+/*
+    This file is part of Magnum.
+
+    Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018
+              Vladimír Vondruš <mosra@centrum.cz>
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included
+    in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+*/
+
+#include "Magnum/Math/Vector3.h"
+#include "Magnum/Primitives/Line.h"
+#include "Magnum/Trade/MeshData2D.h"
+#include "Magnum/Trade/MeshData3D.h"
+
+using namespace Magnum;
+
+int main() {
+{
+/* [line2D-identity] */
+Primitives::line2D({0.0f, 0.0f}, {1.0f, 0.0f});
+/* [line2D-identity] */
+}
+
+{
+/* [line3D-identity] */
+Primitives::line3D({0.0f, 0.0f, 0.0f}, {1.0f, 0.0f, 0.0f});
+/* [line3D-identity] */
+}
+}

src/Magnum/Primitives/Line.cpp

@@ -32,16 +32,20 @@
 
 namespace Magnum { namespace Primitives {
 
+Trade::MeshData2D line2D(const Vector2& a, const Vector2& b) {
+    return Trade::MeshData2D{MeshPrimitive::Lines, {}, {{a, b}}, {}, {}, nullptr};
+}
+
+Trade::MeshData3D line3D(const Vector3& a, const Vector3& b) {
+    return Trade::MeshData3D{MeshPrimitive::Lines, {}, {{a, b}}, {}, {}, {}, nullptr};
+}
+
 Trade::MeshData2D line2D() {
-    return Trade::MeshData2D{MeshPrimitive::Lines, {}, {{
+   return line2D({0.0f, 0.0f}, {1.0f, 0.0f});
-        {0.0f, 0.0f}, {1.0f, 0.0f}
-    }}, {}, {}, nullptr};
 }
 
 Trade::MeshData3D line3D() {
-    return Trade::MeshData3D{MeshPrimitive::Lines, {}, {{
+    return line3D({0.0f, 0.0f, 0.0f}, {1.0f, 0.0f, 0.0f});
-        {0.0f, 0.0f, 0.0f}, {1.0f, 0.0f, 0.0f},
-    }}, {}, {}, {}, nullptr};
 }
 
 #ifdef MAGNUM_BUILD_DEPRECATED

src/Magnum/Primitives/Line.h

@@ -29,6 +29,7 @@
  * @brief Function @ref Magnum::Primitives::line2D(), @ref Magnum::Primitives::line3D()
  */
 
+#include "Magnum/Magnum.h"
 #include "Magnum/Primitives/visibility.h"
 #include "Magnum/Trade/Trade.h"
 
@@ -41,24 +42,43 @@ namespace Magnum { namespace Primitives {
 /**
 @brief 2D line
 
-Unit-size line in direction of positive X axis. Non-indexed
+Non-indexed @ref MeshPrimitive::Lines going from @p a to @p b.
-@ref MeshPrimitive::Lines.
 
 @image html primitives-line2d.png
 
-@see @ref line3D(), @ref axis2D(), @ref crosshair2D()
+@see @ref line3D(), @ref line3D(const Vector3&, const Vector3&), @ref axis2D(),
+    @ref crosshair2D()
+*/
+MAGNUM_PRIMITIVES_EXPORT Trade::MeshData2D line2D(const Vector2& a, const Vector2& b);
+
+/**
+@brief 2D line in an identity transformation
+
+Equivalent to calling @ref line2D(const Vector2&, const Vector2&) as
+
+@snippet MagnumPrimitives.cpp line2D-identity
 */
 MAGNUM_PRIMITIVES_EXPORT Trade::MeshData2D line2D();
 
 /**
 @brief 3D line
 
-Unit-size line in direction of positive X axis. Non-indexed
+Non-indexed @ref MeshPrimitive::Lines going from @p a to @p b.
-@ref MeshPrimitive::Lines.
 
 @image html primitives-line3d.png
 
-@see @ref line2D(), @ref axis3D(), @ref crosshair3D()
+@see @ref line3D(), @ref line2D(const Vector2&, const Vector2&), @ref axis3D(),
+    @ref crosshair3D()
+*/
+MAGNUM_PRIMITIVES_EXPORT Trade::MeshData3D line3D(const Vector3& a, const Vector3& b);
+
+/**
+@brief 3D line in an identity transformation
+
+Unit-size line in direction of positive X axis. Equivalent to calling
+@ref line3D(const Vector3&, const Vector3&) as
+
+@snippet MagnumPrimitives.cpp line3D-identity
 */
 MAGNUM_PRIMITIVES_EXPORT Trade::MeshData3D line3D();