primitives.dox

/*
    This file is part of Magnum.

    Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019,
                2020, 2021, 2022, 2023 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.
*/

namespace Magnum {
/** @page examples-primitives Primitives
@brief Importing mesh data, 3D transformations and input handling.

@tableofcontents
@m_footernavigation

@image html primitives.png

This example shows how to easily create a @ref GL::Mesh from arbitrary external
data and do basic mouse interaction in a 3D scene.

@m_div{m-button m-primary} <a href="https://magnum.graphics/showcase/primitives/">@m_div{m-big}Live web demo @m_enddiv @m_div{m-small} uses WebAssembly & WebGL @m_enddiv </a> @m_enddiv

@section examples-primitives-setup Setting up

The new includes are for a @ref Primitives::cubeSolid(), which returns a
@ref Trade::MeshData, which we then turn into a GL mesh using
@ref MeshTools::compile(). And because we have a 3D scene now, we'll want to
draw it with @ref Shaders::PhongGL instead of plain flat shading.

@dontinclude primitives/PrimitivesExample.cpp
@skip #include
@until Trade/MeshData

This time, for user interactivity we'll need to implement mouse event handlers
and store transformation & projection @ref Math::Matrix4 "Matrix4" plus the
current @ref Math::Color3 "Color3".

@skip class PrimitivesExample
@until };

Because we are displaying a 3D scene, we need to enable depth test to have the
cube rendered in proper Z order. The @ref GL::Renderer::Feature::FaceCulling is
not strictly needed, but for closed meshes it can save a lot of rasterization
work by discarding triangles that face away from camera.

@skip PrimitivesExample::PrimitivesExample
@until GL::Renderer::enable(GL::Renderer::Feature::FaceCulling

@section examples-primitives-mesh Preparing the mesh

Perhaps the biggest leap from previous examples is that setting up the mesh is
now just a simple oneliner:

@skipline _mesh =

The main responsibility here lies on @ref Trade::MeshData, which is a class
capable of describing arbitrary meshes in arbitrary layouts. It's used as the
backbone of the @ref Primitives library as well as of Magnum's asset import
pipeline, which will be shown in the next @ref examples-viewer "Model Viewer example".

The @ref Primitives::cubeSolid() gives us an indexed triangle mesh with
positions and normals. @ref MeshTools::compile() then takes the
@ref Trade::MeshData, uploads it to the GPU, and pops out a @ref GL::Mesh that
owns the index and vertex buffers and has all attributes configured to be
rendered with builtin shaders.

While this admittedly skipped quite a few intermediate steps compared to manual
mesh setup from the previous examples, in practice you'll mostly either deal
with raw attribute arrays or already have a @ref Trade::MeshData to begin with.
Nevertheless, it's not an opaque container --- be sure to go through its
documentation to understand how the data is represented, how the attributes
can be accessed and how it all maps to a @ref GL::Mesh.

@section examples-primitives-transformation Transformation and projection

As a final step in the constructor we specify the initial cube transformation,
rotating it slightly for a 3D look. Earlier we used color literals from
@ref Math::Literals, here we use angle literals. Magnum has strongly-typed
angles, which allows us to conveniently use degrees even though APIs such as
@ref Matrix4::rotationX() accept radians:

@skip _transformation =
@until ;

Then we set up a perspective projection with an aspect ratio matching the
window size and an initial color with an orange hue. For a more thorough
introduction to Magnum's vector math library please see @ref matrix-vector and
@ref transformations.

@skip _projection =
@until }
@until }
@until }

@section examples-primitives-rendering Rendering

In the draw event we clear the framebuffer, now also clearing the depth buffer
as we need it for the depth test. For the shader we hardcode a directional
light source, set the cached color, transformation and projection matrices
including a normal matrix and draw the mesh.

@skip void PrimitivesExample::drawEvent
@until }
@until }
@until }

@section examples-primitives-events Mouse event handling

On a click (press + release) we want to shift the color hue and on mouse drag
we'll rotate the object using a bunch of vector and matrix operations.

To save resources, the application doesn't redraw constantly by default, which
means we have to trigger a @relativeref{Platform::Sdl2Application,redraw()} in
order to see any effect from the events. In case you'd want to draw constantly
--- for example in order to perform an animation --- you can call
@relativeref{Platform::Sdl2Application,redraw()} directly in the
@relativeref{Platform::Sdl2Application,drawEvent()}.

@skip void PrimitivesExample::mousePressEvent
@until }
@until }
@until }
@until }
@until }
@until }
@until }
@until }

The main function is just the macro call, as previously.

@code{.cpp}
MAGNUM_APPLICATION_MAIN(PrimitivesExample)
@endcode

@section examples-primitives-compilation Compilation

Compilation is pretty straigtforward, similar to the @ref examples-triangle "Triangle example".
Again omitting the basic setup described in the @ref getting-started "Getting Started Guide",
we now use also the `MeshTools`, `Primitives` and `Trade` libraries:

@dontinclude primitives/CMakeLists.txt
@skip find_package(
@until Magnum::Trade)

You can now try using different primitives from the @ref Primitives namespace
or render the mesh with a different shader from @ref Shaders namespace. The
full file content is linked below. Full source code is also available in the
[magnum-examples GitHub repository](https://github.com/mosra/magnum-examples/tree/master/src/primitives).

-   @ref primitives/CMakeLists.txt "CMakeLists.txt"
-   @ref primitives/PrimitivesExample.cpp "PrimitivesExample.cpp"

The [ports branch](https://github.com/mosra/magnum-examples/tree/ports/src/primitives)
contains additional patches for @ref CORRADE_TARGET_IOS "iOS",
@ref CORRADE_TARGET_ANDROID "Android" and @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten"
support that aren't present in `master` in order to keep the example code as
simple as possible.

@example primitives/CMakeLists.txt @m_examplenavigation{examples-primitives,primitives/} @m_footernavigation
@example primitives/PrimitivesExample.cpp @m_examplenavigation{examples-primitives,primitives/} @m_footernavigation

*/
}