platform/win/Utilities.h

Go to the documentation of this file.

/*
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */
 
#ifndef META_OCEAN_PLATFORM_WIN_UTILITIES_H
#define META_OCEAN_PLATFORM_WIN_UTILITIES_H
 
#include "ocean/platform/win/Win.h"
#include "ocean/platform/win/Bitmap.h"
 
#include "ocean/base/Frame.h"
 
#include "ocean/cv/PixelBoundingBox.h"
 
#ifdef OCEAN_COMPILER_MSC
    #pragma managed(push, off)
#endif
 
#include "ocean/base/String.h"
 
#ifdef OCEAN_COMPILER_MSC
    #pragma managed(pop)
#endif
 
namespace Ocean
{
 
namespace Platform
{
 
namespace Win
{
 
/**
 * This class implements utilities and helper functions.
 * @ingroup platformwin
 */
class OCEAN_PLATFORM_WIN_EXPORT Utilities
{
    public:
 
        /**
         * Definition of anchor positions for text rendering.
         */
        enum AnchorPosition : uint32_t
        {
            /// Text is anchored at the top-left corner
            AP_TOP_LEFT,
            /// Text is anchored at the top-right corner
            AP_TOP_RIGHT,
            /// Text is anchored at the bottom-left corner
            AP_BOTTOM_LEFT,
            /// Text is anchored at the bottom-right corner
            AP_BOTTOM_RIGHT,
            /// Text is centered
            AP_CENTER
        };
 
    public:
 
        /**
         * Prints a text on the given device context.
         * @param dc The device context on which the text will be drawn
         * @param x Horizontal output position
         * @param y Vertical output position
         * @param text Text to be printed
         */
        static void textOutput(HDC dc, const int x, const int y, const std::string& text);
 
        /**
         * Draws styled text on a device context with customizable font, anchor position, and colors.
         * The text can be positioned using anchor points relative to the window dimensions, with optional shadow for better visibility.
         * @param deviceContext The device context on which the text will be drawn
         * @param text The text to be drawn
         * @param font The name of the font to use (e.g., "Arial")
         * @param fontSize The height of the font in pixels
         * @param bold True to use bold font weight; False for normal weight
         * @param anchorPosition The anchor position for the text
         * @param windowWidth The width of the window, used for anchor calculations
         * @param windowHeight The height of the window, used for anchor calculations
         * @param foregroundColor The color of the text (RGB value)
         * @param backgroundColor The background color of the text, or -1 for transparent background
         * @param shadowColor The color of the shadow, or -1 to disable shadow
         * @param shadowOffsetX The horizontal offset of the shadow in pixels, with range [0, infinity)
         * @param shadowOffsetY The vertical offset of the shadow in pixels, with range [0, infinity)
         * @param marginX The horizontal margin from the window edge in pixels, with range [0, infinity)
         * @param marginY The vertical margin from the window edge in pixels, with range [0, infinity)
         */
        static void textOutput(HDC deviceContext, const std::wstring& text, const std::wstring& font, const unsigned int fontSize, const bool bold, const AnchorPosition anchorPosition, const unsigned int windowWidth, const unsigned int windowHeight, const int32_t foregroundColor, const int32_t backgroundColor = -1, const int32_t shadowColor = -1, const unsigned int shadowOffsetX = 2u, const unsigned int shadowOffsetY = 2u, const unsigned int marginX = 20u, const unsigned int marginY = 20u);
 
        /**
         * Prints a text on the desktop.
         * @param x Horizontal output position
         * @param y Vertical output position
         * @param text Text to be printed
         */
        static void desktopTextOutput(const int x, const int y, const std::string& text);
 
        /**
         * Prints a frame on the given device context.
         * @param dc Device context receiving the frame
         * @param x Horizontal output position
         * @param y Vertical output position
         * @param frame The frame to be printed
         */
        static void frameOutput(HDC dc, const int x, const int y, const Frame& frame);
 
        /**
         * Prints a frame on the given device context.
         * @param dc Device context receiving the text
         * @param x Horizontal output position
         * @param y Vertical output position
         * @param width Output width in pixel
         * @param height Output height in pixel
         * @param frame The frame to be printed
         */
        static void frameOutput(HDC dc, const int x, const int y, const unsigned int width, const unsigned int height, const Frame& frame);
 
        /**
         * Prints a given frame on the Windows' main desktop at a specified location.
         * You do not need to have a GUI application to use this function.<br>
         * Call this function from any application and from any thread.<br>
         * The painted frame will disappear immediately when Windows receives any repaint event.<br>
         * This function is intended for debugging purposes only.
         * @param x Horizontal output position, with range (-infinity, infinity)
         * @param y Vertical output position, with range (-infinity, infinity)
         * @param frame The frame to be printed
         */
        static void desktopFrameOutput(const int x, const int y, const Frame& frame);
 
        /**
         * Prints a given frame on the Windows' main desktop at a specified location.
         * You do not need to have a GUI application to use this function.<br>
         * Call this function from any application and from any thread.<br>
         * The painted frame will disappear immediately when Windows receives any repaint event.<br>
         * This function is intended for debugging purposes only.
         * @param x Horizontal output position, with range (-infinity, infinity)
         * @param y Vertical output position, with range (-infinity, infinity)
         * @param scale The scale that is applied to the frame, a factor of 2 will increase the painted frame by two, with range [1, infinity)
         * @param frame The frame to be printed
         */
        static inline void desktopFrameOutput(const int x, const int y, const unsigned int scale, const Frame& frame);
 
        /**
         * Prints a given frame on the Windows' main desktop at a specified location.
         * You do not need to have a GUI application to use this function.<br>
         * Call this function from any application and from any thread.<br>
         * The painted frame will disappear immediately when Windows receives any repaint event.<br>
         * This function is intended for debugging purposes only.
         * @param x Horizontal output position, with range (-infinity, infinity)
         * @param y Vertical output position, with range (-infinity, infinity)
         * @param width The width of the painted frame in the domain of the desktop, in pixel, with range [1, infinity)
         * @param height The height of the painted frame in the domain of the desktop, in pixel, with range [1, infinity)
         * @param frame The frame to be printed
         */
        static void desktopFrameOutput(const int x, const int y, const unsigned int width, const unsigned int height, const Frame& frame);
 
        /**
         * Prints a bitmap on the given device context.
         * @param dc Device context receiving the bitmap
         * @param x Horizontal output position
         * @param y Vertical output position
         * @param bitmap bitmap to be printed
         */
        static void bitmapOutput(HDC dc, const int x, const int y, const Bitmap& bitmap);
 
        /**
         * Prints a bitmap on the desktop.
         * @param x Horizontal output position
         * @param y Vertical output position
         * @param scale Scale of the output bitmap
         * @param bitmap Bitmap to be printed
         */
        static inline void desktopBitmapOutput(const int x, const int y, const unsigned int scale, const Bitmap& bitmap);
 
        /**
         * Prints a bitmap on the given device context.
         * @param dc Device context receiving the text
         * @param x Horizontal output position
         * @param y Vertical output position
         * @param width Output width in pixel
         * @param height Output height in pixel
         * @param bitmap bitmap to be printed
         */
        static void bitmapOutput(HDC dc, const int x, const int y, const unsigned int width, const unsigned int height, const Bitmap& bitmap);
 
        /**
         * Prints a bitmap on the desktop.
         * @param x Horizontal output position
         * @param y Vertical output position
         * @param bitmap bitmap to be printed
         */
        static void desktopBitmapOutput(const int x, const int y, const Bitmap& bitmap);
 
        /**
         * Prints a bitmap on the desktop.
         * @param x Horizontal output position
         * @param y Vertical output position
         * @param width Output width in pixel
         * @param height Output height in pixel
         * @param bitmap bitmap to be printed
         */
        static void desktopBitmapOutput(const int x, const int y, const unsigned int width, const unsigned int height, const Bitmap& bitmap);
 
        /**
         * Determines the bounding box of a given string with specified font and font size.
         * @param value The string for which the bounding box will be determined
         * @param font The name of the font which will be applied
         * @param size The size of the font
         * @return The bounding box of the given string
         */
        static CV::PixelBoundingBox textBoundingBox(const std::string& value, const std::string& font = std::string(), const unsigned int size = 0u);
 
        /**
         * Determines the bounding box of a given string with specified font and font size.
         * @param value The string for which the bounding box will be determined
         * @param font The name of the font which will be applied
         * @param size The size of the font
         * @return The bounding box of the given string
         */
        static CV::PixelBoundingBox textBoundingBox(const std::wstring& value, const std::wstring& font = std::wstring(), const unsigned int size = 0u);
 
};
 
/**
 * This class implements a scoped device context.
 * The device context is acquired for a given window, or for the entire screen if no window is given, and is released again once the object is disposed.<br>
 * The window handle is kept alongside the device context, as it is needed to release it again.
 * @ingroup platformwin
 */
class OCEAN_PLATFORM_WIN_EXPORT ScopedDC
{
    public:
 
        /**
         * Creates an object not holding a device context.
         */
        ScopedDC() = default;
 
        /**
         * Move constructor.
         * @param scopedDC The object to be moved
         */
        inline ScopedDC(ScopedDC&& scopedDC) noexcept;
 
        /**
         * Acquires the device context of a given window.
         * In case the device context cannot be acquired, the resulting object will be invalid.
         * @param window The window for which the device context will be acquired, nullptr to acquire the device context of the entire screen
         */
        explicit inline ScopedDC(const HWND window);
 
        /**
         * Destructs this object and releases the device context.
         */
        inline ~ScopedDC();
 
        /**
         * Returns whether this object holds a device context.
         * @return True, if so
         */
        inline bool isValid() const;
 
        /**
         * Returns the wrapped device context.
         * Ensure that this object holds a device context before calling this operator.
         * @return The wrapped device context
         * @see isValid().
         */
        inline HDC operator*() const;
 
        /**
         * Explicitly releases the device context.
         */
        inline void release();
 
        /**
         * Move operator.
         * @param scopedDC The object to be moved
         * @return Reference to this object
         */
        inline ScopedDC& operator=(ScopedDC&& scopedDC) noexcept;
 
    protected:
 
        /**
         * Disabled copy constructor.
         */
        ScopedDC(const ScopedDC&) = delete;
 
        /**
         * Disabled assign operator.
         * @return Reference to this object
         */
        ScopedDC& operator=(const ScopedDC&) = delete;
 
    protected:
 
        /// The window for which the device context has been acquired, nullptr for the entire screen or if this object is invalid.
        HWND window_ = nullptr;
 
        /// The wrapped device context, nullptr if this object does not hold one.
        HDC dc_ = nullptr;
};
 
/**
 * This class implements a scoped font which is selected into a device context.
 * The font is created and selected when the object is created, and is deselected and deleted once the object is disposed.<br>
 * A font cannot be deleted while it is still selected into a device context, so both steps belong together.
 * @ingroup platformwin
 */
class OCEAN_PLATFORM_WIN_EXPORT ScopedFont
{
    public:
 
        /**
         * Creates an object not holding a font.
         */
        ScopedFont() = default;
 
        /**
         * Move constructor.
         * @param scopedFont The object to be moved
         */
        inline ScopedFont(ScopedFont&& scopedFont) noexcept;
 
        /**
         * Selects an existing font into a given device context and takes ownership of the font.
         * In case the given font is invalid, the resulting object will be invalid.
         * @param dc The device context into which the font will be selected, must be valid
         * @param font The font to be selected, will be owned by this object
         */
        ScopedFont(HDC dc, HFONT font);
 
        /**
         * Creates a new font and selects it into a given device context.
         * In case the font cannot be created, the resulting object will be invalid.
         * @param dc The device context into which the new font will be selected, must be valid
         * @param logFont The description of the font to be created
         */
        ScopedFont(HDC dc, const LOGFONTW& logFont);
 
        /**
         * Destructs this object, deselects the font and deletes it.
         */
        inline ~ScopedFont();
 
        /**
         * Returns whether this object holds a font.
         * @return True, if so
         */
        inline bool isValid() const;
 
        /**
         * Returns the wrapped font.
         * Ensure that this object holds a font before calling this operator.
         * @return The wrapped font
         * @see isValid().
         */
        inline HFONT operator*() const;
 
        /**
         * Explicitly deselects and deletes the font.
         */
        void release();
 
        /**
         * Move operator.
         * @param scopedFont The object to be moved
         * @return Reference to this object
         */
        inline ScopedFont& operator=(ScopedFont&& scopedFont) noexcept;
 
    protected:
 
        /**
         * Disabled copy constructor.
         */
        ScopedFont(const ScopedFont&) = delete;
 
        /**
         * Disabled assign operator.
         * @return Reference to this object
         */
        ScopedFont& operator=(const ScopedFont&) = delete;
 
    protected:
 
        /// The device context into which the font is selected, nullptr if this object does not hold a font.
        HDC dc_ = nullptr;
 
        /// The font which is selected into the device context, nullptr if this object does not hold a font.
        HFONT font_ = nullptr;
 
        /// The font which was selected into the device context before, nullptr if none was selected.
        HFONT previousFont_ = nullptr;
};
 
/**
 * This class implements a nested scoped object which disables a window object until the scope of all nested elements ends (or until all nested object are released explicitly).
 * The creation of the first nested object disables the window.<br>
 * Following nested objects only increase the internal counter while do not have any further consequence.<br>
 * @ingroup platformwin
 */
class ScopedDisableWindow
{
    protected:
 
        /**
         * This class implements a simple counter for nested disable window objects.
         */
        class DisableWindowCounter : public Singleton<DisableWindowCounter>
        {
            friend class Singleton<DisableWindowCounter>;
            friend class ScopedDisableWindow;
 
            protected:
 
                /**
                 * Definition of a map mapping window handles to counters.
                 */
                using CounterMap = std::unordered_map<HWND, unsigned int>;
 
            protected:
 
                /**
                 * Creates a new DisableWindowCounter object.
                 */
                inline DisableWindowCounter();
 
                /**
                 * Destructs a DisableWindowCounter object.
                 */
                inline ~DisableWindowCounter();
 
                /**
                 * Increases the counter of this object.
                 * @return True, if the counter was zero before the counter has been increased
                 */
                inline bool increase(const HWND windowHandle);
 
                /**
                 * Decreases the counter of this object.
                 * @return True, if the counter is zero after it has been decreased
                 */
                inline bool decrease(const HWND windowHandle);
 
                /**
                 * Returns whether the counter is zero.
                 * @return True, if so
                 */
                inline bool isZero(const HWND windowHandle);
 
                /**
                 * Returns the lock object.
                 * @return Lock object
                 */
                inline Lock& lock();
 
            protected:
 
                /// Disable window counter.
                CounterMap counterMap_;
 
                /// Disable window lock.
                Lock windowLock_;
        };
 
    public:
 
        /**
         * Creates a new scoped object and disables the associated window.
         * @param windowHandle Handle of the window to disable, this window must not be disposed before this scoped object is disposed
         */
        explicit ScopedDisableWindow(const HWND windowHandle);
 
        /**
         * Destructs this scoped object and enables the associated window.
         */
        inline ~ScopedDisableWindow();
 
        /**
         * Explicitly releases the scoped object and enables the associated window (already before the scope ends).
         */
        void release();
 
    protected:
 
        /**
         * Disabled copy constructor.
         * @param window The window that would be copied
         */
        ScopedDisableWindow(const ScopedDisableWindow& window) = delete;
 
        /**
         * Disabled assign operator.
         * @param window The window that would be assigned
         */
        ScopedDisableWindow& operator=(const ScopedDisableWindow& window) = delete;
 
    protected:
 
        /// The associated window, nullptr if the object has been released already.
        HWND handle_ = nullptr;
};
 
#if defined(OCEAN_COMPILER_MSC) && defined(_MANAGED)
 
inline System::String^ toString(const std::string& value)
{
    return gcnew System::String(value.c_str());
}
 
inline System::String^ toString(const char* value)
{
    return gcnew System::String(value);
}
 
inline System::String^ toString(const std::wstring& value)
{
    return gcnew System::String(value.c_str());
}
 
inline System::String^ toString(const wchar_t* value)
{
    return gcnew System::String(value);
}
 
inline std::string toAString(System::String^ value)
{
    char* str = (char*)(void*)System::Runtime::InteropServices::Marshal::StringToHGlobalAnsi(value);
    std::string result(str);
 
    System::Runtime::InteropServices::Marshal::FreeHGlobal(System::IntPtr(str));
 
    return result;
}
 
inline std::wstring toWString(System::String^ value)
{
    char* str = (char*)(void*)System::Runtime::InteropServices::Marshal::StringToHGlobalAnsi(value);
    std::string result(str);
 
    System::Runtime::InteropServices::Marshal::FreeHGlobal(System::IntPtr(str));
 
    return Ocean::String::toWString(result);
}
 
#endif // OCEAN_COMPILER_MSC && _MANAGED
 
inline void Utilities::desktopFrameOutput(const int x, const int y, const unsigned int scale, const Frame& frame)
{
    desktopFrameOutput(x, y, frame.width() * scale, frame.height() * scale, frame);
}
 
inline void Utilities::desktopBitmapOutput(const int x, const int y, const unsigned int scale, const Bitmap& bitmap)
{
    desktopBitmapOutput(x, y, bitmap.width() * scale, bitmap.height() * scale, bitmap);
}
 
inline ScopedDC::ScopedDC(ScopedDC&& scopedDC) noexcept
{
    *this = std::move(scopedDC);
}
 
inline ScopedDC::ScopedDC(const HWND window) :
    window_(window),
    dc_(GetDC(window))
{
    // nothing to do here
}
 
inline ScopedDC::~ScopedDC()
{
    release();
}
 
inline bool ScopedDC::isValid() const
{
    return dc_ != nullptr;
}
 
inline HDC ScopedDC::operator*() const
{
    ocean_assert(isValid());
 
    return dc_;
}
 
inline void ScopedDC::release()
{
    if (dc_ != nullptr)
    {
        ReleaseDC(window_, dc_);
 
        window_ = nullptr;
        dc_ = nullptr;
    }
}
 
inline ScopedDC& ScopedDC::operator=(ScopedDC&& scopedDC) noexcept
{
    if (this != &scopedDC)
    {
        release();
 
        window_ = scopedDC.window_;
        dc_ = scopedDC.dc_;
 
        scopedDC.window_ = nullptr;
        scopedDC.dc_ = nullptr;
    }
 
    return *this;
}
 
inline ScopedFont::ScopedFont(ScopedFont&& scopedFont) noexcept
{
    *this = std::move(scopedFont);
}
 
inline ScopedFont::~ScopedFont()
{
    release();
}
 
inline bool ScopedFont::isValid() const
{
    return font_ != nullptr;
}
 
inline HFONT ScopedFont::operator*() const
{
    ocean_assert(isValid());
 
    return font_;
}
 
inline ScopedFont& ScopedFont::operator=(ScopedFont&& scopedFont) noexcept
{
    if (this != &scopedFont)
    {
        release();
 
        dc_ = scopedFont.dc_;
        font_ = scopedFont.font_;
        previousFont_ = scopedFont.previousFont_;
 
        scopedFont.dc_ = nullptr;
        scopedFont.font_ = nullptr;
        scopedFont.previousFont_ = nullptr;
    }
 
    return *this;
}
 
inline ScopedDisableWindow::DisableWindowCounter::DisableWindowCounter()
{
    // nothing to do here
}
 
inline ScopedDisableWindow::DisableWindowCounter::~DisableWindowCounter()
{
#ifdef OCEAN_DEBUG
 
    for (CounterMap::value_type& counterPair : counterMap_)
    {
        ocean_assert(counterPair.second == 0u);
    }
 
#endif
}
 
inline bool ScopedDisableWindow::DisableWindowCounter::increase(const HWND windowHandle)
{
    counterMap_[windowHandle]++;
 
    return counterMap_[windowHandle] == 1u;
}
 
inline bool ScopedDisableWindow::DisableWindowCounter::decrease(const HWND windowHandle)
{
    ocean_assert(counterMap_.find(windowHandle) != counterMap_.end());
    ocean_assert(counterMap_[windowHandle] >= 1u);
 
    counterMap_[windowHandle]--;
 
    return counterMap_[windowHandle] == 0u;
}
 
inline bool ScopedDisableWindow::DisableWindowCounter::isZero(const HWND windowHandle)
{
    return counterMap_[windowHandle] == 0u;
}
 
inline Lock& ScopedDisableWindow::DisableWindowCounter::lock()
{
    return windowLock_;
}
 
inline ScopedDisableWindow::~ScopedDisableWindow()
{
    release();
}
 
}
 
}
 
}
 
#endif // META_OCEAN_PLATFORM_WIN_UTILITIES_H