Browse Source

doc: converted Platform docs to use compiled code snippets.

They got terribly outdated over the years, ugh.
pull/205/head
Vladimír Vondruš 8 years ago
parent
commit
5c9f74e4b0
  1. 178
      doc/platform.dox
  2. 29
      doc/snippets/CMakeLists.txt
  3. 45
      doc/snippets/MagnumPlatform-custom.cpp
  4. 56
      doc/snippets/MagnumPlatform-windowless-custom.cpp
  5. 47
      doc/snippets/MagnumPlatform-windowless-thread.cpp
  6. 52
      doc/snippets/MagnumPlatform-windowless.cpp
  7. 145
      doc/snippets/MagnumPlatform.cpp

178
doc/platform.dox

@ -64,38 +64,7 @@ blue color is shown in the following code listing.
`base` branch of [Magnum Bootstrap](https://github.com/mosra/magnum-bootstrap)
repository.
@code{.cpp}
#include <Magnum/DefaultFramebuffer.h>
#include <Magnum/Renderer.h>
#include <Magnum/Math/Color.h>
#include <Magnum/Platform/Sdl2Application.h>
using namespace Magnum;
class MyApplication: public Platform::Application {
public:
MyApplication(const Arguments& arguments);
private:
void drawEvent() override;
};
MyApplication::MyApplication(const Arguments& arguments): Platform::Application(arguments) {
// Set clear color to dark blue
Renderer::setClearColor({0.0f, 0.0f, 0.4f});
}
void MyApplication::drawEvent() {
// Clear the window
defaultFramebuffer.clear(FramebufferClear::Color);
// The context is double-buffered, swap buffers
swapBuffers();
}
// main() function implementation
MAGNUM_APPLICATION_MAIN(MyApplication)
@endcode
@snippet MagnumPlatform.cpp windowed
@subsection platform-windowed-viewport Responding to viewport size changes
@ -105,20 +74,7 @@ example by resizing the default framebuffer, you need to reimplement
@ref Platform::Sdl2Application::viewportEvent() "viewportEvent()" function and
pass the new size to the framebuffer:
@code{.cpp}
class MyApplication: public Platform::Application {
// ...
private:
void viewportEvent(const Vector2i& size) override;
};
// ...
void MyApplication::viewportEvent(const Vector2i& size) {
defaultFramebuffer.setViewport({{}, size});
}
@endcode
@snippet MagnumPlatform.cpp size
@section platform-windowless Windowless applications
@ -127,13 +83,13 @@ performing tasks on GPU. There is not yet any platform-independent toolkit
which could handle this in portable way, thus you have to use platform-specific
ones. Magnum provides windowless applications for X11-based Unix, macOS and
Windows. To make things simple, as an example we will use only
@ref Platform::WindowlessGlxApplication, see link for bootstrap application
@ref Platform::WindowlessEglApplication, see link for bootstrap application
below for fully portable example.
You need to implement just @ref Platform::WindowlessGlxApplication::exec() "exec()"
You need to implement just @ref Platform::WindowlessEglApplication::exec() "exec()"
function. The class can be then used directly in @cpp main() @ce, but again,
for convenience and portability it's better to use
@ref MAGNUM_WINDOWLESSGLXAPPLICATION_MAIN() macro.
@ref MAGNUM_WINDOWLESSEGLAPPLICATION_MAIN() macro.
Similarly as with windowed applications, to simplify the porting, the library
provides @cpp Platform::WindowlessApplication @ce typedef and
@ -153,32 +109,7 @@ renderer string and exits is in the following code listing.
is available in `windowless` branch of [Magnum Bootstrap](https://github.com/mosra/magnum-bootstrap)
repository.
@code{.cpp}
#include <Magnum/Context.h>
#include <Magnum/Platform/WindowlessGlxApplication.h>
using namespace Magnum;
class MyApplication: public Platform::WindowlessApplication {
public:
MyApplication(const Arguments& arguments);
int exec() override;
};
MyApplication::MyApplication(const Arguments& arguments): Platform::WindowlessApplication(arguments) {}
int MyApplication::exec() {
Debug() << "OpenGL version:" << Context::current()->versionString();
Debug() << "OpenGL renderer:" << Context::current()->rendererString();
// Exit with success
return 0;
}
// main() function implementation
MAGNUM_WINDOWLESSAPPLICATION_MAIN(MyApplication)
@endcode
@snippet MagnumPlatform-windowless.cpp windowless
@section platform-compilation Compilation with CMake
@ -210,32 +141,14 @@ window size 800x600 pixels). If you want something else, you can pass
application constructor. Using method chaining it can be done conveniently like
this:
@code{.cpp}
MyApplication::MyApplication(int& argc, char** argv):
Platform::Application(argc, argv, Configuration()
.setTitle("My Application")
.setSize({800, 600}))
{
// ...
}
@endcode
@snippet MagnumPlatform.cpp configuration
However, sometimes you would need to configure the application based on some
configuration file or system introspection. In that case you can pass `nullptr`
instead of @ref Platform::Sdl2Application::Configuration "Configuration"
instance and then specify it later with @ref Platform::Sdl2Application::createContext() "createContext()":
@code{.cpp}
MyApplication::MyApplication(int& argc, char** argv): Platform::Application(argc, argv, nullptr) {
// ...
createContext(Configuration()
.setTitle("My Application")
.setSize(size));
// ...
}
@endcode
@snippet MagnumPlatform.cpp createcontext
If the context creation in constructor or @ref Platform::Sdl2Application::createContext() "createContext()"
fails, the application exits. However, it is also possible to negotiate the
@ -244,20 +157,7 @@ The only difference is that this function returns `false` instead of exiting.
You can for example try enabling MSAA and if the context creation fails, fall
back to no-AA rendering:
@code{.cpp}
MyApplication::MyApplication(int& argc, char** argv): Platform::Application(argc, argv, nullptr) {
// ...
Configuration conf;
conf.setTitle("My Application")
.setSampleCount(16);
if(!tryCreateContext(conf))
createContext(conf.setSampleCount(0));
// ...
}
@endcode
@snippet MagnumPlatform.cpp trycreatecontext
@section platform-custom Using custom platform toolkits
@ -272,23 +172,11 @@ code listing.
@note Fully contained application using with manual Magnum initialization on
top of Qt toolkit is available in `base-qt` branch of
[Magnum Bootstrap](https://github.com/mosra/magnum-bootstrap) repository.
@note
There's also @ref examples-triangle-plain-glfw an example showing usage of
plain GLFW to render a basic triangle.
@code{.cpp}
int main(int argc, char** argv) {
// Create OpenGL context ...
{
// Initialize Magnum
Platform::Context context;
// Open window, enter main loop ...
// Magnum context gets destroyed
}
// Delete OpenGL context ...
}
@endcode
@snippet MagnumPlatform-custom.cpp custom
@attention Currently Magnum is limited to single OpenGL context, which must be
always set as current.
@ -340,28 +228,7 @@ windowless application header is included.
@attention With this approach it is possible to switch between different GL
contexts, but make sure that Magnum is used only with its OpenGL context.
@code{.cpp}
int main(int argc, char** argv) {
Platform::WindowlessGLContext glContext{{}};
glContext.makeCurrent();
Platform::Context context{argc, argv};
// Your GL code ...
// Make another context current
eglMakeCurrent();
// Someone else's code ...
// Make Magnum context current again
glContext.makeCurrent();
// Your GL code again ...
// Magnum context gets destroyed
// Windowless GL context gets destroyed
}
@endcode
@snippet MagnumPlatform-windowless-custom.cpp custom
The main purpose of windowless contexts is threaded OpenGL, used for example
for background data processing. The workflow is to create the windowless
@ -373,21 +240,6 @@ current (for example for the main application rendering). See also
@note Context creation is not thread safe on all platforms, that's why it still
has to be done on the main thread.
@code{.cpp}
int main() {
Platform::WindowlessGLContext glContext{{}};
std::thread worker{[&glContext]{
glContext.makeCurrent();
Platform::Context context{0, nullptr};
// Use Magnum here ...
}};
// Independent main application code here ...
worker.join();
}
@endcode
@snippet MagnumPlatform-windowless-thread.cpp thread
*/
}

29
doc/snippets/CMakeLists.txt

@ -55,14 +55,39 @@ if(WITH_SDL2APPLICATION)
add_executable(getting-started-blue getting-started-blue.cpp)
target_link_libraries(getting-started PRIVATE MagnumSdl2Application)
target_link_libraries(getting-started-blue PRIVATE MagnumSdl2Application)
add_library(snippets-MagnumPlatform STATIC MagnumPlatform.cpp)
target_link_libraries(snippets-MagnumPlatform PRIVATE MagnumSdl2Application)
set_target_properties(
getting-started
getting-started-blue
snippets-MagnumPlatform
PROPERTIES FOLDER "Magnum/doc/snippets")
# Otherwise it's not linked correctly. I have no idea why, but whatever.
if(CMAKE_VERSION VERSION_LESS 3.0)
find_package(SDL2 REQUIRED)
target_link_libraries(getting-started PRIVATE SDL2::SDL2)
target_link_libraries(getting-started-blue PRIVATE SDL2::SDL2)
target_link_libraries(snippets-MagnumPlatform PRIVATE SDL2::SDL2)
endif()
endif()
if(WITH_WINDOWLESSEGLAPPLICATION)
add_library(snippets-MagnumPlatform-custom STATIC MagnumPlatform-custom.cpp)
add_library(snippets-MagnumPlatform-windowless STATIC MagnumPlatform-windowless.cpp)
add_library(snippets-MagnumPlatform-windowless-custom STATIC MagnumPlatform-windowless-custom.cpp)
add_library(snippets-MagnumPlatform-windowless-thread STATIC MagnumPlatform-windowless-thread.cpp)
target_link_libraries(snippets-MagnumPlatform-custom PRIVATE MagnumWindowlessEglApplication)
target_link_libraries(snippets-MagnumPlatform-windowless PRIVATE MagnumWindowlessEglApplication)
target_link_libraries(snippets-MagnumPlatform-windowless-custom PRIVATE MagnumWindowlessEglApplication)
target_link_libraries(snippets-MagnumPlatform-windowless-thread PRIVATE MagnumWindowlessEglApplication)
set_target_properties(
getting-started
getting-started-blue
snippets-MagnumPlatform-windowless
snippets-MagnumPlatform-windowless-custom
snippets-MagnumPlatform-windowless-thread
snippets-MagnumPlatform-custom
PROPERTIES FOLDER "Magnum/doc/snippets")
endif()

45
doc/snippets/MagnumPlatform-custom.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/Platform/Context.h>
using namespace Magnum;
/* [custom] */
int main() {
// Create OpenGL context ...
{
/* Initialize Magnum */
Platform::Context context;
// Main loop ...
/* Magnum context gets destroyed */
}
// Delete OpenGL context ...
}
/* [custom] */

56
doc/snippets/MagnumPlatform-windowless-custom.cpp

@ -0,0 +1,56 @@
/*
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/Platform/WindowlessEglApplication.h>
#include <Magnum/Platform/Context.h>
using namespace Magnum;
EGLDisplay display{};
EGLSurface surface{};
EGLContext anotherContext{};
/* [custom] */
int main(int argc, char** argv) {
Platform::WindowlessGLContext glContext{{}};
glContext.makeCurrent();
Platform::Context context{argc, argv};
// Your GL code ...
/* Make another context current */
eglMakeCurrent(display, surface, surface, anotherContext);
// Someone else's code ...
/* Make Magnum context current again */
glContext.makeCurrent();
// Your GL code again ...
/* Magnum context gets destroyed */
/* Windowless GL context gets destroyed */
}
/* [custom] */

47
doc/snippets/MagnumPlatform-windowless-thread.cpp

@ -0,0 +1,47 @@
/*
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 <thread>
#include <Magnum/Platform/WindowlessEglApplication.h>
#include <Magnum/Platform/Context.h>
using namespace Magnum;
/* [thread] */
int main() {
Platform::WindowlessGLContext glContext{{}};
std::thread worker{[&glContext]{
glContext.makeCurrent();
Platform::Context context;
// Use Magnum here ...
}};
// Independent main application code here ...
worker.join();
}
/* [thread] */

52
doc/snippets/MagnumPlatform-windowless.cpp

@ -0,0 +1,52 @@
/*
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.
*/
/* [windowless] */
#include <Magnum/Context.h>
#include <Magnum/Platform/WindowlessEglApplication.h>
using namespace Magnum;
class MyApplication: public Platform::WindowlessApplication {
public:
MyApplication(const Arguments& arguments);
int exec() override;
};
MyApplication::MyApplication(const Arguments& arguments):
Platform::WindowlessApplication{arguments} {}
int MyApplication::exec() {
Debug{} << "OpenGL version:" << Context::current().versionString();
Debug{} << "OpenGL renderer:" << Context::current().rendererString();
/* Exit with success */
return 0;
}
/* main() function implementation */
MAGNUM_WINDOWLESSAPPLICATION_MAIN(MyApplication)
/* [windowless] */

145
doc/snippets/MagnumPlatform.cpp

@ -0,0 +1,145 @@
/*
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.
*/
/* [windowed] */
#include <Magnum/DefaultFramebuffer.h>
#include <Magnum/Renderer.h>
#include <Magnum/Math/Color.h>
#include <Magnum/Platform/Sdl2Application.h>
#include <Magnum/Platform/Context.h>
using namespace Magnum;
class MyApplication: public Platform::Application {
public:
MyApplication(const Arguments& arguments);
private:
void drawEvent() override;
};
MyApplication::MyApplication(const Arguments& arguments): Platform::Application{arguments} {
using namespace Math::Literals;
/* Set clear color to dark blue */
Renderer::setClearColor(0x000066_rgbf);
}
void MyApplication::drawEvent() {
/* Clear the window */
defaultFramebuffer.clear(FramebufferClear::Color);
/* The context is double-buffered, swap buffers */
swapBuffers();
}
/* main() function implementation */
MAGNUM_APPLICATION_MAIN(MyApplication)
/* [windowed] */
namespace B {
/* [size] */
class MyApplication: public Platform::Application {
// ...
private:
void viewportEvent(const Vector2i& size) override;
};
// ...
void MyApplication::viewportEvent(const Vector2i& size) {
defaultFramebuffer.setViewport({{}, size});
}
/* [size] */
}
namespace C {
struct MyApplication: Platform::Application {
MyApplication(const Arguments& arguments);
};
/* [configuration] */
MyApplication::MyApplication(const Arguments& arguments):
Platform::Application(arguments, Configuration{}
.setTitle("My Application")
.setSize({800, 600}))
{
// ...
}
/* [configuration] */
}
namespace D {
constexpr Vector2i size;
struct MyApplication: Platform::Application {
MyApplication(const Arguments& arguments);
};
/* [createcontext] */
MyApplication::MyApplication(const Arguments& arguments):
Platform::Application{arguments, NoCreate}
{
// ...
createContext(Configuration{}
.setTitle("My Application")
.setSize(size));
// ...
}
/* [createcontext] */
}
namespace E {
struct MyApplication: Platform::Application {
MyApplication(const Arguments& arguments);
};
/* [trycreatecontext] */
MyApplication::MyApplication(const Arguments& arguments):
Platform::Application{arguments, NoCreate}
{
// ...
Configuration conf;
conf.setTitle("My Application")
.setSampleCount(16);
if(!tryCreateContext(conf))
createContext(conf.setSampleCount(0));
// ...
}
/* [trycreatecontext] */
}
Loading…
Cancel
Save