eden-emu/SDL
15
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-05-23 13:09:11 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

render: allow render targets to use logical presentation.

Browse source 
Fixes https://github.com/libsdl-org/sdl2-compat/issues/279
This commit is contained in:
Ryan C. Gordon 2025-02-27 17:28:47 -05:00
parent 281f0fae1c
commit 35e8cf8ee6
3 changed files with 296 additions and 219 deletions
Download patch file Download diff file Expand all files Collapse all files

75
include/SDL3/SDL_render.h
View file

@ -490,6 +490,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Rende
* This returns the true output size in pixels, ignoring any render targets or
* logical size and presentation.
*
* For the output size of the current rendering target, with logical size
* adjustments, use SDL_GetCurrentRenderOutputSize() instead.
*
* \param renderer the rendering context.
* \param w a pointer filled in with the width in pixels.
* \param h a pointer filled in with the height in pixels.
@ -508,9 +511,10 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer,
* Get the current output size in pixels of a rendering context.
*
* If a rendering target is active, this will return the size of the rendering
* target in pixels, otherwise if a logical size is set, it will return the
* logical size, otherwise it will return the value of
* SDL_GetRenderOutputSize().
* target in pixels, otherwise return the value of SDL_GetRenderOutputSize().
*
* Rendering target or not, the output will be adjusted by the current
* logical presentation state, dictated by SDL_SetRenderLogicalPresentation().
*
* \param renderer the rendering context.
* \param w a pointer filled in with the current width.
@ -1318,6 +1322,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture *texture);
* To stop rendering to a texture and render to the window again, call this
* function with a NULL `texture`.
*
* Viewport, cliprect, scale, and logical presentation are unique to each
* render target. Get and set functions for these states apply to the current
* render target set by this function, and those states persist on each target
* when the current render target changes.
*
* \param renderer the rendering context.
* \param texture the targeted texture, which must be created with the
* `SDL_TEXTUREACCESS_TARGET` flag, or NULL to render to the
@ -1351,25 +1360,39 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL
extern SDL_DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer);
/**
* Set a device independent resolution and presentation mode for rendering.
* Set a device-independent resolution and presentation mode for rendering.
*
* This function sets the width and height of the logical rendering output.
* The renderer will act as if the window is always the requested dimensions,
* scaling to the actual window resolution as necessary.
* The renderer will act as if the current render target is always the
* requested dimensions, scaling to the actual resolution as necessary.
*
* This can be useful for games that expect a fixed size, but would like to
* scale the output to whatever is available, regardless of how a user resizes
* a window, or if the display is high DPI.
*
* Logical presentation can be used with both render target textures
* and the renderer's window; the state is unique to each render target, and
* this function sets the state for the current render target. It might be
* useful to draw to a texture that matches the window dimensions with logical
* presentation enabled, and then draw that texture across the entire window
* with logical presentation disabled. Be careful not to render both with
* logical presentation enabled, however, as this could produce
* double-letterboxing, etc.
*
* You can disable logical coordinates by setting the mode to
* SDL_LOGICAL_PRESENTATION_DISABLED, and in that case you get the full pixel
* resolution of the output window; it is safe to toggle logical presentation
* resolution of the render target; it is safe to toggle logical presentation
* during the rendering of a frame: perhaps most of the rendering is done to
* specific dimensions but to make fonts look sharp, the app turns off logical
* presentation while drawing text.
* presentation while drawing text, for example.
*
* Letterboxing will only happen if logical presentation is enabled during
* SDL_RenderPresent; be sure to reenable it first if you were using it.
* For the renderer's window, letterboxing is drawn into the framebuffer
* if logical presentation is enabled during SDL_RenderPresent; be sure to
* reenable it before presenting if you were toggling it, otherwise the
* letterbox areas might have artifacts from previous frames (or artifacts
* from external overlays, etc). Letterboxing is never drawn into texture
* render targets; be sure to call SDL_RenderClear() before drawing into
* the texture so the letterboxing areas are cleared, if appropriate.
*
* You can convert coordinates in an event into rendering coordinates using
* SDL_ConvertEventToRenderCoordinates().
@ -1397,6 +1420,9 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *
* This function gets the width and height of the logical rendering output, or
* the output size in pixels if a logical resolution is not enabled.
*
* Each render target has its own logical presentation state. This function
* gets the state for the current render target.
*
* \param renderer the rendering context.
* \param w an int to be filled with the width.
* \param h an int to be filled with the height.
@ -1420,6 +1446,9 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *
* presentation is disabled, it will fill the rectangle with the output size,
* in pixels.
*
* Each render target has its own logical presentation state. This function
* gets the rectangle for the current render target.
*
* \param renderer the rendering context.
* \param rect a pointer filled in with the final presentation rectangle, may
* be NULL.
@ -1536,6 +1565,9 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Rendere
*
* The area's width and height must be >= 0.
*
* Each render target has its own viewport. This function sets the viewport
* for the current render target.
*
* \param renderer the rendering context.
* \param rect the SDL_Rect structure representing the drawing area, or NULL
* to set the viewport to the entire target.
@ -1554,6 +1586,9 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, c
/**
* Get the drawing area for the current target.
*
* Each render target has its own viewport. This function gets the viewport
* for the current render target.
*
* \param renderer the rendering context.
* \param rect an SDL_Rect structure filled in with the current drawing area.
* \returns true on success or false on failure; call SDL_GetError() for more
@ -1575,6 +1610,9 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, S
* whether you should restore a specific rectangle or NULL. Note that the
* viewport is always reset when changing rendering targets.
*
* Each render target has its own viewport. This function checks the viewport
* for the current render target.
*
* \param renderer the rendering context.
* \returns true if the viewport was set to a specific rectangle, or false if
* it was set to NULL (the entire target).
@ -1613,6 +1651,9 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderSafeArea(SDL_Renderer *renderer, S
/**
* Set the clip rectangle for rendering on the specified target.
*
* Each render target has its own clip rectangle. This function
* sets the cliprect for the current render target.
*
* \param renderer the rendering context.
* \param rect an SDL_Rect structure representing the clip area, relative to
* the viewport, or NULL to disable clipping.
@ -1631,6 +1672,9 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, c
/**
* Get the clip rectangle for the current target.
*
* Each render target has its own clip rectangle. This function
* gets the cliprect for the current render target.
*
* \param renderer the rendering context.
* \param rect an SDL_Rect structure filled in with the current clipping area
* or an empty rectangle if clipping is disabled.
@ -1647,7 +1691,10 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, c
extern SDL_DECLSPEC bool SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, SDL_Rect *rect);
/**
* Get whether clipping is enabled on the given renderer.
* Get whether clipping is enabled on the given render target.
*
* Each render target has its own clip rectangle. This function
* checks the cliprect for the current render target.
*
* \param renderer the rendering context.
* \returns true if clipping is enabled or false if not; call SDL_GetError()
@ -1673,6 +1720,9 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *renderer);
* will be handled using the appropriate quality hints. For best results use
* integer scaling factors.
*
* Each render target has its own scale. This function sets the scale for the
* current render target.
*
* \param renderer the rendering context.
* \param scaleX the horizontal scaling factor.
* \param scaleY the vertical scaling factor.
@ -1690,6 +1740,9 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, floa
/**
* Get the drawing scale for the current target.
*
* Each render target has its own scale. This function gets the scale for the
* current render target.
*
* \param renderer the rendering context.
* \param scaleX a pointer filled in with the horizontal scaling factor.
* \param scaleY a pointer filled in with the vertical scaling factor.