Add custom software cursor

- New AeonGUI::Cursor utility (include/aeongui/Cursor.hpp, core/Cursor.cpp):
  disabled by default, raster (RasterImage + hotspot) and SVG (URL +
  render size, hotspot at SVG origin) sources, premultiplied BGRA cache,
  save/restore backing-store composite that never dirties the document.
- Canvas gains GetMutablePixels() (Cairo + Skia) so external compositors
  can blit directly into the output buffer.
- DOM::Window owns a Cursor; mouse handlers do Restore -> update last
  position -> dispatch -> Composite, and Window::Draw discards the
  backing store before redrawing then re-blits.
- Replaced the legacy core/Cursor.cpp stub and dropped its Doxygen
  exclusion.
- Added tests/CursorTest.cpp (9 cases) covering default state, raster
  and SVG SetSource, byte-exact composite/restore round-trip, off-screen
  clipping with sentinels, error handling, and the no-document-dirty
  guarantee on cursor-only motion.

Author: Kwizatz

cmake/Doxyfile.in

@@ -689,7 +689,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = @CMAKE_SOURCE_DIR@/core/Cursor.cpp @CMAKE_SOURCE_DIR@/core/Image.cpp
+EXCLUDE                = @CMAKE_SOURCE_DIR@/core/Image.cpp
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded

core/CMakeLists.txt

@@ -16,6 +16,7 @@ set(AEONGUI_HEADERS
     ../include/aeongui/DrawType.hpp
     ../include/aeongui/Color.hpp
     ../include/aeongui/RasterImage.hpp
+    ../include/aeongui/Cursor.hpp
     ../include/aeongui/ResourceLoader.hpp
     ../include/aeongui/StyleSheet.hpp
     ../include/aeongui/CSSSelector.hpp
@@ -121,6 +122,7 @@ set(AEONGUI_SOURCES
     Color.cpp
     ResourceLoader.cpp
     RasterImage.cpp
+    Cursor.cpp
     StyleSheet.cpp
     Canvas.cpp
     TextLayout.cpp

core/CairoCanvas.cpp

@@ -67,6 +67,20 @@ namespace AeonGUI
         return cairo_image_surface_get_data ( mCairoSurface );
     }
 
+    uint8_t* CairoCanvas::GetMutablePixels()
+    {
+        if ( mCairoSurface )
+        {
+            cairo_surface_flush ( mCairoSurface );
+            uint8_t* data = cairo_image_surface_get_data ( mCairoSurface );
+            // Mark the surface dirty so Cairo re-uploads any cached image data
+            // backed by this buffer the next time it is drawn from.
+            cairo_surface_mark_dirty ( mCairoSurface );
+            return data;
+        }
+        return nullptr;
+    }
+
     size_t CairoCanvas::GetWidth() const
     {
         return mCairoSurface ? static_cast<size_t> ( cairo_image_surface_get_width ( mCairoSurface ) ) : 0;

core/CairoCanvas.hpp

@@ -47,6 +47,7 @@ namespace AeonGUI
         AEONGUI_DLL ~CairoCanvas() final;
         AEONGUI_DLL void ResizeViewport ( uint32_t aWidth, uint32_t aHeight ) final;
         AEONGUI_DLL const uint8_t* GetPixels() const final;
+        AEONGUI_DLL uint8_t* GetMutablePixels() final;
         AEONGUI_DLL size_t GetWidth() const final;
         AEONGUI_DLL size_t GetHeight() const final;
         AEONGUI_DLL size_t GetStride() const final;

core/Cursor.cpp

@@ -1,59 +1,277 @@
-/******************************************************************************
-Copyright 2013 Rodrigo Hernandez Cordoba
+/*
+Copyright (C) 2026 Rodrigo Jose Hernandez Cordoba
 
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
 
-       http://www.apache.org/licenses/LICENSE-2.0
+http://www.apache.org/licenses/LICENSE-2.0
 
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
-******************************************************************************/
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
 
-#include "Cursor.h"
+#include "aeongui/Cursor.hpp"
+
+#include <algorithm>
+#include <cstring>
+#include <stdexcept>
+
+#include "aeongui/Canvas.hpp"
+#include "aeongui/RasterImage.hpp"
+#include "aeongui/dom/Document.hpp"
 
 namespace AeonGUI
 {
-    Cursor::Cursor() :
-        cursor_image ( NULL ),
-        x ( 0 ),
-        y ( 0 ),
-        xoffset ( 0 ),
-        yoffset ( 0 )
+    Cursor::Cursor() = default;
+    Cursor::~Cursor() = default;
+
+    void Cursor::Clear()
     {
+        mPixels.clear();
+        mPixels.shrink_to_fit();
+        mBacking.clear();
+        mBacking.shrink_to_fit();
+        mWidth = 0;
+        mHeight = 0;
+        mHotspotX = 0;
+        mHotspotY = 0;
+        mSavedX = mSavedY = mSavedW = mSavedH = 0;
+        mHasBacking = false;
     }
-    Cursor::~Cursor()
+
+    void Cursor::SetEnabled ( bool aEnabled )
     {
+        if ( mEnabled == aEnabled )
+        {
+            return;
+        }
+        mEnabled = aEnabled;
+        // Drop any pending backing store: it is no longer meaningful and would
+        // otherwise be written back unexpectedly the next time the cursor is
+        // re-enabled.
+        mHasBacking = false;
     }
-    void Cursor::SetCursorImage ( Image* image )
+
+    void Cursor::DiscardBackingStore() noexcept
     {
-        cursor_image = image;
+        mHasBacking = false;
     }
-    Image* Cursor::GetCursorImage()
+
+    void Cursor::SetSource ( const RasterImage& aImage,
+                             int32_t aHotspotX, int32_t aHotspotY )
     {
-        return cursor_image;
+        if ( !aImage.IsLoaded() ||
+             aImage.GetPixelFormat() != RasterImage::PixelFormat::RGBA8 )
+        {
+            throw std::runtime_error ( "Cursor::SetSource: RasterImage is not a loaded RGBA8 image." );
+        }
+        const uint32_t w = aImage.GetWidth();
+        const uint32_t h = aImage.GetHeight();
+        const size_t srcStride = aImage.GetStride();
+        const uint8_t* src = aImage.GetPixels();
+        if ( w == 0 || h == 0 || src == nullptr )
+        {
+            throw std::runtime_error ( "Cursor::SetSource: empty RasterImage." );
+        }
+
+        mWidth = w;
+        mHeight = h;
+        mHotspotX = aHotspotX;
+        mHotspotY = aHotspotY;
+        mPixels.assign ( static_cast<size_t> ( w ) * h * 4u, 0 );
+        // Convert RGBA8 (straight alpha) -> BGRA8 (premultiplied).
+        for ( uint32_t y = 0; y < h; ++y )
+        {
+            const uint8_t* srcRow = src + y * srcStride;
+            uint8_t* dstRow = mPixels.data() + static_cast<size_t> ( y ) * w * 4u;
+            for ( uint32_t x = 0; x < w; ++x )
+            {
+                const uint8_t r = srcRow[x * 4u + 0u];
+                const uint8_t g = srcRow[x * 4u + 1u];
+                const uint8_t b = srcRow[x * 4u + 2u];
+                const uint8_t a = srcRow[x * 4u + 3u];
+                dstRow[x * 4u + 0u] = static_cast<uint8_t> ( ( static_cast<uint32_t> ( b ) * a + 127u ) / 255u );
+                dstRow[x * 4u + 1u] = static_cast<uint8_t> ( ( static_cast<uint32_t> ( g ) * a + 127u ) / 255u );
+                dstRow[x * 4u + 2u] = static_cast<uint8_t> ( ( static_cast<uint32_t> ( r ) * a + 127u ) / 255u );
+                dstRow[x * 4u + 3u] = a;
+            }
+        }
+        // Drop any stale backing store; its rect no longer matches.
+        mBacking.clear();
+        mBacking.shrink_to_fit();
+        mHasBacking = false;
     }
 
-    void Cursor::SetOffsets ( int32_t xoff, int32_t yoff )
+    void Cursor::SetSource ( const std::string& aSvgUrl,
+                             uint32_t aWidth, uint32_t aHeight )
     {
-        xoffset = xoff;
-        yoffset = yoff;
+        if ( aWidth == 0 || aHeight == 0 )
+        {
+            throw std::runtime_error ( "Cursor::SetSource: SVG render size must be > 0." );
+        }
+
+        // Render the SVG into a transient canvas, then snapshot its BGRA pixels.
+        std::unique_ptr<Canvas> canvas = Canvas::Create ( aWidth, aHeight );
+        canvas->Clear();
+        DOM::Document doc;
+        doc.Load ( aSvgUrl );
+        doc.Draw ( *canvas );
+
+        const uint8_t* pixels = canvas->GetPixels();
+        const size_t srcStride = canvas->GetStride();
+        if ( pixels == nullptr )
+        {
+            throw std::runtime_error ( "Cursor::SetSource: SVG render produced no pixels." );
+        }
+
+        mWidth = aWidth;
+        mHeight = aHeight;
+        // SVG hotspot is fixed at the SVG origin (0, 0) by design.
+        mHotspotX = 0;
+        mHotspotY = 0;
+        mPixels.assign ( static_cast<size_t> ( aWidth ) * aHeight * 4u, 0 );
+        // Canvas pixels are already premultiplied BGRA — copy row by row in
+        // case the canvas stride differs from a tightly packed buffer.
+        const size_t dstStride = static_cast<size_t> ( aWidth ) * 4u;
+        for ( uint32_t y = 0; y < aHeight; ++y )
+        {
+            std::memcpy ( mPixels.data() + y * dstStride,
+                          pixels + y * srcStride,
+                          dstStride );
+        }
+        mBacking.clear();
+        mBacking.shrink_to_fit();
+        mHasBacking = false;
     }
-    void Cursor::SetPosition ( int32_t xpos, int32_t ypos )
+
+    void Cursor::Composite ( uint8_t* aBuffer,
+                             size_t aBufferWidth,
+                             size_t aBufferHeight,
+                             size_t aBufferStride,
+                             int32_t aMouseX,
+                             int32_t aMouseY )
     {
-        x = xpos;
-        y = ypos;
+        if ( !mEnabled || !HasSource() || aBuffer == nullptr )
+        {
+            return;
+        }
+
+        // Top-left of the cursor image in buffer coordinates.
+        const int32_t cx = aMouseX - mHotspotX;
+        const int32_t cy = aMouseY - mHotspotY;
+
+        // Clip the cursor rect against the buffer.
+        const int32_t bw = static_cast<int32_t> ( aBufferWidth );
+        const int32_t bh = static_cast<int32_t> ( aBufferHeight );
+        const int32_t x0 = std::max ( cx, 0 );
+        const int32_t y0 = std::max ( cy, 0 );
+        const int32_t x1 = std::min ( cx + static_cast<int32_t> ( mWidth ),  bw );
+        const int32_t y1 = std::min ( cy + static_cast<int32_t> ( mHeight ), bh );
+        if ( x0 >= x1 || y0 >= y1 )
+        {
+            // Fully off-screen: no backing store, nothing to blit.
+            mHasBacking = false;
+            return;
+        }
+
+        const int32_t w = x1 - x0;
+        const int32_t h = y1 - y0;
+        // Offset into the cursor image where the visible region starts.
+        const int32_t sx = x0 - cx;
+        const int32_t sy = y0 - cy;
+
+        // Snapshot the destination pixels before we overwrite them.
+        const size_t backingStride = static_cast<size_t> ( w ) * 4u;
+        mBacking.assign ( backingStride * h, 0 );
+        for ( int32_t row = 0; row < h; ++row )
+        {
+            const uint8_t* dstRow = aBuffer + ( static_cast<size_t> ( y0 + row ) ) * aBufferStride
+                                    + static_cast<size_t> ( x0 ) * 4u;
+            std::memcpy ( mBacking.data() + static_cast<size_t> ( row ) * backingStride,
+                          dstRow, backingStride );
+        }
+        mSavedX = x0;
+        mSavedY = y0;
+        mSavedW = w;
+        mSavedH = h;
+        mHasBacking = true;
+
+        // Alpha-blend cursor (premultiplied src-over) into the buffer.
+        const size_t cursorStride = static_cast<size_t> ( mWidth ) * 4u;
+        for ( int32_t row = 0; row < h; ++row )
+        {
+            const uint8_t* srcRow = mPixels.data()
+                                    + static_cast<size_t> ( sy + row ) * cursorStride
+                                    + static_cast<size_t> ( sx ) * 4u;
+            uint8_t* dstRow = aBuffer + ( static_cast<size_t> ( y0 + row ) ) * aBufferStride
+                              + static_cast<size_t> ( x0 ) * 4u;
+            for ( int32_t col = 0; col < w; ++col )
+            {
+                const uint32_t sb = srcRow[col * 4u + 0u];
+                const uint32_t sg = srcRow[col * 4u + 1u];
+                const uint32_t sr = srcRow[col * 4u + 2u];
+                const uint32_t sa = srcRow[col * 4u + 3u];
+                if ( sa == 0u )
+                {
+                    continue;
+                }
+                if ( sa == 255u )
+                {
+                    dstRow[col * 4u + 0u] = static_cast<uint8_t> ( sb );
+                    dstRow[col * 4u + 1u] = static_cast<uint8_t> ( sg );
+                    dstRow[col * 4u + 2u] = static_cast<uint8_t> ( sr );
+                    dstRow[col * 4u + 3u] = 255u;
+                    continue;
+                }
+                const uint32_t inv = 255u - sa;
+                const uint32_t db = dstRow[col * 4u + 0u];
+                const uint32_t dg = dstRow[col * 4u + 1u];
+                const uint32_t dr = dstRow[col * 4u + 2u];
+                const uint32_t da = dstRow[col * 4u + 3u];
+                dstRow[col * 4u + 0u] = static_cast<uint8_t> ( sb + ( db * inv + 127u ) / 255u );
+                dstRow[col * 4u + 1u] = static_cast<uint8_t> ( sg + ( dg * inv + 127u ) / 255u );
+                dstRow[col * 4u + 2u] = static_cast<uint8_t> ( sr + ( dr * inv + 127u ) / 255u );
+                dstRow[col * 4u + 3u] = static_cast<uint8_t> ( sa + ( da * inv + 127u ) / 255u );
+            }
+        }
     }
 
-    void Cursor::Render ( Renderer* renderer )
+    void Cursor::Restore ( uint8_t* aBuffer,
+                           size_t aBufferWidth,
+                           size_t aBufferHeight,
+                           size_t aBufferStride )
     {
-        if ( cursor_image != NULL )
+        if ( !mEnabled || !HasSource() || !mHasBacking || aBuffer == nullptr )
+        {
+            return;
+        }
+        // Defensive: if the buffer shrank since the snapshot, clamp the
+        // restore region (do not write out of bounds).
+        const int32_t bw = static_cast<int32_t> ( aBufferWidth );
+        const int32_t bh = static_cast<int32_t> ( aBufferHeight );
+        const int32_t x0 = std::max ( mSavedX, 0 );
+        const int32_t y0 = std::max ( mSavedY, 0 );
+        const int32_t x1 = std::min ( mSavedX + mSavedW, bw );
+        const int32_t y1 = std::min ( mSavedY + mSavedH, bh );
+        if ( x0 < x1 && y0 < y1 )
         {
-            renderer->DrawImage ( cursor_image, x - xoffset, y - yoffset );
+            const size_t backingStride = static_cast<size_t> ( mSavedW ) * 4u;
+            const int32_t srcOffsetX = x0 - mSavedX;
+            const int32_t srcOffsetY = y0 - mSavedY;
+            const size_t copyBytes = static_cast<size_t> ( x1 - x0 ) * 4u;
+            for ( int32_t row = 0; row < ( y1 - y0 ); ++row )
+            {
+                std::memcpy ( aBuffer + ( static_cast<size_t> ( y0 + row ) ) * aBufferStride
+                              + static_cast<size_t> ( x0 ) * 4u,
+                              mBacking.data() + static_cast<size_t> ( srcOffsetY + row ) * backingStride
+                              + static_cast<size_t> ( srcOffsetX ) * 4u,
+                              copyBytes );
+            }
         }
+        mHasBacking = false;
     }
 }

core/SkiaCanvas.cpp

@@ -95,6 +95,16 @@ namespace AeonGUI
         return mPixelCache.data();
     }
 
+    uint8_t* SkiaCanvas::GetMutablePixels()
+    {
+        // Ensure the cache reflects the latest Skia surface contents, then
+        // return it for direct overwriting. The cache stays "clean" until
+        // the next canvas drawing operation marks it dirty again — at which
+        // point our writes are discarded (caller must re-blit if needed).
+        ( void ) GetPixels();
+        return mPixelCache.empty() ? nullptr : mPixelCache.data();
+    }
+
     size_t SkiaCanvas::GetWidth() const
     {
         return mWidth;

core/SkiaCanvas.hpp

@@ -46,6 +46,7 @@ namespace AeonGUI
         AEONGUI_DLL ~SkiaCanvas() final;
         AEONGUI_DLL void ResizeViewport ( uint32_t aWidth, uint32_t aHeight ) final;
         AEONGUI_DLL const uint8_t* GetPixels() const final;
+        AEONGUI_DLL uint8_t* GetMutablePixels() final;
         AEONGUI_DLL size_t GetWidth() const final;
         AEONGUI_DLL size_t GetHeight() const final;
         AEONGUI_DLL size_t GetStride() const final;