From 28e9c4ba18002c7c9ba04b9b5e69d459d80a13dd Mon Sep 17 00:00:00 2001 From: BadQuanta Date: Mon, 11 May 2026 10:28:21 +0000 Subject: [PATCH] Pixels, Surfaces, Renderer, oh my... --- CMakeLists.txt | 14 +- examples/CMakeLists.txt | 4 +- examples/HelloRenderer2D.cpp | 66 + examples/HelloWorld.cpp | 27 - include/hdk/sdl.hpp | 4 + include/hdk/sdl/Application.hpp | 27 + include/hdk/sdl/Log.hpp | 96 ++ include/hdk/sdl/Properties.hpp | 139 +-- include/hdk/sdl/event.hpp | 862 +++++++++++++ include/hdk/sdl/main.hpp | 36 + include/hdk/sdl/pixels.hpp | 9 +- include/hdk/sdl/pixels/Palette.hpp | 27 +- include/hdk/sdl/pixels/PixelFormat.hpp | 33 +- include/hdk/sdl/pixels/PixelFormatDetails.hpp | 54 +- include/hdk/sdl/render.hpp | 32 +- include/hdk/sdl/render/Renderer.hpp | 372 +----- include/hdk/sdl/render/Texture.hpp | 169 +-- include/hdk/sdl/video.hpp | 28 +- include/hdk/sdl/video/Display.hpp | 96 +- include/hdk/sdl/video/Surface.hpp | 183 +-- include/hdk/sdl/video/Window.hpp | 152 +-- src/Application.cpp | 0 src/Properties.cpp | 296 +++++ src/event.cpp | 268 ++++ src/pixels.cpp | 18 + src/pixels/Palette.cpp | 67 + src/pixels/PixelFormat.cpp | 88 ++ src/pixels/PixelFormatDetails.cpp | 106 ++ src/render.cpp | 65 + src/render/Renderer.cpp | 1107 +++++++++++++++++ src/render/Texture.cpp | 321 +++++ src/video.cpp | 60 + src/video/Display.cpp | 252 ++++ src/video/Surface.cpp | 255 ++++ src/video/Window.cpp | 455 +++++++ 35 files changed, 4578 insertions(+), 1210 deletions(-) create mode 100644 examples/HelloRenderer2D.cpp delete mode 100644 examples/HelloWorld.cpp create mode 100644 include/hdk/sdl/Application.hpp create mode 100644 include/hdk/sdl/Log.hpp create mode 100644 include/hdk/sdl/event.hpp create mode 100644 include/hdk/sdl/main.hpp create mode 100644 src/Application.cpp create mode 100644 src/Properties.cpp create mode 100644 src/event.cpp create mode 100644 src/pixels.cpp create mode 100644 src/pixels/Palette.cpp create mode 100644 src/pixels/PixelFormat.cpp create mode 100644 src/pixels/PixelFormatDetails.cpp create mode 100644 src/render.cpp create mode 100644 src/render/Renderer.cpp create mode 100644 src/render/Texture.cpp create mode 100644 src/video.cpp create mode 100644 src/video/Display.cpp create mode 100644 src/video/Surface.cpp create mode 100644 src/video/Window.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index 65ff4b4..fd07059 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -5,10 +5,14 @@ project(hdk-sdl LANGUAGES CXX DESCRIPTION "header only shared_ptr wrappers around SDL3 structs and functions" ) + +# Note: The src/ directory contains Doxygen documentation-only .cpp files. +# This is a header-only library; src/ files are not compiled into any targets. + # hdk-sdl OPTIONS -option(HDK_SDL_BUILD_TESTS "Build hdk-sdl tests" ${HDK_BUILD_TESTS}) -option(HDK_SDL_BUILD_EXAMPLES "Build hdk-sdl examples" ${HDK_BUILD_EXAMPLES}) -if(HDK_SDL_BUILD_EXAMPLES) +option(HDK_SDL_TESTS "Build hdk-sdl tests" ${HDK_TESTS}) +option(HDK_SDL_EXAMPLES "Build hdk-sdl examples" ${HDK_EXAMPLES}) +if(HDK_SDL_EXAMPLES) add_subdirectory(examples) endif() @@ -21,7 +25,7 @@ include(FetchContent) FetchContent_Declare( SDL3 GIT_REPOSITORY https://github.com/libsdl-org/SDL.git - GIT_TAG release-3.4.4 + GIT_TAG release-3.4.8 ) FetchContent_MakeAvailable(SDL3) @@ -30,7 +34,7 @@ target_link_libraries(hdk-sdl INTERFACE SDL3::SDL3 hdk-grid) target_include_directories(hdk-sdl INTERFACE ${SDL3_SOURCE_DIR}/include ${CMAKE_CURRENT_SOURCE_DIR}/include) target_compile_features(hdk-sdl INTERFACE cxx_std_17) -if(HDK_SDL_BUILD_TESTS) +if(HDK_SDL_TESTS) add_subdirectory(test) endif() diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt index 558053d..b47a12d 100644 --- a/examples/CMakeLists.txt +++ b/examples/CMakeLists.txt @@ -1,4 +1,4 @@ # Simple examples for using hdk-sdl. -add_executable(HelloWorld HelloWorld.cpp) -target_link_libraries(HelloWorld PRIVATE hdk-sdl) \ No newline at end of file +add_executable(HelloRenderer2D HelloRenderer2D.cpp) +target_link_libraries(HelloRenderer2D PRIVATE hdk-sdl) \ No newline at end of file diff --git a/examples/HelloRenderer2D.cpp b/examples/HelloRenderer2D.cpp new file mode 100644 index 0000000..7ce1f50 --- /dev/null +++ b/examples/HelloRenderer2D.cpp @@ -0,0 +1,66 @@ +#include // Hollow Wrapper to SDL +#include // Hollow Wrapper to SDL main boilerplate via hdk::sdl::ApplicationInterface & the macro HDK_SDL_MAIN_CLASS +namespace hello_renderer_2d { + using namespace hdk; + class HelloRenderer2D : public sdl::PublicApp { + public: + const sdl::Log& AppLog { sdl::Log::Application }; + grid::eps::TapScope taps, loud; + sdl::evt::AllTypes events; + const sdl::evt::EventConduit::Callback_t LOG_EVENT = [&](SDL_Event* event) { + auto description = sdl::Event::GetDescription<1024>(event); + AppLog.Debug("Event received: %s", description.c_str()); + }; + virtual SDL_AppResult Event(SDL_Event* event) override { + // Get a description of the event for logging, you can adjust the buffer size as needed, defaults to 512 + events.Trigger(event); + return AppStatus; + } + + sdl::Window window { nullptr }; + sdl::Renderer renderer { nullptr }; + + virtual SDL_AppResult Init(int argc, char* argv[]) override { + sdl::Log::SetPriorities(SDL_LOG_PRIORITY_DEBUG); + auto [w, r] = sdl::CreateWindowAndRenderer("Hello World", 800, 600, 0); + window = w; + renderer = r; + if (!window || !renderer) { + SDL_Log("Failed to create window or renderer: %s", SDL_GetError()); + return AppStatus = SDL_APP_FAILURE; + } + renderer.SetLogicalPresentation(800, 600, SDL_LOGICAL_PRESENTATION_LETTERBOX); + renderer.SetDrawColor(255, 0, 0, 0); + taps << events.Quit.Attach([&](SDL_Event* event) { + AppStatus = SDL_APP_SUCCESS; + printf("Quit event received, exiting...\n"); + }); + + loud << events.Attach(LOG_EVENT); + SDL_WindowID window_id = window.GetID(); + taps << events.Window[window_id].MouseLeave.Attach([&](SDL_Event* event) { + AppLog.Info("Mouse left the window!"); + loud.PauseAll(); + }); + + taps << events.Window[window_id].MouseEnter.Attach([&](SDL_Event* event) { + AppLog.Info("Mouse entered the window!"); + loud.ResumeAll(); + }); + return AppStatus; + } + + virtual SDL_AppResult Iterate() override { + renderer.SetDrawColor(255, 0, 0, 0); + renderer.FillRect(nullptr); + renderer.SetDrawColor(255, 255, 255, 255); + renderer.DebugTextFormat(0, 0, "Displays: %d", sdl::Display::GetDisplays().size()); + renderer.DebugTextFormat(0, 20, "Render Drivers: %d", sdl::Renderer::GetNumRenderDrivers()); + renderer.Present(); + return AppStatus; + } + }; +} +// We tell the HDK_SDL_MAIN_CLASS macro to use our HelloRenderer2D class +HDK_SDL_MAIN_CLASS(hello_renderer_2d::HelloRenderer2D) +// this builds all the SDL main boilerplate and connects it to our HelloRenderer2D class \ No newline at end of file diff --git a/examples/HelloWorld.cpp b/examples/HelloWorld.cpp deleted file mode 100644 index 9050845..0000000 --- a/examples/HelloWorld.cpp +++ /dev/null @@ -1,27 +0,0 @@ -#include - -using namespace hdk::sdl; - -Window window { nullptr }; -//Renderer renderer { nullptr }; - -int main(int argc, char* argv[]) -{ - window = Window::Create("Hello World", 800, 600, 0); - if (!window) { - SDL_Log("Failed to create window: %s", SDL_GetError()); - return 1; - } - // - SDL_Event event; - bool running = true; - while (running) { - while (SDL_PollEvent(&event)) { - if (event.type == SDL_EVENT_QUIT) { - running = false; - } - } - } - window = nullptr; // Explicitly release the window before quitting SDL - return 0; -} \ No newline at end of file diff --git a/include/hdk/sdl.hpp b/include/hdk/sdl.hpp index ded0e6c..46c554b 100644 --- a/include/hdk/sdl.hpp +++ b/include/hdk/sdl.hpp @@ -11,3 +11,7 @@ #include #include + +#include + +#include diff --git a/include/hdk/sdl/Application.hpp b/include/hdk/sdl/Application.hpp new file mode 100644 index 0000000..603a62e --- /dev/null +++ b/include/hdk/sdl/Application.hpp @@ -0,0 +1,27 @@ +#pragma once +#include +/// @file Application.hpp +/// For complete documentation, see src/Application.cpp +namespace hdk::sdl { + /** SDL Requires this interface to be implemented by the application class. */ + class AppInterface { + public: + virtual SDL_AppResult Event(SDL_Event* event) = 0; + virtual SDL_AppResult Init(int argc, char* argv[]) = 0; + virtual SDL_AppResult Iterate() = 0; + virtual void Quit(SDL_AppResult code) = 0; + }; + /** I'm calling it a public application because the AppStatus member is publicly accessible and so can be + * modified directly by the rest of application logic that has access to this application instance via this subclass. + */ + class PublicApp : public AppInterface { + public: + SDL_AppResult AppStatus { SDL_APP_CONTINUE }; + virtual SDL_AppResult Event(SDL_Event* event) override { return AppStatus; } + virtual SDL_AppResult Init(int argc, char* argv[]) override { return AppStatus; } + virtual SDL_AppResult Iterate() override { return AppStatus; } + virtual void Quit(SDL_AppResult code) override { + // Default quit behavior is to do nothing, allowing the app to control its own lifetime. + } + }; +} // namespace hdk::sdl \ No newline at end of file diff --git a/include/hdk/sdl/Log.hpp b/include/hdk/sdl/Log.hpp new file mode 100644 index 0000000..4bc082d --- /dev/null +++ b/include/hdk/sdl/Log.hpp @@ -0,0 +1,96 @@ +#pragma once +#include +namespace hdk::sdl { + /** + * @brief Log instances represent logging categories: Application, Error, System, Audio, Video, Render, Input, Test, + * etc. + */ + class Log { + public: + const int category; + static const Log Application; + Log(int category) + : category(category) { } + /** https://wiki.libsdl.org/SDL3/SDL_GetDefaultLogOutputFunction */ + static SDL_LogOutputFunction GetDefaultOutputFunction() { return SDL_GetDefaultLogOutputFunction(); } + /** https://wiki.libsdl.org/SDL3/SDL_GetLogOutputFunction */ + static void GetOutputFunction(SDL_LogOutputFunction* callback, void** userdata) { + SDL_GetLogOutputFunction(callback, userdata); + } + /** https://wiki.libsdl.org/SDL3/SDL_GetLogPriority */ + SDL_LogPriority GetPriority() { return SDL_GetLogPriority(category); } + /** https://wiki.libsdl.org/SDL3/SDL_Log */ + + /** https://wiki.libsdl.org/SDL3/SDL_LogCritical */ + void Critical(const char* fmt, ...) const { + va_list args; + va_start(args, fmt); + LogMessageV(SDL_LOG_PRIORITY_CRITICAL, fmt, args); + va_end(args); + } + /** https://wiki.libsdl.org/SDL3/SDL_LogDebug */ + void Debug(const char* fmt, ...) const { + va_list args; + va_start(args, fmt); + LogMessageV(SDL_LOG_PRIORITY_DEBUG, fmt, args); + va_end(args); + } + /** https://wiki.libsdl.org/SDL3/SDL_LogError */ + void Error(const char* fmt, ...) const { + va_list args; + va_start(args, fmt); + LogMessageV(SDL_LOG_PRIORITY_ERROR, fmt, args); + va_end(args); + } + /** https://wiki.libsdl.org/SDL3/SDL_LogInfo */ + void Info(const char* fmt, ...) const { + va_list args; + va_start(args, fmt); + LogMessageV(SDL_LOG_PRIORITY_INFO, fmt, args); + va_end(args); + } + /** https://wiki.libsdl.org/SDL3/SDL_LogMessage */ + void LogMessage(SDL_LogPriority priority, const char* fmt, ...) const { + va_list args; + va_start(args, fmt); + LogMessageV(priority, fmt, args); + va_end(args); + } + /** https://wiki.libsdl.org/SDL3/SDL_LogMessageV */ + void LogMessageV(SDL_LogPriority priority, const char* fmt, va_list args) const { + SDL_LogMessageV(category, priority, fmt, args); + } + /** https://wiki.libsdl.org/SDL3/SDL_LogTrace */ + void Trace(const char* fmt, ...) const { + va_list args; + va_start(args, fmt); + LogMessageV(SDL_LOG_PRIORITY_TRACE, fmt, args); + va_end(args); + } + /** https://wiki.libsdl.org/SDL3/SDL_LogVerbose */ + void Verbose(const char* fmt, ...) const { + va_list args; + va_start(args, fmt); + LogMessageV(SDL_LOG_PRIORITY_VERBOSE, fmt, args); + va_end(args); + } + /** https://wiki.libsdl.org/SDL3/SDL_LogWarn */ + void Warn(const char* fmt, ...) const { + va_list args; + va_start(args, fmt); + LogMessageV(SDL_LOG_PRIORITY_WARN, fmt, args); + va_end(args); + } + /** https://wiki.libsdl.org/SDL3/SDL_ResetLogPriorities */ + static void ResetPriorities() { SDL_ResetLogPriorities(); } + /** https://wiki.libsdl.org/SDL3/SDL_SetLogOutputFunction */ + static void SetOutputFunction(SDL_LogOutputFunction callback, void* userdata) { SDL_SetLogOutputFunction(callback, userdata); } + /** https://wiki.libsdl.org/SDL3/SDL_SetLogPriorities */ + static void SetPriorities(SDL_LogPriority priority) { SDL_SetLogPriorities(priority); } + /** https://wiki.libsdl.org/SDL3/SDL_SetLogPriority */ + void SetPriority(SDL_LogPriority priority) { SDL_SetLogPriority(category, priority); } + /** @todo https://wiki.libsdl.org/SDL3/SDL_SetLogPriorityPrefix */ +// static Log Application(){static Log app(SDL_LOG_CATEGORY_APPLICATION); return app;} + }; + const Log Log::Application(SDL_LOG_CATEGORY_APPLICATION); +} \ No newline at end of file diff --git a/include/hdk/sdl/Properties.hpp b/include/hdk/sdl/Properties.hpp index 28bfd46..f98d953 100644 --- a/include/hdk/sdl/Properties.hpp +++ b/include/hdk/sdl/Properties.hpp @@ -1,176 +1,52 @@ #pragma once -/** - * @file Properties.hpp - * @brief Properties are a set of values represented by a single ID. - */ +/// @file Properties.hpp +/// For complete documentation, see src/Properties.cpp #include #include -/** Many SDL objects have associated properties. */ namespace hdk::sdl { class Properties : public grid::PrimitiveWrapper { public: using grid::PrimitiveWrapper::PrimitiveWrapper; - /** @see SDL_CreateProperties - * https://wiki.libsdl.org/SDL3/SDL_CreateProperties - * @brief Creates a new properties set. - * @return Properties A new properties set. - */ static Properties Create() { return Properties(SDL_CreateProperties()); } - /** @see SDL_ClearProperty - * https://wiki.libsdl.org/SDL3/SDL_ClearProperty - * @brief Clears a property from a properties set. - * @param name - * @return bool True on success, false on failure. - **/ bool ClearProperty(const char* name) const { return SDL_ClearProperty(*this, name); } - /** @see SDL_CopyProperties - * https://wiki.libsdl.org/SDL3/SDL_CopyProperties - * @brief Copies a properties set. - * @return bool True on success, false on failure. - */ bool CopyAllTo(SDL_PropertiesID destination) const { return SDL_CopyProperties(*this, destination); } bool CopyAllFrom(SDL_PropertiesID source) { return SDL_CopyProperties(source, *this); } - /** @see SDL_DestroyProperties - * https://wiki.libsdl.org/SDL3/SDL_DestroyProperties - * @brief Destroys a properties set. - */ void Destroy() { SDL_DestroyProperties(*this); *this = 0; } - /** @see SDL_EnumerateProperties - * https://wiki.libsdl.org/SDL3/SDL_EnumerateProperties - * @brief Enumerates properties in a properties set. - * @param callback An `SDL_EnumeratePropertiesCallback` function pointer. - * @param callback_data Void pointer that is passed to the callback function. - * @return bool True on success, false on failure. - */ bool EnumerateProperties(SDL_EnumeratePropertiesCallback callback, void* callback_data) const { return SDL_EnumerateProperties(*this, callback, callback_data); } - /** @see SDL_GetBooleanProperty - * https://wiki.libsdl.org/SDL3/SDL_GetBooleanProperty - * @brief Gets a boolean property from a properties set. - * @param name The name of the property. - * @param default_value The default value to return if the property does not exist. - * @return bool The value of the property. - */ bool GetBooleanProperty(const char* name, bool default_value) const { return SDL_GetBooleanProperty(*this, name, default_value); } - /** @see SDL_GetFloatProperty - * https://wiki.libsdl.org/SDL3/SDL_GetFloatProperty - * @brief Gets a float property from a properties set. - * @param name The name of the property. - * @param default_value The default value to return if the property does not exist. - * @return float The value of the property. - */ float GetFloatProperty(const char* name, float default_value) const { return SDL_GetFloatProperty(*this, name, default_value); } - /** @see SDL_GetGlobalProperties - * https://wiki.libsdl.org/SDL3/SDL_GetGlobalProperties - * @brief Gets the global properties set. - * @return SDL_PropertiesID The global properties set. - */ static Properties GetGlobalProperties() { return Properties(SDL_GetGlobalProperties()); } - /** @see SDL_GetNumberProperty - * https://wiki.libsdl.org/SDL3/SDL_GetNumberProperty - * @brief Gets a number property from a properties set. - * @param name The name of the property. - * @param default_value The default value to return if the property does not exist. - * @return double The value of the property. - */ double GetNumberProperty(const char* name, double default_value) const { return SDL_GetNumberProperty(*this, name, default_value); } - /** @see SDL_GetPointerProperty - * https://wiki.libsdl.org/SDL3/SDL_GetPointerProperty - * @brief Gets a pointer property from a properties set. - * @param name The name of the property. - * @param default_value The default value to return if the property does not exist. - * @return void* The value of the property. - */ void* GetPointerProperty(const char* name, void* default_value) const { return SDL_GetPointerProperty(*this, name, default_value); } - /** @see SDL_GetPropertyType - * https://wiki.libsdl.org/SDL3/SDL_GetPropertyType - * @brief Gets the type of a property in a properties set. - * @param name The name of the property. - * @return SDL_PropertyType The type of the property. - */ SDL_PropertyType GetPropertyType(const char* name) const { return SDL_GetPropertyType(*this, name); } - /** @see SDL_GetStringProperty - * https://wiki.libsdl.org/SDL3/SDL_GetStringProperty - * @brief Gets a string property from a properties set. - * @param name The name of the property. - * @param default_value The default value to return if the property does not exist. - * @return const char* The value of the property. - */ const char* GetStringProperty(const char* name, const char* default_value) const { return SDL_GetStringProperty(*this, name, default_value); } - /** @see SDL_HasProperty - * https://wiki.libsdl.org/SDL3/SDL_HasProperty - * @brief Checks if a property exists in a properties set. - * @param name The name of the property. - * @return bool True if the property exists, false otherwise. - */ bool HasProperty(const char* name) const { return SDL_HasProperty(*this, name); } - /** @see SDL_LockProperties - * https://wiki.libsdl.org/SDL3/SDL_LockProperties - * @brief Locks a properties set for writing. - * @return bool True on success, false on failure. - */ bool LockProperties() { return SDL_LockProperties(*this); } - /** @see SDL_SetBooleanProperty - * https://wiki.libsdl.org/SDL3/SDL_SetBooleanProperty - * @brief Sets a boolean property in a properties set. - * @param name The name of the property. - * @param value The value to set. - * @return bool True on success, false on failure. - */ bool SetBooleanProperty(const char* name, bool value) { return SDL_SetBooleanProperty(*this, name, value); } // SDL_SetFloatProperty - /** @see SDL_SetFloatProperty - * https://wiki.libsdl.org/SDL3/SDL_SetFloatProperty - * @brief Sets a float property in a properties set. - * @param name The name of the property. - * @param value The value to set. - * @return bool True on success, false on failure. - */ bool SetFloatProperty(const char* name, float value) { return SDL_SetFloatProperty(*this, name, value); } // SDL_SetNumberProperty - /** @see SDL_SetNumberProperty - * https://wiki.libsdl.org/SDL3/SDL_SetNumberProperty - * @brief Sets a number property in a properties set. - * @param name The name of the property. - * @param value The value to set. - * @return bool True on success, false on failure. - */ bool SetNumberProperty(const char* name, double value) { return SDL_SetNumberProperty(*this, name, value); } // SDL_SetPointerProperty - /** @see SDL_SetPointerProperty - * https://wiki.libsdl.org/SDL3/SDL_SetPointerProperty - * @brief Sets a pointer property in a properties set. - * @param name The name of the property. - * @param value The value to set. - * @return bool True on success, false on failure. - */ bool SetPointerProperty(const char* name, void* value) { return SDL_SetPointerProperty(*this, name, value); } // SDL_SetPointerPropertyWithCleanup - /** @see SDL_SetPointerPropertyWithCleanup - * https://wiki.libsdl.org/SDL3/SDL_SetPointerPropertyWithCleanup - * @brief Sets a pointer property in a properties set with a cleanup callback. - * @param name The name of the property. - * @param value The value to set. - * @param cleanup_callback An `SDL_CleanupPropertyCallback` function pointer that is called when the property is cleared or the properties set is destroyed. - * @param userdata Void pointer that is passed to cleanup_callback. - * @return bool True on success, false on failure. - */ bool SetPointerPropertyWithCleanup(const char* name, void* value, SDL_CleanupPropertyCallback cleanup_callback, @@ -178,19 +54,8 @@ namespace hdk::sdl { return SDL_SetPointerPropertyWithCleanup(*this, name, value, cleanup_callback, userdata); } // SDL_SetStringProperty - /** @see SDL_SetStringProperty - * https://wiki.libsdl.org/SDL3/SDL_SetStringProperty - * @brief Sets a string property in a properties set. - * @param name The name of the property. - * @param value The value to set. - * @return bool True on success, false on failure. - */ bool SetStringProperty(const char* name, const char* value) { return SDL_SetStringProperty(*this, name, value); } // SDL_UnlockProperties - /** @see SDL_UnlockProperties - * https://wiki.libsdl.org/SDL3/SDL_UnlockProperties - * @brief Unlocks a properties set after writing. - */ void UnlockProperties() { SDL_UnlockProperties(*this); } }; } \ No newline at end of file diff --git a/include/hdk/sdl/event.hpp b/include/hdk/sdl/event.hpp new file mode 100644 index 0000000..993639c --- /dev/null +++ b/include/hdk/sdl/event.hpp @@ -0,0 +1,862 @@ +#pragma once +/// @file event.hpp +/// For complete documentation, see src/event.cpp +#include +#include +#include +#include +#include +#include +#include + +namespace hdk::sdl { + class Event { + public: + static void AddWatch(SDL_EventFilter filter, void* userdata) { SDL_AddEventWatch(filter, userdata); } + static bool EventEnabled(Uint32 type) { return SDL_EventEnabled(type); } + static void FilterEvents(SDL_EventFilter filter, void* userdata) { SDL_FilterEvents(filter, userdata); } + static void FlushEvent(Uint32 type) { SDL_FlushEvent(type); } + static void FlushEvents(Uint32 min_type, Uint32 max_type) { SDL_FlushEvents(min_type, max_type); } + static int GetDescription(const SDL_Event* event, char* buf, int buflen) { + return SDL_GetEventDescription(event, buf, buflen); + } + static std::string GetDescription(const SDL_Event* event) { + char buf[256]; + GetDescription(event, buf, sizeof(buf)); + return std::string(buf); + } + static bool GetFilter(SDL_EventFilter* filter, void** userdata) { return SDL_GetEventFilter(filter, userdata); } + static Window GetWindowFromEvent(const SDL_Event* event) { + return Window::get_or_view(SDL_GetWindowFromEvent(event)); + } + static bool Has(Uint32 type) { return SDL_HasEvent(type); } + static bool Has(Uint32 min_type, Uint32 max_type) { return SDL_HasEvents(min_type, max_type); } + static int Peep(SDL_Event* events, int numevents, SDL_EventAction action, Uint32 min_type, Uint32 max_type) { + return SDL_PeepEvents(events, numevents, action, min_type, max_type); + } + static bool Poll(SDL_Event* event) { return SDL_PollEvent(event); } + static void Pump() { SDL_PumpEvents(); } + static bool Push(SDL_Event* event) { return SDL_PushEvent(event); } + template static std::string GetDescription(const SDL_Event* event) { + char buf[BUFLEN]; + int actual_length = SDL_GetEventDescription(event, buf, sizeof(buf)); + if (actual_length > BUFLEN) { + return std::string("BUFFER TOO SMALL"); + } + return std::string(buf); + } + }; + +} + +namespace hdk::sdl::evt { + + class EventConduit : public hdk::grid::eps::Conduit { + public: + using hdk::grid::eps::Conduit::Conduit; + }; + + template > + class EventValueRouter : public EventConduit { + public: + // The type of the map of values to dispatch (for child classes to use) + typedef MapType value_dispatch_map_t; + // The map of values to dispatch to + value_dispatch_map_t value_dispatch_map; + // Constructor takes a map of values to dispatch to + EventValueRouter(value_dispatch_map_t dispatch_map) + : value_dispatch_map(dispatch_map) { } + // The extractor function is a pure virtual function that child classes must implement to extract the value from + // the event + virtual ValueType extractor(SDL_Event* event) = 0; + // The Trigger function overrides the base Event Trigger function to extract the value from the event and dispatch + // to the appropriate callback based on that value, as well as triggering any callbacks in the base Event dispatch + // list. + virtual void Trigger(SDL_Event* event) override { + if (!event) + return; + ValueType value = this->extractor(event); + auto it = value_dispatch_map.find(value); + if (it != value_dispatch_map.end() && it->second) { + (*it->second)(event); + } else { + return; + } + EventConduit::Trigger(event); + } + // Allow direct access to the dispatch map for subscribing to specific values + EventType& operator[](ValueType value) { return *value_dispatch_map[value]; } + }; + + class EventTypeRouter + : public EventValueRouter> { + public: + EventTypeRouter(value_dispatch_map_t dispatch_map) + : EventValueRouter(std::move(dispatch_map)) { } + virtual SDL_EventType extractor(SDL_Event* event) override { return (SDL_EventType)event->type; } + }; + + class DisplayEvents : public EventTypeRouter { + public: + EventConduit Orientation, Added, Removed, Moved, DesktopModeChanged, CurrentModeChanged, ContentScaleChanged; + // clang-format off + DisplayEvents() + : EventTypeRouter({ + { SDL_EVENT_DISPLAY_ORIENTATION, &Orientation }, + { SDL_EVENT_DISPLAY_ADDED, &Added }, + { SDL_EVENT_DISPLAY_REMOVED, &Removed }, + { SDL_EVENT_DISPLAY_MOVED, &Moved }, + { SDL_EVENT_DISPLAY_DESKTOP_MODE_CHANGED, &DesktopModeChanged }, + { SDL_EVENT_DISPLAY_CURRENT_MODE_CHANGED, &CurrentModeChanged }, + { SDL_EVENT_DISPLAY_CONTENT_SCALE_CHANGED, &ContentScaleChanged } + }) { } + // clang-format on + }; + + class KeyEvents : public EventTypeRouter { + public: + EventConduit Down, Up; + // clang-format off + KeyEvents() + : EventTypeRouter({ + { SDL_EVENT_KEY_DOWN, &Down }, + { SDL_EVENT_KEY_UP, &Up } + }) { }; + // clang-format on + }; + + class KeysEvents : public EventValueRouter { + public: + KeysEvents() + : EventValueRouter({}) { } + virtual SDL_Keycode extractor(SDL_Event* event) override { return event->key.key; } + }; + + class JoystickAxisEvents : public EventValueRouter { + public: + JoystickAxisEvents() + : EventValueRouter({}) { } + virtual Uint8 extractor(SDL_Event* event) override { return event->jaxis.axis; } + }; + + class JoystickBallEvents : public EventValueRouter { + public: + JoystickBallEvents() + : EventValueRouter({}) { } + virtual Uint8 extractor(SDL_Event* event) override { return event->jball.ball; } + }; + + class JoystickHatEvents : public EventValueRouter { + public: + JoystickHatEvents() + : EventValueRouter({}) { } + virtual Uint8 extractor(SDL_Event* event) override { return event->jhat.hat; } + }; + + class JoystickButtonEvents : public EventTypeRouter { + public: + EventConduit Down, Up; + // clang-format off + JoystickButtonEvents() + : EventTypeRouter({ + { SDL_EVENT_JOYSTICK_BUTTON_DOWN, &Down }, + { SDL_EVENT_JOYSTICK_BUTTON_UP, &Up } + }) { } + // clang-format on + }; + + class JoystickButtonsEvents : public EventValueRouter { + public: + JoystickButtonsEvents() + : EventValueRouter({}) { } + virtual Uint8 extractor(SDL_Event* event) override { return event->jbutton.button; } + }; + + class JoystickEvents : public EventTypeRouter { + public: + JoystickAxisEvents AxisMotion; + JoystickBallEvents BallMotion; + JoystickHatEvents HatMotion; + JoystickButtonsEvents Button; + EventConduit Added, Removed, BatteryUpdated, UpdateComplete; + // clang-format off + JoystickEvents() + : EventTypeRouter({ + { SDL_EVENT_JOYSTICK_AXIS_MOTION, &AxisMotion }, + { SDL_EVENT_JOYSTICK_BALL_MOTION, &BallMotion }, + { SDL_EVENT_JOYSTICK_HAT_MOTION, &HatMotion }, + { SDL_EVENT_JOYSTICK_BUTTON_DOWN, &Button }, + { SDL_EVENT_JOYSTICK_BUTTON_UP, &Button }, + { SDL_EVENT_JOYSTICK_ADDED, &Added }, + { SDL_EVENT_JOYSTICK_REMOVED, &Removed }, + { SDL_EVENT_JOYSTICK_BATTERY_UPDATED, &BatteryUpdated }, + { SDL_EVENT_JOYSTICK_UPDATE_COMPLETE, &UpdateComplete } + }) { } + // clang-format on + }; + + class JoysticksEvents : public EventValueRouter { + public: + JoysticksEvents() + : EventValueRouter({}) { } + virtual SDL_JoystickID extractor(SDL_Event* event) override { + switch (event->type) { + case SDL_EVENT_JOYSTICK_AXIS_MOTION: + return event->jaxis.which; + case SDL_EVENT_JOYSTICK_BALL_MOTION: + return event->jball.which; + case SDL_EVENT_JOYSTICK_HAT_MOTION: + return event->jhat.which; + case SDL_EVENT_JOYSTICK_BUTTON_DOWN: + case SDL_EVENT_JOYSTICK_BUTTON_UP: + return event->jbutton.which; + case SDL_EVENT_JOYSTICK_ADDED: + case SDL_EVENT_JOYSTICK_REMOVED: + case SDL_EVENT_JOYSTICK_BATTERY_UPDATED: + case SDL_EVENT_JOYSTICK_UPDATE_COMPLETE: + return event->jdevice.which; + default: + return -1; // Invalid ID for unsupported event types + } + } + }; + + class GamepadAxisEvents : public EventValueRouter { + public: + GamepadAxisEvents() + : EventValueRouter({}) { } + virtual SDL_GamepadAxis extractor(SDL_Event* event) override { return (SDL_GamepadAxis)event->gaxis.axis; } + }; + + class GamepadButtonEvents : public EventTypeRouter { + public: + EventConduit Down, Up; + // clang-format off + GamepadButtonEvents() + : EventTypeRouter({ + { SDL_EVENT_GAMEPAD_BUTTON_DOWN, &Down }, + { SDL_EVENT_GAMEPAD_BUTTON_UP, &Up } + }) { } + // clang-format on + }; + + class GamepadButtonsEvents : public EventValueRouter { + public: + GamepadButtonsEvents() + : EventValueRouter({}) { } + virtual SDL_GamepadButton extractor(SDL_Event* event) override { + return (SDL_GamepadButton)event->gbutton.button; + } + }; + + class GamepadTouchpadEvents : public EventTypeRouter { + public: + EventConduit Down, Motion, Up; + // clang-format off + GamepadTouchpadEvents() + : EventTypeRouter({ + { SDL_EVENT_GAMEPAD_TOUCHPAD_DOWN, &Down }, + { SDL_EVENT_GAMEPAD_TOUCHPAD_MOTION, &Motion }, + { SDL_EVENT_GAMEPAD_TOUCHPAD_UP, &Up } + }) { } + // clang-format on + }; + + class GamepadEvents : public EventTypeRouter { + public: + GamepadAxisEvents AxisMotion; + GamepadButtonsEvents Button; + EventConduit Added, Removed, Remapped; + GamepadTouchpadEvents Touchpad; + EventConduit SensorUpdate, UpdateComplete, SteamHandleUpdate; + + // clang-format off + GamepadEvents() + : EventTypeRouter({ + { SDL_EVENT_GAMEPAD_AXIS_MOTION, &AxisMotion }, + { SDL_EVENT_GAMEPAD_BUTTON_DOWN, &Button }, + { SDL_EVENT_GAMEPAD_BUTTON_UP, &Button }, + { SDL_EVENT_GAMEPAD_ADDED, &Added }, + { SDL_EVENT_GAMEPAD_REMOVED, &Removed }, + { SDL_EVENT_GAMEPAD_REMAPPED, &Remapped }, + { SDL_EVENT_GAMEPAD_TOUCHPAD_DOWN, &Touchpad }, + { SDL_EVENT_GAMEPAD_TOUCHPAD_MOTION, &Touchpad }, + { SDL_EVENT_GAMEPAD_TOUCHPAD_UP, &Touchpad }, + { SDL_EVENT_GAMEPAD_SENSOR_UPDATE, &SensorUpdate }, + { SDL_EVENT_GAMEPAD_UPDATE_COMPLETE, &UpdateComplete } + }) { + } + // clang-format on + }; + + class GamepadsEvents : public EventValueRouter { + public: + GamepadsEvents() + : EventValueRouter({}) { } + virtual SDL_JoystickID extractor(SDL_Event* event) override { + switch (event->type) { + case SDL_EVENT_GAMEPAD_AXIS_MOTION: + return event->gaxis.which; + case SDL_EVENT_GAMEPAD_BUTTON_DOWN: + case SDL_EVENT_GAMEPAD_BUTTON_UP: + return event->gbutton.which; + case SDL_EVENT_GAMEPAD_ADDED: + case SDL_EVENT_GAMEPAD_REMOVED: + case SDL_EVENT_GAMEPAD_REMAPPED: + return event->gdevice.which; + case SDL_EVENT_GAMEPAD_TOUCHPAD_DOWN: + case SDL_EVENT_GAMEPAD_TOUCHPAD_MOTION: + case SDL_EVENT_GAMEPAD_TOUCHPAD_UP: + return event->gtouchpad.which; + case SDL_EVENT_GAMEPAD_SENSOR_UPDATE: + case SDL_EVENT_GAMEPAD_UPDATE_COMPLETE: + case SDL_EVENT_GAMEPAD_STEAM_HANDLE_UPDATED: + return event->gsensor.which; + default: + return -1; // Invalid ID for unsupported event types + } + } + }; + + class FingerEvents : public EventTypeRouter { + public: + EventConduit Down, Up, Motion, Canceled; + // clang-format off + FingerEvents() + : EventTypeRouter({ + { SDL_EVENT_FINGER_DOWN, &Down }, + { SDL_EVENT_FINGER_UP, &Up }, + { SDL_EVENT_FINGER_MOTION, &Motion } , + { SDL_EVENT_FINGER_CANCELED, &Canceled } + }) { } + // clang-format on + }; + + class DropEvents : public EventTypeRouter { + public: + EventConduit File, Text, Begin, Complete; + // clang-format off + DropEvents() + : EventTypeRouter({ + { SDL_EVENT_DROP_FILE, &File }, + { SDL_EVENT_DROP_TEXT, &Text }, + { SDL_EVENT_DROP_BEGIN, &Begin }, + { SDL_EVENT_DROP_COMPLETE, &Complete } + }) { } + // clang-format on + }; + + class AudioDeviceEvents : public EventTypeRouter { + public: + EventConduit Added, Removed, FormatChanged; + // clang-format off + AudioDeviceEvents() + : EventTypeRouter({ + { SDL_EVENT_AUDIO_DEVICE_ADDED, &Added }, + { SDL_EVENT_AUDIO_DEVICE_REMOVED, &Removed }, + { SDL_EVENT_AUDIO_DEVICE_FORMAT_CHANGED, &FormatChanged } + }) { + } + // clang-format on + }; + + class PenEvents : public EventTypeRouter { + public: + EventConduit ProximityIn, ProximityOut, Down, Up, Motion; + // clang-format off + PenEvents() + : EventTypeRouter({ + { SDL_EVENT_PEN_PROXIMITY_IN, &ProximityIn }, + { SDL_EVENT_PEN_PROXIMITY_OUT, &ProximityOut }, + { SDL_EVENT_PEN_DOWN, &Down }, + { SDL_EVENT_PEN_UP, &Up }, + { SDL_EVENT_PEN_MOTION, &Motion } + }) { } + // clang-format on + }; + + class CameraDeviceEvents : public EventTypeRouter { + public: + EventConduit Added, Removed, Approved, Denied; + // clang-format off + CameraDeviceEvents() + : EventTypeRouter({ + { SDL_EVENT_CAMERA_DEVICE_ADDED, &Added }, + { SDL_EVENT_CAMERA_DEVICE_REMOVED, &Removed }, + { SDL_EVENT_CAMERA_DEVICE_APPROVED, &Approved } , + { SDL_EVENT_CAMERA_DEVICE_DENIED, &Denied} + }) { + } + // clang-format on + }; + + class RenderEvents : public EventTypeRouter { + public: + EventConduit TargetsReset, DeviceReset, DeviceLost; + // clang-format off + RenderEvents() + : EventTypeRouter({ + { SDL_EVENT_RENDER_TARGETS_RESET, &TargetsReset }, + { SDL_EVENT_RENDER_DEVICE_RESET, &DeviceReset }, + { SDL_EVENT_RENDER_DEVICE_LOST, &DeviceLost } + }) { } + // clang-format on + }; + + class KeyboardEvents : public EventTypeRouter { + public: + EventConduit Added, Removed; + // clang-format off + KeyboardEvents() + : EventTypeRouter({ + { SDL_EVENT_KEYBOARD_ADDED, &Added }, + { SDL_EVENT_KEYBOARD_REMOVED, &Removed } + }) { } + // clang-format on + }; + + class MouseButtonEvents : public EventTypeRouter { + public: + EventConduit Down, Up; + // clang-format off + MouseButtonEvents() + : EventTypeRouter({ + { SDL_EVENT_MOUSE_BUTTON_DOWN, &Down }, + { SDL_EVENT_MOUSE_BUTTON_UP, &Up } + }) { } + // clang-format on + }; + + class MouseButtonsEvents : public EventValueRouter { + public: + MouseButtonsEvents() + : EventValueRouter({}) { } + virtual Uint8 extractor(SDL_Event* event) override { return event->button.button; } + }; + + class MouseEvents : public EventTypeRouter { + public: + MouseButtonsEvents Button; + EventConduit Motion, Wheel, Added, Removed; + // clang-format off + MouseEvents() + : EventTypeRouter({ + { SDL_EVENT_MOUSE_MOTION, &Motion }, + { SDL_EVENT_MOUSE_BUTTON_DOWN, &Button }, + { SDL_EVENT_MOUSE_BUTTON_UP, &Button }, + { SDL_EVENT_MOUSE_WHEEL, &Wheel }, + { SDL_EVENT_MOUSE_ADDED, &Added }, + { SDL_EVENT_MOUSE_REMOVED, &Removed } + }) { } + // clang-format on + }; + + class MiceEvents : public EventValueRouter { + public: + MiceEvents() + : EventValueRouter({}) { } + virtual SDL_MouseID extractor(SDL_Event* event) override { + switch (event->type) { + case SDL_EVENT_MOUSE_MOTION: + return event->motion.which; + case SDL_EVENT_MOUSE_BUTTON_DOWN: + case SDL_EVENT_MOUSE_BUTTON_UP: + return event->button.which; + case SDL_EVENT_MOUSE_WHEEL: + return event->wheel.which; + case SDL_EVENT_MOUSE_ADDED: + case SDL_EVENT_MOUSE_REMOVED: + return event->mdevice.which; + default: + return -1; // Invalid ID for unsupported event types + } + } + }; + + class TextEvents : public EventTypeRouter { + public: + EventConduit Input, Editing, EditingCandidates; + // clang-format off + TextEvents() + : EventTypeRouter({ + { SDL_EVENT_TEXT_INPUT, &Input }, + { SDL_EVENT_TEXT_EDITING, &Editing }, + { SDL_EVENT_TEXT_EDITING_CANDIDATES, &EditingCandidates } + }) { } + // clang-format on + }; + + class WindowEvents : public EventTypeRouter { + public: + EventConduit Shown, Hidden, Exposed, Moved, Resized, PixelSizeChanged, MetalViewResized, Minimized, Maximized, Restored, + MouseEnter, MouseLeave, FocusLost, CloseRequested, HitTest, ICCProfChange, DisplayChanged, DisplayScaleChanged, + SafeAreaChanged, Occluded, EnterFullscreen, LeaveFullscreen, LeaveDesktop, TakeFocus, HitTestResult, Destroyed, + HdrStateChanged; + + // @todo possibly refactor to a specialized subclass, + // these are not "WINDOW" events; but events that identify "WindowID", + // and so we dispatch them to handlers for that window so that each window can have its own + // unified set of handlers. + FingerEvents Finger; + PenEvents Pen; + MiceEvents Mouse; + KeysEvents Key; + TextEvents Text; + DropEvents Drop; + RenderEvents Render; + // clang-format off + WindowEvents() + : EventTypeRouter({ + { SDL_EVENT_WINDOW_SHOWN, &Shown }, + { SDL_EVENT_WINDOW_HIDDEN, &Hidden }, + { SDL_EVENT_WINDOW_EXPOSED, &Exposed }, + { SDL_EVENT_WINDOW_MOVED, &Moved }, + { SDL_EVENT_WINDOW_RESIZED, &Resized }, + { SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED, &PixelSizeChanged }, + { SDL_EVENT_WINDOW_METAL_VIEW_RESIZED, &MetalViewResized }, + { SDL_EVENT_WINDOW_MINIMIZED, &Minimized }, + { SDL_EVENT_WINDOW_MAXIMIZED, &Maximized }, + { SDL_EVENT_WINDOW_RESTORED, &Restored }, + { SDL_EVENT_WINDOW_MOUSE_ENTER, &MouseEnter }, + { SDL_EVENT_WINDOW_MOUSE_LEAVE, &MouseLeave }, + { SDL_EVENT_WINDOW_FOCUS_LOST, &FocusLost }, + { SDL_EVENT_WINDOW_CLOSE_REQUESTED, &CloseRequested }, + { SDL_EVENT_WINDOW_HIT_TEST, &HitTest }, + { SDL_EVENT_WINDOW_ICCPROF_CHANGED, &ICCProfChange }, + { SDL_EVENT_WINDOW_DISPLAY_CHANGED, &DisplayChanged }, + { SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED, &DisplayScaleChanged }, + { SDL_EVENT_WINDOW_SAFE_AREA_CHANGED, &SafeAreaChanged }, + { SDL_EVENT_WINDOW_OCCLUDED, &Occluded }, + { SDL_EVENT_WINDOW_ENTER_FULLSCREEN, &EnterFullscreen }, + { SDL_EVENT_WINDOW_LEAVE_FULLSCREEN, &LeaveFullscreen }, + { SDL_EVENT_WINDOW_DESTROYED, &Destroyed }, + { SDL_EVENT_WINDOW_HDR_STATE_CHANGED, &HdrStateChanged }, + + { SDL_EVENT_FINGER_DOWN, &Finger }, + { SDL_EVENT_FINGER_UP, &Finger }, + { SDL_EVENT_FINGER_MOTION, &Finger }, + { SDL_EVENT_FINGER_CANCELED, &Finger }, + + { SDL_EVENT_PEN_MOTION, &Pen }, + + { SDL_EVENT_PEN_BUTTON_DOWN, &Pen }, + { SDL_EVENT_PEN_BUTTON_UP, &Pen }, + + { SDL_EVENT_PEN_AXIS, &Pen }, + + { SDL_EVENT_MOUSE_WHEEL, &Mouse}, + + { SDL_EVENT_MOUSE_MOTION, &Mouse}, + + { SDL_EVENT_MOUSE_BUTTON_DOWN, &Mouse }, + { SDL_EVENT_MOUSE_BUTTON_UP, &Mouse }, + + { SDL_EVENT_KEY_DOWN, &Key }, + { SDL_EVENT_KEY_UP, &Key }, + + { SDL_EVENT_PEN_PROXIMITY_IN, &Pen }, + { SDL_EVENT_PEN_PROXIMITY_OUT, &Pen }, + + { SDL_EVENT_PEN_DOWN, &Pen }, + { SDL_EVENT_PEN_UP, &Pen }, + + { SDL_EVENT_TEXT_INPUT, &Text }, + + { SDL_EVENT_TEXT_EDITING, &Text }, + + { SDL_EVENT_TEXT_EDITING_CANDIDATES, &Text }, + + { SDL_EVENT_RENDER_TARGETS_RESET, &Render }, + { SDL_EVENT_RENDER_DEVICE_RESET, &Render }, + { SDL_EVENT_RENDER_DEVICE_LOST, &Render }, + + { SDL_EVENT_DROP_BEGIN, &Drop }, + { SDL_EVENT_DROP_FILE, &Drop }, + { SDL_EVENT_DROP_TEXT, &Drop }, + { SDL_EVENT_DROP_COMPLETE, &Drop }, + { SDL_EVENT_DROP_POSITION, &Drop } + }) { } + // clang-format on + }; + + class WindowsEvents : public EventValueRouter { + public: + std::map windows; + WindowsEvents() + : EventValueRouter({}) { } + WindowEvents& operator[](SDL_WindowID window_id) { + WindowEvents& window = windows[window_id]; + value_dispatch_map[window_id] = &window; + return window; + } + virtual SDL_WindowID extractor(SDL_Event* event) override { + switch (event->type) { + case SDL_EVENT_WINDOW_SHOWN: + case SDL_EVENT_WINDOW_HIDDEN: + case SDL_EVENT_WINDOW_EXPOSED: + case SDL_EVENT_WINDOW_MOVED: + case SDL_EVENT_WINDOW_RESIZED: + case SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED: + case SDL_EVENT_WINDOW_METAL_VIEW_RESIZED: + case SDL_EVENT_WINDOW_MINIMIZED: + case SDL_EVENT_WINDOW_MAXIMIZED: + case SDL_EVENT_WINDOW_RESTORED: + case SDL_EVENT_WINDOW_MOUSE_ENTER: + case SDL_EVENT_WINDOW_MOUSE_LEAVE: + case SDL_EVENT_WINDOW_FOCUS_GAINED: + case SDL_EVENT_WINDOW_FOCUS_LOST: + case SDL_EVENT_WINDOW_CLOSE_REQUESTED: + case SDL_EVENT_WINDOW_HIT_TEST: + case SDL_EVENT_WINDOW_ICCPROF_CHANGED: + case SDL_EVENT_WINDOW_DISPLAY_CHANGED: + case SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED: + case SDL_EVENT_WINDOW_SAFE_AREA_CHANGED: + case SDL_EVENT_WINDOW_OCCLUDED: + case SDL_EVENT_WINDOW_ENTER_FULLSCREEN: + case SDL_EVENT_WINDOW_LEAVE_FULLSCREEN: + case SDL_EVENT_WINDOW_DESTROYED: + return event->window.windowID; + + case SDL_EVENT_FINGER_DOWN: + case SDL_EVENT_FINGER_UP: + case SDL_EVENT_FINGER_MOTION: + case SDL_EVENT_FINGER_CANCELED: + return event->tfinger.windowID; + + case SDL_EVENT_PEN_BUTTON_DOWN: + case SDL_EVENT_PEN_BUTTON_UP: + return event->pbutton.windowID; + + case SDL_EVENT_PEN_AXIS: + return event->paxis.windowID; + + case SDL_EVENT_MOUSE_WHEEL: + return event->wheel.windowID; + case SDL_EVENT_MOUSE_MOTION: + return event->motion.windowID; + + case SDL_EVENT_MOUSE_BUTTON_DOWN: + case SDL_EVENT_MOUSE_BUTTON_UP: + return event->button.windowID; + + case SDL_EVENT_KEY_DOWN: + case SDL_EVENT_KEY_UP: + return event->key.windowID; + + case SDL_EVENT_PEN_PROXIMITY_IN: + case SDL_EVENT_PEN_PROXIMITY_OUT: + return event->pproximity.windowID; + + case SDL_EVENT_PEN_DOWN: + case SDL_EVENT_PEN_UP: + return event->ptouch.windowID; + + case SDL_EVENT_TEXT_INPUT: + return event->text.windowID; + + case SDL_EVENT_TEXT_EDITING: + return event->edit.windowID; + + case SDL_EVENT_TEXT_EDITING_CANDIDATES: + return event->edit_candidates.windowID; + + case SDL_EVENT_RENDER_TARGETS_RESET: + case SDL_EVENT_RENDER_DEVICE_RESET: + case SDL_EVENT_RENDER_DEVICE_LOST: + return event->render.windowID; + + case SDL_EVENT_DROP_BEGIN: + case SDL_EVENT_DROP_FILE: + case SDL_EVENT_DROP_TEXT: + case SDL_EVENT_DROP_COMPLETE: + case SDL_EVENT_DROP_POSITION: + return event->drop.windowID; + + default: + if (event->type >= SDL_EVENT_USER && event->type <= SDL_EVENT_LAST) { + // User events may have a windowID, but it's not guaranteed, so we check for it here + return event->user.windowID; + } + } + return 0; + } + }; + + class AllTypes : public EventTypeRouter { + public: + EventConduit Quit, Terminating, LowMemory, WillEnterBackground, DidEnterBackground, WillEnterForeground, LocaleChanged, + SystemThemeChanged; + DisplayEvents Display; + WindowsEvents Window; + TextEvents Text; + EventConduit KeymapChanged; + KeysEvents Key; + KeyboardEvents Keyboard; + MiceEvents Mouse; + JoysticksEvents Joystick; + GamepadsEvents Gamepad; + FingerEvents Finger; + EventConduit ClipboardUpdate; + DropEvents Drop; + AudioDeviceEvents AudioDevice; + EventConduit SensorUpdate; + PenEvents Pen; + CameraDeviceEvents CameraDevice; + /* Render Events */ + RenderEvents Render; + // clang-format off + AllTypes() + // https://wiki.libsdl.org/SDL3/SDL_EventType + : EventTypeRouter({ + {SDL_EVENT_QUIT, &Quit }, + {SDL_EVENT_TERMINATING, &Terminating }, + {SDL_EVENT_LOW_MEMORY, &LowMemory }, + {SDL_EVENT_WILL_ENTER_BACKGROUND, &WillEnterBackground }, + {SDL_EVENT_DID_ENTER_BACKGROUND, &DidEnterBackground }, + {SDL_EVENT_WILL_ENTER_FOREGROUND, &WillEnterForeground }, + {SDL_EVENT_LOCALE_CHANGED, &LocaleChanged }, + {SDL_EVENT_SYSTEM_THEME_CHANGED, &SystemThemeChanged }, + {SDL_EVENT_DISPLAY_ORIENTATION, &Display }, + {SDL_EVENT_DISPLAY_ADDED, &Display }, + {SDL_EVENT_DISPLAY_REMOVED, &Display }, + {SDL_EVENT_DISPLAY_MOVED, &Display }, + {SDL_EVENT_DISPLAY_DESKTOP_MODE_CHANGED, &Display }, + {SDL_EVENT_DISPLAY_CURRENT_MODE_CHANGED, &Display }, + {SDL_EVENT_DISPLAY_CONTENT_SCALE_CHANGED, &Display }, + {SDL_EVENT_WINDOW_SHOWN, &Window }, + {SDL_EVENT_WINDOW_HIDDEN, &Window }, + {SDL_EVENT_WINDOW_EXPOSED, &Window }, + {SDL_EVENT_WINDOW_MOVED, &Window }, + {SDL_EVENT_WINDOW_RESIZED, &Window }, + {SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED, &Window }, + {SDL_EVENT_WINDOW_METAL_VIEW_RESIZED, &Window }, + {SDL_EVENT_WINDOW_MINIMIZED, &Window }, + {SDL_EVENT_WINDOW_MAXIMIZED, &Window }, + {SDL_EVENT_WINDOW_RESTORED, &Window }, + {SDL_EVENT_WINDOW_MOUSE_ENTER, &Window }, + {SDL_EVENT_WINDOW_MOUSE_LEAVE, &Window }, + {SDL_EVENT_WINDOW_FOCUS_LOST, &Window }, + {SDL_EVENT_WINDOW_CLOSE_REQUESTED, &Window }, + {SDL_EVENT_WINDOW_HIT_TEST, &Window }, + {SDL_EVENT_WINDOW_ICCPROF_CHANGED, &Window }, + {SDL_EVENT_WINDOW_DISPLAY_CHANGED, &Window }, + {SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED, &Window }, + {SDL_EVENT_WINDOW_SAFE_AREA_CHANGED, &Window }, + {SDL_EVENT_WINDOW_OCCLUDED, &Window }, + {SDL_EVENT_WINDOW_ENTER_FULLSCREEN, &Window }, + {SDL_EVENT_WINDOW_LEAVE_FULLSCREEN, &Window }, + {SDL_EVENT_WINDOW_DESTROYED, &Window }, + {SDL_EVENT_WINDOW_HDR_STATE_CHANGED, &Window }, + {SDL_EVENT_KEY_DOWN, &Key }, + {SDL_EVENT_KEY_UP, &Key }, + {SDL_EVENT_TEXT_EDITING, &Text }, + {SDL_EVENT_TEXT_INPUT, &Text }, + {SDL_EVENT_TEXT_EDITING_CANDIDATES, &Text }, + {SDL_EVENT_KEYMAP_CHANGED, &KeymapChanged }, + {SDL_EVENT_KEYBOARD_ADDED, &Keyboard }, + {SDL_EVENT_KEYBOARD_REMOVED, &Keyboard }, + {SDL_EVENT_MOUSE_MOTION, &Mouse }, + {SDL_EVENT_MOUSE_BUTTON_DOWN, &Mouse }, + {SDL_EVENT_MOUSE_BUTTON_UP, &Mouse }, + {SDL_EVENT_MOUSE_WHEEL, &Mouse }, + {SDL_EVENT_MOUSE_ADDED, &Mouse}, + {SDL_EVENT_MOUSE_REMOVED, &Mouse}, + {SDL_EVENT_JOYSTICK_AXIS_MOTION, &Joystick}, + {SDL_EVENT_JOYSTICK_BALL_MOTION, &Joystick}, + {SDL_EVENT_JOYSTICK_HAT_MOTION, &Joystick}, + {SDL_EVENT_JOYSTICK_BUTTON_DOWN, &Joystick}, + {SDL_EVENT_JOYSTICK_BUTTON_UP, &Joystick}, + {SDL_EVENT_JOYSTICK_ADDED, &Joystick}, + {SDL_EVENT_JOYSTICK_REMOVED, &Joystick}, + {SDL_EVENT_JOYSTICK_BATTERY_UPDATED, &Joystick}, + {SDL_EVENT_JOYSTICK_UPDATE_COMPLETE, &Joystick}, + {SDL_EVENT_GAMEPAD_AXIS_MOTION, &Gamepad}, + {SDL_EVENT_GAMEPAD_BUTTON_DOWN, &Gamepad}, + {SDL_EVENT_GAMEPAD_BUTTON_UP, &Gamepad}, + {SDL_EVENT_GAMEPAD_ADDED, &Gamepad}, + {SDL_EVENT_GAMEPAD_REMOVED, &Gamepad}, + {SDL_EVENT_GAMEPAD_REMAPPED, &Gamepad}, + {SDL_EVENT_GAMEPAD_TOUCHPAD_DOWN, &Gamepad}, + {SDL_EVENT_GAMEPAD_TOUCHPAD_MOTION, &Gamepad}, + {SDL_EVENT_GAMEPAD_TOUCHPAD_UP, &Gamepad}, + {SDL_EVENT_GAMEPAD_SENSOR_UPDATE, &Gamepad}, + {SDL_EVENT_GAMEPAD_UPDATE_COMPLETE, &Gamepad}, + {SDL_EVENT_GAMEPAD_STEAM_HANDLE_UPDATED, &Gamepad}, + {SDL_EVENT_FINGER_DOWN, &Finger}, + {SDL_EVENT_FINGER_UP, &Finger}, + {SDL_EVENT_FINGER_MOTION, &Finger}, + {SDL_EVENT_FINGER_CANCELED, &Finger}, + {SDL_EVENT_CLIPBOARD_UPDATE, &ClipboardUpdate}, + {SDL_EVENT_DROP_FILE, &Drop}, + {SDL_EVENT_DROP_TEXT, &Drop}, + {SDL_EVENT_DROP_BEGIN, &Drop}, + {SDL_EVENT_DROP_COMPLETE, &Drop}, + {SDL_EVENT_DROP_POSITION, &Drop}, + {SDL_EVENT_AUDIO_DEVICE_ADDED, &AudioDevice}, + {SDL_EVENT_AUDIO_DEVICE_REMOVED, &AudioDevice}, + {SDL_EVENT_AUDIO_DEVICE_FORMAT_CHANGED, &AudioDevice}, + {SDL_EVENT_SENSOR_UPDATE, &SensorUpdate}, + {SDL_EVENT_PEN_PROXIMITY_IN, &Pen}, + {SDL_EVENT_PEN_PROXIMITY_OUT, &Pen}, + {SDL_EVENT_PEN_DOWN, &Pen }, + {SDL_EVENT_PEN_UP, &Pen}, + {SDL_EVENT_PEN_BUTTON_DOWN, &Pen}, + {SDL_EVENT_PEN_BUTTON_UP, &Pen}, + {SDL_EVENT_PEN_MOTION, &Pen}, + {SDL_EVENT_PEN_AXIS, &Pen}, + {SDL_EVENT_CAMERA_DEVICE_ADDED, &CameraDevice}, + {SDL_EVENT_CAMERA_DEVICE_REMOVED, &CameraDevice}, + {SDL_EVENT_CAMERA_DEVICE_APPROVED, &CameraDevice }, + {SDL_EVENT_CAMERA_DEVICE_DENIED, &CameraDevice}, + {SDL_EVENT_RENDER_TARGETS_RESET , &Render }, + {SDL_EVENT_RENDER_DEVICE_RESET, &Render}, + {SDL_EVENT_RENDER_DEVICE_LOST, &Render} + }) { }; + // clang-format on + + // In addition to dispatching things to their normal handler we are also going to send all events that have a + // WindowID to the CompleteWindowsEvents handler, so that users can listen for all events related to a specific + // window in one place if they want to. + virtual void Trigger(SDL_Event* event) override { + switch (event->type) { + // SDL_EVENT_WINDOW_* is already forwarded to Window event handlers + // But these following events contain a WindowID, and so we want to forward them too there. + // THat way people can subscribe to things like All mouse events for Window 'x'. + case SDL_EVENT_FINGER_DOWN: + case SDL_EVENT_FINGER_UP: + case SDL_EVENT_FINGER_MOTION: + case SDL_EVENT_FINGER_CANCELED: + case SDL_EVENT_PEN_MOTION: + case SDL_EVENT_PEN_BUTTON_DOWN: + case SDL_EVENT_PEN_BUTTON_UP: + case SDL_EVENT_PEN_AXIS: + case SDL_EVENT_MOUSE_WHEEL: + case SDL_EVENT_MOUSE_MOTION: + case SDL_EVENT_MOUSE_BUTTON_DOWN: + case SDL_EVENT_MOUSE_BUTTON_UP: + case SDL_EVENT_KEY_DOWN: + case SDL_EVENT_KEY_UP: + case SDL_EVENT_PEN_PROXIMITY_IN: + case SDL_EVENT_PEN_PROXIMITY_OUT: + case SDL_EVENT_PEN_DOWN: + case SDL_EVENT_PEN_UP: + case SDL_EVENT_TEXT_INPUT: + case SDL_EVENT_TEXT_EDITING: + case SDL_EVENT_TEXT_EDITING_CANDIDATES: + case SDL_EVENT_RENDER_TARGETS_RESET: + case SDL_EVENT_RENDER_DEVICE_RESET: + case SDL_EVENT_RENDER_DEVICE_LOST: + case SDL_EVENT_DROP_BEGIN: + case SDL_EVENT_DROP_FILE: + case SDL_EVENT_DROP_TEXT: + case SDL_EVENT_DROP_COMPLETE: + case SDL_EVENT_DROP_POSITION: + Window(event); + // default: + // do nothing additional for the others + } + EventTypeRouter::Trigger(event); + } + }; +} // namespace hdk::sdl::evt \ No newline at end of file diff --git a/include/hdk/sdl/main.hpp b/include/hdk/sdl/main.hpp new file mode 100644 index 0000000..729c4a2 --- /dev/null +++ b/include/hdk/sdl/main.hpp @@ -0,0 +1,36 @@ +#pragma once +#define SDL_MAIN_USE_CALLBACKS 1 +#include +#include + +/// @macro HDK_SDL_MAIN_CLASS(klass) +/// @brief Define the SDL main entry point using a class implementing hdk::sdl::ApplicationInterface. +/// @param klass Class name of the application implementation. Must implement hdk::sdl::ApplicationInterface with Init, +/// Event, Iterate, and Quit methods. +/// @details This macro generates the SDL main entry point functions (SDL_AppInit, SDL_AppEvent, SDL_AppIterate, +/// SDL_AppQuit) that create an instance of the specified class and delegate to its methods. This allows users to write +/// their application logic in a clean class structure while still integrating with SDL's application lifecycle. The +/// generated main functions handle the boilerplate of managing the application instance and connecting it to SDL's +/// event loop and lifecycle callbacks. + +#define HDK_SDL_MAIN_CLASS(klass) \ + SDL_AppResult SDL_AppInit(void** appstate, int argc, char* argv[]) { \ + klass* app = new klass(); \ + *appstate = app; \ + return app->Init(argc, argv); \ + } \ + SDL_AppResult SDL_AppEvent(void* appstate, SDL_Event* event) { \ + klass* app = static_cast(appstate); \ + return app->Event(event); \ + } \ + SDL_AppResult SDL_AppIterate(void* appstate) { \ + klass* app = static_cast(appstate); \ + return app->Iterate(); \ + } \ + void SDL_AppQuit(void* appstate, SDL_AppResult result) { \ + klass* app = static_cast(appstate); \ + app->Quit(result); \ + delete app; \ + } + +// end of file \ No newline at end of file diff --git a/include/hdk/sdl/pixels.hpp b/include/hdk/sdl/pixels.hpp index 6e9d60f..20cd38c 100644 --- a/include/hdk/sdl/pixels.hpp +++ b/include/hdk/sdl/pixels.hpp @@ -1,14 +1,11 @@ #pragma once -/** @file pixels.hpp - * @brief glue together various pixel related wrappers that have circular dependencies - */ +/// @file pixels.hpp +/// For complete documentation, see src/pixels.cpp #include "pixels/PixelFormat.hpp" #include "pixels/PixelFormatDetails.hpp" #include "pixels/Palette.hpp" -/** Pixels are a complex subject. */ namespace hdk::sdl { - /** @see https://wiki.libsdl.org/SDL3/SDL_GetPixelFormatDetails */ PixelFormatDetails PixelFormat::GetDetails() const { return PixelFormatDetails::Get(*this); } - + } \ No newline at end of file diff --git a/include/hdk/sdl/pixels/Palette.hpp b/include/hdk/sdl/pixels/Palette.hpp index 921310c..46bad2e 100644 --- a/include/hdk/sdl/pixels/Palette.hpp +++ b/include/hdk/sdl/pixels/Palette.hpp @@ -1,37 +1,18 @@ #pragma once -/** @file Palette.hpp - * @brief HDK sdl video header only wrapper for SDL_Palette struct & related functions - */ +/// @file Palette.hpp +/// For complete documentation, see src/pixels/Palette.cpp #include #include namespace hdk::sdl { - /** - * @brief - * @note - */ class Palette : public hdk::grid::SharedPtrWrapper { public: - /** Inherit constructors from SharedPtrWrapper */ + friend class Texture; + friend class Surface; using hdk::grid::SharedPtrWrapper::SharedPtrWrapper; - /** @see https://wiki.libsdl.org/SDL3/SDL_CreatePalette - * @brief Create a palette with a specified number of colors. - * @param ncolors The number of colors in the palette. - * @return Palette The created palette. If the creation fails, returns an invalid palette. - */ static Palette Create(int ncolors) { return Palette(get_or_cache(SDL_CreatePalette(ncolors), SDL_DestroyPalette)); } - /** @see https://wiki.libsdl.org/SDL3/SDL_DestroyPalette - * @brief Destroy a palette and free its associated memory. - */ void Destroy() const { SDL_DestroyPalette(*this); } - /** @see https://wiki.libsdl.org/SDL3/SDL_SetPaletteColors - * @brief Set a range of colors in a palette. - * @param colors An array of SDL_Color structures representing the colors to set in the palette. - * @param firstcolor The index of the first color to set in the palette. - * @param ncolors The number of colors to set in the palette. - * @return bool True on success, false on failure. - */ bool SetColors(const SDL_Color* colors, int firstcolor, int ncolors) const { return SDL_SetPaletteColors(*this, colors, firstcolor, ncolors); } diff --git a/include/hdk/sdl/pixels/PixelFormat.hpp b/include/hdk/sdl/pixels/PixelFormat.hpp index 1ac1b42..2133f53 100644 --- a/include/hdk/sdl/pixels/PixelFormat.hpp +++ b/include/hdk/sdl/pixels/PixelFormat.hpp @@ -1,52 +1,23 @@ #pragma once -/** @file PixelFormat.hpp - * @brief HDK sdl video header only wrapper for SDL_PixelFormat enum & related functions - */ +/// @file PixelFormat.hpp +/// For complete documentation, see src/pixels/PixelFormat.cpp #include #include -/** PixelFormat makes working with SDL_PixelFormat easier. */ namespace hdk::sdl { /// Forward declare to avoid circular dependency with PixelFormatDetails class PixelFormatDetails; - /** - * @brief - * - */ class PixelFormat : public hdk::grid::PrimitiveWrapper { public: - /** Inherit constructors from PrimitiveWrapper */ using hdk::grid::PrimitiveWrapper::PrimitiveWrapper; - /** @see https://wiki.libsdl.org/SDL3/SDL_GetMasksForPixelFormat - * @brief Get the pixel format masks for a given pixel format. - * @param bpp Pointer to int to be filled in with the number of bytes per pixel. - * @param Rmask Pointer to Uint32 to be filled in with the red mask for the pixel format. - * @param Gmask Pointer to Uint32 to be filled in with the green mask for the pixel format. - * @param Bmask Pointer to Uint32 to be filled in with the blue mask for the pixel format. - * @param Amask Pointer to Uint32 to be filled in with the alpha mask for the pixel format. - * @return bool True on success - */ bool GetMasks(int* bpp, Uint32* Rmask, Uint32* Gmask, Uint32* Bmask, Uint32* Amask) const { return SDL_GetMasksForPixelFormat(*this, bpp, Rmask, Gmask, Bmask, Amask); } // Implemented in `../pixels.hpp` to avoid circular dependency PixelFormatDetails GetDetails() const; - /** @see https://wiki.libsdl.org/SDL3/SDL_GetPixelFormatForMasks - * @brief Get the pixel format for a given set of pixel format masks. - * @param bpp The number of bytes per pixel for the pixel format. - * @param Rmask The red mask for the pixel format. - * @param Gmask The green mask for the pixel format. - * @param Bmask The blue mask for the pixel format. - * @param Amask The alpha mask for the pixel format. - * @return The pixel format corresponding to the given masks, or ::SDL_PIXELFORMAT_UNKNOWN - */ static SDL_PixelFormat GetForMasks(int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask) { return SDL_GetPixelFormatForMasks(bpp, Rmask, Gmask, Bmask, Amask); } - /** @see https://wiki.libsdl.org/SDL3/SDL_GetPixelFormatName - * @brief Get the name of a pixel format. - * @return const char* The name of the pixel format, or "Unknown" if the pixel format is not recognized. - */ const char* GetName() const { return SDL_GetPixelFormatName(*this); } }; diff --git a/include/hdk/sdl/pixels/PixelFormatDetails.hpp b/include/hdk/sdl/pixels/PixelFormatDetails.hpp index 4af846c..de65790 100644 --- a/include/hdk/sdl/pixels/PixelFormatDetails.hpp +++ b/include/hdk/sdl/pixels/PixelFormatDetails.hpp @@ -1,70 +1,24 @@ #pragma once -/** @file Palette.hpp - * @brief HDK sdl video header only wrapper pointers to const SDL_PixelFormatDetails & related functions - * @note Does note use smartpointers because these are SDL owned constant structs. - */ +/// @file PixelFormatDetails.hpp +/// For complete documentation, see src/pixels/PixelFormatDetails.cpp #include #include -/** PixelFormatDetails makes getting the details of a pixel format easier. */ namespace hdk::sdl { - /** - * @brief - * - */ class PixelFormatDetails : public hdk::grid::PrimitiveWrapper { public: - /** Inherit constructors from PrimitiveWrapper */ using hdk::grid::PrimitiveWrapper::PrimitiveWrapper; - /*** @see https://wiki.libsdl.org/SDL3/SDL_GetPixelFormatDetails - * @returns an PixelFormatDetails instance - */ static PixelFormatDetails Get(SDL_PixelFormat format) { return PixelFormatDetails(SDL_GetPixelFormatDetails(format)); } - /** @see https://wiki.libsdl.org/SDL3/SDL_GetRGB - * @brief Get the RGB values for a pixel value - * @param pixel The pixel value to query - * @param palette for indexed formats the palette to use, or NULL for non-indexed formats - * @param r pointer to Uint8 to store the red component - * @param g pointer to Uint8 to store the green component - * @param b pointer to Uint8 to store the blue component - * @param a pointer to Uint8 to store the alpha component - */ - void GetRGB(Uint32 pixel, SDL_Palette* palette, Uint8* r, Uint8* g, Uint8* b, Uint8* a) const { - SDL_GetRGB(pixel, *this, palette, r, g, b, a); + void GetRGB(Uint32 pixel, SDL_Palette* palette, Uint8* r, Uint8* g, Uint8* b) const { + SDL_GetRGB(pixel, *this, palette, r, g, b); } - /** @see https://wiki.libsdl.org/SDL3/SDL_GetRGBA - * @brief Get the RGBA values for a pixel value - * @param pixel The pixel value to query - * @param palette for indexed formats the palette to use, or NULL for non-indexed formats - * @param r pointer to Uint8 to store the red component - * @param g pointer to Uint8 to store the green component - * @param b pointer to Uint8 to store the blue component - * @param a pointer to Uint8 to store the alpha component - */ void GetRGBA(Uint32 pixel, SDL_Palette* palette, Uint8* r, Uint8* g, Uint8* b, Uint8* a) const { SDL_GetRGBA(pixel, *this, palette, r, g, b, a); } - /** @see https://wiki.libsdl.org/SDL3/SDL_MapRGB - * @brief Map RGB values to a pixel value for the pixel format - * @param palette for indexed formats the palette to use, or NULL for non-indexed formats - * @param r The red component of the color - * @param g The green component of the color - * @param b The blue component of the color - * @return The pixel value corresponding to the given RGB values for the pixel format - */ Uint32 MapRGB(SDL_Palette* palette, Uint8 r, Uint8 g, Uint8 b) const { return SDL_MapRGB(*this, palette, r, g, b); } - /** @see https://wiki.libsdl.org/SDL3/SDL_MapRGBA - * @brief Map RGBA values to a pixel value for the pixel format - * @param palette for indexed formats the palette to use, or NULL for non-indexed formats - * @param r The red component of the color - * @param g The green component of the color - * @param b The blue component of the color - * @param a The alpha component of the color - * @return The pixel value corresponding to the given RGBA values for the pixel format - */ Uint32 MapRGBA(SDL_Palette* palette, Uint8 r, Uint8 g, Uint8 b, Uint8 a) const { return SDL_MapRGBA(*this, palette, r, g, b, a); } diff --git a/include/hdk/sdl/render.hpp b/include/hdk/sdl/render.hpp index 994b375..1841869 100644 --- a/include/hdk/sdl/render.hpp +++ b/include/hdk/sdl/render.hpp @@ -1,44 +1,26 @@ #pragma once -/** - * @file render.hpp - * @brief HDK sdl Renderer subsystem. Glues together Texture & Renderer which have circular dependencies - */ +/// @file render.hpp +/// For complete documentation, see src/render.cpp #include #include namespace hdk::sdl { - /** @see https://wiki.libsdl.org/SDL3/SDL_GetRendererFromTexture - * @return Renderer The renderer associated with the texture - */ inline Renderer Texture::GetRenderer() const { /** we may not have created the renderer we get back, if not we will not own it. */ return Renderer(Renderer::get_or_view(SDL_GetRendererFromTexture(*this))); } - /** @see https://wiki.libsdl.org/SDL3/SDL_CreateTexture - * @brief Create a texture for a rendering context. - * @param format The pixel format of the texture - * @param access The access pattern for the texture - * @param w The width of the texture in pixels - * @param h The height of the texture in pixels - * @return Texture The created texture. If the creation fails, returns an invalid texture. - */ inline Texture Renderer::CreateTexture(SDL_PixelFormat format, SDL_TextureAccess access, int w, int h) const { return Texture(Texture::get_or_cache(SDL_CreateTexture(*this, format, access, w, h), SDL_DestroyTexture)); } - /** @see https://wiki.libsdl.org/SDL3/SDL_CreateTextureFromSurface - * @brief Create a texture from an existing surface. - * @param surface The surface to create the texture from. - * @return Texture The created texture. If the creation fails, returns an invalid texture. - */ inline Texture Renderer::CreateTextureFromSurface(SDL_Surface* surface) const { return Texture(Texture::get_or_cache(SDL_CreateTextureFromSurface(*this, surface), SDL_DestroyTexture)); } - /** @see https://wiki.libsdl.org/SDL3/SDL_CreateTextureWithProperties - * @brief Create a texture for a rendering context with specific properties. - * @param properties The properties to create the texture with. - * @return Texture The created texture. If the creation fails, returns an invalid texture. - */ inline Texture Renderer::CreateTextureWithProperties(SDL_PropertiesID properties) const { return Texture(Texture::get_or_cache(SDL_CreateTextureWithProperties(*this, properties), SDL_DestroyTexture)); } + + inline Texture Renderer::GetRenderTarget() const { + /** we may not have created the texture we get back, if not we will not own it. */ + return Texture(Texture::get_or_view(SDL_GetRenderTarget(*this))); + } } \ No newline at end of file diff --git a/include/hdk/sdl/render/Renderer.hpp b/include/hdk/sdl/render/Renderer.hpp index 6466f96..c8a9a71 100644 --- a/include/hdk/sdl/render/Renderer.hpp +++ b/include/hdk/sdl/render/Renderer.hpp @@ -1,38 +1,27 @@ #pragma once -/** @file Renderer.hpp - * @brief HDK sdl video header only wrapper for SDL_Renderer struct & related functions - */ +/// @file Renderer.hpp +/// Header-only wrapper for SDL_Renderer struct & related functions. +/// For complete documentation, see src/render/Renderer.cpp +/// #include #include #include -/** Renderers are used to render 2D graphics in SDL */ +#include + namespace hdk::sdl { class Window; class Texture; - /** - * @brief Wraps the SDL_Renderer struct and related functions in a C++ class that uses shared_ptr for lifetime management. - * - * - */ class Renderer : public hdk::grid::SharedPtrWrapper { public: friend class Window; friend class Texture; friend std::pair CreateWindowAndRenderer( const char* title, int width, int height, SDL_WindowFlags window_flags); - /** Inherit constructors from SharedPtrWrapper */ using hdk::grid::SharedPtrWrapper::SharedPtrWrapper; - /// @todo https://wiki.libsdl.org/SDL3/SDL_AddVulkanRenderSemaphores - /// @todo https://wiki.libsdl.org/SDL3/SDL_ConvertEventToRenderCoordinates - /// @todo https://wiki.libsdl.org/SDL3/SDL_CreateGPURenderer - /// @todo https://wiki.libsdl.org/SDL3/SDL_CreateGPURenderState - /** @see https://wiki.libsdl.org/SDL3/SDL_CreateRenderer - * @brief Create a renderer for a window. - * @param window The window to create the renderer for. If the window is invalid, this function will return an - * invalid renderer. - * @param driverName The name of the rendering driver to initialize. If NULL, the first is used. - * @return Renderer The created renderer. If the creation fails, returns an invalid renderer. - */ + /// @todo SDL_AddVulkanRenderSemaphores + /// @todo SDL_ConvertEventToRenderCoordinates + /// @todo SDL_CreateGPURenderer + /// @todo SDL_CreateGPURenderState static Renderer Create(SDL_Window* window, const char* driverName) { return Renderer(get_or_cache(SDL_CreateRenderer(window, driverName), SDL_DestroyRenderer)); } @@ -41,62 +30,27 @@ namespace hdk::sdl { static Renderer CreateSoftware(SDL_Surface* surface) { return Renderer(get_or_cache(SDL_CreateSoftwareRenderer(surface), SDL_DestroyRenderer)); } - /// @todo https://wiki.libsdl.org/SDL3/SDL_CreateWindowAndRenderer - /// @todo https://wiki.libsdl.org/SDL3/SDL_DestroyGPURenderState - /// @todo https://wiki.libsdl.org/SDL3/SDL_DestroyRenderer + /// @todo SDL_CreateWindowAndRenderer + /// @todo SDL_DestroyGPURenderState + /// @todo SDL_DestroyRenderer /// Implemented in `../render.hpp` to avoid circular dependency with Texture Texture CreateTexture(SDL_PixelFormat format, SDL_TextureAccess access, int w, int h) const; /// Implemented in `../render.hpp` to avoid circular dependency with Texture Texture CreateTextureFromSurface(SDL_Surface* surface) const; /// Implemented in `../render.hpp` to avoid circular dependency with Texture Texture CreateTextureWithProperties(SDL_PropertiesID properties) const; - /** @see https://wiki.libsdl.org/SDL3/SDL_FlushRenderer - * @brief Flush the current rendering commands to the screen. - * @return bool True if the renderer was successfully flushed, false otherwise. - */ bool Flush() const { return SDL_FlushRenderer(*this); } - /// @todo https://wiki.libsdl.org/SDL3/SDL_GDKResumeRenderer - /// @todo https://wiki.libsdl.org/SDL3/SDL_GDKSuspendRenderer - /** @see https://wiki.libsdl.org/SDL3/SDL_GetCurrentRenderOutputSize - * @brief Get the output size in pixels of the current render target. - * @param w A pointer to an int to be filled in with the width of the render output. If the renderer is invalid, - * this will be set to 0. - * @param h A pointer to an int to be filled in with the height of the render output. If the renderer is invalid, - * this will be set to 0. - * @return bool True if the output size was successfully retrieved, false otherwise. - */ + /// @todo SDL_GDKResumeRenderer + /// @todo SDL_GDKSuspendRenderer bool GetOutputSize(int* w, int* h) const { return SDL_GetRenderOutputSize(*this, w, h); } - /** @see https://wiki.libsdl.org/SDL3/SDL_GetDefaultTextureScaleMode - * @brief Get the default texture scale mode for the renderer. - * @param scaleMode A pointer to an SDL_ScaleMode variable to be filled in with the default texture scale mode for - * the renderer. If the renderer is invalid, this will be set to SDL_ScaleMode_None. - * @return bool True if the default texture scale mode was successfully retrieved, false otherwise. - */ bool GetDefaultTextureScaleMode(SDL_ScaleMode* scaleMode) const { return SDL_GetDefaultTextureScaleMode(*this, scaleMode); } - /// @todo https://wiki.libsdl.org/SDL3/SDL_GetGPURendererDevice - // https://wiki.libsdl.org/SDL3/SDL_GetNumRenderDrivers - /** @see https://wiki.libsdl.org/SDL3/SDL_GetRenderClipRect - * @brief Get the clip rectangle for the current rendering target. - * @param rect A pointer to an SDL_Rect structure to be filled in with the clip rectangle for the current - * rendering target. If the renderer is invalid, this will be set to {0, 0, 0, 0}. - * @return bool True if the clip rectangle was successfully retrieved, false otherwise. - */ + /// @todo SDL_GetGPURendererDevice + static int GetNumRenderDrivers() { return SDL_GetNumRenderDrivers(); } + bool GetClipRect(SDL_Rect* rect) const { return SDL_GetRenderClipRect(*this, rect); } - /** @see https://wiki.libsdl.org/SDL3/SDL_GetRenderColorScale - * @brief Get the color scale for the renderer. - * @param scale A pointer to a float to be filled in with the color scale for the renderer. If the renderer is - * invalid, this will be set to 0.0f. - * @return bool True if the color scale was successfully retrieved, false otherwise. - */ bool GetColorScale(float* scale) const { return SDL_GetRenderColorScale(*this, scale); } - /** @see https://wiki.libsdl.org/SDL3/SDL_GetRenderDrawBlendMode - * @brief Get the blend mode used for drawing operations (Fill and Line). - * @param blendMode A pointer to an SDL_BlendMode variable to be filled in with the blend mode used for drawing - * operations. If the renderer is invalid, this will be set to SDL_BlendMode_None. - * @return bool True if the blend mode was successfully retrieved, false otherwise. - */ bool GetDrawBlendMode(SDL_BlendMode* blendMode) const { return SDL_GetRenderDrawBlendMode(*this, blendMode); } /* @see https://wiki.libsdl.org/SDL3/SDL_GetRenderDrawColor * @brief Get the color used for drawing operations (Fill and Line). @@ -187,373 +141,109 @@ namespace hdk::sdl { bool GetSafeArea(SDL_Rect* rect) const { return SDL_GetRenderSafeArea(*this, rect); } /** @see https://wiki.libsdl.org/SDL3/SDL_GetRenderScale * @brief Get the scale of the current render target. - * @param scaleX A pointer to a float to be filled in with the horizontal scale factor. + * @param scaleX A pointer to a float to be filled in with the horizontal scale factor. * @param scaleY A pointer to a float to be filled in with the vertical scale factor. * @return bool True on success */ bool GetScale(float* scaleX, float* scaleY) const { return SDL_GetRenderScale(*this, scaleX, scaleY); } - /** - @todo https://wiki.libsdl.org/SDL3/SDL_GetRenderTarget - **/ - /** @see https://wiki.libsdl.org/SDL3/SDL_GetRenderTextureAddressMode - * @brief Get the texture address mode for the current render target. - * @param u_mode A pointer to an SDL_TextureAddressMode variable - * @param v_mode A pointer to an SDL_TextureAddressMode variable - * @return bool True on success - */ + /// Implemented in `../render.hpp` to avoid circular dependency with Texture + Texture GetRenderTarget() const; bool GetTextureAddressMode(SDL_TextureAddressMode* u_mode, SDL_TextureAddressMode* v_mode) const { return SDL_GetRenderTextureAddressMode(*this, u_mode, v_mode); } - /** @see https://wiki.libsdl.org/SDL3/SDL_GetRenderViewport - * @brief Get the viewport for the current render target. - * @param rect A pointer to an SDL_Rect structure to be filled in with the viewport - * @return bool True on success - */ bool GetViewport(SDL_Rect* rect) const { return SDL_GetRenderViewport(*this, rect); } - /** @see https://wiki.libsdl.org/SDL3/SDL_GetRenderVSync - * @brief Get the vertical sync setting for the current renderer. - * @param vsync A pointer to an int to store the vertical sync setting - * @return bool True on success - */ bool GetVSync(int* vsync) const { return SDL_GetRenderVSync(*this, vsync); } /** @todo https://wiki.libsdl.org/SDL3/SDL_GetRenderWindow **/ - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderClear - * @brief Clear the current rendering target with the drawing color. - * @return bool True if the renderer was successfully cleared, false otherwise. - */ bool Clear() const { return SDL_RenderClear(*this); } - // - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderClipEnabled - * @brief Check whether clipping is enabled for the current render target. - * @return bool True if clipping is enabled, false otherwise. - */ - // https://wiki.libsdl.org/SDL3/SDL_RenderCoordinatesFromWindow - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderCoordinatesFromWindow - * @brief Convert window coordinates to renderer coordinates. - * @param windowX The x coordinate in window space - * @param windowY The y coordinate in window space - * @param rendererX A pointer to a float to be filled in with the x coordinate - * @param rendererY A pointer to a float to be filled in with the y coordinate - * @return bool True if the coordinates were successfully converted, false otherwise. - */ + bool ClipEnabled() const { return SDL_RenderClipEnabled(*this); } bool CoordinatesFromWindow(float windowX, float windowY, float* rendererX, float* rendererY) const { return SDL_RenderCoordinatesFromWindow(*this, windowX, windowY, rendererX, rendererY); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderCoordinatesToWindow - * @brief Convert renderer coordinates to window coordinates. - * @param rendererX The x coordinate in renderer space - * @param rendererY The y coordinate in renderer space - * @param windowX A pointer to a float to be filled in with the x coordinate - * @param windowY A pointer to a float to be filled in with the y coordinate - * @return bool True if the coordinates were successfully converted, false otherwise. - */ bool CoordinatesToWindow(float rendererX, float rendererY, float* windowX, float* windowY) const { return SDL_RenderCoordinatesToWindow(*this, rendererX, rendererY, windowX, windowY); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderDebugText - * @brief Render debug text at a specific position in the current render target. - * @param x The x coordinate of the text position - * @param y The y coordinate of the text position - * @param text The text to render - * @return bool True if the text was successfully rendered, false otherwise. - */ bool DebugText(float x, float y, const char* text) const { return SDL_RenderDebugText(*this, x, y, text); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderDebugTextFormat - * @brief Render formatted debug text at a specific position in the current render target. - * @param x The x coordinate of the text position - * @param y The y coordinate of the text position - * @param fmt The formatted text to render (printf-style format string) - * @param args The arguments for the formatted text - * @return bool True if the text was successfully rendered, false otherwise. - */ template bool DebugTextFormat(float x, float y, const char* fmt, Args... args) const { return SDL_RenderDebugTextFormat(*this, x, y, fmt, args...); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderFillRect - * @brief fill rectangle with current draw color - * @param rect pointer to rectangle to fill, or NULL to fill the entire render target - * @return bool true on success - */ bool FillRect(const SDL_FRect* rect) const { return SDL_RenderFillRect(*this, rect); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderFillRects - * @brief fill multiple rectangles with current draw color - * @param rects pointer to array of rectangles to fill - * @param count number of rectangles in the array - * @return bool true on success - */ bool FillRects(const SDL_FRect* rects, int count) const { return SDL_RenderFillRects(*this, rects, count); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderGeometry - * @brief Render geometry with the current render target - * @param texture The texture to use for rendering - * @param vertices Pointer to an array of vertices - * @param numVertices Number of vertices in the array - * @param indices Pointer to an array of indices - * @param numIndices Number of indices in the array - * @return bool True on success, false on failure - */ bool RenderGeometry( SDL_Texture* texture, const SDL_Vertex* vertices, int numVertices, const int* indices, int numIndices) const { return SDL_RenderGeometry(*this, texture, vertices, numVertices, indices, numIndices); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderGeometryRaw - * @brief render a list of triangles with optional texture and index data - * @param texture The texture to use for rendering, or NULL for no texture - * @param xy Pointer to an array of 2D vertex positions (x, y) in normalized coordinates (0.0 to 1.0) - * @param xy_stride The byte stride between consecutive vertex positions in the xy array - * @param color Pointer to an array of vertex colors - * @param color_stride The byte stride between consecutive vertex colors in the color array - * @param uv Pointer to an array of texture coordinates (u, v) in normalized coordinates (0.0 to 1.0), or NULL if - * not using textures - * @param uv_stride The byte stride between consecutive texture coordinates in the uv array - * @param numVertices The number of vertices in the xy, color, and uv arrays - * @param indices Pointer to an array of vertex indices that define the triangles to render, or NULL to render the - * vertices in sequential order - * @param numIndices The number of indices - * @param sizeIndices The byte size of each index in the indices array (1, 2, or 4 bytes) - * @return bool True on success - */ bool RenderGeometryRaw(SDL_Texture* texture, const float* xy, int xy_stride, const SDL_FColor* color, int color_stride, const float* uv, int uv_stride, int numVertices, const void* indices, int numIndices, int sizeIndices) const { return SDL_RenderGeometryRaw(*this, texture, xy, xy_stride, color, color_stride, uv, uv_stride, numVertices, indices, numIndices, sizeIndices); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderLine - * @brief render line with current draw color - * @param x1 - * @param y1 - * @param x2 - * @param y2 - * @return bool true on success - */ bool RenderLine(float x1, float y1, float x2, float y2) const { return SDL_RenderLine(*this, x1, y1, x2, y2); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderLines - * @brief render multiple lines with current draw color - * @param points - * @param count number of points in the array - * @return bool true on success - */ bool RenderLines(const SDL_FPoint* points, int count) const { return SDL_RenderLines(*this, points, count); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderPoint - * @brief render point with current draw color - * @param x - * @param y - * @return bool true on success - */ bool RenderPoint(float x, float y) const { return SDL_RenderPoint(*this, x, y); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderPoints - * @brief render multiple points with current draw color - * @param points - * @param count number of points in the array - * @return bool true on success - */ bool RenderPoints(const SDL_FPoint* points, int count) const { return SDL_RenderPoints(*this, points, count); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderPresent - * @brief Update the screen with any rendering performed since the previous call. - * @return bool True if the screen was successfully updated, false otherwise. - */ bool Present() const { return SDL_RenderPresent(*this); } - /** @todo https://wiki.libsdl.org/SDL3/SDL_RenderReadPixels */ - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderRect - * @brief render rectangle outline with current draw color - * @param rect pointer to rectangle to outline, or NULL to outline the entire render target - * @return bool true on success - */ + Surface ReadPixels(const SDL_Rect* rect) const { + return Surface(Surface::get_or_cache(SDL_RenderReadPixels(*this, rect), SDL_DestroySurface)); + } + bool RenderRect(const SDL_FRect* rect) const { return SDL_RenderRect(*this, rect); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderRects - * @brief render multiple rectangle outlines with current draw color - * @param rects pointer to array of rectangles to outline - * @param count number of rectangles in the array - * @return bool true on success - */ bool RenderRects(const SDL_FRect* rects, int count) const { return SDL_RenderRects(*this, rects, count); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderTexture - * @brief Render texture - * @param texture - * @param src - * @param dst - * @return bool true on success - */ bool RenderTexture(SDL_Texture* texture, const SDL_FRect* src, const SDL_FRect* dst) const { return SDL_RenderTexture(*this, texture, src, dst); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderTexture9Grid - * @brief Render a texture with 9-grid scaling - * @param texture - * @param src - * @param left_width - * @param right_width - * @param top_height - * @param bottom_height - * @param scale - * @param dst - * @return bool true on success - */ bool RenderTexture9Grid(SDL_Texture* texture, const SDL_FRect* src, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect* dst) const { return SDL_RenderTexture9Grid( *this, texture, src, left_width, right_width, top_height, bottom_height, scale, dst); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderTexture9GridTiled - * @brief Render a texture with 9-grid scaling and tiling - * @param texture - * @param src - * @param left_width - * @param right_width - * @param top_height - * @param bottom_height - * @param scale - * @param dst - * @param tile_scale - * @return bool true on success - */ bool RenderTexture9GridTiled(SDL_Texture* texture, const SDL_FRect* src, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect* dst, float tile_scale) const { return SDL_RenderTexture9GridTiled( *this, texture, src, left_width, right_width, top_height, bottom_height, scale, dst, tile_scale); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderTextureAffine - * @brief Render a texture with affine transformations - * @param texture - * @param src - * @param origin - * @param right - * @param down - * @return bool true on success - */ bool RenderTextureAffine(SDL_Texture* texture, const SDL_FRect* src, const SDL_FPoint* origin, const SDL_FPoint* right, const SDL_FPoint* down) const { return SDL_RenderTextureAffine(*this, texture, src, origin, right, down); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderTextureRotated - * @brief Render a texture with rotation and flipping - * @param texture - * @param srcrect - * @param dstrect - * @param angle - * @param center - * @param flip - * @return bool true on success - */ bool RenderTextureRotated(SDL_Texture* texture, const SDL_FRect* srcrect, const SDL_FRect* dstrect, double angle, const SDL_FPoint* center, SDL_FlipMode flip) const { return SDL_RenderTextureRotated(*this, texture, srcrect, dstrect, angle, center, flip); } - /** @see https://wiki.libsdl.org/SDL3/SDL_RenderTextureTiled - * @brief Render a texture with tiling - * @param texture - * @param srcrect - * @param scale - * @param dstrect - * @param tile_scale - * @return bool true on success - */ bool RenderTextureTiled( SDL_Texture* texture, const SDL_FRect* srcrect, float scale, const SDL_FRect* dstrect, float tile_scale) const { return SDL_RenderTextureTiled(*this, texture, srcrect, scale, dstrect); } - /** @see https://wiki.libsdl.org/SDL3/SDL_SetDefaultTextureScaleMode - * @brief Set the default texture scale mode for the renderer. - * @param scaleMode The default texture scale mode for the renderer. - * @return bool True if the default texture scale mode was successfully set, false otherwise. - */ bool SetDefaultTextureScaleMode(SDL_ScaleMode scaleMode) const { return SDL_SetDefaultTextureScaleMode(*this, scaleMode); } - /** @todo https://wiki.libsdl.org/SDL3/SDL_SetGPURenderState + /** @todo SDL_SetGPURenderState // https://wiki.libsdl.org/SDL3/SDL_SetGPURenderStateFragmentUniforms // https://wiki.libsdl.org/SDL3/SDL_SetGPURenderStateSamplerBindings // https://wiki.libsdl.org/SDL3/SDL_SetGPURenderStateStorageBuffers // https://wiki.libsdl.org/SDL3/SDL_SetGPURenderStateStorageTextures **/ - /** @see https://wiki.libsdl.org/SDL3/SDL_SetRenderClipRect - * @brief Set the clip rectangle for the current rendering target. - * @param rect - * @return bool true on success - */ bool SetClipRect(const SDL_Rect* rect) const { return SDL_SetRenderClipRect(*this, rect); } - /** @see https://wiki.libsdl.org/SDL3/SDL_SetRenderColorScale - * @brief Set the color scale for the renderer. - * @param scale The color scale for the renderer. - * @return bool true on success - */ bool SetRenderColorScale(float scale) const { return SDL_SetRenderColorScale(*this, scale); } - /** @see https://wiki.libsdl.org/SDL3/SDL_SetRenderDrawBlendMode - * @brief Set the blend mode used for drawing operations (Fill and Line). - * @param blendMode The blend mode used for drawing operations. - * @return bool true on success - */ bool SetDrawBlendMode(SDL_BlendMode blendMode) const { return SDL_SetRenderDrawBlendMode(*this, blendMode); } - /** @see https://wiki.libsdl.org/SDL3/SDL_SetRenderDrawColor - * @brief Set the color used for drawing operations (Fill and Line). - * @param r The red component of the drawing color - * @param g The green component of the drawing color - * @param b The blue component of the drawing color - * @param a The alpha component of the drawing color - * @return bool true on success - */ - bool SetDrawColor(Uint8 r, Uint8 g, Uint8 b, Uint8 a) const { - return SDL_SetRenderDrawColor(*this, r, g, b, a); - } - /** @see https://wiki.libsdl.org/SDL3/SDL_SetRenderDrawColorFloat - * @brief Set the color used for drawing operations (Fill and Line) as floats. - * @param r The red component of the drawing color - * @param g The green component of the drawing color - * @param b The blue component of the drawing color - * @param a The alpha component of the drawing color - * @return bool true on success - */ + bool SetDrawColor(Uint8 r, Uint8 g, Uint8 b, Uint8 a) const { return SDL_SetRenderDrawColor(*this, r, g, b, a); } bool SetDrawColorFloat(float r, float g, float b, float a) const { return SDL_SetRenderDrawColorFloat(*this, r, g, b, a); } - /** @see https://wiki.libsdl.org/SDL3/SDL_SetRenderLogicalPresentation - * @brief Set the logical presentation for the renderer. - * @param w The width of the logical presentation - * @param h The height of the logical presentation - * @param mode The presentation mode for the logical presentation - * @return bool true on success - */ bool SetLogicalPresentation(int w, int h, SDL_RendererLogicalPresentation mode) const { return SDL_SetRenderLogicalPresentation(*this, w, h, mode); } - /** @see https://wiki.libsdl.org/SDL3/SDL_SetRenderScale - * @brief Set the scale for the current render target. - * @param scaleX The horizontal scale factor - * @param scaleY The vertical scale factor - * @return bool true on success - */ bool SetScale(float scaleX, float scaleY) const { return SDL_SetRenderScale(*this, scaleX, scaleY); } - /** @see https://wiki.libsdl.org/SDL3/SDL_SetRenderTarget - * @brief Set the render target to a texture or the default render target. - * @param texture The texture to set as the render target, or NULL to set the default render target - * @return bool true on success - */ bool SetRenderTarget(SDL_Texture* texture) const { return SDL_SetRenderTarget(*this, texture); } - /** @see https://wiki.libsdl.org/SDL3/SDL_SetRenderTextureAddressMode - * @brief Set the texture address mode for the current render target. - * @param u_mode The texture address mode for the horizontal direction - * @param v_mode The texture address mode for the vertical direction - * @return bool true on success - */ bool SetTextureAddressMode(SDL_TextureAddressMode u_mode, SDL_TextureAddressMode v_mode) const { return SDL_SetRenderTextureAddressMode(*this, u_mode, v_mode); } - /** @see https://wiki.libsdl.org/SDL3/SDL_SetRenderViewport - * @brief Set the viewport for the current render target. - * @param rect A pointer to an SDL_Rect structure representing the viewport, or NULL to use the entire render - * target. - * @return bool True if the viewport was successfully set, false otherwise. - */ + bool ViewportSet() const { return SDL_RenderViewportSet(*this); } bool SetViewport(const SDL_Rect* rect) const { return SDL_SetRenderViewport(*this, rect); } - /** @see https://wiki.libsdl.org/SDL3/SDL_SetRenderVSync - * @brief Set the vertical sync setting for the current renderer. - * @param vsync The vertical sync setting to use (0 for no vsync, 1 for vsync, -1 for adaptive vsync) - * @return bool True on success, false on failure - */ - bool SetVSync(int vsync) const { return SDL_SetRenderVSync(*this, vsync); } - /// Forward declare: implemented in ../video.hpp to avoid circular dependency + bool SetVSync(int vsync) const { return SDL_SetRenderVSync(*this, vsync); } + /// Implemented in ../video.hpp to avoid circular dependency Window GetWindow() const; }; } \ No newline at end of file diff --git a/include/hdk/sdl/render/Texture.hpp b/include/hdk/sdl/render/Texture.hpp index 4dabbfc..12ca05a 100644 --- a/include/hdk/sdl/render/Texture.hpp +++ b/include/hdk/sdl/render/Texture.hpp @@ -1,11 +1,10 @@ #pragma once -/** @file Texture.hpp - * @brief HDK sdl video header only wrapper for SDL_Texture struct & related functions - */ +/// @file Texture.hpp +/// For complete documentation, see src/render/Texture.cpp #include #include #include -/** Textures are used to store pixel data that can be rendered by a renderer. */ +#include namespace hdk::sdl { /// Forward declare to avoid circular dependency with Renderer class Renderer; @@ -13,226 +12,68 @@ namespace hdk::sdl { class Texture : public hdk::grid::SharedPtrWrapper { public: friend class Renderer; - /** Inherit constructors from SharedPtrWrapper */ using hdk::grid::SharedPtrWrapper::SharedPtrWrapper; - /** @see https://wiki.libsdl.org/SDL3/SDL_CreateTexture - * @brief Create a texture for a rendering context. - * @param renderer The rendering context to create the texture for. - * @param format The pixel format of the texture - * @param access The access pattern for the texture - * @param w The width of the texture in pixels - * @param h The height of the texture in pixels - * @return Texture The created texture. If the creation fails, returns an invalid texture. - */ static Texture Create(SDL_Renderer* renderer, SDL_PixelFormat format, SDL_TextureAccess access, int w, int h) { return Texture(get_or_cache(SDL_CreateTexture(renderer, format, access, w, h), SDL_DestroyTexture)); } - /** @see https://wiki.libsdl.org/SDL3/SDL_CreateTextureFromSurface - * @brief Create a texture from an existing surface. - * @param renderer The rendering context to create the texture for. - * @param surface The surface to create the texture from. - * @return Texture The created texture. If the creation fails, returns an invalid texture. - */ static Texture CreateFromSurface(SDL_Renderer* renderer, SDL_Surface* surface) { return Texture(get_or_cache(SDL_CreateTextureFromSurface(renderer, surface), SDL_DestroyTexture)); } - /** @see https://wiki.libsdl.org/SDL3/SDL_CreateTextureWithProperties - * @brief Create a texture for a rendering context with specific properties. - * @param renderer The rendering context to create the texture for. - * @param properties The properties to create the texture with. - * @return Texture The created texture. If the creation fails, returns an invalid texture. - */ static Texture CreateWithProperties(SDL_Renderer* renderer, SDL_PropertiesID properties) { return Texture(get_or_cache(SDL_CreateTextureWithProperties(renderer, properties), SDL_DestroyTexture)); } - // https://wiki.libsdl.org/SDL3/SDL_DestroyTexture - /** @see https://wiki.libsdl.org/SDL3/SDL_GetTextureAlphaMod - * @brief Get the alpha modulation value for a texture. - * @param alpha A pointer to an int - * @return bool true on success - */ bool GetAlphaMod(Uint8* alpha) const { return SDL_GetTextureAlphaMod(*this, alpha); } Uint8 GetAlphaMod() const { Uint8 alpha; SDL_GetTextureAlphaMod(*this, &alpha); return alpha; } - /** @see https://wiki.libsdl.org/SDL3/SDL_GetTextureAlphaModFloat - * @brief Get the alpha modulation value for a texture as a float. - * @param alpha A pointer to a float - * @return bool true on success - */ bool GetAlphaModFloat(float* alpha) const { return SDL_GetTextureAlphaModFloat(*this, alpha); } float GetAlphaModFloat() const { float alpha; SDL_GetTextureAlphaModFloat(*this, &alpha); return alpha; } - /** @see https://wiki.libsdl.org/SDL3/SDL_GetTextureBlendMode - * @brief Get the blend mode for a texture. - * @param blendMode A pointer to an SDL_BlendMode variable to be filled in - * @return bool true on success - */ bool GetBlendMode(SDL_BlendMode* blendMode) const { return SDL_GetTextureBlendMode(*this, blendMode); } SDL_BlendMode GetBlendMode() const { SDL_BlendMode blendMode; SDL_GetTextureBlendMode(*this, &blendMode); return blendMode; } - /** @see https://wiki.libsdl.org/SDL3/SDL_GetTextureColorMod - * @brief Get the color modulation values for a texture. - * @param r A pointer to a Uint8 to be filled in with the red color - * @param g A pointer to a Uint8 to be filled in with the green color - * @param b A pointer to a Uint8 to be filled in with the blue color - * @return bool true on success - */ bool GetColorMod(Uint8* r, Uint8* g, Uint8* b) const { return SDL_GetTextureColorMod(*this, r, g, b); } - /** @see https://wiki.libsdl.org/SDL3/SDL_GetTextureColorModFloat - * @brief Get the color modulation values for a texture as floats. - * @param r A pointer to a float to be filled in with the red color - * @param g A pointer to a float to be filled in with the green color - * @param b A pointer to a float to be filled in with the blue color - * @return bool true on success - */ bool GetColorModFloat(float* r, float* g, float* b) const { return SDL_GetTextureColorModFloat(*this, r, g, b); } - /** @todo https://wiki.libsdl.org/SDL3/SDL_GetTexturePalette **/ - /** https://wiki.libsdl.org/SDL3/SDL_GetTextureProperties - * @brief Get the properties of a texture. - * @returns Properties associated with the texture. - */ + Palette GetPalette() const { return Palette(Palette::get_or_cache(SDL_GetTexturePalette(*this), SDL_DestroyPalette)); } Properties GetProperties() const { return Properties(SDL_GetTextureProperties(*this)); } /// Implemented in `../render.hpp` to avoid circular dependency with Renderer Renderer GetRenderer() const; - /** @see https://wiki.libsdl.org/SDL3/SDL_GetTextureScaleMode - * @brief Get the scale mode for a texture. - * @param scaleMode A pointer to an SDL_ScaleMode variable to be filled in - * @return bool true on success - */ bool GetScaleMode(SDL_ScaleMode* scaleMode) const { return SDL_GetTextureScaleMode(*this, scaleMode); } SDL_ScaleMode GetScaleMode() const { SDL_ScaleMode scaleMode; SDL_GetTextureScaleMode(*this, &scaleMode); return scaleMode; } - /** @see https://wiki.libsdl.org/SDL3/SDL_GetTextureSize - * @brief Get the size of a texture. - * @param w A pointer to a float to be filled in with the width - * @param h A pointer to a float to be filled in with the height - * @return bool true on success - */ bool GetSize(float* w, float* h) const { return SDL_GetTextureSize(*this, w, h); } - /** @see https://wiki.libsdl.org/SDL3/SDL_LockTexture - * @brief Lock a portion of the texture for write-only pixel access. - * @param rect A pointer to an SDL_Rect structure representing the area to lock, or NULL to lock the entire - * texture. - * @param pixels A pointer to a void* to be filled in with the locked pixels. You can cast this to the appropriate - * type based on the texture's pixel format. - * @param pitch A pointer to an int to be filled in with the pitch of the locked pixels (the length of a row of - * pixels in bytes). - * @return bool true on success - */ bool Lock(const SDL_Rect* rect, void** pixels, int* pitch) const { return SDL_LockTexture(*this, rect, pixels, pitch); } - /** @see https://wiki.libsdl.org/SDL3/SDL_LockTextureToSurface - * @brief Lock a portion of the texture for write-only pixel access and create an SDL_Surface that can be used to - * access the pixels. - * @param rect A pointer to an SDL_Rect structure representing the area to lock, or NULL to lock the entire - * texture. - * @param surface A pointer to an SDL_Surface* to be filled in with the created surface. You must free this - * surface with SDL_FreeSurface when you are done with it. - * @return bool true on success - */ bool LockToSurface(const SDL_Rect* rect, SDL_Surface** surface) const { return SDL_LockTextureToSurface(*this, rect, surface); } - /** @see https://wiki.libsdl.org/SDL3/SDL_SetTextureAlphaMod - * @brief Set the alpha modulation value for a texture. - * @param alpha The alpha modulation value to set - * @return bool true on success - */ bool SetAlphaMod(Uint8 alpha) const { return SDL_SetTextureAlphaMod(*this, alpha); } - /** @see https://wiki.libsdl.org/SDL3/SDL_SetTextureAlphaModFloat - * @brief Set the alpha modulation value for a texture as a float. - * @param alpha The alpha modulation value to set - * @return bool true on success - */ bool SetAlphaModFloat(float alpha) const { return SDL_SetTextureAlphaModFloat(*this, alpha); } - /** @see https://wiki.libsdl.org/SDL3/SDL_SetTextureBlendMode - * @brief Set the blend mode for a texture. - * @param blendMode The blend mode to set - * @return bool true on success - */ bool SetBlendMode(SDL_BlendMode blendMode) const { return SDL_SetTextureBlendMode(*this, blendMode); } - /** @see https://wiki.libsdl.org/SDL3/SDL_SetTextureColorMod - * @brief Set the color modulation values for a texture. - * @param r The red color modulation value to set - * @param g The green color modulation value to set - * @param b The blue color modulation value to set - * @return bool true on success - */ bool SetColorMod(Uint8 r, Uint8 g, Uint8 b) const { return SDL_SetTextureColorMod(*this, r, g, b); } - /** @see https://wiki.libsdl.org/SDL3/SDL_SetTextureColorModFloat - * @brief Set the color modulation values for a texture as floats. - * @param r The red color modulation value to set - * @param g The green color modulation value to set - * @param b The blue color modulation value to set - * @return bool true on success - */ bool SetColorModFloat(float r, float g, float b) const { return SDL_SetTextureColorModFloat(*this, r, g, b); } - /** @todo https://wiki.libsdl.org/SDL3/SDL_SetTexturePalette **/ - /** @see https://wiki.libsdl.org/SDL3/SDL_SetTextureScaleMode - * @brief Set the scale mode for a texture. - * @param scaleMode The scale mode to set - * @return bool true on success - */ + bool SetPalette(SDL_Palette* palette) const { return SDL_SetTexturePalette(*this, palette); } bool SetScaleMode(SDL_ScaleMode scaleMode) const { return SDL_SetTextureScaleMode(*this, scaleMode); } - /** @see https://wiki.libsdl.org/SDL3/SDL_UnlockTexture - * @brief Unlock a texture, enabling the changes made to the texture's pixels to be rendered. - */ void Unlock() const { SDL_UnlockTexture(*this); } - /** @see https://wiki.libsdl.org/SDL3/SDL_UpdateNVTexture - * @brief Update a rectangle within a texture with new pixel data in NV12 or NV21 format. - * @param rect A pointer to an SDL_Rect structure representing the area to update, or NULL to update the entire - * texture. - * @param Yplane A pointer to the pixel data for the Y plane of the texture. The format of this data should be a - * contiguous array of bytes, where each byte represents the intensity of the Y component for a pixel. - * @param Ypitch The pitch of the Y plane pixel data (the length of a row of pixels in bytes). - * @param UVplane A pointer to the pixel data for the interleaved U and V planes of the texture. The format of - * this data should be a contiguous array of bytes, where each pair of bytes represents the U and V components for - * a pixel. The U and V values should be interleaved, meaning that the first byte represents the U component and - * the second byte represents the V component for a pixel. - * @param UVpitch The pitch of the interleaved U and V plane pixel data (the length of a row of pixels in bytes). - * @return bool true on success - */ bool UpdateNV(const SDL_Rect* rect, const Uint8* Yplane, int Ypitch, const Uint8* UVplane, int UVpitch) const { return SDL_UpdateNVTexture(*this, rect, Yplane, Ypitch, UVplane, UVpitch); } - /** @see https://wiki.libsdl.org/SDL3/SDL_UpdateTexture - * @brief Update a rectangle within a texture with new pixel data. - * @param rect A pointer to an SDL_Rect structure representing the area to update, or NULL to update the entire - * texture. - * @param pixels A pointer to the pixel data to update the texture with. The format of this data should match the - * pixel format of the texture. - * @param pitch The pitch of the pixel data (the length of a row of pixels in bytes). - * @return bool true on success - */ bool Update(const SDL_Rect* rect, const void* pixels, int pitch) const { return SDL_UpdateTexture(*this, rect, pixels, pitch); } - /** @see https://wiki.libsdl.org/SDL3/SDL_UpdateYUVTexture - * @brief Update a rectangle within a texture - * @param rect A pointer to an SDL_Rect structure representing the area to update, or NULL to update the entire - * texture. - * @param Yplane A pointer to the pixel data for the Y plane of the texture. - * @param Ypitch The pitch of the Y plane pixel data (the length of a row of pixels in bytes). - * @param Uplane A pointer to the pixel data for the U plane of the texture. - * @param Upitch The pitch of the U plane pixel data (the length of a row of pixels in bytes). - * @param Vplane A pointer to the pixel data for the V plane of the texture. - * @param Vpitch The pitch of the V plane pixel data (the length of a row of pixels in bytes). - * @return bool true on success - */ bool UpdateYUV(const SDL_Rect* rect, const Uint8* Yplane, int Ypitch, const Uint8* Uplane, int Upitch, const Uint8* Vplane, int Vpitch) const { return SDL_UpdateYUVTexture(*this, rect, Yplane, Ypitch, Uplane, Upitch, Vplane, Vpitch); } diff --git a/include/hdk/sdl/video.hpp b/include/hdk/sdl/video.hpp index 05bb360..9e2354c 100644 --- a/include/hdk/sdl/video.hpp +++ b/include/hdk/sdl/video.hpp @@ -1,9 +1,6 @@ #pragma once -/** - * @file video.hpp - * @brief Marries the two classes together resolving what would otherwise be circular dependencies between Window and - * Renderer - */ +/// @file video.hpp +/// For complete documentation, see src/video.cpp #include #include #include @@ -13,26 +10,8 @@ #include namespace hdk::sdl { - /** @see SDL_GetRenderer - * https://wiki.libsdl.org/SDL3/SDL_GetRenderer - * @brief Get the renderer associated with a window. - * @return Renderer The renderer associated with the window. If the window is invalid or has no renderer, returns an - * invalid renderer. - */ inline Renderer Window::GetRenderer() const { return Renderer(Renderer::get_or_view(SDL_GetRenderer(*this))); } - /** @see SDL_GetRenderWindow - * https://wiki.libsdl.org/SDL3/SDL_GetRenderWindow - */ inline Window Renderer::GetWindow() const { return Window(Window::get_or_view(SDL_GetRenderWindow(*this))); } - /** @see SDL_CreateWindowAndRenderer - * https://wiki.libsdl.org/SDL3/SDL_CreateWindowAndRenderer - * @brief Create a window and renderer with one function call. - * @param title - * @param width - * @param height - * @param window_flags - * @return std::pair - */ inline std::pair CreateWindowAndRenderer( const char* title, int width, int height, SDL_WindowFlags window_flags) { SDL_Window* window_ptr = nullptr; @@ -44,4 +23,7 @@ namespace hdk::sdl { return { Window(nullptr), Renderer(nullptr) }; } } + inline Palette Surface::CreatePalette() const { + return Palette::get_or_cache(SDL_CreateSurfacePalette(*this), SDL_DestroyPalette); + } } \ No newline at end of file diff --git a/include/hdk/sdl/video/Display.hpp b/include/hdk/sdl/video/Display.hpp index 0ecd528..c35c8b5 100644 --- a/include/hdk/sdl/video/Display.hpp +++ b/include/hdk/sdl/video/Display.hpp @@ -1,100 +1,28 @@ #pragma once -/** - * @file Display.hpp - * @brief HDK sdl video header only wrapper for the SDL_DisplayID type and related functions - */ +/// @file Display.hpp +/// For complete documentation, see src/video/Display.cpp #include #include #include #include -/** Displays represent physical display devices such as monitors. */ namespace hdk::sdl { - /** - * @brief A wrapper for SDL_DisplayID that provides type safety and convenience functions for working with display IDs - * in SDL. - * - */ class Display : public grid::PrimitiveWrapper { public: using grid::PrimitiveWrapper::PrimitiveWrapper; - /** @see SDL_GetClosestFullscreenDisplayMode - * https://wiki.libsdl.org/SDL3/SDL_GetClosestFullscreenDisplayMode - * @brief Get the closest match to the requested display mode for fullscreen mode. - * @param w requested width in pixels - * @param h requested height in pixels - * @param refresh_rate 0.0f for desktop refresh rate, - * @param include_high_density_modes whether to include high density display modes in the search - * @param closest A pointer to a display mode to be filled in with the closest match of the available display - * modes. May be NULL to just get the number of matching video modes. - * @return bool true on success - */ bool GetClosestFullscreenMode( int w, int h, float refresh_rate, bool include_high_density_modes, SDL_DisplayMode* closest) { return SDL_GetClosestFullscreenDisplayMode(*this, w, h, refresh_rate, include_high_density_modes, closest); } - /** @see SDL_GetCurrentDisplayMode - * https://wiki.libsdl.org/SDL3/SDL_GetCurrentDisplayMode - * @brief Get the current display mode of a display. - * @return display mode of the display. - */ const SDL_DisplayMode* GetCurrentMode() const { return SDL_GetCurrentDisplayMode(*this); } - /** @see SDL_GetCurrentDisplayOrientation - * https://wiki.libsdl.org/SDL3/SDL_GetCurrentDisplayOrientation - * @return orientation of the display - */ SDL_DisplayOrientation GetCurrentOrientation() const { return SDL_GetCurrentDisplayOrientation(*this); } - /** @see SDL_GetDesktopDisplayMode - * https://wiki.libsdl.org/SDL3/SDL_GetDesktopDisplayMode - * @return desktop display mode of the display - */ const SDL_DisplayMode* GetDesktopMode() const { return SDL_GetDesktopDisplayMode(*this); } - /** @see SDL_GetDisplayBounds - * https://wiki.libsdl.org/SDL3/SDL_GetDisplayBounds - * @brief Get the bounds of a display. - * @param rect A pointer to an SDL_Rect structure to be filled in with the display - * @return bool true on success - */ bool GetBounds(SDL_Rect* rect) const { return SDL_GetDisplayBounds(*this, rect); } - /** @see SDL_GetDisplayContentScale - * https://wiki.libsdl.org/SDL3/SDL_GetDisplayContentScale - * @return The content scale factor for the display - */ float GetContentScale() const { return SDL_GetDisplayContentScale(*this); } - /** @see SDL_GetDisplayForPoint - * https://wiki.libsdl.org/SDL3/SDL_GetDisplayForPoint - * @brief Get the display that contains a point. - * @param point A pointer to an SDL_Point structure representing the point to query - */ static Display GetForPoint(const SDL_Point* point) { return Display(SDL_GetDisplayForPoint(point)); } - /** @see SDL_GetDisplayForRect - * https://wiki.libsdl.org/SDL3/SDL_GetDisplayForRect - * @brief Get the display that most closely intersects a rectangle. - * @param rect A pointer to an SDL_Rect structure representing the rectangle to query - */ static Display GetForRect(const SDL_Rect* rect) { return Display(SDL_GetDisplayForRect(rect)); } - /** @see SDL_GetDisplayForWindow - * https://wiki.libsdl.org/SDL3/SDL_GetDisplayForWindow - * @brief Get the display associated with a window. - * @param window The window to query - * @return Display The display associated with the window - */ static Display GetForWindow(SDL_Window* window) { return Display(SDL_GetDisplayForWindow(window)); } - /** @see SDL_GetDisplayName - * https://wiki.libsdl.org/SDL3/SDL_GetDisplayName - * @return The name of the display. - */ const char* GetName() const { return SDL_GetDisplayName(*this); } - /** @see SDL_GetDisplayProperties - * https://wiki.libsdl.org/SDL3/SDL_GetDisplayProperties - * @return Properties associated with the display. - */ Properties GetProperties() const { return Properties(SDL_GetDisplayProperties(*this)); } - /** @see SDL_GetDisplays - * https://wiki.libsdl.org/SDL3/SDL_GetDisplays - * @param count pointer to int filled with the count of displays - * @returns an array of DisplayIDs representing the displays - * @note Must be freed with SDL_free() when finished. - */ static SDL_DisplayID* GetDisplays(int* count) { return SDL_GetDisplays(count); } /** @see SDL_GetDisplays * @returns std::vector Display(s) available @@ -112,19 +40,7 @@ namespace hdk::sdl { } return displays; } - /** @see SDL_GetDisplayUsableBounds - * https://wiki.libsdl.org/SDL3/SDL_GetDisplayUsableBounds - * @brief Get the usable bounds of a display. - * @param rect A pointer to an SDL_Rect structure to be filled in with the usable bounds - * @return bool true on success - */ bool GetUsableBounds(SDL_Rect* rect) const { return SDL_GetDisplayUsableBounds(*this, rect); } - /** @see SDL_GetFullscreenDisplayModes - * https://wiki.libsdl.org/SDL3/SDL_GetFullscreenDisplayModes - * @param count pointer to int filled with the count of display modes - * @return null terminated array of display modes available for fullscreen mode - * @note Must be freed with SDL_free() when finished. - */ SDL_DisplayMode** GetFullscreenModes(int* count) const { return SDL_GetFullscreenDisplayModes(*this, count); } /** @see SDL_GetFullscreenDisplayModes * @returns std::vector of display modes available for fullscreen mode @@ -142,15 +58,7 @@ namespace hdk::sdl { } return displayModes; } - /** @see SDL_GetNaturalDisplayOrientation - * https://wiki.libsdl.org/SDL3/SDL_GetNaturalDisplayOrientation - * @return The natural orientation of the display - */ SDL_DisplayOrientation GetNaturalOrientation() const { return SDL_GetNaturalDisplayOrientation(*this); } - /** @see SDL_GetPrimaryDisplay - * https://wiki.libsdl.org/SDL3/SDL_GetPrimaryDisplay - * @return The primary display - */ static Display GetPrimaryDisplay() { return Display(SDL_GetPrimaryDisplay()); } }; } \ No newline at end of file diff --git a/include/hdk/sdl/video/Surface.hpp b/include/hdk/sdl/video/Surface.hpp index 0dca5bd..f344ff9 100644 --- a/include/hdk/sdl/video/Surface.hpp +++ b/include/hdk/sdl/video/Surface.hpp @@ -1,199 +1,83 @@ #pragma once -/** @file Surface.hpp - * @brief Defines the Surface class for handling SDL surfaces. - */ +/// @file Surface.hpp +/// For complete documentation, see src/video/Surface.cpp #include #include -/** Surfaces hold bitmap data **/ +#include namespace hdk::sdl { + class Palette; + class Surface : public hdk::grid::SharedPtrWrapper { public: - /** Inherit constructors from SharedPtrWrapper */ + friend class Renderer; using hdk::grid::SharedPtrWrapper::SharedPtrWrapper; - /** @see https://wiki.libsdl.org/SDL3/SDL_AddSurfaceAlternateImage - * @brief Add an alternate image to a surface. - * @param surface The surface to add the alternate image to. - * @return bool true on success - */ bool AddAlternateImage(SDL_Surface* surface) const { return SDL_AddSurfaceAlternateImage(*this, surface); } - /** @see https://wiki.libsdl.org/SDL3/SDL_BlitSurface - * @brief Perform a fast blit from `this` surface to the destination surface. - * @param dst_surface The destination surface to blit on to. - * @param dst_rect A pointer to an SDL_Rect structure representing the area on the destination surface to blit - * onto, or NULL to blit onto the entire surface. - * @param src_rect A pointer to an SDL_Rect structure representing the area of the source surface to blit, or - * NULL to blit the entire surface. - * @return bool true on success - */ bool BlitTo( SDL_Surface* dst_surface, const SDL_Rect* dst_rect = nullptr, const SDL_Rect* src_rect = nullptr) const { return SDL_BlitSurface(*this, src_rect, dst_surface, dst_rect); } - /** @see https://wiki.libsdl.org/SDL3/SDL_BlitSurface - * @brief Perform a fast blit to `this` surface from a source surface. - * @param src_surface The source surface to blit from. - * @param src_rect A pointer to an SDL_Rect structure representing the area on the source surface to blit - * from, or NULL to blit the entire surface. - * @param dst_rect A pointer to an SDL_Rect structure representing the area of the destination surface to blit, - * or NULL to blit the entire surface. - * @return bool true on success - */ bool BlitFrom( SDL_Surface* src_surface, const SDL_Rect* src_rect = nullptr, const SDL_Rect* dst_rect = nullptr) const { return SDL_BlitSurface(src_surface, src_rect, *this, dst_rect); } - /** @see https://wiki.libsdl.org/SDL3/SDL_BlitSurface9Grid - * @brief Perform a blit with 9-grid scaling from `this` surface to the destination surface. - * @param dst_surface The destination surface to blit on to. - * @param dst_rect A pointer to an SDL_Rect structure representing the area on the destination - * @param left_width The width of the left columns of the 9-grid - * @param right_width The width of the right columns of the 9-grid - * @param top_height The height of the top rows of the 9-grid - * @param bottom_height The height of the bottom rows of the 9-grid - * @param scale The scale factor to apply to the center of the 9-grid - * @param scale_mode - * @param src_rect - * @return bool true on success - */ bool Blit9GridTo(SDL_Surface* dst_surface, const SDL_Rect* dst_rect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scale_mode, const SDL_Rect* src_rect = nullptr) const { return SDL_BlitSurface9Grid(*this, src_rect, left_width, right_width, top_height, bottom_height, scale, scale_mode, dst_surface, dst_rect); } - /** @see https://wiki.libsdl.org/SDL3/SDL_BlitSurface9Grid - * @brief Perform a blit with 9-grid scaling to `this` surface from a source surface. - * @param src_surface The source surface to blit from. - * @param src_rect - * @param left_width The width of the left columns of the 9-grid - * @param right_width The width of the right columns of the 9-grid - * @param top_height The height of the top rows of the 9-grid - * @param bottom_height The height of the bottom rows of the 9-grid - * @param scale The scale factor to apply to the center of the 9-grid - * @param scale_mode - * @param dst_rect A pointer to an SDL_Rect structure representing the area on the destination surface to blit, or - NULL to blit the entire surface. - * @return bool true on success - */ bool Blit9GridFrom(SDL_Surface* src_surface, const SDL_Rect* src_rect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scale_mode, const SDL_Rect* dst_rect = nullptr) const { return SDL_BlitSurface9Grid(src_surface, src_rect, left_width, right_width, top_height, bottom_height, scale, scale_mode, *this, dst_rect); } - /** @see https://wiki.libsdl.org/SDL3/SDL_BlitSurfaceScaled - * @brief Perform a scaled blit from `this` surface to the destination surface. - * @param dst_surface The destination surface to blit on to. - * @param dst_rect A pointer to an SDL_Rect structure representing the area on the destination - * @param scale_mode The scale mode to use for scaling the surface - * @param src_rect A pointer to an SDL_Rect structure representing the area of the source - * surface to blit, or NULL to blit the entire surface. - * @return bool true on success - */ bool BlitScaledTo(SDL_Surface* dst_surface, const SDL_Rect* dst_rect, SDL_ScaleMode scale_mode, const SDL_Rect* src_rect = nullptr) const { return SDL_BlitSurfaceScaled(*this, src_rect, dst_surface, dst_rect, scale_mode); } - /** @see https://wiki.libsdl.org/SDL3/SDL_BlitSurfaceScaled - * @brief Perform a scaled blit to `this` surface from a source surface. - * @param src_surface The source surface to blit from. - * @param src_rect A pointer to an SDL_Rect structure representing the area on the source - * @param scale_mode The scale mode to use for scaling the surface - * @param dst_rect A pointer to an SDL_Rect structure representing the area on the destination surface to blit, or - * NULL to blit the entire surface. - * @return bool true - */ bool BlitScaledFrom(SDL_Surface* src_surface, const SDL_Rect* src_rect, SDL_ScaleMode scale_mode, const SDL_Rect* dst_rect = nullptr) const { return SDL_BlitSurfaceScaled(src_surface, src_rect, *this, dst_rect, scale_mode); } - /** @see https://wiki.libsdl.org/SDL3/SDL_BlitSurfaceTiled - * @brief Perform a tiled blit from `this` surface to the destination surface. - * @param dst_surface The destination surface to blit on to. - * @param dst_rect A pointer to an SDL_Rect structure representing the area on the destination surface to blit - * onto, or NULL to blit onto the entire surface. - * @param src_rect A pointer to an SDL_Rect structure representing the area of the source surface to blit, or NULL - * to blit the entire surface. - * @return bool true on success - */ bool BlitTiledTo( SDL_Surface* dst_surface, const SDL_Rect* dst_rect = nullptr, const SDL_Rect* src_rect = nullptr) const { return SDL_BlitSurfaceTiled(*this, src_rect, dst_surface, dst_rect); } - /** @see https://wiki.libsdl.org/SDL3/SDL_BlitSurfaceTiled - * @brief Perform a tiled blit to `this` surface from a source surface. - * @param src_surface The source surface to blit from. - * @param src_rect A pointer to an SDL_Rect structure representing the area on the source surface to blit, or NULL - * to blit the entire surface. - * @param dst_rect A pointer to an SDL_Rect structure representing the area of the destination surface to blit, or - * NULL to blit the entire surface. - * @return bool true on success - */ bool BlitTiledFrom( SDL_Surface* src_surface, const SDL_Rect* src_rect = nullptr, const SDL_Rect* dst_rect = nullptr) const { return SDL_BlitSurfaceTiled(src_surface, src_rect, *this, dst_rect); } - /** @see https://wiki.libsdl.org/SDL3/SDL_BlitSurfaceTiledWithScale - * @brief Perform a tiled blit with scale from `this` surface to the destination surface. - * @param dst_surface The destination surface to blit on to. - * @param dst_rect A pointer to an SDL_Rect structure representing the area on the destination surface to blit - * onto, or NULL to blit onto the entire surface. - * @param scale The scale factor to apply to the source surface when blitting. - * @param scale_mode The scale mode to use for scaling the surface - * @param src_rect A pointer to an SDL_Rect structure representing the area of the source - */ bool BlitTiledWithScaleTo(SDL_Surface* dst_surface, const SDL_Rect* dst_rect, float scale, SDL_ScaleMode scale_mode, const SDL_Rect* src_rect = nullptr) const { return SDL_BlitSurfaceTiledWithScale(*this, src_rect, scale, scale_mode, dst_surface, dst_rect); } - /** @see https://wiki.libsdl.org/SDL3/SDL_BlitSurfaceTiledWithScale - * @brief Perform a tiled blit with scale to `this` surface from a source surface. - * @param src_surface The source surface to blit from. - * @param src_rect A pointer to an SDL_Rect structure representing the area of the source surface to blit, or NULL - * to blit the entire surface. - * @param scale The scale factor to apply to the source surface when blitting. - * @param scale_mode The scale mode to use for scaling the surface - * @param dst_rect A pointer to an SDL_Rect structure representing the area of the destination surface to blit, or - * NULL to blit the entire surface. - * @return bool true on success - */ bool BlitTiledWithScaleFrom(SDL_Surface* src_surface, const SDL_Rect* src_rect, float scale, SDL_ScaleMode scale_mode, const SDL_Rect* dst_rect = nullptr) const { return SDL_BlitSurfaceTiledWithScale(src_surface, src_rect, scale, scale_mode, *this, dst_rect); } - /** @todo https://wiki.libsdl.org/SDL3/SDL_BlitSurfaceUnchecked - */ - /** @todo https://wiki.libsdl.org/SDL3/SDL_BlitSurfaceUncheckedScaled - */ - /** @see https://wiki.libsdl.org/SDL3/SDL_ClearSurface - * @brief Clear the surface to the specified color. - * @param r - * @param g - * @param b - * @param a - */ + bool BlitUncheckedTo(SDL_Surface* dst_surface, const SDL_Rect* dst_rect = nullptr, const SDL_Rect* src_rect = nullptr) const { + return SDL_BlitSurfaceUnchecked(*this, src_rect, dst_surface, dst_rect); + } + bool BlitUncheckedFrom(SDL_Surface* src_surface, const SDL_Rect* src_rect = nullptr, const SDL_Rect* dst_rect = nullptr) const { + return SDL_BlitSurfaceUnchecked(src_surface, src_rect, *this, dst_rect); + } + bool BlitUncheckedScaledTo(SDL_Surface* dst_surface, const SDL_Rect* dst_rect, SDL_ScaleMode scale_mode, + const SDL_Rect* src_rect = nullptr) const { + return SDL_BlitSurfaceUncheckedScaled(*this, src_rect, dst_surface, dst_rect, scale_mode); + } + bool BlitUncheckedScaledFrom(SDL_Surface* src_surface, const SDL_Rect* src_rect, SDL_ScaleMode scale_mode, + const SDL_Rect* dst_rect = nullptr) const { + return SDL_BlitSurfaceUncheckedScaled(src_surface, src_rect, *this, dst_rect, scale_mode); + } void Clear(float r, float g, float b, float a) const { SDL_ClearSurface(*this, r, g, b, a); } /** @todo https://wiki.libsdl.org/SDL3/SDL_ConvertPixels */ /** @todo https://wiki.libsdl.org/SDL3/SDL_ConvertPixelsAndColorspace */ - /** @see https://wiki.libsdl.org/SDL3/SDL_ConvertSurface - * @brief Convert surface to specified pixel format. - * @param format The pixel format to convert to. - * @return A new Surface instance with the converted surface, or nullptr on failure. - */ Surface Convert(SDL_PixelFormat format) const { return get_or_cache(SDL_ConvertSurface(*this, format), SDL_DestroySurface); } - /** @see https://wiki.libsdl.org/SDL3/SDL_ConvertSurfaceAndColorspace - * @brief Convert surface to specified pixel format and colorspace. - * @param format - * @param palette (optional) The palette to use for the converted surface, or NULL to use the palette from the - * original surface. - * @param colorspace - * @param properties (optional) can be 0. - * @return A new Surface instance with the converted surface, or nullptr on failure. - */ Surface ConvertAndColorspace(SDL_PixelFormat format, SDL_Palette* palette, SDL_Colorspace colorspace, SDL_PropertiesID properties = 0) const { return get_or_cache( @@ -221,7 +105,11 @@ namespace hdk::sdl { static Surface CreateFrom(int w, int h, SDL_PixelFormat format, void* pixels, int pitch) { return get_or_cache(SDL_CreateSurfaceFrom(w, h, format, pixels, pitch), SDL_DestroySurface); } - /** @todo https://wiki.libsdl.org/SDL3/SDL_CreateSurfacePalette */ + /** @see https://wiki.libsdl.org/SDL3/SDL_CreateSurfacePalette + * @brief Create a new surface with a palette. + * @returns a new pallet on success or nullptr on failure + */ + Palette CreatePalette() const; /** @see https://wiki.libsdl.org/SDL3/SDL_DestroySurface */ /** @see https://wiki.libsdl.org/SDL3/SDL_DuplicateSurface @@ -289,8 +177,27 @@ namespace hdk::sdl { * @return The colorspace of the surface. */ SDL_Colorspace GetColorspace() const { return SDL_GetSurfaceColorspace(*this); } - /** @todo https://wiki.libsdl.org/SDL3/SDL_GetSurfaceImages + /** @see https://wiki.libsdl.org/SDL3/SDL_GetSurfaceImages + * @brief Get the surface's alternative images. + * @param count pointer to an int variable to receive the number of alternative images + * @return An array of Surface instances representing the surface's alternative images, or nullptr */ + SDL_Surface** GetImages(int* count) const { return SDL_GetSurfaceImages(*this, count); } + /** + * @brief Get the surface's alternative images as a list. + * @return A list of Surface instances representing the surface's alternative images. + */ + std::list GetImages() const { + int count = 0; + SDL_Surface** images = GetImages(&count); + std::list image_list; + for (int i = 0; i < count; ++i) { + image_list.emplace_back(get_or_cache(images[i], SDL_DestroySurface)); + } + SDL_free(images); + return image_list; + } + /** @todo https://wiki.libsdl.org/SDL3/SDL_GetSurfacePalette */ /** @see https://wiki.libsdl.org/SDL3/SDL_GetSurfaceProperties diff --git a/include/hdk/sdl/video/Window.hpp b/include/hdk/sdl/video/Window.hpp index 3988410..6127c83 100644 --- a/include/hdk/sdl/video/Window.hpp +++ b/include/hdk/sdl/video/Window.hpp @@ -1,62 +1,35 @@ #pragma once -/** - * @file Window.hpp - * @brief HDK sdl video header only wrapper for SDL_Window struct & related functions - */ +/// @file Window.hpp +/// For complete documentation, see src/video/Window.cpp #include #include #include -/** Windows are the primary interface for rendering and interacting with the user in SDL */ namespace hdk::sdl { class Renderer; + namespace evt { + class EventConduit; + } class Window : public hdk::grid::SharedPtrWrapper { public: friend class Renderer; + friend class evt::EventConduit; friend std::pair CreateWindowAndRenderer(const char* title, int width, int height, SDL_WindowFlags window_flags); - /** Inherit constructors from SharedPtrWrapper */ using hdk::grid::SharedPtrWrapper::SharedPtrWrapper; - /** - * https://wiki.libsdl.org/SDL3/SDL_CreateWindow - * https://wiki.libsdl.org/SDL3/SDL_DestroyWindowSurface - * - * @param title The title of the window - * @param w The width of the window in pixels. - * @param h The height of the window in pixels. - * @param flags 0, or one or more SDL_WindowFlags OR'd together. - * @return A Window instance that manages the created SDL_Window. If window creation fails, the returned Window - * will evaluate to false (i.e., it will be null). - */ + using hdk::grid::SharedPtrWrapper::get_or_cache; + using hdk::grid::SharedPtrWrapper::get_or_view; static Window Create(const char* title, int w, int h, SDL_WindowFlags flags) { return Window(get_or_cache(SDL_CreateWindow(title, w, h, flags), SDL_DestroyWindow)); } - /** @see SDL_CreateWindowWithProperties - * https://wiki.libsdl.org/SDL3/SDL_CreateWindowWithProperties - * @brief Create a window with properties. - * @param propertiesID The ID of the properties set to use for the window. - * @return Window The created window. If the creation fails, returns an invalid window. - */ static Window CreateWithProperties( SDL_PropertiesID propertiesID) { return Window( get_or_cache(SDL_CreateWindowWithProperties(propertiesID), SDL_DestroyWindow)); } - /** - * https://wiki.libsdl.org/SDL3/SDL_GetWindowFromID - * @brief Get window for WindowID - * @param id The ID of the window. - * @return A Window instance that wraps the SDL_Window. If no window with the given ID exists, the returned Window - * will evaluate to false (i.e., it will be null). - */ static Window GetFromID(SDL_WindowID id) { /** Because it is possible windows were created by other means, we use get_or_view to wrap the SDL_Window * without taking ownership */ return Window(get_or_view(SDL_GetWindowFromID(id))); } - /** - * https://wiki.libsdl.org/SDL3/SDL_GetGrabbedWindow - * @brief Get the currently grabbed window, if any. - * @return A Window instance that wraps the currently grabbed SDL_Window. If no window is - */ static Window GetGrabbed() { /** Because it is possible windows were created by other means, we use get_or_view to wrap the SDL_Window * without taking ownership */ @@ -64,138 +37,29 @@ namespace hdk::sdl { } public: // Instance Properties - /** - * https://wiki.libsdl.org/SDL3/SDL_GetWindowAspectRatio - * @brief Get the aspect ratio of the window. - * @param min_aspect_ratio A pointer to a float that will be filled with the minimum aspect ratio of the window. - * @param max_aspect_ratio A pointer to a float that will be filled with the - * @return bool True if the aspect ratio was successfully retrieved, false otherwise. - */ bool GetAspectRatio(float* min_aspect_ratio, float* max_aspect_ratio) const { return SDL_GetWindowAspectRatio(*this, min_aspect_ratio, max_aspect_ratio); } - /** https://wiki.libsdl.org/SDL3/SDL_GetWindowBordersSize - * @brief Get the size of the window borders. - * @param top A pointer to an int that will be filled with the size of the top border of the window. - * @param left A pointer to an int that will be filled with the size of the left border of the window. - * @param bottom A pointer to an int that will be filled with the size of the bottom border of the window. - * @param right A pointer to an int that will be filled with the size of the right border of the window. - * @return bool True if the border sizes were successfully retrieved, false otherwise. - */ bool GetBordersSize(int* top, int* left, int* bottom, int* right) const { return SDL_GetWindowBordersSize(*this, top, left, bottom, right); } - /** https://wiki.libsdl.org/SDL3/SDL_GetWindowDisplayScale - * @brief Get the display scale of the window. - * @return float The display scale of the window. If the window is invalid, returns 0.0f. - */ float GetDisplayScale() const { return SDL_GetWindowDisplayScale(*this); } - /** https://wiki.libsdl.org/SDL3/SDL_GetWindowFlags - * @brief Get the flags of the window. - * @return SDL_WindowFlags The flags of the window. If the window is invalid, returns 0. - */ SDL_WindowFlags GetFlags() const { return SDL_GetWindowFlags(*this); } - /** https://wiki.libsdl.org/SDL3/SDL_GetWindowFullscreenMode - * @brief Get the fullscreen mode of the window. - * @return const SDL_DisplayMode* A pointer to an SDL_DisplayMode structure that will be filled with the - * fullscreen mode of the window. If the window is not in fullscreen mode or is invalid, returns nullptr. - */ const SDL_DisplayMode* GetFullscreenMode() const { return SDL_GetWindowFullscreenMode(*this); } - /** https://wiki.libsdl.org/SDL3/SDL_GetWindowID - * @brief Get the ID of the window. - * @return SDL_WindowID The ID of the window. If the window is invalid, returns 0. - */ SDL_WindowID GetID() const { return SDL_GetWindowID(*this); } - /** https://wiki.libsdl.org/SDL3/SDL_GetWindowKeyboardGrab - * @brief Get the keyboard grab state of the window. - * @return SDL_bool True if the window has grabbed the keyboard, false otherwise. - */ bool GetKeyboardGrab() const { return SDL_GetWindowKeyboardGrab(*this); } - /** https://wiki.libsdl.org/SDL3/SDL_SetWindowKeyboardGrab - * @brief Set the keyboard grab state of the window. - * @param grabbed True to grab the keyboard, false to release it. - * @return bool True if the keyboard grab state was successfully set, false otherwise. - */ bool SetKeyboardGrab(bool grabbed) const { return SDL_SetWindowKeyboardGrab(*this, grabbed); } - /** https://wiki.libsdl.org/SDL3/SDL_GetWindowMouseGrab - * @brief Get the mouse grab state of the window. - * @return SDL_bool True if the window has grabbed the mouse, false otherwise. - */ bool GetMouseGrab() const { return SDL_GetWindowMouseGrab(*this); } - /** https://wiki.libsdl.org/SDL3/SDL_SetWindowMouseGrab - * @brief Set the mouse grab state of the window. - * @param grabbed True to grab the mouse, false to release it. - * @return bool True if the mouse grab state was successfully set, false otherwise. - */ bool SetMouseGrab(bool grabbed) const { return SDL_SetWindowMouseGrab(*this, grabbed); } - /** SDL_GetWindowMouseRect - * https://wiki.libsdl.org/SDL3/SDL_GetWindowMouseRect - * @brief Get the mouse rectangle of the window. - * @return const SDL_Rect* A pointer to an SDL_Rect structure that will be filled with the mouse rectangle of the - * window. If the window is invalid, returns nullptr. - */ const SDL_Rect* GetMouseRect() const { return SDL_GetWindowMouseRect(*this); } - /** @see SDL_SetWindowMouseRect - * https://wiki.libsdl.org/SDL3/SDL_SetWindowMouseRect - * @brief Set the mouse rectangle of the window. - * @param rect A pointer to an SDL_Rect structure that defines the mouse rectangle of the window. - * @return bool True if the mouse rectangle was successfully set, false otherwise. - */ bool SetMouseRect(const SDL_Rect* rect) const { return SDL_SetWindowMouseRect(*this, rect); } - /** https://wiki.libsdl.org/SDL3/SDL_GetWindowMaximumSize - * @brief Get the maximum size of the window. - * @param w A pointer to an int that will be filled with the maximum width of the window. - * @param h A pointer to an int that will be filled with the maximum height of the window. - * @return bool True if the maximum size was successfully retrieved, false otherwise. - */ bool GetMaximumSize(int* w, int* h) const { return SDL_GetWindowMaximumSize(*this, w, h); } - /** https://wiki.libsdl.org/SDL3/SDL_SetWindowMaximumSize - * @brief Set the maximum size of the window. - * @param w The maximum width of the window in pixels. - * @param h The maximum height of the window in pixels. - * @return bool True if the maximum size was successfully set, false otherwise. - */ bool SetMaximumSize(int w, int h) const { return SDL_SetWindowMaximumSize(*this, w, h); } - /** https://wiki.libsdl.org/SDL3/SDL_GetWindowMinimumSize - * @brief Get the minimum size of the window. - * @param w A pointer to an int that will be filled with the minimum width of the window. - * @param h A pointer to an int that will be filled with the minimum height of the window. - * @return bool True if the minimum size was successfully retrieved, false otherwise. - */ bool GetMinimumSize(int* w, int* h) const { return SDL_GetWindowMinimumSize(*this, w, h); } - /** https://wiki.libsdl.org/SDL3/SDL_SetWindowMinimumSize - * @brief Set the minimum size of the window. - * @param w The minimum width of the window in pixels. - * @param h The minimum height of the window in pixels. - * @return bool True if the minimum size was successfully set, false otherwise. - */ bool SetMinimumSize(int w, int h) const { return SDL_SetWindowMinimumSize(*this, w, h); } - /** https://wiki.libsdl.org/SDL3/SDL_SetWindowSize - * @brief Set the size of the window. - * @param w The width of the window in pixels. - * @param h The height of the window in pixels. - * @return bool True if the size was successfully set, false otherwise. - */ bool SetSize(int w, int h) const { return SDL_SetWindowSize(*this, w, h); } - /** https://wiki.libsdl.org/SDL3/SDL_GetWindowSize - * @brief Get the size of the window. - * @param w A pointer to an int that will be filled with the width of the window. - * @param h A pointer to an int that will be filled with the height of the window. - * @return bool True if the size was successfully retrieved, false otherwise. - */ bool GetSize(int* w, int* h) const { return SDL_GetWindowSize(*this, w, h); } - /** https://wiki.libsdl.org/SDL3/SDL_GetWindowSafeArea - * @brief Get the safe area of the window. - * @param rect A pointer to an SDL_Rect structure that will be filled with the safe area of the window. If the - * window is invalid, the rect will be set to {0, 0, 0, 0}. - * @return bool True if the safe area was successfully retrieved, false otherwise. - */ bool GetSafeArea(SDL_Rect* rect) const { return SDL_GetWindowSafeArea(*this, rect); } - /** @see SDL_GetWindowOpacity - * https://wiki.libsdl.org/SDL3/SDL_GetWindowOpacity - * @brief Get the opacity of the window. - * @return float The opacity of the window. If the window is invalid, returns 0.0f. - */ float GetOpacity() const { return SDL_GetWindowOpacity(*this); } /** @see SDL_SetWindowOpacity * https://wiki.libsdl.org/SDL3/SDL_SetWindowOpacity diff --git a/src/Application.cpp b/src/Application.cpp new file mode 100644 index 0000000..e69de29 diff --git a/src/Properties.cpp b/src/Properties.cpp new file mode 100644 index 0000000..489d1ad --- /dev/null +++ b/src/Properties.cpp @@ -0,0 +1,296 @@ +/** + * @file Properties.cpp + * @brief Documentation for Properties class - wraps SDL_PropertiesID for property set management + * + * Properties are a set of values represented by a single ID, used to pass flexible configuration + * to SDL functions. This file contains the complete documentation for the Properties wrapper class. + * The actual implementation is header-only in Properties.hpp. + */ + +namespace hdk::sdl { + // Forward declarations + class Properties; + + // ============================================================================ + // Properties class - Core documentation + // ============================================================================ + + /** + * @class Properties + * @brief Wraps SDL_PropertiesID type for managing sets of key-value properties + * + * Properties provide a flexible way to pass configuration parameters to SDL functions and to store + * metadata on SDL objects. Each property set is identified by an ID and can contain multiple typed values. + * + * Property types supported: + * - Boolean (SDL_PROP_BOOL) + * - Number (double) (SDL_PROP_NUMBER) + * - Float (float) (SDL_PROP_FLOAT) + * - Pointer (void*) (SDL_PROP_POINTER) + * - String (const char*) (SDL_PROP_STRING) + * + * @see https://wiki.libsdl.org/SDL3/SDL_PropertiesID + */ + + // ============================================================================ + // Factory Methods + // ============================================================================ + + /** + * @fn static Properties Properties::Create() + * @brief Create a new properties set + * + * Creates an empty properties set that can be populated with properties. + * + * @return Properties A new properties set + * @see https://wiki.libsdl.org/SDL3/SDL_CreateProperties + */ + + /** + * @fn static Properties Properties::GetGlobalProperties() + * @brief Get the global properties set + * + * Returns the global properties set that is shared across the SDL library. + * + * @return Properties The global properties set + * @see https://wiki.libsdl.org/SDL3/SDL_GetGlobalProperties + */ + + // ============================================================================ + // Property Management + // ============================================================================ + + /** + * @fn void Properties::Destroy() + * @brief Destroy a properties set and free its associated memory + * + * Destroys the properties set and releases all associated resources. This is typically + * called automatically when the last reference is released. + * + * @see https://wiki.libsdl.org/SDL3/SDL_DestroyProperties + */ + + /** + * @fn bool Properties::ClearProperty(const char* name) const + * @brief Clear a property from this properties set + * + * Removes a property and its value from the set. + * + * @param name The name of the property to clear + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_ClearProperty + */ + + /** + * @fn bool Properties::HasProperty(const char* name) const + * @brief Check if a property exists in this set + * + * @param name The name of the property to check + * @return bool True if the property exists, false otherwise + * @see https://wiki.libsdl.org/SDL3/SDL_HasProperty + */ + + /** + * @fn SDL_PropertyType Properties::GetPropertyType(const char* name) const + * @brief Get the type of a property in this set + * + * @param name The name of the property + * @return SDL_PropertyType The type of the property + * @see https://wiki.libsdl.org/SDL3/SDL_GetPropertyType + */ + + /** + * @fn bool Properties::EnumerateProperties(SDL_EnumeratePropertiesCallback callback, void* callback_data) const + * @brief Enumerate all properties in this set + * + * Calls the provided callback function for each property in the set. + * + * @param callback An SDL_EnumeratePropertiesCallback function pointer + * @param callback_data Void pointer passed to the callback function + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_EnumerateProperties + */ + + /** + * @fn bool Properties::CopyAllTo(SDL_PropertiesID destination) const + * @brief Copy all properties from this set to another set + * + * Copies all properties to the destination set, overwriting any existing properties with the same names. + * + * @param destination The destination properties set ID + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_CopyProperties + */ + + /** + * @fn bool Properties::CopyAllFrom(SDL_PropertiesID source) + * @brief Copy all properties from another set to this set + * + * @param source The source properties set ID + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_CopyProperties + */ + + // ============================================================================ + // Boolean Properties + // ============================================================================ + + /** + * @fn bool Properties::GetBooleanProperty(const char* name, bool default_value) const + * @brief Get a boolean property value + * + * @param name The name of the property + * @param default_value The value to return if the property does not exist + * @return bool The value of the property, or default_value if not found + * @see https://wiki.libsdl.org/SDL3/SDL_GetBooleanProperty + */ + + /** + * @fn bool Properties::SetBooleanProperty(const char* name, bool value) + * @brief Set a boolean property value + * + * @param name The name of the property + * @param value The value to set + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetBooleanProperty + */ + + // ============================================================================ + // Number Properties (double) + // ============================================================================ + + /** + * @fn double Properties::GetNumberProperty(const char* name, double default_value) const + * @brief Get a number (double) property value + * + * @param name The name of the property + * @param default_value The value to return if the property does not exist + * @return double The value of the property, or default_value if not found + * @see https://wiki.libsdl.org/SDL3/SDL_GetNumberProperty + */ + + /** + * @fn bool Properties::SetNumberProperty(const char* name, double value) + * @brief Set a number (double) property value + * + * @param name The name of the property + * @param value The value to set + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetNumberProperty + */ + + // ============================================================================ + // Float Properties + // ============================================================================ + + /** + * @fn float Properties::GetFloatProperty(const char* name, float default_value) const + * @brief Get a float property value + * + * @param name The name of the property + * @param default_value The value to return if the property does not exist + * @return float The value of the property, or default_value if not found + * @see https://wiki.libsdl.org/SDL3/SDL_GetFloatProperty + */ + + /** + * @fn bool Properties::SetFloatProperty(const char* name, float value) + * @brief Set a float property value + * + * @param name The name of the property + * @param value The value to set + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetFloatProperty + */ + + // ============================================================================ + // String Properties + // ============================================================================ + + /** + * @fn const char* Properties::GetStringProperty(const char* name, const char* default_value) const + * @brief Get a string property value + * + * @param name The name of the property + * @param default_value The value to return if the property does not exist + * @return const char* The value of the property, or default_value if not found + * @see https://wiki.libsdl.org/SDL3/SDL_GetStringProperty + */ + + /** + * @fn bool Properties::SetStringProperty(const char* name, const char* value) + * @brief Set a string property value + * + * @param name The name of the property + * @param value The value to set (copied internally) + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetStringProperty + */ + + // ============================================================================ + // Pointer Properties + // ============================================================================ + + /** + * @fn void* Properties::GetPointerProperty(const char* name, void* default_value) const + * @brief Get a pointer property value + * + * @param name The name of the property + * @param default_value The value to return if the property does not exist + * @return void* The value of the property, or default_value if not found + * @see https://wiki.libsdl.org/SDL3/SDL_GetPointerProperty + */ + + /** + * @fn bool Properties::SetPointerProperty(const char* name, void* value) + * @brief Set a pointer property value + * + * Sets a property with no automatic cleanup. Use SetPointerPropertyWithCleanup for pointers + * that need cleanup when the property is cleared. + * + * @param name The name of the property + * @param value The pointer value to set + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetPointerProperty + */ + + /** + * @fn bool Properties::SetPointerPropertyWithCleanup(const char* name, void* value, SDL_CleanupPropertyCallback cleanup_callback, void* userdata = nullptr) + * @brief Set a pointer property with a cleanup callback + * + * Sets a pointer property that will be cleaned up using the provided callback when the + * property is cleared or the properties set is destroyed. + * + * @param name The name of the property + * @param value The pointer value to set + * @param cleanup_callback Function called to clean up the pointer + * @param userdata Optional user data passed to the cleanup callback + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetPointerPropertyWithCleanup + */ + + // ============================================================================ + // Property Lock Control + // ============================================================================ + + /** + * @fn bool Properties::LockProperties() + * @brief Lock a properties set for atomic writes + * + * Locks the properties set to prevent concurrent modifications during a series of property updates. + * Must be followed by a call to UnlockProperties(). + * + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_LockProperties + */ + + /** + * @fn void Properties::UnlockProperties() + * @brief Unlock a properties set after writing + * + * Releases the lock acquired by LockProperties(). + * + * @see https://wiki.libsdl.org/SDL3/SDL_UnlockProperties + */ + +} diff --git a/src/event.cpp b/src/event.cpp new file mode 100644 index 0000000..dee39be --- /dev/null +++ b/src/event.cpp @@ -0,0 +1,268 @@ +/** + * @file event.cpp + * @brief Documentation for the SDL event dispatcher API declared in event.hpp + * + * The implementation of this API is header-only in event.hpp. This file exists + * to keep the header compact while still providing complete generated Doxygen + * docs for the public event routing surface. + */ + +#include "hdk/sdl/event.hpp" + +namespace hdk::sdl::evt { + + // ============================================================================ + // Core dispatch API + // ============================================================================ + + /** + * @class Event + * @brief Base event dispatcher and thin wrapper around SDL's event queue APIs. + * + * Inherits callback-list dispatch semantics from + * hdk::grid::eps::Conduit and adds static convenience + * wrappers for SDL3 event queue operations. + */ + + /** + * @fn static void Event::AddWatch(SDL_EventFilter filter, void* userdata) + * @brief Install an SDL global event watch callback. + * @param filter Callback invoked by SDL for watched events. + * @param userdata Opaque user data passed to @p filter. + * @see https://wiki.libsdl.org/SDL3/SDL_AddEventWatch + */ + + /** + * @fn static bool Event::EventEnabled(Uint32 type) + * @brief Query whether an SDL event type is enabled. + * @param type SDL event type. + * @return True if the type is enabled. + * @see https://wiki.libsdl.org/SDL3/SDL_EventEnabled + */ + + /** + * @fn static void Event::FilterEvents(SDL_EventFilter filter, void* userdata) + * @brief Apply a filter callback to queued events. + * @param filter Filter callback. + * @param userdata Opaque user data passed to @p filter. + * @see https://wiki.libsdl.org/SDL3/SDL_FilterEvents + */ + + /** + * @fn static void Event::FlushEvent(Uint32 type) + * @brief Remove all queued events of one type. + * @param type SDL event type. + * @see https://wiki.libsdl.org/SDL3/SDL_FlushEvent + */ + + /** + * @fn static void Event::FlushEvents(Uint32 min_type, Uint32 max_type) + * @brief Remove all queued events in an inclusive type range. + * @param min_type Lower bound event type. + * @param max_type Upper bound event type. + * @see https://wiki.libsdl.org/SDL3/SDL_FlushEvents + */ + + /** + * @fn static int Event::GetDescription(const SDL_Event* event, char* buf, int buflen) + * @brief Write a text description of an event into caller-owned storage. + * @param event Event to describe. + * @param buf Destination character buffer. + * @param buflen Buffer size in bytes. + * @return Number of bytes written. + */ + + /** + * @fn static std::string Event::GetDescription(const SDL_Event* event) + * @brief Return a string description of an event. + * @param event Event to describe. + * @return Human-readable event text. + */ + + /** + * @fn static bool Event::GetFilter(SDL_EventFilter* filter, void** userdata) + * @brief Retrieve SDL's currently installed global event filter. + * @param filter Output callback pointer. + * @param userdata Output user data pointer. + * @return True if a filter is currently installed. + * @see https://wiki.libsdl.org/SDL3/SDL_GetEventFilter + */ + + /** + * @fn static Window Event::GetWindowFromEvent(const SDL_Event* event) + * @brief Resolve the wrapped window referenced by an event, if any. + * @param event Event that may carry a window id. + * @return Window wrapper view for the event-associated SDL_Window. + */ + + /** + * @fn static bool Event::Has(Uint32 type) + * @brief Check whether queued events exist for one type. + * @param type SDL event type. + * @return True if at least one matching event exists. + * @see https://wiki.libsdl.org/SDL3/SDL_HasEvent + */ + + /** + * @fn static bool Event::Has(Uint32 min_type, Uint32 max_type) + * @brief Check whether queued events exist in an inclusive type range. + * @param min_type Lower bound event type. + * @param max_type Upper bound event type. + * @return True if any matching event exists. + * @see https://wiki.libsdl.org/SDL3/SDL_HasEvents + */ + + /** + * @fn static int Event::Peep(SDL_Event* events, int numevents, SDL_EventAction action, Uint32 min_type, Uint32 max_type) + * @brief Query, push, or remove multiple events according to action. + * @param events Event buffer used by SDL. + * @param numevents Number of entries in @p events. + * @param action SDL peep action. + * @param min_type Lower bound event type. + * @param max_type Upper bound event type. + * @return Number of events handled, or negative on error. + * @see https://wiki.libsdl.org/SDL3/SDL_PeepEvents + */ + + /** + * @fn bool Event::Poll(SDL_Event* event) + * @brief Pop one event from SDL's queue. + * @param event Output event object. + * @return True if an event was returned. + * @see https://wiki.libsdl.org/SDL3/SDL_PollEvent + */ + + /** + * @fn static void Event::Pump() + * @brief Pump input devices to update SDL's event queue. + * @see https://wiki.libsdl.org/SDL3/SDL_PumpEvents + */ + + /** + * @fn static bool Event::Push(SDL_Event* event) + * @brief Push a user-provided event into SDL's queue. + * @param event Event to enqueue. + * @return True on success. + * @see https://wiki.libsdl.org/SDL3/SDL_PushEvent + */ + + // ============================================================================ + // Generic value-based dispatch + // ============================================================================ + + /** + * @class EventValueRouter + * @brief Generic dispatcher that first extracts a key from SDL_Event. + * + * The extracted key is used to choose a child dispatcher from + * value_dispatch_map. If a matching key exists, the event is forwarded to that + * child and then to this dispatcher's own callback list. + * + * @tparam ValueType Key extracted from an event. + * @tparam EventType Dispatcher/value stored in the map. + * @tparam MapType Associative container mapping keys to dispatchers. + */ + + /** + * @fn EventValueRouter::EventValueRouter(value_dispatch_map_t dispatch_map) + * @brief Construct with an initial key-to-dispatcher map. + * @param dispatch_map Initial dispatch map. + */ + + /** + * @fn ValueType EventValueRouter::extractor(SDL_Event* event) + * @brief Extract the key used to select a child dispatcher. + * @param event Event to inspect. + * @return Extracted key value. + */ + + /** + * @fn void EventValueRouter::Trigger(SDL_Event* event) + * @brief Route an event to a child dispatcher selected by extracted key. + * @param event Event to dispatch. + */ + + /** + * @fn EventType& EventValueRouter::operator[](ValueType value) + * @brief Access or create child dispatcher for a key. + * @param value Dispatch key. + * @return Reference to mapped child dispatcher. + */ + + /** + * @class EventTypeRouter + * @brief Specialized value-dispatcher keyed by SDL_EventType. + */ + + /** + * @fn SDL_EventType EventTypeRouter::extractor(SDL_Event* event) + * @brief Return event->type as the dispatch key. + * @param event Event to inspect. + * @return Event type value. + */ + + // ============================================================================ + // Category dispatchers + // ============================================================================ + + /** @class DisplayEvents @brief Dispatchers for display-related SDL events. */ + /** @class KeyEvents @brief Dispatchers for key down and key up events. */ + /** @class KeysEvents @brief Per-keycode key dispatcher. */ + + /** @class JoystickAxisEvents @brief Per-axis joystick motion dispatcher. */ + /** @class JoystickBallEvents @brief Per-ball joystick motion dispatcher. */ + /** @class JoystickHatEvents @brief Per-hat joystick motion dispatcher. */ + /** @class JoystickButtonEvents @brief Joystick button down/up dispatcher. */ + /** @class JoystickButtonsEvents @brief Per-button joystick dispatcher. */ + /** @class JoystickEvents @brief All joystick events for one joystick device. */ + /** @class JoysticksEvents @brief Joystick dispatcher keyed by SDL_JoystickID. */ + + /** @class GamepadAxisEvents @brief Per-axis gamepad motion dispatcher. */ + /** @class GamepadButtonEvents @brief Gamepad button down/up dispatcher. */ + /** @class GamepadButtonsEvents @brief Per-button gamepad dispatcher. */ + /** @class GamepadTouchpadEvents @brief Gamepad touchpad down/move/up dispatcher. */ + /** @class GamepadEvents @brief All gamepad events for one controller. */ + /** @class GamepadsEvents @brief Gamepad dispatcher keyed by SDL_JoystickID. */ + + /** @class FingerEvents @brief Dispatchers for finger touch events. */ + /** @class PinchEvents @brief Dispatchers for pinch gesture events. */ + /** @class DropEvents @brief Dispatchers for drag-and-drop events. */ + /** @class AudioDeviceEvents @brief Dispatchers for audio device lifecycle events. */ + /** @class PenEvents @brief Dispatchers for pen/stylus events. */ + /** @class CameraDeviceEvents @brief Dispatchers for camera device events. */ + /** @class RenderEvents @brief Dispatchers for renderer reset/loss events. */ + /** @class KeyboardEvents @brief Dispatchers for keyboard add/remove events. */ + /** @class MouseButtonEvents @brief Dispatchers for mouse button down/up events. */ + /** @class MouseButtonsEvents @brief Per-button mouse dispatcher. */ + /** @class MouseEvents @brief Mouse motion/button/wheel dispatcher for one mouse. */ + /** @class MiceEvents @brief Mouse dispatcher keyed by SDL_MouseID. */ + /** @class ScreenKeyboardEvents @brief Dispatchers for screen keyboard visibility events. */ + /** @class TextEvents @brief Dispatchers for text input and composition events. */ + /** @class WindowEvents @brief Window-scoped dispatcher for window and window-associated input events. */ + /** @class WindowsEvents @brief Dispatcher keyed by SDL_WindowID. */ + + /** + * @fn SDL_WindowID WindowsEvents::extractor(SDL_Event* event) + * @brief Extract the relevant window id from supported event unions. + * @param event Event to inspect. + * @return SDL_WindowID associated with the event, 0 when unavailable. + */ + + // ============================================================================ + // Top-level routing + // ============================================================================ + + /** + * @class AllTypes + * @brief Top-level dispatcher that routes all supported SDL event types. + * + * Exposes category dispatchers (window, keyboard, mouse, joystick, gamepad, + * text, etc.) and base event hooks. Events carrying a window id are also + * forwarded into the window-scoped dispatcher to support per-window listeners. + */ + + /** + * @fn void AllTypes::Trigger(SDL_Event* event) + * @brief Dispatch event by type and additionally by window id when applicable. + * @param event Event to route. + */ diff --git a/src/pixels.cpp b/src/pixels.cpp new file mode 100644 index 0000000..f1657ec --- /dev/null +++ b/src/pixels.cpp @@ -0,0 +1,18 @@ +/** + * @file pixels.cpp + * @brief contains documentation for pixels.hpp + */ + +namespace hdk::sdl { + /** + * @fn PixelFormatDetails PixelFormat::GetDetails() const + * @brief Get detailed information about this pixel format + * + * Returns a PixelFormatDetails object containing detailed information about the pixel format, + * including component bit depths, masks, and layout information. + * + * @return PixelFormatDetails An object containing format details + * @see https://wiki.libsdl.org/SDL3/SDL_GetPixelFormatDetails + */ + +} diff --git a/src/pixels/Palette.cpp b/src/pixels/Palette.cpp new file mode 100644 index 0000000..b5294e5 --- /dev/null +++ b/src/pixels/Palette.cpp @@ -0,0 +1,67 @@ +/** + * @file Palette.cpp + * @brief Documentation for Palette class - wraps SDL_Palette with C++ shared_ptr lifetime management + * + * Palettes are used for indexed-color pixel formats and color mapping. This file contains the + * complete documentation for the Palette wrapper class. The actual implementation is header-only + * in Palette.hpp. + */ + +namespace hdk::sdl { + // Forward declarations + class Palette; + + // ============================================================================ + // Palette class - Core documentation + // ============================================================================ + + /** + * @class Palette + * @brief Wraps SDL_Palette struct with C++ shared_ptr lifetime management + * + * Palettes are used for indexed-color images and color mapping. This wrapper uses shared_ptr + * for automatic lifetime management. Multiple copies of a Palette instance will share ownership + * of the underlying SDL_Palette; the palette is destroyed when the last copy goes out of scope. + * + * @see https://wiki.libsdl.org/SDL3/SDL_Palette + */ + + // ============================================================================ + // Factory Methods + // ============================================================================ + + /** + * @fn static Palette Palette::Create(int ncolors) + * @brief Create a palette with the specified number of colors + * + * @param ncolors The number of colors in the palette + * @return Palette The created palette. If creation fails, returns an invalid palette + * @see https://wiki.libsdl.org/SDL3/SDL_CreatePalette + */ + + // ============================================================================ + // Palette Operations + // ============================================================================ + + /** + * @fn void Palette::Destroy() const + * @brief Destroy the palette and free its associated memory + * + * Note: This is typically called automatically when the last copy of the Palette + * instance is destroyed due to shared_ptr lifetime management. + * + * @see https://wiki.libsdl.org/SDL3/SDL_DestroyPalette + */ + + /** + * @fn bool Palette::SetColors(const SDL_Color* colors, int firstcolor, int ncolors) const + * @brief Set a range of colors in this palette + * + * @param colors An array of SDL_Color structures with the colors to set + * @param firstcolor The index of the first color to set + * @param ncolors The number of colors to set + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetPaletteColors + */ + +} diff --git a/src/pixels/PixelFormat.cpp b/src/pixels/PixelFormat.cpp new file mode 100644 index 0000000..f45cba9 --- /dev/null +++ b/src/pixels/PixelFormat.cpp @@ -0,0 +1,88 @@ +/** + * @file PixelFormat.cpp + * @brief Documentation for PixelFormat class - wraps SDL_PixelFormat enum type + * + * PixelFormat provides type-safe access to SDL_PixelFormat values and related utility functions. + * This file contains the complete documentation. The actual implementation is header-only in PixelFormat.hpp. + */ + +namespace hdk::sdl { + // Forward declarations + class PixelFormat; + class PixelFormatDetails; + + // ============================================================================ + // PixelFormat class - Core documentation + // ============================================================================ + + /** + * @class PixelFormat + * @brief Wraps SDL_PixelFormat enum with convenience methods + * + * Provides type-safe access to pixel format enumerations and utility functions for working + * with different pixel formats. PixelFormat is a lightweight wrapper that doesn't manage + * lifetime since pixel formats are typically owned by SDL or the user. + * + * @see https://wiki.libsdl.org/SDL3/SDL_PixelFormat + */ + + // ============================================================================ + // Format Information + // ============================================================================ + + /** + * @fn const char* PixelFormat::GetName() const + * @brief Get the name of this pixel format + * + * Returns a human-readable name for the pixel format (e.g., "SDL_PIXELFORMAT_RGBA8888"). + * + * @return const char* The name of the pixel format, or "Unknown" if not recognized + * @see https://wiki.libsdl.org/SDL3/SDL_GetPixelFormatName + */ + + /** + * @fn bool PixelFormat::GetMasks(int* bpp, Uint32* Rmask, Uint32* Gmask, Uint32* Bmask, Uint32* Amask) const + * @brief Get the pixel format masks for this format + * + * Retrieves the bit masks that identify the different color components within a pixel value. + * This is useful for manual pixel manipulation. + * + * @param bpp Pointer to int filled with bytes per pixel + * @param Rmask Pointer to Uint32 filled with red component mask + * @param Gmask Pointer to Uint32 filled with green component mask + * @param Bmask Pointer to Uint32 filled with blue component mask + * @param Amask Pointer to Uint32 filled with alpha component mask + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_GetMasksForPixelFormat + */ + + /** + * @fn PixelFormatDetails PixelFormat::GetDetails() const + * @brief Get detailed information about this pixel format + * + * Returns a PixelFormatDetails object with additional information about the format. + * + * @return PixelFormatDetails An object containing format details + * @see https://wiki.libsdl.org/SDL3/SDL_GetPixelFormatDetails + */ + + // ============================================================================ + // Static Format Queries + // ============================================================================ + + /** + * @fn static SDL_PixelFormat PixelFormat::GetForMasks(int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask) + * @brief Get the pixel format for a given set of pixel format masks + * + * Finds the pixel format that corresponds to the provided color component masks. + * + * @param bpp The number of bytes per pixel + * @param Rmask The red component mask + * @param Gmask The green component mask + * @param Bmask The blue component mask + * @param Amask The alpha component mask + * @return SDL_PixelFormat The pixel format corresponding to the masks, or SDL_PIXELFORMAT_UNKNOWN + * @see https://wiki.libsdl.org/SDL3/SDL_GetPixelFormatForMasks + */ + +} diff --git a/src/pixels/PixelFormatDetails.cpp b/src/pixels/PixelFormatDetails.cpp new file mode 100644 index 0000000..24e8cc5 --- /dev/null +++ b/src/pixels/PixelFormatDetails.cpp @@ -0,0 +1,106 @@ +/** + * @file PixelFormatDetails.cpp + * @brief Documentation for PixelFormatDetails class - wraps const SDL_PixelFormatDetails pointer + * + * PixelFormatDetails provides access to detailed information about pixel format layout. + * This file contains the complete documentation. The actual implementation is header-only + * in PixelFormatDetails.hpp. + */ + +namespace hdk::sdl { + // Forward declarations + class PixelFormatDetails; + + // ============================================================================ + // PixelFormatDetails class - Core documentation + // ============================================================================ + + /** + * @class PixelFormatDetails + * @brief Wraps const SDL_PixelFormatDetails pointer with pixel format information + * + * Provides detailed information about a pixel format including bit depths, byte order, + * and component layout. This is a read-only wrapper around SDL's constant pixel format + * details structure. No lifetime management is needed as the data is owned by SDL. + * + * @see https://wiki.libsdl.org/SDL3/SDL_PixelFormatDetails + */ + + // ============================================================================ + // Factory Method + // ============================================================================ + + /** + * @fn static PixelFormatDetails PixelFormatDetails::Get(SDL_PixelFormat format) + * @brief Get detailed information for a pixel format + * + * Retrieves the detailed information structure for the specified pixel format. + * + * @param format The pixel format to query + * @return PixelFormatDetails An object containing the format details + * @see https://wiki.libsdl.org/SDL3/SDL_GetPixelFormatDetails + */ + + // ============================================================================ + // Color Conversion Methods + // ============================================================================ + + /** + * @fn void PixelFormatDetails::GetRGB(Uint32 pixel, SDL_Palette* palette, Uint8* r, Uint8* g, Uint8* b) const + * @brief Extract RGB values from a pixel value for this format + * + * Converts a pixel value (as stored in memory) to its RGB color components. + * + * @param pixel The pixel value to decompose + * @param palette The palette to use (for indexed formats), or nullptr for non-indexed formats + * @param r Pointer to Uint8 to store the red component (0-255) + * @param g Pointer to Uint8 to store the green component (0-255) + * @param b Pointer to Uint8 to store the blue component (0-255) + * @see https://wiki.libsdl.org/SDL3/SDL_GetRGB + */ + + /** + * @fn void PixelFormatDetails::GetRGBA(Uint32 pixel, SDL_Palette* palette, Uint8* r, Uint8* g, Uint8* b, Uint8* a) const + * @brief Extract RGBA values from a pixel value for this format + * + * Converts a pixel value (as stored in memory) to its RGBA color components. + * + * @param pixel The pixel value to decompose + * @param palette The palette to use (for indexed formats), or nullptr for non-indexed formats + * @param r Pointer to Uint8 to store the red component (0-255) + * @param g Pointer to Uint8 to store the green component (0-255) + * @param b Pointer to Uint8 to store the blue component (0-255) + * @param a Pointer to Uint8 to store the alpha component (0-255) + * @see https://wiki.libsdl.org/SDL3/SDL_GetRGBA + */ + + /** + * @fn Uint32 PixelFormatDetails::MapRGB(SDL_Palette* palette, Uint8 r, Uint8 g, Uint8 b) const + * @brief Map RGB values to a pixel value for this format + * + * Converts RGB color components to a pixel value as stored in this format. + * + * @param palette The palette to use (for indexed formats), or nullptr for non-indexed formats + * @param r The red component (0-255) + * @param g The green component (0-255) + * @param b The blue component (0-255) + * @return Uint32 The pixel value corresponding to the RGB values + * @see https://wiki.libsdl.org/SDL3/SDL_MapRGB + */ + + /** + * @fn Uint32 PixelFormatDetails::MapRGBA(SDL_Palette* palette, Uint8 r, Uint8 g, Uint8 b, Uint8 a) const + * @brief Map RGBA values to a pixel value for this format + * + * Converts RGBA color components to a pixel value as stored in this format. + * + * @param palette The palette to use (for indexed formats), or nullptr for non-indexed formats + * @param r The red component (0-255) + * @param g The green component (0-255) + * @param b The blue component (0-255) + * @param a The alpha component (0-255) + * @return Uint32 The pixel value corresponding to the RGBA values + * @see https://wiki.libsdl.org/SDL3/SDL_MapRGBA + */ + +} diff --git a/src/render.cpp b/src/render.cpp new file mode 100644 index 0000000..ab116fe --- /dev/null +++ b/src/render.cpp @@ -0,0 +1,65 @@ +/** + * @file render.cpp + * @brief Documentation for render.hpp circular dependency resolver + * + * The render.hpp header resolves circular dependencies between Renderer and Texture classes + * which both need to reference each other for full functionality. This file documents the + * inline implementations that bridge these dependencies. + */ + +namespace hdk::sdl { + /** + * @fn Renderer Texture::GetRenderer() const + * @brief Get the renderer that created this texture + * + * Returns a reference to the Renderer that created this texture. The returned renderer + * is a view-only reference (non-owning) since it may have been created separately. + * + * @return Renderer A wrapper around the renderer + * @see https://wiki.libsdl.org/SDL3/SDL_GetRendererFromTexture + */ + + /** + * @fn Texture Renderer::CreateTexture(SDL_PixelFormat format, SDL_TextureAccess access, int w, int h) const + * @brief Create a texture for this renderer + * + * Creates a texture that can be rendered by this renderer. + * + * @param format The pixel format of the texture + * @param access The access pattern (static, streaming, or target) + * @param w Width in pixels + * @param h Height in pixels + * @return Texture The created texture + * @see https://wiki.libsdl.org/SDL3/SDL_CreateTexture + */ + + /** + * @fn Texture Renderer::CreateTextureFromSurface(SDL_Surface* surface) const + * @brief Create a texture from a surface using this renderer + * + * @param surface The surface to create the texture from + * @return Texture The created texture + * @see https://wiki.libsdl.org/SDL3/SDL_CreateTextureFromSurface + */ + + /** + * @fn Texture Renderer::CreateTextureWithProperties(SDL_PropertiesID properties) const + * @brief Create a texture with properties using this renderer + * + * @param properties The properties object for texture creation + * @return Texture The created texture + * @see https://wiki.libsdl.org/SDL3/SDL_CreateTextureWithProperties + */ + + /** + * @fn Texture Renderer::GetRenderTarget() const + * @brief Get the current render target texture for this renderer + * + * Returns the texture that this renderer is currently rendering to, if any. + * If rendering to the default target (screen), returns an invalid texture. + * + * @return Texture The render target texture, or an invalid texture if using default target + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderTarget + */ + +} diff --git a/src/render/Renderer.cpp b/src/render/Renderer.cpp new file mode 100644 index 0000000..cd6f4dc --- /dev/null +++ b/src/render/Renderer.cpp @@ -0,0 +1,1107 @@ +/** + * @file Renderer.cpp + * @brief Documentation for Renderer class - wraps SDL_Renderer with C++ shared_ptr lifetime management + * + * Renderers are used to render 2D graphics in SDL. This file contains the complete documentation + * for the Renderer wrapper class. The actual implementation is header-only in Renderer.hpp. + */ + +namespace hdk::sdl { + // Forward declarations + class Renderer; + class Texture; + class Window; + + // ============================================================================ + // Renderer class - Core documentation + // ============================================================================ + + /** + * @class Renderer + * @brief Wraps the SDL_Renderer struct and related functions in a C++ class with shared_ptr lifetime management + * + * Renderers are used to render 2D graphics in SDL. This wrapper uses shared_ptr for automatic + * lifetime management. Multiple copies of a Renderer instance will share ownership of the + * underlying SDL_Renderer; the renderer is destroyed when the last copy goes out of scope. + * + * Inherits from SharedPtrWrapper and provides a C++-style interface to SDL's + * rendering API while maintaining compatibility with SDL's C API by providing implicit + * conversion to SDL_Renderer*. + * + * @see https://wiki.libsdl.org/SDL3/SDL_Renderer + */ + + // ============================================================================ + // Factory Methods - Creating Renderers + // ============================================================================ + + /** + * @fn static Renderer Renderer::Create(SDL_Window* window, const char* driverName) + * @brief Create a renderer for a window + * + * Creates a renderer associated with the provided window. The renderer will automatically + * be destroyed when all copies of the returned Renderer instance are destroyed. + * + * @param window The window to create the renderer for. If the window is invalid, this + * function will return an invalid renderer (one that evaluates to false). + * @param driverName The name of the rendering driver to initialize. If NULL, the first + * available driver is used. + * @return Renderer A new Renderer instance managing the created SDL_Renderer. If the + * creation fails, returns an invalid renderer. + * + * @see https://wiki.libsdl.org/SDL3/SDL_CreateRenderer + */ + + /** + * @fn static Renderer Renderer::CreateSoftware(SDL_Surface* surface) + * @brief Create a software renderer for a surface + * + * Creates a software renderer that draws to the provided surface. This renderer performs + * pixel manipulation in software rather than using hardware acceleration. It is slower + * than hardware renderers but can be useful when hardware acceleration is unavailable or + * for special rendering effects. + * + * @param surface A valid SDL_Surface to render into. The surface's pixel data will be + * modified by rendering operations. + * @return Renderer A new Renderer instance managing the created software renderer. + * Returns an invalid renderer if creation fails. + * + * @see https://wiki.libsdl.org/SDL3/SDL_CreateSoftwareRenderer + */ + + /** + * @fn static Renderer Renderer::GetFromWindow(SDL_Window* window) + * @brief Get the renderer associated with a window + * + * Retrieves the renderer that was previously created for the given window. This does not + * take ownership of the renderer; if you need to keep a reference, store it before the + * original Renderer instance is destroyed. + * + * The returned Renderer will evaluate to false if no renderer is associated with the window + * or if the window is invalid. + * + * @param window The window to query for its renderer + * @return Renderer A Renderer instance wrapping the SDL_Renderer associated with the window. + * Note: we may not have created the renderer we get back, if not we will + * not own it (uses weak reference). + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderer + */ + + /** + * @fn static Renderer Renderer::GetFromTexture(SDL_Texture* texture) + * @brief Get the renderer associated with a texture + * + * Retrieves the renderer that owns or created the given texture. This does not take + * ownership of the renderer. + * + * @param texture The texture to query for its associated renderer + * @return Renderer A Renderer instance wrapping the SDL_Renderer that owns the texture. + * Note: we may not have created the renderer we get back, if not we will + * not own it (uses weak reference). + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetRendererFromTexture + */ + + /** + * @fn static int Renderer::GetNumRenderDrivers() + * @brief Get the number of 2D rendering drivers available + * + * Returns the count of available rendering drivers on the current platform. This can be + * used to enumerate available drivers using GetDriver(). + * + * @return The number of 2D rendering drivers available, or -1 on failure. + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetNumRenderDrivers + */ + + /** + * @fn static const char* Renderer::GetDriver(int index) + * @brief Get the name of a renderer driver specified by an index + * + * Returns the name of the rendering driver at the given index. Valid indices range from + * 0 to GetNumRenderDrivers()-1. + * + * @param index The index of the rendering driver to query, starting at 0. + * @return const char* A pointer to the driver name string. The string is valid for the + * lifetime of the SDL library. + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderDriver + */ + + // ============================================================================ + // Texture Creation Methods + // ============================================================================ + + /** + * @fn Texture Renderer::CreateTexture(SDL_PixelFormat format, SDL_TextureAccess access, int w, int h) const + * @brief Create a texture for this renderer + * + * Creates a new texture with the specified pixel format and access pattern. The texture + * will be associated with this renderer and cannot be used with other renderers. + * + * Implementation: Defined in ../render.hpp to avoid circular dependency with Texture class. + * + * @param format The pixel format of the texture + * @param access How the texture can be accessed (static, streaming, or target) + * @param w The width of the texture in pixels + * @param h The height of the texture in pixels + * @return Texture A new Texture instance managing the created SDL_Texture + * + * @see https://wiki.libsdl.org/SDL3/SDL_CreateTexture + */ + + /** + * @fn Texture Renderer::CreateTextureFromSurface(SDL_Surface* surface) const + * @brief Create a texture from a surface + * + * Creates a texture from the provided surface, copying the pixel data. The surface is not + * modified and can be freed immediately after this call. + * + * Implementation: Defined in ../render.hpp to avoid circular dependency with Texture class. + * + * @param surface A valid SDL_Surface to copy pixel data from + * @return Texture A new Texture instance containing the surface's pixel data + * + * @see https://wiki.libsdl.org/SDL3/SDL_CreateTextureFromSurface + */ + + /** + * @fn Texture Renderer::CreateTextureWithProperties(SDL_PropertiesID properties) const + * @brief Create a texture with properties + * + * Creates a texture using the provided properties object for fine-grained configuration. + * This allows specifying advanced texture parameters beyond what the simpler Create methods + * offer. + * + * Implementation: Defined in ../render.hpp to avoid circular dependency with Texture class. + * + * @param properties The ID of the properties set to use for texture creation + * @return Texture A new Texture instance managing the created SDL_Texture + * + * @see https://wiki.libsdl.org/SDL3/SDL_CreateTextureWithProperties + */ + + /** + * @fn Texture Renderer::GetRenderTarget() const + * @brief Get the current render target texture + * + * Returns the texture that is currently set as the render target, or an invalid texture + * if rendering is going to the window surface. + * + * Implementation: Defined in ../render.hpp to avoid circular dependency with Texture class. + * + * @return Texture The texture currently used as the render target, or an invalid Texture + * if the default render target (window) is active. + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderTarget + */ + + // ============================================================================ + // Rendering Operations + // ============================================================================ + + /** + * @fn bool Renderer::Clear() const + * @brief Clear the current rendering target with the drawing color + * + * Clears the entire render target (either the window or the current target texture) to + * the current draw color. Use SetDrawColor() to set the clear color. This operation is + * typically called at the beginning of each frame. + * + * @return bool True if successfully cleared, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderClear + */ + + /** + * @fn bool Renderer::Present() const + * @brief Update the screen with any rendering performed since the previous call + * + * Presents the accumulated rendering commands to the display. This is the synchronization + * point that shows all drawing operations on screen. After calling Present(), the framebuffer + * is typically ready for the next frame. + * + * For most applications, the typical frame pattern is: + * 1. SetDrawColor() - set clear color + * 2. Clear() - clear the rendering target + * 3. RenderTexture() - draw your content + * 4. Present() - show the frame + * + * @return bool True if successfully presented, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderPresent + */ + + /** + * @fn bool Renderer::Flush() const + * @brief Flush the current rendering commands to the screen + * + * Forces pending rendering commands to be submitted to the GPU without waiting for + * Present(). This can be useful if you want to ensure commands are sent but aren't + * ready to display the frame yet. Most applications should use Present() instead. + * + * @return bool True if the renderer was successfully flushed, false otherwise + * + * @see https://wiki.libsdl.org/SDL3/SDL_FlushRenderer + */ + + /** + * @fn bool Renderer::ReadPixels(const SDL_Rect* rect) const + * @brief Read pixels from the current render target + * + * Reads pixel data from the current render target and returns it as a Surface. This is + * useful for screenshots or pixel-perfect operations. Reading pixels can be slow on + * some platforms, especially with hardware renderers. + * + * @param rect A pointer to an SDL_Rect structure representing the area to read, or NULL + * to read the entire render target. + * @return Surface An hdk::sdl::Surface containing the pixel data, or an invalid Surface + * on failure. + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderReadPixels + */ + + // ============================================================================ + // Drawing Primitives + // ============================================================================ + + /** + * @fn bool Renderer::RenderPoint(float x, float y) const + * @brief Render a point with current draw color + * + * Draws a single pixel at the specified coordinates using the current draw color. + * + * @param x The x coordinate of the point + * @param y The y coordinate of the point + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderPoint + */ + + /** + * @fn bool Renderer::RenderPoints(const SDL_FPoint* points, int count) const + * @brief Render multiple points with current draw color + * + * Draws multiple points at once, which may be more efficient than calling RenderPoint() + * repeatedly. + * + * @param points A pointer to an array of SDL_FPoint structures + * @param count The number of points in the array + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderPoints + */ + + /** + * @fn bool Renderer::RenderLine(float x1, float y1, float x2, float y2) const + * @brief Render a line with current draw color + * + * Draws a line from (x1, y1) to (x2, y2) using the current draw color. + * + * @param x1 The x coordinate of the line start + * @param y1 The y coordinate of the line start + * @param x2 The x coordinate of the line end + * @param y2 The y coordinate of the line end + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderLine + */ + + /** + * @fn bool Renderer::RenderLines(const SDL_FPoint* points, int count) const + * @brief Render multiple line segments with current draw color + * + * Draws multiple connected line segments. Each consecutive pair of points defines a line segment. + * + * @param points A pointer to an array of SDL_FPoint structures + * @param count The number of points in the array + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderLines + */ + + /** + * @fn bool Renderer::RenderRect(const SDL_FRect* rect) const + * @brief Render a rectangle outline with current draw color + * + * Draws the outline of a rectangle without filling it. + * + * @param rect A pointer to an SDL_FRect structure to outline, or NULL to outline the + * entire render target + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderRect + */ + + /** + * @fn bool Renderer::RenderRects(const SDL_FRect* rects, int count) const + * @brief Render multiple rectangle outlines with current draw color + * + * Draws the outlines of multiple rectangles efficiently. + * + * @param rects A pointer to an array of SDL_FRect structures + * @param count The number of rectangles in the array + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderRects + */ + + /** + * @fn bool Renderer::FillRect(const SDL_FRect* rect) const + * @brief Fill a rectangle with current draw color + * + * Draws a filled rectangle using the current draw color. + * + * @param rect A pointer to an SDL_FRect structure to fill, or NULL to fill the entire + * render target + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderFillRect + */ + + /** + * @fn bool Renderer::FillRects(const SDL_FRect* rects, int count) const + * @brief Fill multiple rectangles with current draw color + * + * Draws multiple filled rectangles efficiently. + * + * @param rects A pointer to an array of SDL_FRect structures + * @param count The number of rectangles in the array + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderFillRects + */ + + // ============================================================================ + // Texture Rendering + // ============================================================================ + + /** + * @fn bool Renderer::RenderTexture(SDL_Texture* texture, const SDL_FRect* src, const SDL_FRect* dst) const + * @brief Render a texture + * + * Copies a portion of a texture to the render target. The src rectangle specifies the + * region of the texture to copy, and dst specifies where to place it on the render target. + * If either rectangle is NULL, the operation uses defaults (entire texture for src, entire + * render target for dst). + * + * @param texture The texture to render + * @param src The source rectangle in the texture, or NULL to use the entire texture + * @param dst The destination rectangle on the render target, or NULL to use the entire target + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderTexture + */ + + /** + * @fn bool Renderer::RenderTextureRotated(SDL_Texture* texture, const SDL_FRect* srcrect, const SDL_FRect* dstrect, double angle, const SDL_FPoint* center, SDL_FlipMode flip) const + * @brief Render a texture with rotation and optional flipping + * + * Renders a texture with rotation around a center point and optional horizontal/vertical flipping. + * + * @param texture The texture to render + * @param srcrect The source rectangle in the texture, or NULL for entire texture + * @param dstrect The destination rectangle on the render target + * @param angle The rotation angle in degrees (clockwise) + * @param center A point indicating the center of rotation, or NULL to use the center of dstrect + * @param flip Flip mode for the texture (none, horizontal, vertical, or both) + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderTextureRotated + */ + + /** + * @fn bool Renderer::RenderTextureAffine(SDL_Texture* texture, const SDL_FRect* src, const SDL_FPoint* origin, const SDL_FPoint* right, const SDL_FPoint* down) const + * @brief Render a texture with affine transformations + * + * Renders a texture with arbitrary affine transformation (rotation, scaling, skewing). + * The three points define the transformed position and size of the texture. + * + * @param texture The texture to render + * @param src The source rectangle in the texture, or NULL for entire texture + * @param origin A point that defines the upper-left corner of the transformed texture + * @param right A point that defines where the upper-right corner of the texture will be placed + * @param down A point that defines where the lower-left corner of the texture will be placed + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderTextureAffine + */ + + /** + * @fn bool Renderer::RenderTexture9Grid(SDL_Texture* texture, const SDL_FRect* src, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect* dst) const + * @brief Render a texture with 9-grid scaling + * + * Renders a texture using 9-grid scaling (also known as 9-slice scaling). The source + * texture is divided into 9 regions (corners, edges, center) and the destination is + * constructed to preserve the corners while scaling the edges and center. + * + * @param texture The texture to render + * @param src The source rectangle defining the texture region + * @param left_width The width of the left edge (fixed, not scaled) + * @param right_width The width of the right edge (fixed, not scaled) + * @param top_height The height of the top edge (fixed, not scaled) + * @param bottom_height The height of the bottom edge (fixed, not scaled) + * @param scale A scale factor to apply to the center and edges + * @param dst The destination rectangle where the scaled texture is drawn + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderTexture9Grid + */ + + /** + * @fn bool Renderer::RenderTexture9GridTiled(SDL_Texture* texture, const SDL_FRect* src, float left_width, float right_width, float top_height, float bottom_height, float scale, const SDL_FRect* dst, float tile_scale) const + * @brief Render a texture with 9-grid scaling and tiling + * + * Like RenderTexture9Grid, but the center region is tiled instead of scaled. + * + * @param texture The texture to render + * @param src The source rectangle defining the texture region + * @param left_width The width of the left edge (fixed) + * @param right_width The width of the right edge (fixed) + * @param top_height The height of the top edge (fixed) + * @param bottom_height The height of the bottom edge (fixed) + * @param scale A scale factor to apply to fixed edges + * @param dst The destination rectangle + * @param tile_scale A scale factor for the center tiles + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderTexture9GridTiled + */ + + /** + * @fn bool Renderer::RenderTextureTiled(SDL_Texture* texture, const SDL_FRect* srcrect, float scale, const SDL_FRect* dstrect, float tile_scale) const + * @brief Render a texture with tiling + * + * Renders a texture repeatedly (tiled) to fill the destination rectangle. + * + * @param texture The texture to tile and render + * @param srcrect The source rectangle in the texture (defines the tile), or NULL for entire texture + * @param scale A scale factor for the texture + * @param dstrect The destination rectangle to fill with tiled texture + * @param tile_scale A scale factor applied to the tiling pattern + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderTextureTiled + */ + + /** + * @fn bool Renderer::RenderGeometry(SDL_Texture* texture, const SDL_Vertex* vertices, int numVertices, const int* indices, int numIndices) const + * @brief Render geometry with optional texture + * + * Renders arbitrary geometry defined by an array of vertices and optional index array. + * This is useful for rendering custom shapes or meshes. + * + * @param texture The texture to apply, or NULL for untextured geometry + * @param vertices A pointer to an array of SDL_Vertex structures + * @param numVertices The number of vertices in the array + * @param indices A pointer to an array of vertex indices (triangle indices), or NULL to + * use vertices in order + * @param numIndices The number of indices in the array + * @return bool True on success, false on failure + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderGeometry + */ + + /** + * @fn bool Renderer::RenderGeometryRaw(SDL_Texture* texture, const float* xy, int xy_stride, const SDL_FColor* color, int color_stride, const float* uv, int uv_stride, int numVertices, const void* indices, int numIndices, int sizeIndices) const + * @brief Render a list of triangles with optional texture and fine-grained vertex data + * + * A low-level rendering function that provides more control over vertex data layout. + * Vertex positions, colors, and texture coordinates are specified as separate arrays + * with configurable strides. + * + * @param texture The texture to use for rendering, or NULL for untextured rendering + * @param xy Pointer to an array of 2D vertex positions (x, y coordinates) + * @param xy_stride The byte stride between consecutive vertex positions in the xy array + * @param color Pointer to an array of vertex colors (SDL_FColor format) + * @param color_stride The byte stride between consecutive vertex colors + * @param uv Pointer to an array of texture coordinates (u, v in 0.0-1.0 range), or NULL + * if not using textures + * @param uv_stride The byte stride between consecutive texture coordinates + * @param numVertices The number of vertices + * @param indices Pointer to an array of vertex indices that define triangles, or NULL to + * render vertices in order + * @param numIndices The number of indices (must be divisible by 3 for triangles) + * @param sizeIndices The byte size of each index: 1, 2, or 4 + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderGeometryRaw + */ + + // ============================================================================ + // Some Debug Text Rendering + // ============================================================================ + + /** + * @fn bool Renderer::DebugText(float x, float y, const char* text) const + * @brief Render debug text at a specific position + * + * Renders simple monospace debug text on the current render target. This is useful for + * displaying FPS counters, debug info, or other temporary text. The text is drawn in + * white by default and should not be used for production UI. + * + * @param x The x coordinate of the text position + * @param y The y coordinate of the text position + * @param text The text string to render (NULL-terminated) + * @return bool True if successfully rendered, false otherwise + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderDebugText + */ + + /** + * @fn template bool Renderer::DebugTextFormat(float x, float y, const char* fmt, Args... args) const + * @brief Render formatted debug text at a specific position + * + * Like DebugText, but supports printf-style formatting for dynamic text. + * + * @param x The x coordinate of the text position + * @param y The y coordinate of the text position + * @param fmt A printf-style format string + * @param args Arguments for the format string + * @return bool True if successfully rendered, false otherwise + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderDebugTextFormat + */ + + // ============================================================================ + // Color and Blend Mode Management + // ============================================================================ + + /** + * @fn bool Renderer::SetDrawColor(Uint8 r, Uint8 g, Uint8 b, Uint8 a) const + * @brief Set the color used for drawing operations (Fill and Line) + * + * Sets the draw color for subsequent primitive drawing operations (points, lines, rectangles). + * Color components are in 8-bit format (0-255). + * + * @param r The red component of the drawing color (0-255) + * @param g The green component of the drawing color (0-255) + * @param b The blue component of the drawing color (0-255) + * @param a The alpha component of the drawing color (0-255) + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_SetRenderDrawColor + */ + + /** + * @fn bool Renderer::SetDrawColorFloat(float r, float g, float b, float a) const + * @brief Set the color used for drawing operations as floats + * + * Like SetDrawColor, but accepts color components as floats (0.0-1.0) for easier blending + * with floating-point graphics calculations. + * + * @param r The red component (0.0-1.0) + * @param g The green component (0.0-1.0) + * @param b The blue component (0.0-1.0) + * @param a The alpha component (0.0-1.0) + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_SetRenderDrawColorFloat + */ + + /** + * @fn bool Renderer::GetDrawColor(Uint8* r, Uint8* g, Uint8* b, Uint8* a) const + * @brief Get the color currently used for drawing operations + * + * Retrieves the current draw color set by SetDrawColor. + * + * @param r A pointer to a Uint8 to store the red component. If renderer is invalid, set to 0. + * @param g A pointer to a Uint8 to store the green component. If renderer is invalid, set to 0. + * @param b A pointer to a Uint8 to store the blue component. If renderer is invalid, set to 0. + * @param a A pointer to a Uint8 to store the alpha component. If renderer is invalid, set to 0. + * @return bool True if successfully retrieved, false otherwise + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderDrawColor + */ + + /** + * @fn bool Renderer::GetDrawColorFloat(float* r, float* g, float* b, float* a) const + * @brief Get the color currently used for drawing operations as floats + * + * Like GetDrawColor, but returns components as floats (0.0-1.0). + * + * @param r A pointer to a float for the red component. Set to 0.0f if renderer is invalid. + * @param g A pointer to a float for the green component. Set to 0.0f if renderer is invalid. + * @param b A pointer to a float for the blue component. Set to 0.0f if renderer is invalid. + * @param a A pointer to a float for the alpha component. Set to 0.0f if renderer is invalid. + * @return bool True if successfully retrieved, false otherwise + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderDrawColorFloat + */ + + /** + * @fn bool Renderer::SetDrawBlendMode(SDL_BlendMode blendMode) const + * @brief Set the blend mode for drawing operations + * + * Sets how colors are blended when drawing primitives. Common modes include SDL_BLENDMODE_NONE, + * SDL_BLENDMODE_BLEND (alpha blending), SDL_BLENDMODE_ADD (additive), etc. + * + * @param blendMode The SDL_BlendMode to use + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_SetRenderDrawBlendMode + */ + + /** + * @fn bool Renderer::GetDrawBlendMode(SDL_BlendMode* blendMode) const + * @brief Get the blend mode used for drawing operations + * + * Retrieves the current blend mode for primitives. + * + * @param blendMode A pointer to an SDL_BlendMode to fill with the current blend mode. + * Set to SDL_BlendMode_None if renderer is invalid. + * @return bool True if successfully retrieved, false otherwise + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderDrawBlendMode + */ + + /** + * @fn bool Renderer::SetRenderColorScale(float scale) const + * @brief Set the color scale for the renderer + * + * Scales all rendering colors by the given factor. Useful for brightness adjustments + * or gamma correction. + * + * @param scale The color scale factor (typical range 0.0-1.0+) + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_SetRenderColorScale + */ + + /** + * @fn bool Renderer::GetColorScale(float* scale) const + * @brief Get the color scale for the renderer + * + * @param scale A pointer to a float to store the current color scale. + * Set to 0.0f if renderer is invalid. + * @return bool True if successfully retrieved, false otherwise + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderColorScale + */ + + // ============================================================================ + // Viewport and Logical Presentation + // ============================================================================ + + /** + * @fn bool Renderer::SetViewport(const SDL_Rect* rect) const + * @brief Set the viewport for the current render target + * + * The viewport defines the area of the render target where drawing occurs. Setting a + * smaller viewport than the render target size allows drawing to a sub-region. + * + * @param rect A pointer to an SDL_Rect representing the viewport, or NULL to use the + * entire render target + * @return bool True if successfully set, false otherwise + * + * @see https://wiki.libsdl.org/SDL3/SDL_SetRenderViewport + */ + + /** + * @fn bool Renderer::GetViewport(SDL_Rect* rect) const + * @brief Get the viewport for the current render target + * + * @param rect A pointer to an SDL_Rect to fill with the current viewport + * @return bool True if successfully retrieved, false otherwise + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderViewport + */ + + /** + * @fn bool Renderer::ViewportSet() const + * @brief Check if the viewport is explicitly set + * + * @return bool True if viewport is set, false if using default (entire render target) + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderViewportSet + */ + + /** + * @fn bool Renderer::SetLogicalPresentation(int w, int h, SDL_RendererLogicalPresentation mode) const + * @brief Set the logical presentation for device-independent resolution + * + * Logical presentation allows specifying a virtual resolution that is independent of + * the actual window/display size. The renderer handles scaling and letterboxing automatically. + * This is useful for games that should look the same on different screen sizes. + * + * @param w The width of the logical presentation + * @param h The height of the logical presentation + * @param mode The presentation mode (how to handle aspect ratio differences) + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_SetRenderLogicalPresentation + */ + + /** + * @fn bool Renderer::GetLogicalPresentation(int* w, int* h, SDL_RendererLogicalPresentation* mode) const + * @brief Get the logical presentation settings + * + * @param w A pointer to an int to store the logical width + * @param h A pointer to an int to store the logical height + * @param mode A pointer to an SDL_RendererLogicalPresentation to store the mode + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderLogicalPresentation + */ + + /** + * @fn bool Renderer::GetLogicalPresentationRect(SDL_FRect* rect) const + * @brief Get the logical presentation rectangle + * + * Returns the rectangle describing where the logical presentation area is positioned + * within the actual render target (accounting for scaling and aspect ratio preservation). + * + * @param rect A pointer to an SDL_FRect to store the logical presentation rectangle + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderLogicalPresentationRect + */ + + // ============================================================================ + // Scaling and Transform + // ============================================================================ + + /** + * @fn bool Renderer::SetScale(float scaleX, float scaleY) const + * @brief Set the scale for the current render target + * + * Sets a scale factor for rendering. All coordinates and sizes are multiplied by + * these factors. Useful for zooming in/out of a scene. + * + * @param scaleX The horizontal scale factor + * @param scaleY The vertical scale factor + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_SetRenderScale + */ + + /** + * @fn bool Renderer::GetScale(float* scaleX, float* scaleY) const + * @brief Get the scale of the current render target + * + * @param scaleX A pointer to a float to store the horizontal scale factor + * @param scaleY A pointer to a float to store the vertical scale factor + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderScale + */ + + /** + * @fn bool Renderer::SetRenderTarget(SDL_Texture* texture) const + * @brief Set the render target to a texture + * + * Redirects rendering operations to draw into a texture instead of the window. + * This is useful for rendering to offscreen buffers, creating post-processing effects, + * or rendering scenes that will be used as textures. + * + * Pass NULL to reset to the default render target (window). + * + * @param texture The texture to set as render target, or NULL for the default target + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_SetRenderTarget + */ + + // ============================================================================ + // Clipping + // ============================================================================ + + /** + * @fn bool Renderer::SetClipRect(const SDL_Rect* rect) const + * @brief Set the clip rectangle for the current rendering target + * + * Sets a clipping region; only pixels within this rectangle will be modified by + * rendering operations. Pass NULL to disable clipping. + * + * @param rect A pointer to an SDL_Rect defining the clip region, or NULL to disable + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_SetRenderClipRect + */ + + /** + * @fn bool Renderer::GetClipRect(SDL_Rect* rect) const + * @brief Get the clip rectangle for the current rendering target + * + * @param rect A pointer to an SDL_Rect to fill with the clip rectangle. + * Set to {0, 0, 0, 0} if renderer is invalid or clipping is disabled. + * @return bool True if successfully retrieved, false otherwise + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderClipRect + */ + + /** + * @fn bool Renderer::ClipEnabled() const + * @brief Check if clipping is enabled + * + * @return bool True if clipping is enabled, false otherwise + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderClipEnabled + */ + + // ============================================================================ + // Texture Address Mode + // ============================================================================ + + /** + * @fn bool Renderer::SetTextureAddressMode(SDL_TextureAddressMode u_mode, SDL_TextureAddressMode v_mode) const + * @brief Set the texture address mode for the current render target + * + * Controls how texture coordinates outside the 0.0-1.0 range are handled when rendering. + * + * @param u_mode The address mode for the u (horizontal) texture coordinate + * @param v_mode The address mode for the v (vertical) texture coordinate + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_SetRenderTextureAddressMode + */ + + /** + * @fn bool Renderer::GetTextureAddressMode(SDL_TextureAddressMode* u_mode, SDL_TextureAddressMode* v_mode) const + * @brief Get the texture address mode for the current render target + * + * @param u_mode A pointer to an SDL_TextureAddressMode for the u coordinate + * @param v_mode A pointer to an SDL_TextureAddressMode for the v coordinate + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderTextureAddressMode + */ + + // ============================================================================ + // Texture Scale Mode + // ============================================================================ + + /** + * @fn bool Renderer::SetDefaultTextureScaleMode(SDL_ScaleMode scaleMode) const + * @brief Set the default texture scale mode for the renderer + * + * Controls how textures are scaled when rendered at sizes different from their native size. + * Options include nearest-neighbor (pixelated) and linear filtering (smooth). + * + * @param scaleMode The scale mode to use + * @return bool True if set, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_SetDefaultTextureScaleMode + */ + + /** + * @fn bool Renderer::GetDefaultTextureScaleMode(SDL_ScaleMode* scaleMode) const + * @brief Get the default texture scale mode for the renderer + * + * @param scaleMode A pointer to an SDL_ScaleMode to fill with the current mode. + * Set to SDL_ScaleMode_None if renderer is invalid. + * @return bool True if successfully retrieved, false otherwise + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetDefaultTextureScaleMode + */ + + // ============================================================================ + // Coordinate Conversion + // ============================================================================ + + /** + * @fn bool Renderer::CoordinatesFromWindow(float windowX, float windowY, float* rendererX, float* rendererY) const + * @brief Convert window coordinates to renderer coordinates + * + * Translates coordinates from window space (affected by viewport, scale, logical presentation) + * to renderer/logical space. Useful for converting mouse coordinates or other window events. + * + * @param windowX The x coordinate in window space + * @param windowY The y coordinate in window space + * @param rendererX A pointer to a float to store the converted x coordinate + * @param rendererY A pointer to a float to store the converted y coordinate + * @return bool True if successfully converted, false otherwise + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderCoordinatesFromWindow + */ + + /** + * @fn bool Renderer::CoordinatesToWindow(float rendererX, float rendererY, float* windowX, float* windowY) const + * @brief Convert renderer coordinates to window coordinates + * + * Translates coordinates from renderer/logical space to window space. + * + * @param rendererX The x coordinate in renderer space + * @param rendererY The y coordinate in renderer space + * @param windowX A pointer to a float to store the converted x coordinate + * @param windowY A pointer to a float to store the converted y coordinate + * @return bool True if successfully converted, false otherwise + * + * @see https://wiki.libsdl.org/SDL3/SDL_RenderCoordinatesToWindow + */ + + // ============================================================================ + // Vertical Synchronization + // ============================================================================ + + /** + * @fn bool Renderer::SetVSync(int vsync) const + * @brief Set the vertical sync setting for the current renderer + * + * Controls whether the renderer waits for the display's vertical refresh to prevent + * screen tearing. + * + * @param vsync The vsync setting: + * - 0: no vsync, render as fast as possible + * - 1: wait for vsync (prevents tearing) + * - -1: adaptive vsync (tear-free only if possible, otherwise no wait) + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_SetRenderVSync + */ + + /** + * @fn bool Renderer::GetVSync(int* vsync) const + * @brief Get the vertical sync setting for the current renderer + * + * @param vsync A pointer to an int to store the current vsync setting + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderVSync + */ + + // ============================================================================ + // Properties and Information + // ============================================================================ + + /** + * @fn const char* Renderer::GetName() const + * @brief Get the name of the renderer + * + * Returns the human-readable name of the rendering backend (e.g., "direct3d11", "opengl", "metal"). + * + * @return const char* A pointer to the renderer name string, or NULL if renderer is invalid + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetRendererName + */ + + /** + * @fn Properties Renderer::GetProperties() const + * @brief Get the properties of a renderer + * + * Returns a Properties object containing detailed information about the renderer's + * configuration and capabilities. + * + * @return Properties An hdk::sdl::Properties object with the renderer's properties + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetRendererProperties + */ + + /** + * @fn int Renderer::GetOutputSize(int* w, int* h) const + * @brief Get the output size in pixels of the current render target + * + * Returns the dimensions of the current render target (window or texture). + * + * @param w A pointer to an int to store the width. Set to 0 if renderer is invalid. + * @param h A pointer to an int to store the height. Set to 0 if renderer is invalid. + * @return bool True if successfully retrieved, false otherwise + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetCurrentRenderOutputSize + */ + + /** + * @fn bool Renderer::GetSafeArea(SDL_Rect* rect) const + * @brief Get the safe area of the renderer + * + * On devices with notches or curved edges, returns the rectangle of the safe area + * where content should be rendered to avoid being cut off. + * + * @param rect A pointer to an SDL_Rect to fill with the safe area rectangle + * @return bool True on success, false on error + * + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderSafeArea + */ + + /** + * @fn Window Renderer::GetWindow() const + * @brief Get the window associated with this renderer + * + * Returns the Window that this renderer renders to. + * + * Implementation: Defined in ../video.hpp to avoid circular dependency with Window class. + * + * @return Window A Window instance wrapping the SDL_Window associated with this renderer + */ + + // ============================================================================ + // Unimplemented Features (TODO) + // ============================================================================ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_AddVulkanRenderSemaphores + */ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_ConvertEventToRenderCoordinates + */ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_CreateGPURenderer + */ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_CreateGPURenderState + */ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_CreateRendererWithProperties + */ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_CreateWindowAndRenderer + */ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_DestroyGPURenderState + */ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_DestroyRenderer + */ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_GDKResumeRenderer + */ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_GDKSuspendRenderer + */ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_GetGPURendererDevice + */ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_GetRenderMetalCommandEncoder + */ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_GetRenderMetalLayer + */ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_GetRenderWindow + */ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_SetGPURenderState + */ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_SetGPURenderStateFragmentUniforms + */ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_SetGPURenderStateSamplerBindings + */ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_SetGPURenderStateStorageBuffers + */ + + /** + * @todo https://wiki.libsdl.org/SDL3/SDL_SetGPURenderStateStorageTextures + */ +} diff --git a/src/render/Texture.cpp b/src/render/Texture.cpp new file mode 100644 index 0000000..f4e54d5 --- /dev/null +++ b/src/render/Texture.cpp @@ -0,0 +1,321 @@ +/** + * @file Texture.cpp + * @brief Documentation for Texture class - wraps SDL_Texture with C++ shared_ptr lifetime management + * + * Textures are used to store pixel data that can be rendered efficiently by a renderer. This file contains + * the complete documentation for the Texture wrapper class. The actual implementation is header-only in Texture.hpp. + */ + +namespace hdk::sdl { + // Forward declarations + class Texture; + class Renderer; + class Palette; + class Properties; + + // ============================================================================ + // Texture class - Core documentation + // ============================================================================ + + /** + * @class Texture + * @brief Wraps SDL_Texture struct with C++ shared_ptr lifetime management + * + * Textures are used to store pixel data that can be rendered by a Renderer. This wrapper uses shared_ptr + * for automatic lifetime management. Multiple copies of a Texture instance will share ownership of the + * underlying SDL_Texture; the texture is destroyed when the last copy goes out of scope. + * + * Textures are optimized for rendering performance and are typically created from surfaces. + * + * @see https://wiki.libsdl.org/SDL3/SDL_Texture + */ + + // ============================================================================ + // Factory Methods - Creating Textures + // ============================================================================ + + /** + * @fn static Texture Texture::Create(SDL_Renderer* renderer, SDL_PixelFormat format, SDL_TextureAccess access, int w, int h) + * @brief Create a texture for a rendering context + * + * Creates an empty texture with the specified format and access pattern. + * + * @param renderer The rendering context to create the texture for + * @param format The pixel format of the texture + * @param access The access pattern (static, streaming, or target) + * @param w The width of the texture in pixels + * @param h The height of the texture in pixels + * @return Texture The created texture. If creation fails, returns an invalid texture + * @see https://wiki.libsdl.org/SDL3/SDL_CreateTexture + */ + + /** + * @fn static Texture Texture::CreateFromSurface(SDL_Renderer* renderer, SDL_Surface* surface) + * @brief Create a texture from an existing surface + * + * Creates a texture by copying pixel data from a surface. + * + * @param renderer The rendering context to create the texture for + * @param surface The surface to create the texture from + * @return Texture The created texture. If creation fails, returns an invalid texture + * @see https://wiki.libsdl.org/SDL3/SDL_CreateTextureFromSurface + */ + + /** + * @fn static Texture Texture::CreateWithProperties(SDL_Renderer* renderer, SDL_PropertiesID properties) + * @brief Create a texture for a rendering context with specific properties + * + * Creates a texture with fine-grained control via a properties object. + * + * @param renderer The rendering context to create the texture for + * @param properties The properties to create the texture with + * @return Texture The created texture. If creation fails, returns an invalid texture + * @see https://wiki.libsdl.org/SDL3/SDL_CreateTextureWithProperties + */ + + // ============================================================================ + // Texture Modulation - Alpha + // ============================================================================ + + /** + * @fn bool Texture::GetAlphaMod(Uint8* alpha) const + * @brief Get the alpha modulation value for this texture + * + * @param alpha Pointer to Uint8 to be filled with alpha value (0-255) + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_GetTextureAlphaMod + */ + + /** + * @fn Uint8 Texture::GetAlphaMod() const + * @brief Get the alpha modulation value for this texture + * + * Convenience overload that returns the value directly. + * + * @return Uint8 The alpha modulation value (0-255) + * @see https://wiki.libsdl.org/SDL3/SDL_GetTextureAlphaMod + */ + + /** + * @fn bool Texture::GetAlphaModFloat(float* alpha) const + * @brief Get the alpha modulation value as a float (0.0-1.0) + * + * @param alpha Pointer to float to be filled with alpha value + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_GetTextureAlphaModFloat + */ + + /** + * @fn float Texture::GetAlphaModFloat() const + * @brief Get the alpha modulation value as a float + * + * @return float The alpha modulation value (0.0-1.0) + * @see https://wiki.libsdl.org/SDL3/SDL_GetTextureAlphaModFloat + */ + + /** + * @fn bool Texture::SetAlphaMod(Uint8 alpha) const + * @brief Set the alpha modulation value for this texture + * + * @param alpha The alpha value to set (0-255) + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetTextureAlphaMod + */ + + /** + * @fn bool Texture::SetAlphaModFloat(float alpha) const + * @brief Set the alpha modulation value for this texture as a float + * + * @param alpha The alpha value to set (0.0-1.0) + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetTextureAlphaModFloat + */ + + // ============================================================================ + // Texture Blending + // ============================================================================ + + /** + * @fn bool Texture::GetBlendMode(SDL_BlendMode* blendMode) const + * @brief Get the blend mode for this texture + * + * @param blendMode Pointer to SDL_BlendMode to be filled with the blend mode + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_GetTextureBlendMode + */ + + /** + * @fn SDL_BlendMode Texture::GetBlendMode() const + * @brief Get the blend mode for this texture + * + * @return SDL_BlendMode The blend mode of the texture + * @see https://wiki.libsdl.org/SDL3/SDL_GetTextureBlendMode + */ + + /** + * @fn bool Texture::SetBlendMode(SDL_BlendMode blendMode) const + * @brief Set the blend mode for this texture + * + * @param blendMode The blend mode to set + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetTextureBlendMode + */ + + // ============================================================================ + // Texture Modulation - Color + // ============================================================================ + + /** + * @fn bool Texture::GetColorMod(Uint8* r, Uint8* g, Uint8* b) const + * @brief Get the color modulation values for this texture + * + * @param r Pointer to Uint8 for red component (0-255) + * @param g Pointer to Uint8 for green component (0-255) + * @param b Pointer to Uint8 for blue component (0-255) + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_GetTextureColorMod + */ + + /** + * @fn bool Texture::GetColorModFloat(float* r, float* g, float* b) const + * @brief Get the color modulation values as floats (0.0-1.0) + * + * @param r Pointer to float for red component + * @param g Pointer to float for green component + * @param b Pointer to float for blue component + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_GetTextureColorModFloat + */ + + /** + * @fn bool Texture::SetColorMod(Uint8 r, Uint8 g, Uint8 b) const + * @brief Set the color modulation values for this texture + * + * @param r Red component (0-255) + * @param g Green component (0-255) + * @param b Blue component (0-255) + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetTextureColorMod + */ + + /** + * @fn bool Texture::SetColorModFloat(float r, float g, float b) const + * @brief Set the color modulation values as floats + * + * @param r Red component (0.0-1.0) + * @param g Green component (0.0-1.0) + * @param b Blue component (0.0-1.0) + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetTextureColorModFloat + */ + + // ============================================================================ + // Texture Palette and Properties + // ============================================================================ + + /** + * @fn Palette Texture::GetPalette() const + * @brief Get the palette associated with this texture, if any + * + * Returns the palette used by indexed-color textures. + * + * @return Palette The palette associated with the texture, or an invalid palette if not applicable + * @see https://wiki.libsdl.org/SDL3/SDL_GetTexturePalette + */ + + /** + * @fn bool Texture::SetPalette(SDL_Palette* palette) const + * @brief Set the palette for this texture + * + * @param palette The palette to set for indexed-color textures + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetTexturePalette + */ + + /** + * @fn Properties Texture::GetProperties() const + * @brief Get the properties of this texture + * + * @return Properties Properties object associated with the texture + * @see https://wiki.libsdl.org/SDL3/SDL_GetTextureProperties + */ + + /** + * @fn Renderer Texture::GetRenderer() const + * @brief Get the renderer associated with this texture + * + * @return Renderer The renderer that created this texture + * @see https://wiki.libsdl.org/SDL3/SDL_GetRendererFromTexture + */ + + // ============================================================================ + // Texture Scaling and Size + // ============================================================================ + + /** + * @fn bool Texture::GetScaleMode(SDL_ScaleMode* scaleMode) const + * @brief Get the scale mode for this texture + * + * @param scaleMode Pointer to SDL_ScaleMode to be filled + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_GetTextureScaleMode + */ + + /** + * @fn SDL_ScaleMode Texture::GetScaleMode() const + * @brief Get the scale mode for this texture + * + * @return SDL_ScaleMode The scale mode of the texture + * @see https://wiki.libsdl.org/SDL3/SDL_GetTextureScaleMode + */ + + /** + * @fn bool Texture::SetScaleMode(SDL_ScaleMode scaleMode) const + * @brief Set the scale mode for this texture + * + * @param scaleMode The scale mode to set + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetTextureScaleMode + */ + + /** + * @fn bool Texture::GetSize(float* w, float* h) const + * @brief Get the size of this texture + * + * @param w Pointer to float to be filled with width + * @param h Pointer to float to be filled with height + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_GetTextureSize + */ + + // ============================================================================ + // Texture Locking - Direct Pixel Access + // ============================================================================ + + /** + * @fn bool Texture::Lock(const SDL_Rect* rect, void** pixels, int* pitch) const + * @brief Lock a portion of this texture for write-only pixel access + * + * Gains direct access to texture pixels for manual modification. Must be unlocked when finished. + * + * @param rect Area to lock, or nullptr to lock entire texture + * @param pixels Pointer to be filled with locked pixel data + * @param pitch Pointer to be filled with pitch (row size in bytes) + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_LockTexture + */ + + /** + * @fn bool Texture::LockToSurface(const SDL_Rect* rect, SDL_Surface** surface) const + * @brief Lock a portion of this texture and create an SDL_Surface for pixel access + * + * Locks texture pixels and wraps them in an SDL_Surface for easier manipulation. + * Must free the returned surface with SDL_FreeSurface when done. + * + * @param rect Area to lock, or nullptr to lock entire texture + * @param surface Pointer to SDL_Surface* to be filled + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_LockTextureToSurface + */ + +} diff --git a/src/video.cpp b/src/video.cpp new file mode 100644 index 0000000..e2696de --- /dev/null +++ b/src/video.cpp @@ -0,0 +1,60 @@ +/** + * @file video.cpp + * @brief Documentation for video.hpp circular dependency resolver + * + * The video.hpp header resolves circular dependencies between Window and Renderer classes. + * This file documents the inline implementations that enable windows to access their + * associated renderers and vice versa. + */ + +namespace hdk::sdl { + /** + * @fn Renderer Window::GetRenderer() const + * @brief Get the renderer associated with this window + * + * Returns a reference to the renderer that was created for this window. If the window + * has no associated renderer, returns an invalid renderer. + * + * @return Renderer The associated renderer + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderer + */ + + /** + * @fn Window Renderer::GetWindow() const + * @brief Get the window associated with this renderer + * + * Returns a reference to the window that this renderer was created for. The returned + * window is a view-only reference (non-owning) since it may have been created separately. + * + * @return Window The associated window + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderWindow + */ + + /** + * @fn std::pair CreateWindowAndRenderer(const char* title, int width, int height, SDL_WindowFlags window_flags) + * @brief Create a window and renderer with a single call + * + * A convenience function that creates both a window and a renderer for that window. + * This is often more efficient than creating them separately. + * + * @param title The title of the window + * @param width The width of the window in pixels + * @param height The height of the window in pixels + * @param window_flags Flags controlling window behavior + * @return std::pair A pair containing the created window and renderer. + * Both will be invalid if creation fails + * @see https://wiki.libsdl.org/SDL3/SDL_CreateWindowAndRenderer + */ + + /** + * @fn Palette Surface::CreatePalette() const + * @brief Create a palette from this surface + * + * Creates a new palette based on the color format of this surface. + * Useful for indexed-color surfaces. + * + * @return Palette The created palette + * @see https://wiki.libsdl.org/SDL3/SDL_CreateSurfacePalette + */ + +} diff --git a/src/video/Display.cpp b/src/video/Display.cpp new file mode 100644 index 0000000..395dc4f --- /dev/null +++ b/src/video/Display.cpp @@ -0,0 +1,252 @@ +/** + * @file Display.cpp + * @brief Documentation for Display class - wraps SDL_DisplayID with convenience methods for display queries + * + * Displays represent physical display devices such as monitors. This file contains the complete documentation + * for the Display wrapper class. The actual implementation is header-only in Display.hpp. + */ + +namespace hdk::sdl { + // Forward declarations + class Display; + + // ============================================================================ + // Display class - Core documentation + // ============================================================================ + + /** + * @class Display + * @brief Wraps SDL_DisplayID type with convenience methods for working with displays + * + * Displays represent physical display devices (monitors) in the system. This wrapper provides + * type-safe access to display-related queries and operations while maintaining compatibility + * with SDL's C API. + * + * Displays provide access to: + * - Display modes and resolution information + * - Display bounds and usable areas + * - Content scaling factors + * - Display orientation + * - Display names and properties + * + * @see https://wiki.libsdl.org/SDL3/SDL_DisplayID + */ + + // ============================================================================ + // Display Mode Queries + // ============================================================================ + + /** + * @fn bool Display::GetClosestFullscreenMode(int w, int h, float refresh_rate, bool include_high_density_modes, SDL_DisplayMode* closest) + * @brief Get the closest match to the requested fullscreen display mode + * + * Searches for the closest matching display mode for fullscreen rendering. + * + * @param w Requested width in pixels + * @param h Requested height in pixels + * @param refresh_rate Desired refresh rate (0.0f for desktop refresh rate) + * @param include_high_density_modes Whether to include high-density display modes + * @param closest Pointer to SDL_DisplayMode to be filled with the closest match + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_GetClosestFullscreenDisplayMode + */ + + /** + * @fn const SDL_DisplayMode* Display::GetCurrentMode() const + * @brief Get the current display mode of this display + * + * Returns the currently active display mode. + * + * @return const SDL_DisplayMode* Pointer to the current display mode + * @see https://wiki.libsdl.org/SDL3/SDL_GetCurrentDisplayMode + */ + + /** + * @fn const SDL_DisplayMode* Display::GetDesktopMode() const + * @brief Get the desktop display mode of this display + * + * Returns the native/default display mode when no fullscreen application is running. + * + * @return const SDL_DisplayMode* Pointer to the desktop display mode + * @see https://wiki.libsdl.org/SDL3/SDL_GetDesktopDisplayMode + */ + + /** + * @fn SDL_DisplayMode** Display::GetFullscreenModes(int* count) const + * @brief Get all fullscreen display modes available on this display + * + * Returns an array of all display modes that can be used for fullscreen rendering. + * Must be freed with SDL_free() when finished. + * + * @param count Pointer to int filled with the count of available modes + * @return SDL_DisplayMode** Null-terminated array of display mode pointers + * @see https://wiki.libsdl.org/SDL3/SDL_GetFullscreenDisplayModes + */ + + /** + * @fn std::vector Display::GetFullscreenModes() const + * @brief Get all fullscreen display modes as a std::vector + * + * Convenience overload that returns display modes in a std::vector. + * + * @return std::vector Vector of available display modes + * @see https://wiki.libsdl.org/SDL3/SDL_GetFullscreenDisplayModes + */ + + // ============================================================================ + // Display Orientation + // ============================================================================ + + /** + * @fn SDL_DisplayOrientation Display::GetCurrentOrientation() const + * @brief Get the current orientation of this display + * + * Returns the current orientation (portrait, landscape, etc.) of the display. + * + * @return SDL_DisplayOrientation The current orientation + * @see https://wiki.libsdl.org/SDL3/SDL_GetCurrentDisplayOrientation + */ + + /** + * @fn SDL_DisplayOrientation Display::GetNaturalOrientation() const + * @brief Get the natural orientation of this display + * + * Returns the display's natural/default orientation when physically rotated to its standard position. + * + * @return SDL_DisplayOrientation The natural orientation + * @see https://wiki.libsdl.org/SDL3/SDL_GetNaturalDisplayOrientation + */ + + // ============================================================================ + // Display Geometry and Area + // ============================================================================ + + /** + * @fn bool Display::GetBounds(SDL_Rect* rect) const + * @brief Get the bounds of this display + * + * Returns the rectangular area occupied by this display in screen coordinates. + * + * @param rect Pointer to SDL_Rect to be filled with display bounds + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_GetDisplayBounds + */ + + /** + * @fn bool Display::GetUsableBounds(SDL_Rect* rect) const + * @brief Get the usable bounds of this display + * + * Returns the rectangular area that is safe to display content in, accounting for taskbars, docks, + * notches, and other system UI elements that may obscure content. + * + * @param rect Pointer to SDL_Rect to be filled with usable bounds + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_GetDisplayUsableBounds + */ + + // ============================================================================ + // Display Scale and Content + // ============================================================================ + + /** + * @fn float Display::GetContentScale() const + * @brief Get the content scale factor for this display + * + * Returns the scale factor for high-DPI displays. Typical values are 1.0 for normal DPI + * and 2.0 or higher for high-DPI displays. + * + * @return float The content scale factor + * @see https://wiki.libsdl.org/SDL3/SDL_GetDisplayContentScale + */ + + // ============================================================================ + // Display Properties and Name + // ============================================================================ + + /** + * @fn const char* Display::GetName() const + * @brief Get the name of this display + * + * Returns a human-readable name for the display (e.g., "HDMI-1", "Built-in Display"). + * + * @return const char* The display name + * @see https://wiki.libsdl.org/SDL3/SDL_GetDisplayName + */ + + /** + * @fn Properties Display::GetProperties() const + * @brief Get the properties associated with this display + * + * @return Properties Properties object for this display + * @see https://wiki.libsdl.org/SDL3/SDL_GetDisplayProperties + */ + + // ============================================================================ + // Static Display Queries + // ============================================================================ + + /** + * @fn static Display Display::GetPrimaryDisplay() + * @brief Get the primary display + * + * Returns the display used for the application's main window. + * + * @return Display The primary display + * @see https://wiki.libsdl.org/SDL3/SDL_GetPrimaryDisplay + */ + + /** + * @fn static Display Display::GetForPoint(const SDL_Point* point) + * @brief Get the display that contains a point + * + * Finds which display contains the given screen coordinates. + * + * @param point Pointer to SDL_Point representing screen coordinates + * @return Display The display containing the point + * @see https://wiki.libsdl.org/SDL3/SDL_GetDisplayForPoint + */ + + /** + * @fn static Display Display::GetForRect(const SDL_Rect* rect) + * @brief Get the display that most closely intersects a rectangle + * + * Finds the display that has the largest intersection with the given rectangle. + * + * @param rect Pointer to SDL_Rect in screen coordinates + * @return Display The display that most closely intersects the rectangle + * @see https://wiki.libsdl.org/SDL3/SDL_GetDisplayForRect + */ + + /** + * @fn static Display Display::GetForWindow(SDL_Window* window) + * @brief Get the display associated with a window + * + * Returns the display on which the given window is primarily displayed. + * + * @param window The window to query + * @return Display The display associated with the window + * @see https://wiki.libsdl.org/SDL3/SDL_GetDisplayForWindow + */ + + /** + * @fn static SDL_DisplayID* Display::GetDisplays(int* count) + * @brief Get all displays in the system + * + * Returns an array of all available displays. Must be freed with SDL_free() when finished. + * + * @param count Pointer to int filled with the count of displays + * @return SDL_DisplayID* Array of display IDs + * @see https://wiki.libsdl.org/SDL3/SDL_GetDisplays + */ + + /** + * @fn static std::vector Display::GetDisplays() + * @brief Get all displays as a std::vector + * + * Convenience overload that returns all displays in a std::vector. + * + * @return std::vector Vector of all displays + * @see https://wiki.libsdl.org/SDL3/SDL_GetDisplays + */ + +} diff --git a/src/video/Surface.cpp b/src/video/Surface.cpp new file mode 100644 index 0000000..ffa8096 --- /dev/null +++ b/src/video/Surface.cpp @@ -0,0 +1,255 @@ +/** + * @file Surface.cpp + * @brief Documentation for Surface class - wraps SDL_Surface with C++ shared_ptr lifetime management + * + * Surfaces hold bitmap data and are used for pixel manipulation and blitting operations. This file contains + * the complete documentation for the Surface wrapper class. The actual implementation is header-only in Surface.hpp. + */ + +namespace hdk::sdl { + // Forward declarations + class Surface; + class Palette; + + // ============================================================================ + // Surface class - Core documentation + // ============================================================================ + + /** + * @class Surface + * @brief Wraps SDL_Surface struct with C++ shared_ptr lifetime management + * + * Surfaces hold pixel data for 2D images. This wrapper uses shared_ptr for automatic lifetime management. + * Multiple copies of a Surface instance will share ownership of the underlying SDL_Surface; the surface + * is destroyed when the last copy goes out of scope. + * + * Surfaces are commonly used for: + * - Loading and manipulating image data + * - Pixel-level operations + * - Blitting operations between surfaces + * - Creating textures from surface data + * + * @see https://wiki.libsdl.org/SDL3/SDL_Surface + */ + + // ============================================================================ + // Surface Alternate Images + // ============================================================================ + + /** + * @fn bool Surface::AddAlternateImage(SDL_Surface* surface) const + * @brief Add an alternate image to a surface + * + * Adds an alternative representation of the surface data, used for high-DPI or variant formats. + * + * @param surface The alternate surface to add + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_AddSurfaceAlternateImage + */ + + // ============================================================================ + // Surface Blitting Operations + // ============================================================================ + + /** + * @fn bool Surface::BlitTo(SDL_Surface* dst_surface, const SDL_Rect* dst_rect = nullptr, const SDL_Rect* src_rect = nullptr) const + * @brief Perform a fast blit from this surface to a destination surface + * + * Copies the surface data to the destination surface with optional clipping and scaling. + * + * @param dst_surface The destination surface to blit onto + * @param dst_rect Area on destination to blit to, or nullptr to blit to entire surface + * @param src_rect Area of this surface to blit, or nullptr to blit entire surface + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_BlitSurface + */ + + /** + * @fn bool Surface::BlitFrom(SDL_Surface* src_surface, const SDL_Rect* src_rect = nullptr, const SDL_Rect* dst_rect = nullptr) const + * @brief Perform a fast blit from a source surface to this surface + * + * Copies data from source surface to this surface. + * + * @param src_surface The source surface to blit from + * @param src_rect Area of source to blit, or nullptr to blit entire surface + * @param dst_rect Area on this surface to blit to, or nullptr to blit to entire surface + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_BlitSurface + */ + + /** + * @fn bool Surface::Blit9GridTo(SDL_Surface* dst_surface, const SDL_Rect* dst_rect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scale_mode, const SDL_Rect* src_rect = nullptr) const + * @brief Perform a 9-grid scaled blit from this surface to destination + * + * Performs a blit with 9-grid scaling, where the surface is divided into 9 regions (corners, edges, center) + * and scaled differently to preserve corner appearance while scaling edges and center. + * + * @param dst_surface The destination surface + * @param dst_rect Area on destination to blit to + * @param left_width Width of left edge columns + * @param right_width Width of right edge columns + * @param top_height Height of top edge rows + * @param bottom_height Height of bottom edge rows + * @param scale Scale factor for center region + * @param scale_mode Scaling algorithm to use + * @param src_rect Area of this surface to blit, or nullptr for entire surface + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_BlitSurface9Grid + */ + + /** + * @fn bool Surface::Blit9GridFrom(SDL_Surface* src_surface, const SDL_Rect* src_rect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scale_mode, const SDL_Rect* dst_rect = nullptr) const + * @brief Perform a 9-grid scaled blit from source surface to this surface + * + * @param src_surface The source surface + * @param src_rect Area of source to blit + * @param left_width Width of left edge columns + * @param right_width Width of right edge columns + * @param top_height Height of top edge rows + * @param bottom_height Height of bottom edge rows + * @param scale Scale factor for center region + * @param scale_mode Scaling algorithm to use + * @param dst_rect Area on this surface to blit to, or nullptr for entire surface + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_BlitSurface9Grid + */ + + /** + * @fn bool Surface::BlitScaledTo(SDL_Surface* dst_surface, const SDL_Rect* dst_rect, SDL_ScaleMode scale_mode, const SDL_Rect* src_rect = nullptr) const + * @brief Perform a scaled blit from this surface to destination + * + * Blits this surface to the destination with scaling. + * + * @param dst_surface The destination surface + * @param dst_rect Area on destination to blit to + * @param scale_mode Scaling algorithm to use + * @param src_rect Area of this surface to blit, or nullptr for entire surface + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_BlitSurfaceScaled + */ + + /** + * @fn bool Surface::BlitScaledFrom(SDL_Surface* src_surface, const SDL_Rect* src_rect, SDL_ScaleMode scale_mode, const SDL_Rect* dst_rect = nullptr) const + * @brief Perform a scaled blit from source surface to this surface + * + * @param src_surface The source surface + * @param src_rect Area of source to blit + * @param scale_mode Scaling algorithm to use + * @param dst_rect Area on this surface to blit to, or nullptr for entire surface + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_BlitSurfaceScaled + */ + + /** + * @fn bool Surface::BlitTiledTo(SDL_Surface* dst_surface, const SDL_Rect* dst_rect = nullptr, const SDL_Rect* src_rect = nullptr) const + * @brief Perform a tiled blit from this surface to destination + * + * Tiles this surface repeatedly to fill the destination rectangle. + * + * @param dst_surface The destination surface + * @param dst_rect Area on destination to fill with tiles, or nullptr for entire surface + * @param src_rect Area of this surface to tile, or nullptr for entire surface + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_BlitSurfaceTiled + */ + + /** + * @fn bool Surface::BlitTiledFrom(SDL_Surface* src_surface, const SDL_Rect* src_rect = nullptr, const SDL_Rect* dst_rect = nullptr) const + * @brief Perform a tiled blit from source surface to this surface + * + * @param src_surface The source surface + * @param src_rect Area of source to tile, or nullptr for entire surface + * @param dst_rect Area on this surface to fill, or nullptr for entire surface + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_BlitSurfaceTiled + */ + + /** + * @fn bool Surface::BlitTiledWithScaleTo(SDL_Surface* dst_surface, const SDL_Rect* dst_rect, float scale, SDL_ScaleMode scale_mode, const SDL_Rect* src_rect = nullptr) const + * @brief Perform a tiled blit with scaling from this surface to destination + * + * @param dst_surface The destination surface + * @param dst_rect Area on destination to fill + * @param scale Scale factor to apply to tiles + * @param scale_mode Scaling algorithm to use + * @param src_rect Area of this surface to tile, or nullptr for entire surface + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_BlitSurfaceTiledWithScale + */ + + /** + * @fn bool Surface::BlitTiledWithScaleFrom(SDL_Surface* src_surface, const SDL_Rect* src_rect, float scale, SDL_ScaleMode scale_mode, const SDL_Rect* dst_rect = nullptr) const + * @brief Perform a tiled blit with scaling from source surface to this surface + * + * @param src_surface The source surface + * @param src_rect Area of source to tile + * @param scale Scale factor to apply to tiles + * @param scale_mode Scaling algorithm to use + * @param dst_rect Area on this surface to fill, or nullptr for entire surface + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_BlitSurfaceTiledWithScale + */ + + /** + * @fn bool Surface::BlitUncheckedTo(SDL_Surface* dst_surface, const SDL_Rect* dst_rect = nullptr, const SDL_Rect* src_rect = nullptr) const + * @brief Perform a fast blit without clipping or bounds checking + * + * Faster blit when you're certain the rectangles don't need clipping. + * + * @param dst_surface The destination surface + * @param dst_rect Area on destination to blit to, or nullptr for entire surface + * @param src_rect Area of this surface to blit, or nullptr for entire surface + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_BlitSurfaceUnchecked + */ + + /** + * @fn bool Surface::BlitUncheckedFrom(SDL_Surface* src_surface, const SDL_Rect* src_rect = nullptr, const SDL_Rect* dst_rect = nullptr) const + * @brief Perform a fast blit from source to this surface without clipping + * + * @param src_surface The source surface + * @param src_rect Area of source to blit, or nullptr for entire surface + * @param dst_rect Area on this surface to blit to, or nullptr for entire surface + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_BlitSurfaceUnchecked + */ + + /** + * @fn bool Surface::BlitUncheckedScaledTo(SDL_Surface* dst_surface, const SDL_Rect* dst_rect, SDL_ScaleMode scale_mode, const SDL_Rect* src_rect = nullptr) const + * @brief Perform a scaled blit without clipping + * + * @param dst_surface The destination surface + * @param dst_rect Area on destination to blit to + * @param scale_mode Scaling algorithm to use + * @param src_rect Area of this surface to blit, or nullptr for entire surface + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_BlitSurfaceUncheckedScaled + */ + + /** + * @fn bool Surface::BlitUncheckedScaledFrom(SDL_Surface* src_surface, const SDL_Rect* src_rect, SDL_ScaleMode scale_mode, const SDL_Rect* dst_rect = nullptr) const + * @brief Perform a scaled blit from source to this surface without clipping + * + * @param src_surface The source surface + * @param src_rect Area of source to blit + * @param scale_mode Scaling algorithm to use + * @param dst_rect Area on this surface to blit to, or nullptr for entire surface + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_BlitSurfaceUncheckedScaled + */ + + // ============================================================================ + // Surface Palette and Colorkey + // ============================================================================ + + /** + * @fn Palette Surface::CreatePalette() const + * @brief Create a new palette from this surface + * + * Creates a palette based on the pixel format of this surface. + * + * @return Palette The created palette, or an invalid palette on failure + * @see https://wiki.libsdl.org/SDL3/SDL_CreateSurfacePalette + */ + +} diff --git a/src/video/Window.cpp b/src/video/Window.cpp new file mode 100644 index 0000000..f441306 --- /dev/null +++ b/src/video/Window.cpp @@ -0,0 +1,455 @@ +/** + * @file Window.cpp + * @brief Documentation for Window class - wraps SDL_Window with C++ shared_ptr lifetime management + * + * Windows are the primary interface for rendering and interacting with the user in SDL. This file contains + * the complete documentation for the Window wrapper class. The actual implementation is header-only in Window.hpp. + */ + +namespace hdk::sdl { + // Forward declarations + class Window; + class Renderer; + + // ============================================================================ + // Window class - Core documentation + // ============================================================================ + + /** + * @class Window + * @brief Wraps SDL_Window struct with C++ shared_ptr lifetime management + * + * Windows are the primary interface for rendering and interacting with the user in SDL. This wrapper uses + * shared_ptr for automatic lifetime management. Multiple copies of a Window instance will share ownership + * of the underlying SDL_Window; the window is destroyed when the last copy goes out of scope. + * + * @see https://wiki.libsdl.org/SDL3/SDL_Window + */ + + // ============================================================================ + // Factory Methods - Creating Windows + // ============================================================================ + + /** + * @fn static Window Window::Create(const char* title, int w, int h, SDL_WindowFlags flags) + * @brief Create a window with the specified properties + * + * Creates a new window with the given title, dimensions, and flags. The window will automatically + * be destroyed when all copies of the returned Window instance are destroyed. + * + * @param title The title of the window to be displayed in the title bar + * @param w The width of the window in pixels + * @param h The height of the window in pixels + * @param flags 0, or one or more SDL_WindowFlags OR'd together to control window behavior + * @return Window A new Window instance managing the created SDL_Window. If creation fails, returns an invalid window + * @see https://wiki.libsdl.org/SDL3/SDL_CreateWindow + */ + + /** + * @fn static Window Window::CreateWithProperties(SDL_PropertiesID propertiesID) + * @brief Create a window with properties + * + * Creates a window with specific properties set via a properties object. This allows fine-grained control + * over window creation parameters. + * + * @param propertiesID The ID of the properties set to use for the window + * @return Window The created window. If the creation fails, returns an invalid window + * @see https://wiki.libsdl.org/SDL3/SDL_CreateWindowWithProperties + */ + + /** + * @fn static Window Window::GetFromID(SDL_WindowID id) + * @brief Get window instance for the given window ID + * + * Retrieves a Window wrapper for an SDL_Window identified by its ID. If the window was created by other + * means (not through this wrapper), it will be wrapped without taking ownership. + * + * @param id The ID of the window to retrieve + * @return Window A Window instance wrapping the SDL_Window. If no window with the given ID exists, + * returns an invalid window (evaluates to false) + * @see https://wiki.libsdl.org/SDL3/SDL_GetWindowFromID + */ + + /** + * @fn static Window Window::GetGrabbed() + * @brief Get the currently grabbed window + * + * Returns a Window instance wrapping the window that has grabbed input focus, if any. + * + * @return Window A Window instance wrapping the currently grabbed SDL_Window. If no window is currently + * grabbed, returns an invalid window + * @see https://wiki.libsdl.org/SDL3/SDL_GetGrabbedWindow + */ + + // ============================================================================ + // Window Properties and Queries + // ============================================================================ + + /** + * @fn bool Window::GetAspectRatio(float* min_aspect_ratio, float* max_aspect_ratio) const + * @brief Get the aspect ratio of the window + * + * @param min_aspect_ratio Pointer to float filled with minimum aspect ratio + * @param max_aspect_ratio Pointer to float filled with maximum aspect ratio + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_GetWindowAspectRatio + */ + + /** + * @fn bool Window::GetBordersSize(int* top, int* left, int* bottom, int* right) const + * @brief Get the size of the window borders + * + * Retrieves the width of the borders around the window, which varies by platform and window decoration style. + * + * @param top Pointer to int filled with top border size + * @param left Pointer to int filled with left border size + * @param bottom Pointer to int filled with bottom border size + * @param right Pointer to int filled with right border size + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_GetWindowBordersSize + */ + + /** + * @fn float Window::GetDisplayScale() const + * @brief Get the display scale of the window + * + * Returns the scale factor of the display on which the window is located. This is important for + * high-DPI displays where the scale factor may be greater than 1.0. + * + * @return float The display scale of the window. If the window is invalid, returns 0.0f + * @see https://wiki.libsdl.org/SDL3/SDL_GetWindowDisplayScale + */ + + /** + * @fn SDL_WindowFlags Window::GetFlags() const + * @brief Get the flags of the window + * + * Returns the flags that were used when creating the window, indicating window state and properties. + * + * @return SDL_WindowFlags The flags of the window. If the window is invalid, returns 0 + * @see https://wiki.libsdl.org/SDL3/SDL_GetWindowFlags + */ + + /** + * @fn const SDL_DisplayMode* Window::GetFullscreenMode() const + * @brief Get the fullscreen mode of the window + * + * Returns the display mode being used for fullscreen rendering, if the window is in fullscreen mode. + * + * @return const SDL_DisplayMode* Pointer to display mode structure. If the window is not in fullscreen + * mode or is invalid, returns nullptr + * @see https://wiki.libsdl.org/SDL3/SDL_GetWindowFullscreenMode + */ + + /** + * @fn SDL_WindowID Window::GetID() const + * @brief Get the unique ID of the window + * + * @return SDL_WindowID The ID of the window. If the window is invalid, returns 0 + * @see https://wiki.libsdl.org/SDL3/SDL_GetWindowID + */ + + // ============================================================================ + // Keyboard and Mouse Grab Control + // ============================================================================ + + /** + * @fn bool Window::GetKeyboardGrab() const + * @brief Get the keyboard grab state of the window + * + * Checks whether this window has exclusive access to keyboard input. + * + * @return bool True if the window has grabbed the keyboard, false otherwise + * @see https://wiki.libsdl.org/SDL3/SDL_GetWindowKeyboardGrab + */ + + /** + * @fn bool Window::SetKeyboardGrab(bool grabbed) const + * @brief Set the keyboard grab state of the window + * + * Enables or disables exclusive keyboard input capture for this window. + * + * @param grabbed True to grab the keyboard, false to release it + * @return bool True if successful, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetWindowKeyboardGrab + */ + + /** + * @fn bool Window::GetMouseGrab() const + * @brief Get the mouse grab state of the window + * + * Checks whether this window has exclusive access to mouse input. + * + * @return bool True if the window has grabbed the mouse, false otherwise + * @see https://wiki.libsdl.org/SDL3/SDL_GetWindowMouseGrab + */ + + /** + * @fn bool Window::SetMouseGrab(bool grabbed) const + * @brief Set the mouse grab state of the window + * + * Enables or disables exclusive mouse input capture for this window. + * + * @param grabbed True to grab the mouse, false to release it + * @return bool True if successful, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetWindowMouseGrab + */ + + /** + * @fn const SDL_Rect* Window::GetMouseRect() const + * @brief Get the mouse rectangle of the window + * + * Returns the area within the window that constrains mouse movement, if any. + * + * @return const SDL_Rect* Pointer to rect structure. If the window is invalid or no rect is set, returns nullptr + * @see https://wiki.libsdl.org/SDL3/SDL_GetWindowMouseRect + */ + + /** + * @fn bool Window::SetMouseRect(const SDL_Rect* rect) const + * @brief Set the mouse rectangle of the window + * + * Constrains mouse movement to a specific rectangular area within the window. + * + * @param rect Pointer to SDL_Rect defining the constraint area. Pass nullptr to remove constraints + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetWindowMouseRect + */ + + // ============================================================================ + // Window Size Control + // ============================================================================ + + /** + * @fn bool Window::GetMaximumSize(int* w, int* h) const + * @brief Get the maximum size of the window + * + * @param w Pointer to int filled with maximum width in pixels + * @param h Pointer to int filled with maximum height in pixels + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_GetWindowMaximumSize + */ + + /** + * @fn bool Window::SetMaximumSize(int w, int h) const + * @brief Set the maximum size of the window + * + * @param w Maximum width of the window in pixels + * @param h Maximum height of the window in pixels + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetWindowMaximumSize + */ + + /** + * @fn bool Window::GetMinimumSize(int* w, int* h) const + * @brief Get the minimum size of the window + * + * @param w Pointer to int filled with minimum width in pixels + * @param h Pointer to int filled with minimum height in pixels + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_GetWindowMinimumSize + */ + + /** + * @fn bool Window::SetMinimumSize(int w, int h) const + * @brief Set the minimum size of the window + * + * @param w Minimum width of the window in pixels + * @param h Minimum height of the window in pixels + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetWindowMinimumSize + */ + + /** + * @fn bool Window::SetSize(int w, int h) const + * @brief Set the size of the window + * + * @param w Width of the window in pixels + * @param h Height of the window in pixels + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetWindowSize + */ + + /** + * @fn bool Window::GetSize(int* w, int* h) const + * @brief Get the current size of the window + * + * @param w Pointer to int filled with width in pixels + * @param h Pointer to int filled with height in pixels + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_GetWindowSize + */ + + /** + * @fn bool Window::GetSafeArea(SDL_Rect* rect) const + * @brief Get the safe area of the window + * + * Returns the region of the window that is safe to display content in, accounting for notches, rounded corners, + * and other display features that may obscure content. + * + * @param rect Pointer to SDL_Rect to be filled with the safe area. Set to {0, 0, 0, 0} if invalid + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_GetWindowSafeArea + */ + + // ============================================================================ + // Window Appearance + // ============================================================================ + + /** + * @fn float Window::GetOpacity() const + * @brief Get the opacity of the window + * + * Returns the transparency level of the window, where 0.0 is fully transparent and 1.0 is fully opaque. + * + * @return float The opacity of the window. If the window is invalid, returns 0.0f + * @see https://wiki.libsdl.org/SDL3/SDL_GetWindowOpacity + */ + + /** + * @fn bool Window::SetOpacity(float opacity) const + * @brief Set the opacity of the window + * + * Sets the transparency level of the window. + * + * @param opacity Opacity value from 0.0 (fully transparent) to 1.0 (fully opaque) + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetWindowOpacity + */ + + /** + * @fn bool Window::GetTitle() const + * @brief Get the title of the window + * + * @return const char* The title of the window, or nullptr if invalid + * @see https://wiki.libsdl.org/SDL3/SDL_GetWindowTitle + */ + + /** + * @fn bool Window::SetTitle(const char* title) const + * @brief Set the title of the window + * + * @param title The new title string to display in the window's title bar + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetWindowTitle + */ + + // ============================================================================ + // Window Position + // ============================================================================ + + /** + * @fn bool Window::GetPosition(int* x, int* y) const + * @brief Get the position of the window + * + * @param x Pointer to int filled with x coordinate + * @param y Pointer to int filled with y coordinate + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_GetWindowPosition + */ + + /** + * @fn bool Window::SetPosition(int x, int y) const + * @brief Set the position of the window + * + * @param x The x coordinate of the window's top-left corner + * @param y The y coordinate of the window's top-left corner + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetWindowPosition + */ + + // ============================================================================ + // Window State Control + // ============================================================================ + + /** + * @fn void Window::Destroy() const + * @brief Destroy the window + * + * Destroys the window and frees associated resources. Note: This is typically called automatically + * when the last copy of the Window instance is destroyed due to shared_ptr lifetime management. + * + * @see https://wiki.libsdl.org/SDL3/SDL_DestroyWindow + */ + + /** + * @fn bool Window::Hide() const + * @brief Hide the window + * + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_HideWindow + */ + + /** + * @fn bool Window::Show() const + * @brief Show the window + * + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_ShowWindow + */ + + /** + * @fn bool Window::Maximize() const + * @brief Maximize the window + * + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_MaximizeWindow + */ + + /** + * @fn bool Window::Minimize() const + * @brief Minimize the window + * + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_MinimizeWindow + */ + + /** + * @fn bool Window::Restore() const + * @brief Restore the window to normal state + * + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_RestoreWindow + */ + + /** + * @fn bool Window::Raise() const + * @brief Raise the window above other windows + * + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_RaiseWindow + */ + + /** + * @fn bool Window::SetFullscreen(bool fullscreen) const + * @brief Set the fullscreen state of the window + * + * @param fullscreen True to enable fullscreen, false to disable + * @return bool True on success, false on failure + * @see https://wiki.libsdl.org/SDL3/SDL_SetWindowFullscreen + */ + + // ============================================================================ + // Associated Objects + // ============================================================================ + + /** + * @fn Renderer Window::GetRenderer() const + * @brief Get the renderer associated with this window + * + * Returns a Renderer instance for the renderer that was created for this window. The returned renderer + * is a shared_ptr copy if we created it, or a non-owning view if it was created elsewhere. + * + * @return Renderer The associated renderer, or an invalid renderer if none exists + * @see https://wiki.libsdl.org/SDL3/SDL_GetRenderer + */ + + /** + * @fn Properties Window::GetProperties() const + * @brief Get the properties associated with this window + * + * @return Properties The properties object for this window + * @see https://wiki.libsdl.org/SDL3/SDL_GetWindowProperties + */ + +}