Skip to content

Commit

Permalink
doc: now that plugins "just work", we can be honest and document that.
Browse files Browse the repository at this point in the history
  • Loading branch information
mosra committed Oct 15, 2019
1 parent 3a33fac commit 6e02ad5
Show file tree
Hide file tree
Showing 5 changed files with 180 additions and 23 deletions.
2 changes: 1 addition & 1 deletion doc/primitives.dox
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,7 @@ we now need some additional libraries, like `MeshTools` and `Primitives`,
everything else is the same as previously:

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

You can now try using another primitive from @ref Primitives namespace or
Expand Down
102 changes: 95 additions & 7 deletions doc/textured-triangle.dox
Original file line number Diff line number Diff line change
Expand Up @@ -195,9 +195,10 @@ Compilation is slightly more complicated compared to previous examples, because
we need to compile our resources into the executable.

The `resources.conf` file lists all resources which need to be compiled into
the executable --- that is our GLSL shader sources and the texture image. All
resource groups need to have unique identifier by which they are accessed, we
will use `textured-triangle-data` as above. As said above, the resource
the executable --- that is our GLSL shader sources and the texture image (the
one used in the above screenshot is [stone.tga](https://github.com/mosra/magnum-examples/raw/master/src/textured-triangle/stone.tga)).
All resource groups need to have unique identifier by which they are accessed,
we will use `textured-triangle-data` as above. As said above, the resource
compilation process is explained thoroughly in Corrade's
@ref resource-management "resource management tutorial".

Expand All @@ -214,15 +215,45 @@ After that we compile the resources using the
@ref corrade-cmake-add-resource "corrade_add_resource()" macro and create an
executable from the result and other source files. Last step is linking to all
needed libraries. The plugin is loaded dynamically, so it's not handled by
CMake at all.
CMake in any way.

@dontinclude textured-triangle/CMakeLists.txt
@skip corrade_add_resource
@until Magnum::Trade)

You can now try playing around with the shader source, modifying texture
coordinates or adding other effects. The full file content is linked below.
Full source code is also available in the
@m_class{m-block m-success}

@par Enabling additional Magnum components in your project
If you're using the CMake subproject setup described in the
@ref getting-started "Getting Started Guide", you'll need to modify the
top-level `CMakeLists.txt` to enable the @ref Trade::TgaImporter "TgaImporter"
plugin as well. Because the plugins are loaded at runtime, CMake doesn't
know we need them to be built --- one option is to list them explicitly
like shown below, another (but uglier) is to not use `EXCLUDE_FROM_ALL` on
the magnum subdirectory, so everything is always built implicitly. The
plugin modules are placed into `Debug/lib/magnum-d/importers` (or
`Debug/bin/magnum-d/importers` on Windows) in the build directory and the
@ref Trade library will find them there on its own.
@par
@code{.cmake}
...

set(WITH_SDL2APPLICATION ON CACHE BOOL "" FORCE)
set(WITH_TGAIMPORTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum EXCLUDE_FROM_ALL)

# So the TgaImporter gets built implicitly
add_custom_target(plugins ALL DEPENDS Magnum::TgaImporter)
@endcode
@par
If you're using a Magnum package, @ref Trade::TgaImporter "TgaImporter" is
included by default (and you don't need to do anything in CMake in order to
use it); if you build it yourself, make sure you have `WITH_TGAIMPORTER`
enabled.

Once the application builds and starts, you can now try playing around with the
shader source, modifying texture coordinates or adding other effects. 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/textured-triangle).

- @ref textured-triangle/CMakeLists.txt "CMakeLists.txt"
Expand All @@ -240,6 +271,63 @@ contains additional patches for @ref CORRADE_TARGET_IOS "iOS",
support that aren't present in `master` in order to keep the example code as
simple as possible.

@section examples-textured-triangle-importers PNG, JPEG and other file formats

In an effort to keep the core Magnum repository small, it has support just for
the TGA format. But it doesn't stop there, the
@ref building-plugins "Magnum Plugins" repository provides support for many
more file formats. Let's try loading arbitrary files instead --- the
@ref Trade::AnyImageImporter "AnyImageImporter" plugin autodetects a file
format and then delegates to a plugin that knows how to load PNGs. All you
need to do is load it instead of @cpp "TgaImporter" @ce and then bundle a
different file type --- or rewrite the example to take files from the
filesystem instead:

@code{.cpp}
Containers::Pointer<Trade::AbstractImporter> importer =
manager.loadAndInstantiate("AnyImageImporter");
if(!importer) std::exit(1);

if(!importer->openFile("/path/to/myfile.jpg"))
std::exit(2);
@endcode

See @ref plugins for more information about how plugin loading and selection
works. The next tutorial, @ref examples-viewer, expands further on this topic
and also shows how to open files passed via command-line arguments.

@m_class{m-block m-success}

@par Enabling Magnum Plugins in your project
If you're using the CMake subproject setup described in the
@ref getting-started "Getting Started Guide", you'll need to modify the
top-level `CMakeLists.txt` to add Magnum Plugins as a subdirectory and
enable the new plugins. The @ref Trade::StbImageImporter "StbImageImporter"
is an universal dependency-less plugin that can handle PNGs, JPEGs and
other common files:
@par
@code{.cmake}
...

set(WITH_ANYIMAGEIMPORTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum EXCLUDE_FROM_ALL)

set(WITH_STBIMAGEIMPORTER ON CACHE BOOL "" FORCE)
# git clone https://github.com/mosra/magnum-plugins.git
add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL)

add_custom_target(plugins ALL DEPENDS
Magnum::AnyImageImporter
MagnumPlugins::StbImageImporter)
@endcode
@par
If you're using packaged Magnum, install
@ref building-plugins-packages "Magnum Plugins" the same way as you did with
Magnum, all the above-mentioned plugins are included by default (and you
don't need to do anything in CMake in order to use them). If you build it
yourself, make sure you have `WITH_ANYIMAGEIMPORTER` enabled for Magnum and
`WITH_STBIMAGEIMPORTER` enabled for Magnum Plugins.

@example textured-triangle/CMakeLists.txt @m_examplenavigation{examples-textured-triangle,textured-triangle/} @m_footernavigation
@example textured-triangle/resources.conf @m_examplenavigation{examples-textured-triangle,textured-triangle/} @m_footernavigation
@example textured-triangle/TexturedTriangleExample.cpp @m_examplenavigation{examples-textured-triangle,textured-triangle/} @m_footernavigation
Expand Down
26 changes: 12 additions & 14 deletions doc/triangle.dox
Original file line number Diff line number Diff line change
Expand Up @@ -129,14 +129,10 @@ background:
MAGNUM_APPLICATION_MAIN(TriangleExample)
@endcode

That's all, now we can compile the whole example using CMake. Apart from the
standard CMake setup related to version requirements and paths to
`FindMagnum.cmake`, `FindSDL2.cmake` and `FindCorrade.cmake`, as described in
the @ref getting-started "Getting Started Guide", the setup is as follows.
First we require the `Magnum` package with `GL`, `Shaders` and
`Sdl2Application` components. It's recommended to also use Corrade's set of
compiler flags to enable additional warnings. Then we create our executable and
link to all Magnum libraries we requested. See @ref cmake for more information.
That's all, now we can compile the whole example using CMake. Continuing from
the @ref getting-started-review "Getting Started Guide", the only addition
is finding & linking the @ref Magnum::Shaders library that's now being used as
well:

@dontinclude triangle/CMakeLists.txt
@skip find_package
Expand All @@ -156,12 +152,14 @@ contains additional patches for @ref CORRADE_TARGET_IOS "iOS",
support that aren't present in `master` in order to keep the example code as
simple as possible.

@m_div{m-note m-success} There's also an alternative version of this example
that sidesteps the @ref Platform::Sdl2Application "Platform::Application"
wrapper classes to show that it's possible to hook into OpenGL context and
window surface provided by a third party library. See @ref examples-triangle-plain-glfw
for details.
@m_enddiv
@m_class{m-note m-success}

@par
There's also an alternative version of this example that sidesteps the
@ref Platform::Sdl2Application "Platform::Application" wrapper classes to
show that it's possible to hook into OpenGL context and window surface
provided by a third party library. See @ref examples-triangle-plain-glfw
for details.

@example triangle/CMakeLists.txt @m_examplenavigation{examples-triangle,triangle/} @m_footernavigation
@example triangle/TriangleExample.cpp @m_examplenavigation{examples-triangle,triangle/} @m_footernavigation
Expand Down
45 changes: 44 additions & 1 deletion doc/viewer.dox
Original file line number Diff line number Diff line change
Expand Up @@ -318,16 +318,59 @@ to talk about.
Compilation is again nothing special:

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

@m_class{m-block m-success}

@par Enabling model-loading plugins in your project
The core Magnum repository contains a very rudimentary OBJ file loader in
@ref Trade::ObjImporter "ObjImporter", and you can try it with the
`scene.obj` file linked below. For more advanced models,
@ref building-plugins "Magnum Plugins" provide
@ref Trade::TinyGltfImporter "TinyGltfImporter" that can load the
`scene.gltf`, and there are more plugins for various other formats.
@par
If you're using the CMake subproject setup, you'll need to modify the
top-level `CMakeLists.txt` to enable these --- expanding on what
@ref examples-textured-triangle-importers "was shown in the previous tutorial":
@par
@code{.cmake}
...

# If you want to load just basic OBJs
set(WITH_ANYIMAGEIMPORTER ON CACHE BOOL "" FORCE)
set(WITH_ANYSCENEIMPORTER ON CACHE BOOL "" FORCE)
set(WITH_OBJIMPORTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum EXCLUDE_FROM_ALL)

# If you want to load (textured) glTF as well
set(WITH_STBIMAGEIMPORTER ON CACHE BOOL "" FORCE)
set(WITH_TINYGLTFIMPORTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL)

add_custom_target(plugins ALL DEPENDS
Magnum::AnyImageImporter
Magnum::AnySceneImporter
Magnum::ObjImporter
MagnumPlugins::StbImageImporter
MagnumPlugins::TinyGltfImporter)
@endcode
@par
If you're using packaged Magnum, all the above-mentioned plugins are
included by default (and you don't need to do anything in CMake in order to
use them); if you build it yourself, make sure you have the desired
`WITH_*` options enabled.

You can experiment by loading scenes of varying complexity and formats, adding
light and camera property import or supporting more than just diffuse Phong
materials. 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/viewer).

- @ref viewer/CMakeLists.txt "CMakeLists.txt"
- @ref viewer/ViewerExample.cpp "ViewerExample.cpp"
- [scene.obj](https://github.com/mosra/magnum-examples/raw/master/src/viewer/scene.obj)
- [scene.gltf](https://github.com/mosra/magnum-examples/raw/master/src/viewer/scene.gltf)

The [ports branch](https://github.com/mosra/magnum-examples/tree/ports/src/viewer)
contains additional patches for @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten"
Expand Down
28 changes: 28 additions & 0 deletions src/viewer/scene.obj
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
o Cube
v 1.0 1.0 -1.0
v 1.0 -1.0 -1.0
v 1.0 1.0 1.0
v 1.0 -1.0 1.0
v -1.0 1.0 -1.0
v -1.0 -1.0 -1.0
v -1.0 1.0 1.0
v -1.0 -1.0 1.0
vn 0.0 1.0 0.0
vn 0.0 0.0 1.0
vn -1.0 0.0 0.0
vn 0.0 -1.0 0.0
vn 1.0 0.0 0.0
vn 0.0 0.0 -1.0
s off
f 5//1 3//1 1//1
f 3//2 8//2 4//2
f 7//3 6//3 8//3
f 2//4 8//4 6//4
f 1//5 4//5 2//5
f 5//6 2//6 6//6
f 5//1 7//1 3//1
f 3//2 7//2 8//2
f 7//3 5//3 6//3
f 2//4 4//4 8//4
f 1//5 3//5 4//5
f 5//6 1//6 2//6

0 comments on commit 6e02ad5

Please sign in to comment.