Add better mouse coordinate conversion functions

Update logical_size property to return None instead of (0, 0),
None is a more expected return value for this state.

Update samples to highlight the tile under the mouse

Author: HexDecimal

CHANGELOG.md

@@ -6,6 +6,15 @@ This project adheres to [Semantic Versioning](https://semver.org/) since version
 
 ## [Unreleased]
 
+### Added
+
+- Added methods: `Renderer.coordinates_from_window` and `Renderer.coordinates_to_window`
+- Added `tcod.event.convert_coordinates_from_window`.
+
+### Changed
+
+- `Renderer.logical_size` now returns `None` instead of `(0, 0)` when logical size is unset.
+
 ## [19.6.3] - 2026-01-12
 
 Fix missing deployment

examples/samples_tcod.py

@@ -1379,6 +1379,8 @@ def redraw_display() -> None:
     SAMPLES[cur_sample].on_draw()
     sample_console.blit(root_console, SAMPLE_SCREEN_X, SAMPLE_SCREEN_Y)
     draw_stats()
+    if 0 <= mouse_tile_xy[0] < root_console.width and 0 <= mouse_tile_xy[1] < root_console.height:
+        root_console.rgb[["fg", "bg"]].T[mouse_tile_xy] = (0, 0, 0), (255, 255, 255)  # Highlight mouse tile
     if context.sdl_renderer:
         # Clear the screen to ensure no garbage data outside of the logical area is displayed
         context.sdl_renderer.draw_color = (0, 0, 0, 255)
@@ -1410,25 +1412,20 @@ def handle_time() -> None:
     frame_length.append(frame_times[-1] - frame_times[-2])
 
 
+mouse_tile_xy = (-1, -1)
+"""Last known mouse tile position."""
+
+
 def handle_events() -> None:
+    global mouse_tile_xy
     for event in tcod.event.get():
-        if context.sdl_renderer:  # Manual handing of tile coordinates since context.present is skipped
-            assert context.sdl_window
-            tile_width = context.sdl_window.size[0] / root_console.width
-            tile_height = context.sdl_window.size[1] / root_console.height
-
-            if isinstance(event, (tcod.event.MouseState, tcod.event.MouseMotion)):
-                event.tile = tcod.event.Point(event.position.x // tile_width, event.position.y // tile_height)
-            if isinstance(event, tcod.event.MouseMotion):
-                prev_tile = (
-                    (event.position[0] - event.motion[0]) // tile_width,
-                    (event.position[1] - event.motion[1]) // tile_height,
-                )
-                event.tile_motion = tcod.event.Point(event.tile[0] - prev_tile[0], event.tile[1] - prev_tile[1])
-        else:
-            context.convert_event(event)
-
-        SAMPLES[cur_sample].on_event(event)
+        tile_event = tcod.event.convert_coordinates_from_window(event, context, root_console)
+        SAMPLES[cur_sample].on_event(tile_event)
+        match tile_event:
+            case tcod.event.MouseMotion(position=(x, y)):
+                mouse_tile_xy = int(x), int(y)
+            case tcod.event.WindowEvent(type="WindowLeave"):
+                mouse_tile_xy = -1, -1
 
 
 def draw_samples_menu() -> None:

tcod/event.py

@@ -87,13 +87,15 @@
 import sys
 import warnings
 from collections.abc import Callable, Iterator, Mapping
-from typing import TYPE_CHECKING, Any, Final, Generic, Literal, NamedTuple, TypeVar
+from typing import TYPE_CHECKING, Any, Final, Generic, Literal, NamedTuple, TypeVar, overload
 
 import numpy as np
 from typing_extensions import deprecated
 
+import tcod.context
 import tcod.event_constants
 import tcod.sdl.joystick
+import tcod.sdl.render
 import tcod.sdl.sys
 from tcod.cffi import ffi, lib
 from tcod.event_constants import *  # noqa: F403
@@ -103,6 +105,7 @@
     from numpy.typing import NDArray
 
 T = TypeVar("T")
+_EventType = TypeVar("_EventType", bound="Event")
 
 
 class _ConstantsWithPrefix(Mapping[int, str]):
@@ -1564,6 +1567,78 @@ def get_mouse_state() -> MouseState:
     return MouseState((xy[0], xy[1]), (int(tile[0]), int(tile[1])), buttons)
 
 
+@overload
+def convert_coordinates_from_window(
+    event: _EventType,
+    /,
+    context: tcod.context.Context | tcod.sdl.render.Renderer,
+    console: tcod.console.Console | tuple[int, int],
+    dest_rect: tuple[int, int, int, int] | None = None,
+) -> _EventType: ...
+@overload
+def convert_coordinates_from_window(
+    xy: tuple[float, float],
+    /,
+    context: tcod.context.Context | tcod.sdl.render.Renderer,
+    console: tcod.console.Console | tuple[int, int],
+    dest_rect: tuple[int, int, int, int] | None = None,
+) -> tuple[float, float]: ...
+def convert_coordinates_from_window(
+    event: _EventType | tuple[float, float],
+    /,
+    context: tcod.context.Context | tcod.sdl.render.Renderer,
+    console: tcod.console.Console | tuple[int, int],
+    dest_rect: tuple[int, int, int, int] | None = None,
+) -> _EventType | tuple[float, float]:
+    """Return an event or position with window mouse coordinates converted into console tile coordinates.
+
+    Args:
+        event: :any:`Event` to convert, or the `(x, y)` coordinates to convert.
+        context: Context or Renderer to fetch the SDL renderer from for reference with conversions.
+        console: A console used as a size reference.
+            Otherwise the `(columns, rows)` can be given directly as a tuple.
+        dest_rect: The consoles rendering destination as `(x, y, width, height)`.
+            If None is given then the whole rendering target is assumed.
+
+    .. versionadded:: Unreleased
+    """
+    if isinstance(context, tcod.context.Context):
+        maybe_renderer: Final = context.sdl_renderer
+        if maybe_renderer is None:
+            return event
+        context = maybe_renderer
+
+    if isinstance(console, tcod.console.Console):
+        console = console.width, console.height
+
+    if dest_rect is None:
+        dest_rect = (0, 0, *(context.logical_size or context.output_size))
+
+    x_scale: Final = console[0] / dest_rect[2]
+    y_scale: Final = console[1] / dest_rect[3]
+    x_offset: Final = dest_rect[0]
+    y_offset: Final = dest_rect[1]
+
+    if not isinstance(event, Event):
+        x, y = context.coordinates_from_window(event)
+        return (x - x_offset) * x_scale, (y - y_offset) * y_scale
+
+    if isinstance(event, MouseMotion):
+        previous_position = convert_coordinates_from_window(
+            ((event.position[0] - event.motion[0]), (event.position[1] - event.motion[1])), context, console, dest_rect
+        )
+        position = convert_coordinates_from_window(event.position, context, console, dest_rect)
+        event.motion = tcod.event.Point(position[0] - previous_position[0], position[1] - previous_position[1])
+        event._tile_motion = tcod.event.Point(
+            int(position[0]) - int(previous_position[0]), int(position[1]) - int(previous_position[1])
+        )
+    if isinstance(event, (MouseState, MouseMotion)):
+        event.position = event._tile = tcod.event.Point(
+            *convert_coordinates_from_window(event.position, context, console, dest_rect)
+        )
+    return event
+
+
 @ffi.def_extern()  # type: ignore[untyped-decorator]
 def _sdl_event_watcher(userdata: Any, sdl_event: Any) -> int:
     callback: Callable[[Event], None] = ffi.from_handle(userdata)

tcod/sdl/render.py

@@ -439,16 +439,16 @@ def draw_blend_mode(self, value: int) -> None:
 
     @property
     def output_size(self) -> tuple[int, int]:
-        """Get the (width, height) pixel resolution of the rendering context.
+        """Get the (width, height) pixel resolution of the current rendering context.
 
         .. seealso::
-            https://wiki.libsdl.org/SDL_GetRendererOutputSize
+            https://wiki.libsdl.org/SDL3/SDL_GetCurrentRenderOutputSize
 
         .. versionadded:: 13.5
         """
         out = ffi.new("int[2]")
         _check(lib.SDL_GetCurrentRenderOutputSize(self.p, out, out + 1))
-        return out[0], out[1]
+        return tuple(out)
 
     @property
     def clip_rect(self) -> tuple[int, int, int, int] | None:
@@ -481,10 +481,8 @@ def set_logical_presentation(self, resolution: tuple[int, int], mode: LogicalPre
         _check(lib.SDL_SetRenderLogicalPresentation(self.p, width, height, mode))
 
     @property
-    def logical_size(self) -> tuple[int, int]:
-        """Get current independent (width, height) resolution.
-
-        Might be (0, 0) if a resolution was never assigned.
+    def logical_size(self) -> tuple[int, int] | None:
+        """Get current independent (width, height) resolution, or None if logical size is unset.
 
         .. seealso::
             https://wiki.libsdl.org/SDL3/SDL_GetRenderLogicalPresentation
@@ -493,10 +491,14 @@ def logical_size(self) -> tuple[int, int]:
 
         .. versionchanged:: 19.0
             Setter is deprecated, use :any:`set_logical_presentation` instead.
+
+        .. versionchanged:: Unreleased
+            Return ``None`` instead of ``(0, 0)`` when logical size is disabled.
         """
         out = ffi.new("int[2]")
         lib.SDL_GetRenderLogicalPresentation(self.p, out, out + 1, ffi.NULL)
-        return out[0], out[1]
+        out_tuple = tuple(out)
+        return None if out_tuple == (0, 0) else out_tuple
 
     @logical_size.setter
     @deprecated("Use set_logical_presentation method to correctly setup logical size.")
@@ -509,7 +511,7 @@ def scale(self) -> tuple[float, float]:
         """Get or set an (x_scale, y_scale) multiplier for drawing.
 
         .. seealso::
-            https://wiki.libsdl.org/SDL_RenderSetScale
+            https://wiki.libsdl.org/SDL3/SDL_SetRenderScale
 
         .. versionadded:: 13.5
         """
@@ -526,7 +528,7 @@ def viewport(self) -> tuple[int, int, int, int] | None:
         """Get or set the drawing area for the current rendering target.
 
         .. seealso::
-            https://wiki.libsdl.org/SDL_RenderSetViewport
+            https://wiki.libsdl.org/SDL3/SDL_SetRenderViewport
 
         .. versionadded:: 13.5
         """
@@ -753,6 +755,32 @@ def geometry(
             )
         )
 
+    def coordinates_from_window(self, xy: tuple[float, float], /) -> tuple[float, float]:
+        """Return the renderer coordinates from the given windows coordinates.
+
+        .. seealso::
+            https://wiki.libsdl.org/SDL3/SDL_RenderCoordinatesFromWindow
+
+        .. versionadded:: Unreleased
+        """
+        x, y = xy
+        out_xy = ffi.new("float[2]")
+        _check(lib.SDL_RenderCoordinatesFromWindow(self.p, x, y, out_xy, out_xy + 1))
+        return tuple(out_xy)
+
+    def coordinates_to_window(self, xy: tuple[float, float], /) -> tuple[float, float]:
+        """Return the window coordinates from the given render coordinates.
+
+        .. seealso::
+            https://wiki.libsdl.org/SDL3/SDL_RenderCoordinatesToWindow
+
+        .. versionadded:: Unreleased
+        """
+        x, y = xy
+        out_xy = ffi.new("float[2]")
+        _check(lib.SDL_RenderCoordinatesToWindow(self.p, x, y, out_xy, out_xy + 1))
+        return tuple(out_xy)
+
 
 def new_renderer(
     window: tcod.sdl.video.Window,