diff --git a/intern/ghost/GHOST_IContext.hh b/intern/ghost/GHOST_IContext.hh index 6b941954905..83fe7f4917f 100644 --- a/intern/ghost/GHOST_IContext.hh +++ b/intern/ghost/GHOST_IContext.hh @@ -46,7 +46,15 @@ class GHOST_IContext { */ virtual GHOST_TSuccess releaseDrawingContext() = 0; + /** + * Gets the OpenGL frame-buffer associated with the OpenGL context + * \return The ID of an OpenGL frame-buffer object. + */ virtual unsigned int getDefaultFramebuffer() = 0; + /** + * Swaps front and back buffers of a window. + * \return A boolean success indicator. + */ virtual GHOST_TSuccess swapBuffers() = 0; #ifdef WITH_VULKAN_BACKEND diff --git a/intern/ghost/GHOST_ISystem.hh b/intern/ghost/GHOST_ISystem.hh index 1e7786cc625..2d4997b5677 100644 --- a/intern/ghost/GHOST_ISystem.hh +++ b/intern/ghost/GHOST_ISystem.hh @@ -180,10 +180,12 @@ class GHOST_ISystem { /** * Installs a timer. - * Note that, on most operating systems, messages need to be processed in order + * + * \note On most operating systems, messages need to be processed in order * for the timer callbacks to be invoked. - * \param delay: The time to wait for the first call to the timerProc (in milliseconds). - * \param interval: The interval between calls to the timerProc (in milliseconds). + * + * \param delay: The time to wait for the first call to the #timerProc (in milliseconds). + * \param interval: The interval between calls to the #timerProc. * \param timerProc: The callback invoked when the interval expires. * \param userData: Placeholder for user data. * \return A timer task (0 if timer task installation failed). @@ -280,6 +282,7 @@ class GHOST_ISystem { /** * Native pixel size support (MacBook 'retina'). + * \return The pixel size in float. */ virtual bool useNativePixel() = 0; @@ -324,6 +327,7 @@ class GHOST_ISystem { /** * Retrieves events from the queue and send them to the event consumers. + * The event stack will be empty afterwards. */ virtual void dispatchEvents() = 0; @@ -427,7 +431,7 @@ class GHOST_ISystem { #ifdef WITH_INPUT_NDOF /** - * Sets 3D mouse deadzone + * Sets 3D mouse dead-zone. * \param deadzone: Dead-zone of the 3D mouse (both for rotation and pan) relative to full range */ virtual void setNDOFDeadZone(float deadzone) = 0; @@ -455,6 +459,8 @@ class GHOST_ISystem { /** * Put data to the Clipboard + * \param buffer: The buffer to copy to the clipboard. + * \param selection: The clipboard to copy too only used on X11. */ virtual void putClipboard(const char *buffer, bool selection) const = 0; diff --git a/intern/ghost/GHOST_IWindow.hh b/intern/ghost/GHOST_IWindow.hh index 50c86ed7a0b..6fd992f3f90 100644 --- a/intern/ghost/GHOST_IWindow.hh +++ b/intern/ghost/GHOST_IWindow.hh @@ -45,8 +45,8 @@ class GHOST_IWindow { virtual bool getValid() const = 0; /** - * Returns the associated OS object/handle - * \return The associated OS object/handle + * Returns the associated OS object/handle. + * \return The associated OS object/handle. */ virtual void *getOSWindow() const = 0; @@ -167,8 +167,8 @@ class GHOST_IWindow { virtual void setAcceptDragOperation(bool canAccept) = 0; /** - * Returns acceptance of the dropped object - * Usually called by the "object dropped" event handling function + * Returns acceptance of the dropped object. + * Usually called by the "object dropped" event handling function. */ virtual bool canAcceptDragOperation() const = 0; @@ -186,14 +186,14 @@ class GHOST_IWindow { virtual GHOST_TSuccess setState(GHOST_TWindowState state) = 0; /** - * Sets the window "modified" status, indicating unsaved changes + * Sets the window "modified" status, indicating unsaved changes. * \param isUnsavedChanges: Unsaved changes or not. * \return Indication of success. */ virtual GHOST_TSuccess setModifiedState(bool isUnsavedChanges) = 0; /** - * Gets the window "modified" status, indicating unsaved changes + * Gets the window "modified" status, indicating unsaved changes. * \return True if there are unsaved changes */ virtual bool getModifiedState() = 0; @@ -239,6 +239,7 @@ class GHOST_IWindow { virtual unsigned int getDefaultFramebuffer() = 0; #ifdef WITH_VULKAN_BACKEND + /** \copydoc #GHOST_GetVulkanSwapChainFormat */ virtual GHOST_TSuccess getVulkanSwapChainFormat( GHOST_VulkanSwapChainData *r_swap_chain_data) = 0; #endif @@ -274,7 +275,7 @@ class GHOST_IWindow { virtual GHOST_TSuccess setProgressBar(float progress) = 0; /** - * Hides the progress bar in the icon + * Hides the progress bar in the icon. */ virtual GHOST_TSuccess endProgressBar() = 0; @@ -295,6 +296,10 @@ class GHOST_IWindow { */ virtual GHOST_TSuccess setCursorShape(GHOST_TStandardCursor cursorShape) = 0; + /** + * Gets the cursor grab region, if unset the window is used. + * reset when grab is disabled. + */ virtual GHOST_TSuccess getCursorGrabBounds(GHOST_Rect &bounds) const = 0; virtual void getCursorGrabState(GHOST_TGrabCursorMode &mode, @@ -302,6 +307,9 @@ class GHOST_IWindow { GHOST_Rect &bounds, bool &use_software_cursor) = 0; + /** + * Return true when a software cursor should be used. + */ virtual bool getCursorGrabUseSoftwareDisplay() = 0; /** @@ -354,6 +362,9 @@ class GHOST_IWindow { return GHOST_kSuccess; } + /** + * If this window was opened using native pixel size, return the scaling factor. + */ virtual float getNativePixelSize() = 0; /** diff --git a/intern/ghost/GHOST_Types.h b/intern/ghost/GHOST_Types.h index 3ae984af100..2765d98d7cf 100644 --- a/intern/ghost/GHOST_Types.h +++ b/intern/ghost/GHOST_Types.h @@ -850,12 +850,23 @@ typedef struct { } GHOST_VulkanOpenXRData; +/** + * Return argument passed to #GHOST_IContext:::getVulkanHandles. + * + * The members of this struct are assigned values. + */ typedef struct { + /** The instance handle. */ VkInstance instance; + /** The physics device handle. */ VkPhysicalDevice physical_device; + /** The device handle. */ VkDevice device; + /** The graphic queue family id. */ uint32_t graphic_queue_family; + /** The queue handle. */ VkQueue queue; + /** The #std::mutex mutex. */ void *queue_mutex; } GHOST_VulkanHandles; diff --git a/intern/ghost/intern/GHOST_Context.hh b/intern/ghost/intern/GHOST_Context.hh index d37d8608b8c..a4bcfc17906 100644 --- a/intern/ghost/intern/GHOST_Context.hh +++ b/intern/ghost/intern/GHOST_Context.hh @@ -43,22 +43,13 @@ class GHOST_Context : public GHOST_IContext { return active_context_; } - /** - * Swaps front and back buffers of a window. - * \return A boolean success indicator. - */ + /** \copydoc #GHOST_IContext::swapBuffers */ GHOST_TSuccess swapBuffers() override = 0; - /** - * Activates the drawing context of this window. - * \return A boolean success indicator. - */ + /** \copydoc #GHOST_IContext::activateDrawingContext */ GHOST_TSuccess activateDrawingContext() override = 0; - /** - * Release the drawing context of the calling thread. - * \return A boolean success indicator. - */ + /** \copydoc #GHOST_IContext::releaseDrawingContext */ GHOST_TSuccess releaseDrawingContext() override = 0; /** @@ -137,57 +128,26 @@ class GHOST_Context : public GHOST_IContext { return false; } - /** - * Gets the OpenGL frame-buffer associated with the OpenGL context - * \return The ID of an OpenGL frame-buffer object. - */ + /** \copydoc #GHOST_IContext::getDefaultFramebuffer */ unsigned int getDefaultFramebuffer() override { return 0; } #ifdef WITH_VULKAN_BACKEND - /** - * Get Vulkan handles for the given context. - * - * These handles are the same for a given context. - * Should only be called when using a Vulkan context. - * Other contexts will not return any handles and leave the - * handles where the parameters are referring to unmodified. - * - * \param r_instance: After calling this function the VkInstance - * referenced by this parameter will contain the VKInstance handle - * of the context associated with the `context` parameter. - * \param r_physical_device: After calling this function the VkPhysicalDevice - * referenced by this parameter will contain the VKPhysicalDevice handle - * of the context associated with the `context` parameter. - * \param r_device: After calling this function the VkDevice - * referenced by this parameter will contain the VKDevice handle - * of the context associated with the `context` parameter. - * \param r_graphic_queue_family: After calling this function the uint32_t - * referenced by this parameter will contain the graphic queue family id - * of the context associated with the `context` parameter. - * \param r_queue: After calling this function the VkQueue - * referenced by this parameter will contain the VKQueue handle - * of the context associated with the `context` parameter. - * \param r_queue_mutex: After calling this function the std::mutex referred - * by this parameter will contain the mutex of the context associated - * with the context parameter. - * \returns GHOST_kFailure when context isn't a Vulkan context. - * GHOST_kSuccess when the context is a Vulkan context and the - * handles have been set. - */ + /** \copydoc #GHOST_IContext::getVulkanHandles */ virtual GHOST_TSuccess getVulkanHandles(GHOST_VulkanHandles & /* r_handles */) override { return GHOST_kFailure; }; - + /** \copydoc #GHOST_IContext::getVulkanSwapChainFormat */ virtual GHOST_TSuccess getVulkanSwapChainFormat( GHOST_VulkanSwapChainData * /*r_swap_chain_data*/) override { return GHOST_kFailure; } + /** \copydoc #GHOST_IContext::setVulkanSwapBuffersCallbacks */ virtual GHOST_TSuccess setVulkanSwapBuffersCallbacks( std::function /*swap_buffers_pre_callback*/, std::function /*swap_buffers_post_callback*/, diff --git a/intern/ghost/intern/GHOST_Event.hh b/intern/ghost/intern/GHOST_Event.hh index 0458147bf3e..1a09f7ef407 100644 --- a/intern/ghost/intern/GHOST_Event.hh +++ b/intern/ghost/intern/GHOST_Event.hh @@ -27,38 +27,25 @@ class GHOST_Event : public GHOST_IEvent { { } - /** - * Returns the event type. - * \return The event type. - */ + /** \copydoc #GHOST_IEvent::getType */ GHOST_TEventType getType() const override { return m_type; } - /** - * Returns the time this event was generated. - * \return The event generation time. - */ + /** \copydoc #GHOST_IEvent::getTime */ uint64_t getTime() const override { return m_time; } - /** - * Returns the window this event was generated on, - * or nullptr if it is a 'system' event. - * \return The generating window. - */ + /** \copydoc #GHOST_IEvent::getWindow */ GHOST_IWindow *getWindow() const override { return m_window; } - /** - * Returns the event data. - * \return The event data. - */ + /** \copydoc #GHOST_IEvent::getData */ GHOST_TEventDataPtr getData() const override { return m_data; diff --git a/intern/ghost/intern/GHOST_System.hh b/intern/ghost/intern/GHOST_System.hh index 7e3b7817b1c..9a4baf99e7e 100644 --- a/intern/ghost/intern/GHOST_System.hh +++ b/intern/ghost/intern/GHOST_System.hh @@ -53,81 +53,41 @@ class GHOST_System : public GHOST_ISystem { * Time(r) functionality ***************************************************************************************/ - /** - * Installs a timer. - * - * \note On most operating systems, messages need to be processed in order - * for the timer callbacks to be invoked. - * - * \param delay: The time to wait for the first call to the #timerProc (in milliseconds). - * \param interval: The interval between calls to the #timerProc. - * \param timerProc: The callback invoked when the interval expires. - * \param userData: Placeholder for user data. - * \return A timer task (0 if timer task installation failed). - */ + /** \copydoc #GHOST_ISystem::installTimer */ GHOST_ITimerTask *installTimer(uint64_t delay, uint64_t interval, GHOST_TimerProcPtr timerProc, GHOST_TUserDataPtr userData = nullptr) override; - - /** - * Removes a timer. - * \param timerTask: Timer task to be removed. - * \return Indication of success. - */ + /** \copydoc #GHOST_ISystem::removeTimer */ GHOST_TSuccess removeTimer(GHOST_ITimerTask *timerTask) override; /*************************************************************************************** * Display/window management functionality ***************************************************************************************/ - /** - * Dispose a window. - * \param window: Pointer to the window to be disposed. - * \return Indication of success. - */ + /** \copydoc #GHOST_ISystem::disposeWindow */ GHOST_TSuccess disposeWindow(GHOST_IWindow *window) override; - /** - * Create a new off-screen context. - * Never explicitly delete the context, use #disposeContext() instead. - * \return The new context (or 0 if creation failed). - */ + /** \copydoc #GHOST_ISystem::createOffscreenContext */ GHOST_IContext *createOffscreenContext(GHOST_GPUSettings gpuSettings) override = 0; - /** - * Returns whether a window is valid. - * \param window: Pointer to the window to be checked. - * \return Indication of validity. - */ + /** \copydoc #GHOST_ISystem::validWindow */ bool validWindow(GHOST_IWindow *window) override; - /** - * Native pixel size support (MacBook 'retina'). - * \return The pixel size in float. - */ + /** \copydoc #GHOST_ISystem::useNativePixel */ bool useNativePixel() override; bool m_nativePixel; - /** - * Focus window after opening, or put them in the background. - */ + /** \copydoc #GHOST_ISystem::useWindowFocus */ void useWindowFocus(const bool use_focus) override; bool m_windowFocus; - /** - * Focus and raise windows on mouse hover. - */ + /** \copydoc #GHOST_ISystem::setAutoFocus */ void setAutoFocus(const bool auto_focus) override; bool m_autoFocus; - /** - * Get the Window under the cursor. - * \param x: The x-coordinate of the cursor. - * \param y: The y-coordinate of the cursor. - * \return The window under the cursor or nullptr if none. - */ + /** \copydoc #GHOST_ISystem::getWindowUnderCursor */ GHOST_IWindow *getWindowUnderCursor(int32_t x, int32_t y) override; /*************************************************************************************** @@ -137,27 +97,16 @@ class GHOST_System : public GHOST_ISystem { /** * Inherited from GHOST_ISystem but left pure virtual * + * 
    * virtual bool processEvents(bool waitForEvent) = 0;
+   *
*/ - /** - * Dispatches all the events on the stack. - * The event stack will be empty afterwards. - */ + /** \copydoc #GHOST_ISystem::dispatchEvents */ void dispatchEvents() override; - - /** - * Adds the given event consumer to our list. - * \param consumer: The event consumer to add. - * \return Indication of success. - */ + /** \copydoc #GHOST_ISystem::addEventConsumer */ GHOST_TSuccess addEventConsumer(GHOST_IEventConsumer *consumer) override; - - /** - * Remove the given event consumer to our list. - * \param consumer: The event consumer to remove. - * \return Indication of success. - */ + /** \copydoc #GHOST_ISystem::removeEventConsumer */ GHOST_TSuccess removeEventConsumer(GHOST_IEventConsumer *consumer) override; /*************************************************************************************** @@ -168,13 +117,16 @@ class GHOST_System : public GHOST_ISystem { * that converts from screen-coordinates to client coordinates. * Implementations may override. */ + /** \copydoc #GHOST_ISystem::getCursorPositionClientRelative */ GHOST_TSuccess getCursorPositionClientRelative(const GHOST_IWindow *window, int32_t &x, int32_t &y) const override; + /** \copydoc #GHOST_ISystem::setCursorPositionClientRelative */ GHOST_TSuccess setCursorPositionClientRelative(GHOST_IWindow *window, int32_t x, int32_t y) override; + /** \copydoc #GHOST_ISystem::getCursorPreferredLogicalSize */ uint32_t getCursorPreferredLogicalSize() const override; /** @@ -189,40 +141,20 @@ class GHOST_System : public GHOST_ISystem { * Access to mouse button and keyboard states. ***************************************************************************************/ - /** - * Returns the state of a modifier key (outside the message queue). - * \param mask: The modifier key state to retrieve. - * \param isDown: The state of a modifier key (true == pressed). - * \return Indication of success. - */ + /** \copydoc #GHOST_ISystem::getModifierKeyState */ GHOST_TSuccess getModifierKeyState(GHOST_TModifierKey mask, bool &isDown) const override; - /** - * Returns the state of a mouse button (outside the message queue). - * \param mask: The button state to retrieve. - * \param isDown: Button state. - * \return Indication of success. - */ + /** \copydoc #GHOST_ISystem::getButtonState */ GHOST_TSuccess getButtonState(GHOST_TButton mask, bool &isDown) const override; - /** - * Enable multi-touch gestures if supported. - * \param use: Enable or disable. - */ + /** \copydoc #GHOST_ISystem::setMultitouchGestures */ void setMultitouchGestures(const bool use) override; - /** - * Set which tablet API to use. Only affects Windows, other platforms have a single API. - * \param api: Enum indicating which API to use. - */ + /** \copydoc #GHOST_ISystem::setTabletAPI */ void setTabletAPI(GHOST_TTabletAPI api) override; GHOST_TTabletAPI getTabletAPI(); - /** - * Get the color of the pixel at the current mouse cursor location - * \param r_color: returned sRGB float colors - * \return Success value (true == successful and supported by platform) - */ + /** \copydoc #GHOST_ISystem::getPixelAtCursor */ GHOST_TSuccess getPixelAtCursor(float r_color[3]) const override; #ifdef WITH_INPUT_NDOF @@ -230,13 +162,36 @@ class GHOST_System : public GHOST_ISystem { * Access to 3D mouse. ***************************************************************************************/ - /** - * Sets 3D mouse dead-zone - * \param deadzone: Dead-zone of the 3D mouse (both for rotation and pan) relative to full range. - */ + /** \copydoc #GHOST_ISystem::setNDOFDeadZone */ void setNDOFDeadZone(float deadzone) override; #endif + /*************************************************************************************** + * Access to the Clipboard + ***************************************************************************************/ + + /** \copydoc #GHOST_ISystem::getClipboard */ + char *getClipboard(bool selection) const override = 0; + /** \copydoc #GHOST_ISystem::putClipboard */ + void putClipboard(const char *buffer, bool selection) const override = 0; + /** \copydoc #GHOST_ISystem::hasClipboardImage */ + GHOST_TSuccess hasClipboardImage() const override; + /** \copydoc #GHOST_ISystem::getClipboardImage */ + uint *getClipboardImage(int *r_width, int *r_height) const override; + /** \copydoc #GHOST_ISystem::putClipboardImage */ + GHOST_TSuccess putClipboardImage(uint *rgba, int width, int height) const override; + + /** \copydoc #GHOST_ISystem::showMessageBox */ + GHOST_TSuccess showMessageBox(const char * /*title*/, + const char * /*message*/, + const char * /*help_label*/, + const char * /*continue_label*/, + const char * /*link*/, + GHOST_DialogOptions /*dialog_options*/) const override + { + return GHOST_kFailure; + }; + /*************************************************************************************** * Other (internal) functionality. ***************************************************************************************/ @@ -285,86 +240,20 @@ class GHOST_System : public GHOST_ISystem { */ virtual GHOST_TSuccess getButtons(GHOST_Buttons &buttons) const = 0; - /** - * Returns the selection buffer - * \param selection: Only used on X11. - * \return Returns the clipboard data - */ - char *getClipboard(bool selection) const override = 0; - - /** - * Put data to the Clipboard - * \param buffer: The buffer to copy to the clipboard. - * \param selection: The clipboard to copy too only used on X11. - */ - void putClipboard(const char *buffer, bool selection) const override = 0; - - /** - * Returns GHOST_kSuccess if the clipboard contains an image. - */ - GHOST_TSuccess hasClipboardImage() const override; - - /** - * Get image data from the Clipboard - * \param r_width: the returned image width in pixels. - * \param r_height: the returned image height in pixels. - * \return pointer uint array in RGBA byte order. Caller must free. - */ - uint *getClipboardImage(int *r_width, int *r_height) const override; - - /** - * Put image data to the Clipboard - * \param rgba: uint array in RGBA byte order. - * \param width: the image width in pixels. - * \param height: the image height in pixels. - */ - GHOST_TSuccess putClipboardImage(uint *rgba, int width, int height) const override; - - /** - * Show a system message box - * \param title: The title of the message box. - * \param message: The message to display. - * \param help_label: Help button label. - * \param continue_label: Continue button label. - * \param link: An optional hyperlink. - * \param dialog_options: Options how to display the message. - */ - GHOST_TSuccess showMessageBox(const char * /*title*/, - const char * /*message*/, - const char * /*help_label*/, - const char * /*continue_label*/, - const char * /*link*/, - GHOST_DialogOptions /*dialog_options*/) const override - { - return GHOST_kFailure; - }; - /*************************************************************************************** * Debugging ***************************************************************************************/ - /** - * Specify whether debug messages are to be shown. - * \param debug: Flag for systems to debug. - */ + /** \copydoc #GHOST_ISystem::initDebug */ void initDebug(GHOST_Debug debug) override; - /** - * Check whether debug messages are to be shown. - */ + /** \copydoc #GHOST_ISystem::isDebugEnabled */ bool isDebugEnabled() override; protected: - /** - * Initialize the system. - * \return Indication of success. - */ + /** \copydoc #GHOST_ISystem::init */ GHOST_TSuccess init() override; - - /** - * Shut the system down. - * \return Indication of success. - */ + /** \copydoc #GHOST_ISystem::exit */ GHOST_TSuccess exit() override; /** The timer manager. */ @@ -381,12 +270,12 @@ class GHOST_System : public GHOST_ISystem { GHOST_NDOFManager *m_ndofManager; #endif - /** Prints all the events. */ #ifdef WITH_GHOST_DEBUG + /** Prints all the events. */ GHOST_EventPrinter *m_eventPrinter; #endif // WITH_GHOST_DEBUG - /* Use multi-touch gestures? */ + /** Use multi-touch gestures. */ bool m_multitouchGestures; /** Which tablet API to use. */ diff --git a/intern/ghost/intern/GHOST_SystemPaths.hh b/intern/ghost/intern/GHOST_SystemPaths.hh index 8971e72a898..7785de7a537 100644 --- a/intern/ghost/intern/GHOST_SystemPaths.hh +++ b/intern/ghost/intern/GHOST_SystemPaths.hh @@ -25,28 +25,12 @@ class GHOST_SystemPaths : public GHOST_ISystemPaths { ~GHOST_SystemPaths() override = default; public: - /** - * Determine the base directory in which shared resources are located. It will first try to use - * "unpack and run" path, then look for properly installed path, including versioning. - * \return Unsigned char string pointing to system directory (eg `/usr/share/blender/`). - */ + /** \copydoc #GHOST_SystemPaths::getSystemDir */ const char *getSystemDir(int version, const char *versionstr) const override = 0; - - /** - * Determine the base directory in which user configuration is stored, including versioning. - * If needed, it will create the base directory. - * \return Unsigned char string pointing to user directory (eg `~/.blender/`). - */ + /** \copydoc #GHOST_SystemPaths::getUserDir */ const char *getUserDir(int version, const char *versionstr) const override = 0; - - /** - * Determine the directory of the current binary. - * \return Unsigned char string pointing to the binary directory. - */ + /** \copydoc #GHOST_SystemPaths::getBinaryDir */ const char *getBinaryDir() const override = 0; - - /** - * Add the file to the operating system most recently used files - */ + /** \copydoc #GHOST_SystemPaths::addToSystemRecentFiles */ void addToSystemRecentFiles(const char *filepath) const override = 0; }; diff --git a/intern/ghost/intern/GHOST_TimerTask.hh b/intern/ghost/intern/GHOST_TimerTask.hh index 8110660da1f..f3f6fdc3768 100644 --- a/intern/ghost/intern/GHOST_TimerTask.hh +++ b/intern/ghost/intern/GHOST_TimerTask.hh @@ -89,37 +89,25 @@ class GHOST_TimerTask : public GHOST_ITimerTask { m_next = next; } - /** - * Returns the timer callback. - * \return the timer callback. - */ + /** \copydoc #GHOST_ITimerTask::getTimerProc */ GHOST_TimerProcPtr getTimerProc() const override { return m_timerProc; } - /** - * Changes the timer callback. - * \param timerProc: The timer callback. - */ + /** \copydoc #GHOST_ITimerTask::setTimerProc */ void setTimerProc(const GHOST_TimerProcPtr timerProc) override { m_timerProc = timerProc; } - /** - * Returns the timer user data. - * \return The timer user data. - */ + /** \copydoc #GHOST_ITimerTask::getUserData */ GHOST_TUserDataPtr getUserData() const override { return m_userData; } - /** - * Changes the time user data. - * \param userData: The timer user data. - */ + /** \copydoc #GHOST_ITimerTask::setUserData */ void setUserData(const GHOST_TUserDataPtr userData) override { m_userData = userData; diff --git a/intern/ghost/intern/GHOST_Window.hh b/intern/ghost/intern/GHOST_Window.hh index 7c565864fca..e73aaa40fa3 100644 --- a/intern/ghost/intern/GHOST_Window.hh +++ b/intern/ghost/intern/GHOST_Window.hh @@ -69,57 +69,39 @@ class GHOST_Window : public GHOST_IWindow { */ ~GHOST_Window() override; - /** - * Returns indication as to whether the window is valid. - * \return The validity of the window. - */ + /** \copydoc #GHOST_IWindow::getValid */ bool getValid() const override { return m_context != nullptr; } - /** - * Returns the associated OS object/handle - * \return The associated OS object/handle - */ + /** \copydoc #GHOST_IWindow::getOSWindow */ void *getOSWindow() const override; + /** \copydoc #GHOST_IWindow::setPath */ GHOST_TSuccess setPath(const char * /*filepath*/) override { return GHOST_kFailure; } - /** - * Return the current window decoration style flags. - */ + /** \copydoc #GHOST_IWindow::getWindowDecorationStyleFlags */ virtual GHOST_TWindowDecorationStyleFlags getWindowDecorationStyleFlags() override; - /** - * Set the window decoration style flags. - * \param styleFlags: Window decoration style flags. - */ + /** \copydoc #GHOST_IWindow::setWindowDecorationStyleFlags */ virtual void setWindowDecorationStyleFlags( GHOST_TWindowDecorationStyleFlags styleFlags) override; - /** - * Set the window decoration style settings. - * \param decorationSettings: Window decoration style settings. - */ + /** \copydoc #GHOST_IWindow::setWindowDecorationStyleSettings */ virtual void setWindowDecorationStyleSettings( GHOST_WindowDecorationStyleSettings decorationSettings) override; - /** - * Apply the window decoration style using the current flags and settings. - */ + /** \copydoc #GHOST_IWindow::applyWindowDecorationStyle */ virtual GHOST_TSuccess applyWindowDecorationStyle() override { return GHOST_kSuccess; } - /** - * Returns the current cursor shape. - * \return The current cursor shape. - */ + /** \copydoc #GHOST_IWindow::getCursorShape */ inline GHOST_TStandardCursor getCursorShape() const override; bool isDialog() const override @@ -127,21 +109,10 @@ class GHOST_Window : public GHOST_IWindow { return false; } - /** - * Set the shape of the cursor. - * \param cursorShape: The new cursor shape type id. - * \return Indication of success. - */ + /** \copydoc #GHOST_IWindow::setCursorShape */ GHOST_TSuccess setCursorShape(GHOST_TStandardCursor cursorShape) override; - /** - * Set the shape of the cursor to a custom cursor. - * \param bitmap: The bitmap data for the cursor. - * \param mask: The mask data for the cursor. - * \param hotX: The X coordinate of the cursor hot-spot. - * \param hotY: The Y coordinate of the cursor hot-spot. - * \return Indication of success. - */ + /** \copydoc #GHOST_IWindow::setCustomCursorShape */ GHOST_TSuccess setCustomCursorShape(uint8_t *bitmap, uint8_t *mask, int sizex, @@ -152,10 +123,7 @@ class GHOST_Window : public GHOST_IWindow { GHOST_TSuccess getCursorBitmap(GHOST_CursorBitmapRef *bitmap) override; - /** - * Returns the visibility state of the cursor. - * \return The visibility state of the cursor. - */ + /** \copydoc #GHOST_IWindow::getCursorVisibility */ inline bool getCursorVisibility() const override; inline GHOST_TGrabCursorMode getCursorGrabMode() const; inline bool getCursorGrabModeIsWarp() const; @@ -164,123 +132,72 @@ class GHOST_Window : public GHOST_IWindow { inline void getCursorGrabAccum(int32_t &x, int32_t &y) const; inline void setCursorGrabAccum(int32_t x, int32_t y); - /** - * Shows or hides the cursor. - * \param visible: The new visibility state of the cursor. - * \return Indication of success. - */ + /** \copydoc #GHOST_IWindow::setCursorVisibility */ GHOST_TSuccess setCursorVisibility(bool visible) override; - /** - * Sets the cursor grab. - * \param mode: The new grab state of the cursor. - * \return Indication of success. - */ + /** \copydoc #GHOST_IWindow::setCursorGrab */ GHOST_TSuccess setCursorGrab(GHOST_TGrabCursorMode mode, GHOST_TAxisFlag wrap_axis, GHOST_Rect *bounds, int32_t mouse_ungrab_xy[2]) override; - /** - * Gets the cursor grab region, if unset the window is used. - * reset when grab is disabled. - */ + /** \copydoc #GHOST_IWindow::getCursorGrabBounds */ GHOST_TSuccess getCursorGrabBounds(GHOST_Rect &bounds) const override; void getCursorGrabState(GHOST_TGrabCursorMode &mode, GHOST_TAxisFlag &wrap_axis, GHOST_Rect &bounds, bool &use_software_cursor) override; - /** - * Return true when a software cursor should be used. - */ + /** \copydoc #GHOST_IWindow::getCursorGrabUseSoftwareDisplay */ bool getCursorGrabUseSoftwareDisplay() override; - /** - * Sets the progress bar value displayed in the window/application icon - * \param progress: The progress percentage (0.0 to 1.0). - */ + /** \copydoc #GHOST_IWindow::setProgressBar */ GHOST_TSuccess setProgressBar(float /*progress*/) override { return GHOST_kFailure; } - /** - * Hides the progress bar in the icon - */ + /** \copydoc #GHOST_IWindow::endProgressBar */ GHOST_TSuccess endProgressBar() override { return GHOST_kFailure; } - /** - * Sets the swap interval for #swapBuffers. - * \param interval: The swap interval to use. - * \return A boolean success indicator. - */ + /** \copydoc #GHOST_IWindow::setSwapInterval */ GHOST_TSuccess setSwapInterval(int interval) override; - - /** - * Gets the current swap interval for #swapBuffers. - * \return An integer. - */ + /** \copydoc #GHOST_IWindow::getSwapInterval */ GHOST_TSuccess getSwapInterval(int &intervalOut) override; - /** - * Tells if the ongoing drag & drop object can be accepted upon mouse drop. - */ + /** \copydoc #GHOST_IWindow::setAcceptDragOperation */ void setAcceptDragOperation(bool canAccept) override; - /** - * Returns acceptance of the dropped object - * Usually called by the "object dropped" event handling function - */ + /** \copydoc #GHOST_IWindow::canAcceptDragOperation */ bool canAcceptDragOperation() const override; - /** - * Sets the window "modified" status, indicating unsaved changes - * \param isUnsavedChanges: Unsaved changes or not. - * \return Indication of success. - */ + /** \copydoc #GHOST_IWindow::setModifiedState */ GHOST_TSuccess setModifiedState(bool isUnsavedChanges) override; - /** - * Gets the window "modified" status, indicating unsaved changes - * \return True if there are unsaved changes - */ + /** \copydoc #GHOST_IWindow::getModifiedState */ bool getModifiedState() override; - /** - * Returns the type of drawing context used in this window. - * \return The current type of drawing context. - */ + /** \copydoc #GHOST_IWindow::getDrawingContextType */ inline GHOST_TDrawingContextType getDrawingContextType() override; /** - * Tries to install a rendering context in this window. - * Child classes do not need to overload this method, + * \copydoc #GHOST_IWindow::setDrawingContextType + * + * \note Child classes do not need to overload this method, * They should overload #newDrawingContext instead. - * \param type: The type of rendering context installed. - * \return Indication as to whether installation has succeeded. */ GHOST_TSuccess setDrawingContextType(GHOST_TDrawingContextType type) override; - /** - * Returns the drawing context used in this window. - * \return The current drawing context. - */ + /** \copydoc #GHOST_IWindow::getDrawingContext */ GHOST_IContext *getDrawingContext() override; - /** - * Swaps front and back buffers of a window. - * \return A boolean success indicator. - */ + /** \copydoc #GHOST_IWindow::swapBuffers */ GHOST_TSuccess swapBuffers() override; - /** - * Activates the drawing context of this window. - * \return A boolean success indicator. - */ + /** \copydoc #GHOST_IWindow::activateDrawingContext */ GHOST_TSuccess activateDrawingContext() override; /** @@ -296,35 +213,28 @@ class GHOST_Window : public GHOST_IWindow { */ GHOST_Context *getContext(); - /** - * Gets the OpenGL frame-buffer associated with the window's contents. - * \return The ID of an OpenGL frame-buffer object. - */ + /** \copydoc #GHOST_IWindow::getDefaultFramebuffer */ unsigned int getDefaultFramebuffer() override; #ifdef WITH_VULKAN_BACKEND + /** \copydoc #GHOST_GetVulkanSwapChainFormat */ virtual GHOST_TSuccess getVulkanSwapChainFormat( GHOST_VulkanSwapChainData *r_swap_chain_data) override; #endif - /** - * Returns the window user data. - * \return The window user data. - */ + /** \copydoc #GHOST_IWindow::getUserData */ GHOST_TUserDataPtr getUserData() const override { return m_userData; } - /** - * Changes the window user data. - * \param userData: The window user data. - */ + /** \copydoc #GHOST_IWindow::setUserData */ void setUserData(const GHOST_TUserDataPtr userData) override { m_userData = userData; } + /** \copydoc #GHOST_IWindow::getNativePixelSize */ float getNativePixelSize() override { if (m_nativePixelSize > 0.0f) { @@ -333,10 +243,7 @@ class GHOST_Window : public GHOST_IWindow { return 1.0f; } - /** - * Returns the recommended DPI for this window. - * \return The recommended DPI for this window. - */ + /** \copydoc #GHOST_IWindow::getDPIHint */ uint16_t getDPIHint() override { return 96; @@ -378,16 +285,10 @@ class GHOST_Window : public GHOST_IWindow { return GHOST_kSuccess; } - /** - * Sets the cursor shape on the window using - * native window system calls. - */ + /** \copydoc #GHOST_IWindow::setWindowCursorShape */ virtual GHOST_TSuccess setWindowCursorShape(GHOST_TStandardCursor shape) = 0; - /** - * Sets the cursor shape on the window using - * native window system calls. - */ + /** \copydoc #GHOST_IWindow::setWindowCustomCursorShape */ virtual GHOST_TSuccess setWindowCustomCursorShape(uint8_t *bitmap, uint8_t *mask, int szx,