Clip rectangle bounds and pagination of large texture atlases in SDL2

Direct Answer

Inclusive top-left, exclusive bottom-right coordinates map through the logical-to-output transform. When SDL_RenderSetLogicalSize uses a non-integer scale factor, the GPU rasterizes clip edges at sub-pixel positions. Each backend (Direct3D, OpenGL, Metal, Vulkan) applies its own top-left fill convention, so a clip rectangle that ends at logical coordinate x=100 with 1.5× scaling may include or exclude the physical pixel at 150 depending on the driver.

Chaining clip rectangles for atlas pagination works, but adjacent pages share a seam. Because the bottom/right edge is exclusive, a page ending at y=256 and the next starting at y=256 will drop a pixel row under fractional scaling. Add a 1-pixel guard band (overlap pages by 1 pixel) or force integer scaling with SDL_RenderSetIntegerScale(SDL_TRUE).

Performance impact is negligible on desktop GPUs; on low-end/embedded GPUs (Raspberry Pi VC4, older mobile), frequent clip changes can flush the tile buffer. Batch all draw calls that share the same clip region before switching.

Confirmed Behavior

• SDL_RenderSetClipRect coordinates are always in the current render target's coordinate system. Switching render targets resets the clip to the target's full bounds.
• SDL_RenderSetClipRect(NULL) disables clipping but does not restore a previous rectangle. Nested clipping requires a manual stack.
• No API exists to query the active clip rectangle. Maintain a shadow copy in application state to avoid redundant calls and to restore previous clips.
• Texture coordinate precision matters at page boundaries. Use SDL_RenderCopyF with float destination rectangles to avoid UV snapping errors.

Practical Steps for Artifact-Free Pagination

1. Decide on a scaling strategy:
   • Integer-only: Call SDL_RenderSetIntegerScale(renderer, SDL_TRUE) and set logical size to an integer divisor of the window size. Clip rectangles then align to the pixel grid exactly.
   • Fractional with guard band: Define each atlas page's clip rect with a 1-pixel overlap on the bottom and right edges (e.g., page 0: y=0..257, page 1: y=256..513). Draw pages in order; the overlap hides the exclusive-edge drop.
2. Track clip state in a small struct:

   typedef struct { SDL_Rect rect; bool active; } ClipState;

   Push/pop this stack instead of calling SDL directly for nested clips.
3. Batch draws per clip region. Set the clip once, submit all sprites for that page, then change to the next clip.
4. Use SDL_RenderCopyF for the source atlas region so texture coordinates remain precise at page boundaries.

Verification Checklist

• Render a known pattern (alternating colored lines) across page seams at your target scale factor. Capture a screenshot and count pixel rows at each boundary.
• Profile clip-state-change overhead on the target hardware: wrap batched vs. per-sprite clip changes with SDL_GetPerformanceCounter and compare frame times.
• Confirm integer scaling alignment by enabling SDL_HINT_RENDER_LOGICAL_SIZE_MODE=letterbox and SDL_RenderSetIntegerScale(SDL_TRUE); verify clip rects snap to the pixel grid.

One Missing Diagnostic

What is the target hardware class (desktop GPU, Raspberry Pi, mobile SoC, etc.) and the typical logical-to-window scale factor you expect? This determines whether integer scaling is feasible or whether you must design for fractional guard bands.