From 02c1c8cfd4468282c0457b5512d6686357467c28 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Tue, 7 Jun 2016 21:33:59 +0200 Subject: [PATCH] Platform: don't copy windowless app docs from windowed apps. The docs weren't correct in 90% cases -- mainly in case of createContext() function, docs of which were extended to clearly specify what's done inside. --- src/Magnum/Platform/Sdl2Application.h | 3 +- .../Platform/WindowlessCglApplication.h | 40 +++++++++++++++-- .../Platform/WindowlessEglApplication.h | 35 +++++++++++++-- .../Platform/WindowlessGlxApplication.h | 44 +++++++++++++++++-- .../Platform/WindowlessIosApplication.h | 35 +++++++++++++-- .../Platform/WindowlessNaClApplication.h | 35 +++++++++++++-- .../Platform/WindowlessWglApplication.h | 44 +++++++++++++++++-- .../WindowlessWindowsEglApplication.h | 35 +++++++++++++-- 8 files changed, 242 insertions(+), 29 deletions(-) diff --git a/src/Magnum/Platform/Sdl2Application.h b/src/Magnum/Platform/Sdl2Application.h index 110a62436..b18bf7c4c 100644 --- a/src/Magnum/Platform/Sdl2Application.h +++ b/src/Magnum/Platform/Sdl2Application.h @@ -342,7 +342,8 @@ class Sdl2Application { * * Creates application with default or user-specified configuration. * See @ref Configuration for more information. The program exits if - * the context cannot be created, see below for an alternative. + * the context cannot be created, see @ref tryCreateContext() for an + * alternative. */ #ifdef DOXYGEN_GENERATING_OUTPUT explicit Sdl2Application(const Arguments& arguments, const Configuration& configuration = Configuration()); diff --git a/src/Magnum/Platform/WindowlessCglApplication.h b/src/Magnum/Platform/WindowlessCglApplication.h index 374fa864c..693fe8ee8 100644 --- a/src/Magnum/Platform/WindowlessCglApplication.h +++ b/src/Magnum/Platform/WindowlessCglApplication.h @@ -106,7 +106,16 @@ class WindowlessCglApplication { class Configuration; - /** @copydoc Sdl2Application::Sdl2Application(const Arguments&, const Configuration&) */ + /** + * @brief Default constructor + * @param arguments Application arguments + * @param configuration Configuration + * + * Creates application with default or user-specified configuration. + * See @ref Configuration for more information. The program exits if + * the context cannot be created, see @ref tryCreateContext() for an + * alternative. + */ #ifdef DOXYGEN_GENERATING_OUTPUT explicit WindowlessCglApplication(const Arguments& arguments, const Configuration& configuration = Configuration()); #else @@ -115,7 +124,13 @@ class WindowlessCglApplication { explicit WindowlessCglApplication(const Arguments& arguments); #endif - /** @copydoc Sdl2Application::Sdl2Application(const Arguments&, std::nullptr_t) */ + /** + * @brief Constructor + * @param arguments Application arguments + * + * Unlike above, the context is not created and must be created later + * with @ref createContext() or @ref tryCreateContext(). + */ explicit WindowlessCglApplication(const Arguments& arguments, std::nullptr_t); /** @brief Copying is not allowed */ @@ -144,7 +159,19 @@ class WindowlessCglApplication { thus this is faster than public pure virtual destructor */ ~WindowlessCglApplication(); - /** @copydoc Sdl2Application::createContext() */ + /** + * @brief Create context with given configuration + * + * Must be called if and only if the context wasn't created by the + * constructor itself. Error message is printed and the program exits + * if the context cannot be created, see @ref tryCreateContext() for an + * alternative. + * + * On desktop GL, if version is not specified in @p configuration, the + * application first tries to create core context (OpenGL 3.2+), if + * that fails, tries OpenGL 3.0+ and as a last attempt falls back to + * compatibility OpenGL 2.1 context. + */ #ifdef DOXYGEN_GENERATING_OUTPUT void createContext(const Configuration& configuration = Configuration()); #else @@ -153,7 +180,12 @@ class WindowlessCglApplication { void createContext(); #endif - /** @copydoc Sdl2Application::tryCreateContext() */ + /** + * @brief Try to create context with given configuration + * + * Unlike @ref createContext() returns `false` if the context cannot be + * created, `true` otherwise. + */ bool tryCreateContext(const Configuration& configuration); private: diff --git a/src/Magnum/Platform/WindowlessEglApplication.h b/src/Magnum/Platform/WindowlessEglApplication.h index 034e66b0d..b262ef3f7 100644 --- a/src/Magnum/Platform/WindowlessEglApplication.h +++ b/src/Magnum/Platform/WindowlessEglApplication.h @@ -106,7 +106,16 @@ class WindowlessEglApplication { class Configuration; - /** @copydoc Sdl2Application::Sdl2Application(const Arguments&, const Configuration&) */ + /** + * @brief Default constructor + * @param arguments Application arguments + * @param configuration Configuration + * + * Creates application with default or user-specified configuration. + * See @ref Configuration for more information. The program exits if + * the context cannot be created, see @ref tryCreateContext() for an + * alternative. + */ #ifdef DOXYGEN_GENERATING_OUTPUT explicit WindowlessEglApplication(const Arguments& arguments, const Configuration& configuration = Configuration()); #else @@ -115,7 +124,13 @@ class WindowlessEglApplication { explicit WindowlessEglApplication(const Arguments& arguments); #endif - /** @copydoc Sdl2Application::Sdl2Application(const Arguments&, std::nullptr_t) */ + /** + * @brief Constructor + * @param arguments Application arguments + * + * Unlike above, the context is not created and must be created later + * with @ref createContext() or @ref tryCreateContext(). + */ explicit WindowlessEglApplication(const Arguments& arguments, std::nullptr_t); /** @brief Copying is not allowed */ @@ -144,7 +159,14 @@ class WindowlessEglApplication { thus this is faster than public pure virtual destructor */ ~WindowlessEglApplication(); - /** @copydoc Sdl2Application::createContext() */ + /** + * @brief Create context with given configuration + * + * Must be called if and only if the context wasn't created by the + * constructor itself. Error message is printed and the program exits + * if the context cannot be created, see @ref tryCreateContext() for an + * alternative. + */ #ifdef DOXYGEN_GENERATING_OUTPUT void createContext(const Configuration& configuration = Configuration()); #else @@ -153,7 +175,12 @@ class WindowlessEglApplication { void createContext(); #endif - /** @copydoc Sdl2Application::tryCreateContext() */ + /** + * @brief Try to create context with given configuration + * + * Unlike @ref createContext() returns `false` if the context cannot be + * created, `true` otherwise. + */ bool tryCreateContext(const Configuration& configuration); private: diff --git a/src/Magnum/Platform/WindowlessGlxApplication.h b/src/Magnum/Platform/WindowlessGlxApplication.h index bdc2d9ee2..0e7325957 100644 --- a/src/Magnum/Platform/WindowlessGlxApplication.h +++ b/src/Magnum/Platform/WindowlessGlxApplication.h @@ -109,7 +109,16 @@ class WindowlessGlxApplication { class Configuration; - /** @copydoc Sdl2Application::Sdl2Application(const Arguments&, const Configuration&) */ + /** + * @brief Default constructor + * @param arguments Application arguments + * @param configuration Configuration + * + * Creates application with default or user-specified configuration. + * See @ref Configuration for more information. The program exits if + * the context cannot be created, see @ref tryCreateContext() for an + * alternative. + */ #ifdef DOXYGEN_GENERATING_OUTPUT explicit WindowlessGlxApplication(const Arguments& arguments, const Configuration& configuration = Configuration()); #else @@ -118,7 +127,13 @@ class WindowlessGlxApplication { explicit WindowlessGlxApplication(const Arguments& arguments); #endif - /** @copydoc Sdl2Application::Sdl2Application(const Arguments&, std::nullptr_t) */ + /** + * @brief Constructor + * @param arguments Application arguments + * + * Unlike above, the context is not created and must be created later + * with @ref createContext() or @ref tryCreateContext(). + */ explicit WindowlessGlxApplication(const Arguments& arguments, std::nullptr_t); /** @brief Copying is not allowed */ @@ -147,7 +162,23 @@ class WindowlessGlxApplication { thus this is faster than public pure virtual destructor */ ~WindowlessGlxApplication(); - /** @copydoc Sdl2Application::createContext() */ + /** + * @brief Create context with given configuration + * + * Must be called if and only if the context wasn't created by the + * constructor itself. Error message is printed and the program exits + * if the context cannot be created, see @ref tryCreateContext() for an + * alternative. + * + * On desktop GL, if version is not specified in @p configuration, the + * application first tries to create core context (OpenGL 3.1+) and if + * that fails, falls back to compatibility OpenGL 2.1 context. However, + * on binary AMD and NVidia drivers, creating core context does not use + * the largest available version. If the application detects such case, + * the core context is destroyed and compatibility OpenGL 2.1 context + * is created instead to make the driver use the latest available + * version. + */ #ifdef DOXYGEN_GENERATING_OUTPUT void createContext(const Configuration& configuration = Configuration()); #else @@ -156,7 +187,12 @@ class WindowlessGlxApplication { void createContext(); #endif - /** @copydoc Sdl2Application::tryCreateContext() */ + /** + * @brief Try to create context with given configuration + * + * Unlike @ref createContext() returns `false` if the context cannot be + * created, `true` otherwise. + */ bool tryCreateContext(const Configuration& configuration); private: diff --git a/src/Magnum/Platform/WindowlessIosApplication.h b/src/Magnum/Platform/WindowlessIosApplication.h index aa08accdb..459afc39a 100644 --- a/src/Magnum/Platform/WindowlessIosApplication.h +++ b/src/Magnum/Platform/WindowlessIosApplication.h @@ -102,7 +102,16 @@ class WindowlessIosApplication { class Configuration; - /** @copydoc Sdl2Application::Sdl2Application(const Arguments&, const Configuration&) */ + /** + * @brief Default constructor + * @param arguments Application arguments + * @param configuration Configuration + * + * Creates application with default or user-specified configuration. + * See @ref Configuration for more information. The program exits if + * the context cannot be created, see @ref tryCreateContext() for an + * alternative. + */ #ifdef DOXYGEN_GENERATING_OUTPUT explicit WindowlessIosApplication(const Arguments& arguments, const Configuration& configuration = Configuration()); #else @@ -111,7 +120,13 @@ class WindowlessIosApplication { explicit WindowlessIosApplication(const Arguments& arguments); #endif - /** @copydoc Sdl2Application::Sdl2Application(const Arguments&, std::nullptr_t) */ + /** + * @brief Constructor + * @param arguments Application arguments + * + * Unlike above, the context is not created and must be created later + * with @ref createContext() or @ref tryCreateContext(). + */ explicit WindowlessIosApplication(const Arguments& arguments, std::nullptr_t); /** @brief Copying is not allowed */ @@ -140,7 +155,14 @@ class WindowlessIosApplication { thus this is faster than public pure virtual destructor */ ~WindowlessIosApplication(); - /** @copydoc Sdl2Application::createContext() */ + /** + * @brief Create context with given configuration + * + * Must be called if and only if the context wasn't created by the + * constructor itself. Error message is printed and the program exits + * if the context cannot be created, see @ref tryCreateContext() for an + * alternative. + */ #ifdef DOXYGEN_GENERATING_OUTPUT void createContext(const Configuration& configuration = Configuration()); #else @@ -149,7 +171,12 @@ class WindowlessIosApplication { void createContext(); #endif - /** @copydoc Sdl2Application::tryCreateContext() */ + /** + * @brief Try to create context with given configuration + * + * Unlike @ref createContext() returns `false` if the context cannot be + * created, `true` otherwise. + */ bool tryCreateContext(const Configuration& configuration); private: diff --git a/src/Magnum/Platform/WindowlessNaClApplication.h b/src/Magnum/Platform/WindowlessNaClApplication.h index 1156a16dd..b130f475a 100644 --- a/src/Magnum/Platform/WindowlessNaClApplication.h +++ b/src/Magnum/Platform/WindowlessNaClApplication.h @@ -113,7 +113,16 @@ class WindowlessNaClApplication: public pp::Instance, public pp::Graphics3DClien class Configuration; - /** @copydoc Sdl2Application::Sdl2Application(const Arguments&, const Configuration&) */ + /** + * @brief Default constructor + * @param arguments Application arguments + * @param configuration Configuration + * + * Creates application with default or user-specified configuration. + * See @ref Configuration for more information. The program exits if + * the context cannot be created, see @ref tryCreateContext() for an + * alternative. + */ #ifdef DOXYGEN_GENERATING_OUTPUT explicit WindowlessNaClApplication(const Arguments& arguments, const Configuration& configuration = Configuration()); #else @@ -122,7 +131,13 @@ class WindowlessNaClApplication: public pp::Instance, public pp::Graphics3DClien explicit WindowlessNaClApplication(const Arguments& arguments); #endif - /** @copydoc Sdl2Application::Sdl2Application(const Arguments&, std::nullptr_t) */ + /** + * @brief Constructor + * @param arguments Application arguments + * + * Unlike above, the context is not created and must be created later + * with @ref createContext() or @ref tryCreateContext(). + */ explicit WindowlessNaClApplication(const Arguments& arguments, std::nullptr_t); /** @brief Copying is not allowed */ @@ -156,7 +171,14 @@ class WindowlessNaClApplication: public pp::Instance, public pp::Graphics3DClien thus this is faster than public pure virtual destructor */ ~WindowlessNaClApplication(); - /** @copydoc Sdl2Application::createContext() */ + /** + * @brief Create context with given configuration + * + * Must be called if and only if the context wasn't created by the + * constructor itself. Error message is printed and the program exits + * if the context cannot be created, see @ref tryCreateContext() for an + * alternative. + */ #ifdef DOXYGEN_GENERATING_OUTPUT void createContext(const Configuration& configuration = Configuration()); #else @@ -165,7 +187,12 @@ class WindowlessNaClApplication: public pp::Instance, public pp::Graphics3DClien void createContext(); #endif - /** @copydoc Sdl2Application::tryCreateContext() */ + /** + * @brief Try to create context with given configuration + * + * Unlike @ref createContext() returns `false` if the context cannot be + * created, `true` otherwise. + */ bool tryCreateContext(const Configuration& configuration); private: diff --git a/src/Magnum/Platform/WindowlessWglApplication.h b/src/Magnum/Platform/WindowlessWglApplication.h index d5cfd2545..0b5b4f6d4 100644 --- a/src/Magnum/Platform/WindowlessWglApplication.h +++ b/src/Magnum/Platform/WindowlessWglApplication.h @@ -117,7 +117,16 @@ class WindowlessWglApplication { static int create(LRESULT(CALLBACK windowProcedure)(HWND, UINT, WPARAM, LPARAM)); #endif - /** @copydoc Sdl2Application::Sdl2Application(const Arguments&, const Configuration&) */ + /** + * @brief Default constructor + * @param arguments Application arguments + * @param configuration Configuration + * + * Creates application with default or user-specified configuration. + * See @ref Configuration for more information. The program exits if + * the context cannot be created, see @ref tryCreateContext() for an + * alternative. + */ #ifdef DOXYGEN_GENERATING_OUTPUT explicit WindowlessWglApplication(const Arguments& arguments, const Configuration& configuration = Configuration()); #else @@ -126,7 +135,13 @@ class WindowlessWglApplication { explicit WindowlessWglApplication(const Arguments& arguments); #endif - /** @copydoc Sdl2Application::Sdl2Application(const Arguments&, std::nullptr_t) */ + /** + * @brief Constructor + * @param arguments Application arguments + * + * Unlike above, the context is not created and must be created later + * with @ref createContext() or @ref tryCreateContext(). + */ explicit WindowlessWglApplication(const Arguments& arguments, std::nullptr_t); /** @brief Copying is not allowed */ @@ -155,7 +170,23 @@ class WindowlessWglApplication { thus this is faster than public pure virtual destructor */ ~WindowlessWglApplication(); - /** @copydoc Sdl2Application::createContext() */ + /** + * @brief Create context with given configuration + * + * Must be called if and only if the context wasn't created by the + * constructor itself. Error message is printed and the program exits + * if the context cannot be created, see @ref tryCreateContext() for an + * alternative. + * + * On desktop GL, if version is not specified in @p configuration, the + * application first tries to create core context (OpenGL 3.1+) and if + * that fails, falls back to compatibility OpenGL 2.1 context. However, + * on binary AMD and NVidia drivers, creating core context does not use + * the largest available version. If the application detects such case, + * the core context is destroyed and compatibility OpenGL 2.1 context + * is created instead to make the driver use the latest available + * version. + */ #ifdef DOXYGEN_GENERATING_OUTPUT void createContext(const Configuration& configuration = Configuration()); #else @@ -164,7 +195,12 @@ class WindowlessWglApplication { void createContext(); #endif - /** @copydoc Sdl2Application::tryCreateContext() */ + /** + * @brief Try to create context with given configuration + * + * Unlike @ref createContext() returns `false` if the context cannot be + * created, `true` otherwise. + */ bool tryCreateContext(const Configuration& configuration); private: diff --git a/src/Magnum/Platform/WindowlessWindowsEglApplication.h b/src/Magnum/Platform/WindowlessWindowsEglApplication.h index 3910d8be1..87c6e663f 100644 --- a/src/Magnum/Platform/WindowlessWindowsEglApplication.h +++ b/src/Magnum/Platform/WindowlessWindowsEglApplication.h @@ -112,7 +112,16 @@ class WindowlessWindowsEglApplication { static int create(LRESULT(CALLBACK windowProcedure)(HWND, UINT, WPARAM, LPARAM)); #endif - /** @copydoc Sdl2Application::Sdl2Application(const Arguments&, const Configuration&) */ + /** + * @brief Default constructor + * @param arguments Application arguments + * @param configuration Configuration + * + * Creates application with default or user-specified configuration. + * See @ref Configuration for more information. The program exits if + * the context cannot be created, see @ref tryCreateContext() for an + * alternative. + */ #ifdef DOXYGEN_GENERATING_OUTPUT explicit WindowlessWindowsEglApplication(const Arguments& arguments, const Configuration& configuration = Configuration()); #else @@ -121,7 +130,13 @@ class WindowlessWindowsEglApplication { explicit WindowlessWindowsEglApplication(const Arguments& arguments); #endif - /** @copydoc Sdl2Application::Sdl2Application(const Arguments&, std::nullptr_t) */ + /** + * @brief Constructor + * @param arguments Application arguments + * + * Unlike above, the context is not created and must be created later + * with @ref createContext() or @ref tryCreateContext(). + */ explicit WindowlessWindowsEglApplication(const Arguments& arguments, std::nullptr_t); /** @brief Copying is not allowed */ @@ -150,7 +165,14 @@ class WindowlessWindowsEglApplication { thus this is faster than public pure virtual destructor */ ~WindowlessWindowsEglApplication(); - /** @copydoc Sdl2Application::createContext() */ + /** + * @brief Create context with given configuration + * + * Must be called if and only if the context wasn't created by the + * constructor itself. Error message is printed and the program exits + * if the context cannot be created, see @ref tryCreateContext() for an + * alternative. + */ #ifdef DOXYGEN_GENERATING_OUTPUT void createContext(const Configuration& configuration = Configuration()); #else @@ -159,7 +181,12 @@ class WindowlessWindowsEglApplication { void createContext(); #endif - /** @copydoc Sdl2Application::tryCreateContext() */ + /** + * @brief Try to create context with given configuration + * + * Unlike @ref createContext() returns `false` if the context cannot be + * created, `true` otherwise. + */ bool tryCreateContext(const Configuration& configuration); private: