From ec20dea1e25492885b659b4663e5810e805fa075 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sat, 6 Jan 2018 18:48:21 +0100 Subject: [PATCH] Platform: un-deprecate creation of Platform::Context without passing args. I deprecated that because I wanted to be sure that I properly update all my code to actually propagate the options. But now I see that this is actually a valid case -- the engine being in a thread or in some other way hidden from the outside *shouldn't* need access to argc/argv. Also updated the docs to say it's completely harmless to propagate the args. --- src/Magnum/Context.h | 23 +++++++++++++++-------- src/Magnum/Platform/Context.h | 31 +++++++++++++++++++++++-------- 2 files changed, 38 insertions(+), 16 deletions(-) diff --git a/src/Magnum/Context.h b/src/Magnum/Context.h index 27da95ad1..8da8bee14 100644 --- a/src/Magnum/Context.h +++ b/src/Magnum/Context.h @@ -97,24 +97,31 @@ also possible to create the context without using any `*Application` class using @ref Platform::Context subclass, see @ref platform documentation for more information. -## Command-line options +@section Context-command-line Command-line options The context is configurable through command-line options, that are passed either from the `Platform::*Application` classes or from the @ref Platform::Context class. Usage: - [--magnum-help] [--magnum-disable-workarounds LIST] [--magnum-disable-extensions LIST] ... +@code{.sh} + [--magnum-help] [--magnum-disable-workarounds LIST] + [--magnum-disable-extensions LIST] ... +@endcode Arguments: -- `...` -- main application arguments (see `-h` or `--help` for details) -- `--magnum-help` -- display this help message and exit -- `--magnum-disable-workarounds LIST` -- driver workarounds to disable (see - `src/Magnum/Implementation/driverSpecific.cpp` for detailed info) - (environment: `MAGNUM_DISABLE_WORKAROUNDS`) -- `--magnum-disable-extensions LIST` -- OpenGL extensions to disable +- `...` --- main application arguments (see `-h` or `--help` for details) +- `--magnum-help` --- display this help message and exit +- `--magnum-disable-workarounds LIST` --- driver workarounds to disable (see + [src/Magnum/Implementation/driverSpecific.cpp](https://github.com/mosra/magnum/blob/master/src/Magnum/Implementation/driverSpecific.cpp) + for detailed info) (environment: `MAGNUM_DISABLE_WORKAROUNDS`) +- `--magnum-disable-extensions LIST` --- OpenGL extensions to disable (environment: `MAGNUM_DISABLE_EXTENSIONS`) +Note that all options are prefixed with `--magnum-` to avoid conflicts with +options passed to the application itself. Options that don't have this prefix +are completely ignored, see documentation of the +@ref Utility-Arguments-delegating "Utility::Arguments" class for details. */ class MAGNUM_EXPORT Context { public: diff --git a/src/Magnum/Platform/Context.h b/src/Magnum/Platform/Context.h index 4597c156d..b87535dd0 100644 --- a/src/Magnum/Platform/Context.h +++ b/src/Magnum/Platform/Context.h @@ -50,9 +50,9 @@ class Context: public Magnum::Context { * is unsupported or any other error occurs, a message is printed to * output and the application exits. See @ref Context(NoCreateT, Int, char**) * and @ref tryCreate() for an alternative. - * @see @fn_gl{Get} with @def_gl{MAJOR_VERSION}, @def_gl{MINOR_VERSION}, - * @def_gl{CONTEXT_FLAGS}, @def_gl{NUM_EXTENSIONS}, - * @fn_gl{GetString} with @def_gl{EXTENSIONS} + * @see @ref Context-command-line, @fn_gl{Get} with @def_gl{MAJOR_VERSION}, + * @def_gl{MINOR_VERSION}, @def_gl{CONTEXT_FLAGS}, + * @def_gl{NUM_EXTENSIONS}, @fn_gl{GetString} with @def_gl{EXTENSIONS} */ explicit Context(Int argc, const char** argv): Context{NoCreate, argc, argv} { create(); } @@ -62,12 +62,16 @@ class Context: public Magnum::Context { /** @overload */ explicit Context(Int argc, std::nullptr_t argv): Context{argc, static_cast(argv)} {} - #ifdef MAGNUM_BUILD_DEPRECATED - /** @copybrief Context(Int, const char**) - * @deprecated Use @ref Context(Int, const char**) instead. + /** + * @brief Default constructor + * + * Equivalent to passing @cpp {0, nullptr} @ce to + * @ref Context(Int, const char**). Even if the command-line options + * are not propagated, it's still possible to affect the renderer + * behavior from the environment. See @ref Context-command-line for + * more information. */ - CORRADE_DEPRECATED("use Context(Int, const char**) instead") explicit Context(): Context(0, nullptr) {} - #endif + explicit Context(): Context{0, nullptr} {} /** * @brief Construct the class without doing complete setup @@ -90,6 +94,17 @@ class Context: public Magnum::Context { /** @overload */ explicit Context(NoCreateT, Int argc, std::nullptr_t argv): Context{NoCreate, argc, static_cast(argv)} {} + /** + * @brief Construct the class without doing complete setup + * + * Equivalent to passing @cpp {NoCreate, 0, nullptr} @ce to + * @ref Context(NoCreateT, Int, const char**). Even if the command-line + * options are not propagated, it's still possible to affect the + * renderer behavior from the environment. See @ref Context-command-line + * for more information. + */ + explicit Context(NoCreateT): Context{NoCreate, 0, nullptr} {} + /** * @brief Complete the context setup and exit on failure *