Disclosure: This draft was generated with AI and checked against the cited primary sources, with a separate AI editorial review. It was prepared for the FrameSprite team, which has a commercial interest in FrameSprite. Proposed examples are not executed tests unless explicitly identified as recorded fixture results.
SDL3 separates a texture's size query from its property queries. Use SDL_GetTextureSize with float output variables for dimensions, and use texture properties when you need format or access information. Do not cast an old integer output pointer into the new function. The size-query reference defines the signature.
Key Takeaways
- Update types and failure handling during migration.
- Keep source image size separate from displayed destination size.
- Validate grid arithmetic before converting dimensions into frame counts.
Replace the query contract, not just the name
An SDL2 helper may return width, height, format and access mode together. Replacing its function name while retaining the old arguments does not create an SDL3-compatible helper.
Split those responsibilities in the application. One routine can retrieve source dimensions; another can inspect the properties required by an upload or target-creation path. SDL_GetTextureProperties documents the latter information and its named properties.
Avoid storing the result in a vague size variable reused for source pixels, preview targets and screen rectangles. Those values may agree for a simple test image and diverge as soon as the character is scaled.
Query dimensions with the declared types
A minimal SDL3 query is:
/* SDL 3.2+ fragment; not compiled or run here. */
float texture_w = 0.0f;
float texture_h = 0.0f;
if (!SDL_GetTextureSize(texture, &texture_w, &texture_h)) {
SDL_Log("Texture size query failed: %s", SDL_GetError());
/* Stop this import path before using the dimensions. */
}
The early-stop policy matters. Do not continue calculating columns from zero-valued outputs after a failed query. In a complete function, return an error or keep the last valid asset contract.
A float output API does not imply that a PNG suddenly contains fractional source pixels. It changes the function's interface. When using a fixed-grid importer, validate that the values represent the integer pixel dimensions expected by that importer.
Validate the grid before slicing
For a hypothetical 256 by 128 image with 64 by 64 frames and no padding, the intended grid has four columns and two rows. If padding or outer margins exist, include them explicitly before testing divisibility.
Do not silently truncate a division when the result is not integral. A partially packed last row or mismatched frame size deserves an import diagnostic. The sprite-sheet creation guide covers that source contract.
| Value | Meaning |
|---|---|
| Texture width and height | Whole uploaded source image |
| Frame width and height | One intended sampling cell |
| Destination rectangle | Display size |
| Frame count | Valid cells selected by metadata |
For texture creation, SDL_CreateTexture still accepts integer dimensions. Keep that creation boundary distinct from the float query interface.
Acceptance on more than one sheet
Test a single-frame texture, a regular sheet and an intentionally invalid sheet whose dimensions do not match the declared grid. Confirm the invalid case reports an error instead of producing a shortened or shifted animation.
Check a padded sheet using the atlas gutter guide. Then change only the display destination and confirm the calculated source-frame count remains unchanged.
Record the migrated dimension and property queries in the delivery checklist. This is a source-based SDL 3.2+ migration recipe. No SDL program was compiled, no image was queried, and the numeric grid is a constructed example.
Keep integer conversion inside the importer
Once a grid importer has checked dimensions and divisibility, convert them into its documented integer representation in one place. Avoid several independent casts in loading, animation and export code, because each can conceal a different truncation assumption. Keep the original query result available in an error report alongside declared cell size and padding. That gives an artist a concrete mismatch to inspect instead of a vague wrong-frame message. A successful dimension query proves the query worked, not that every declared frame rectangle is valid.
Sources and editorial ownership
Primary references checked on October 20, 2026:
Editorial owner: FrameSprite Workflow Team. Editorial and verification policy. Report a documentation correction.
Top comments (0)