add SDL_RenderTextureAffine

[expikr]

Closes #11279

This is the lowest-possible overhead API for planar texture copy, leaving the responsibility of calculating the points entirely to the users, allowing them to perform flips, stretches, shears, and rotations by calculating the basis vectors directly.

bool SDL_RenderTextureAffine(
    SDL_Renderer *renderer, 
    SDL_Texture *texture,
    const SDL_FRect *srcrect,
    const SDL_FPoint *origin,
    const SDL_FPoint *right,
    const SDL_FPoint *down
)

Type	Name	Description
SDL_Renderer *	renderer	the renderer which should copy parts of a texture.
SDL_Texture *	texture	the source texture.
const SDL_FRect *	srcrect	a pointer to the source rectangle, or NULL for the entire texture.
const SDL_FPoint *	origin	a pointer to a point indicating the location the top-left corner of srcrect should be mapped to, or NULL for the rendering target's origin.
const SDL_FPoint *	right	a pointer to a point indicating the location the top-right corner of srcrect should be mapped to, or NULL for the rendering target's top-right corner.
const SDL_FPoint *	down	a pointer to a point indicating the location the bottom-left corner of srcrect should be mapped to, or NULL for the rendering target's bottom-left corner.

[slouken]

Isn't this already achievable by using the RenderGeometry API?

[expikr]

This is adjacent to RenderTextureRotated in providing a streamlined interface for a highly constrained 2D-only usecase of a "simple texture copy", i.e.

• the texture source is always a axis-aligned rect
• you always have just four vertices
• the four vertices encode a 2D-only transformation on the source rect.

The raison d'etre of RenderTexture* APIs over RenderGeometry is to save you from repetitively specifying two mirrored triangles every time, given the common usecase of a "simple planar texture copy" rather than "arbitrary texture map to arbitrary shapes".

Compared to RenderTextureRotated, there is far more justification for including this one, having far less overhead with a much simpler interface while affording users to use their own basis vectors, e.g. the Box2D usecase supplying raw sin and cousins mentioned in the issue by @brainstream,

Another convenience feature is that NULL lets you reuse the dimension data, whereas with render geometry you would have to cumbersomely query the source and destination texture dimensions at every single call site.

You can draw a comparison with GDI like so:

• RenderTexture <--> BitBlt
• RenderTextureAffine <--> PlgBlt
• RenderTextureRotated <--> N/A, since it's achievable with PlgBlt and would just add unnecessary overhead with cumbersome arguments to specify flipping flags and center offsets etc