SDL_BlitSurface() and SDL_BlitSurfaceScaled() now have a const dstrect parameter

This was originally to avoid duplicating clipping work in Maelstrom on a 486 computer. This has been confusing for users and computers are a little faster these days, so we'll make it work the way people expect.

docs/README-migration.md

@@ -1717,6 +1717,8 @@ But if you're migrating your code which uses masks, you probably have a format i
 0x0000F800 0x000007E0 0x0000001F 0x00000000 => SDL_PIXELFORMAT_RGB565
 ```
 
+SDL_BlitSurface() and SDL_BlitSurfaceScaled() now have a const `dstrect` parameter and do not fill it in with the final destination rectangle.
+
 SDL_BlitSurfaceScaled() and SDL_BlitSurfaceUncheckedScaled() now take a scale paramater.
 
 SDL_SoftStretch() now takes a scale paramater.

include/SDL3/SDL_surface.h

@@ -958,9 +958,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL
  *                copied, or NULL to copy the entire surface.
  * \param dst the SDL_Surface structure that is the blit target.
  * \param dstrect the SDL_Rect structure representing the x and y position in
- *                the destination surface. On input the width and height are
+ *                the destination surface, or NULL for (0,0). The width and height are ignored, and are copied from `srcrect`. If you want a specific width and height, you should use SDL_BlitSurfaceScaled().
- *                ignored (taken from srcrect), and on output this is filled
- *                in with the actual rectangle used after clipping.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -972,7 +970,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL
  *
  * \sa SDL_BlitSurfaceScaled
  */
-extern SDL_DECLSPEC int SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, SDL_Rect *dstrect);
+extern SDL_DECLSPEC int SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect);
 
 /**
  * Perform low-level surface blitting only.
@@ -985,7 +983,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect
  *                copied, may not be NULL.
  * \param dst the SDL_Surface structure that is the blit target.
  * \param dstrect the SDL_Rect structure representing the target rectangle in
- *                the destination surface.
+ *                the destination surface, may not be NULL.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1030,8 +1028,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src, const SDL_Rect
  *                copied, or NULL to copy the entire surface.
  * \param dst the SDL_Surface structure that is the blit target.
  * \param dstrect the SDL_Rect structure representing the target rectangle in
- *                the destination surface, filled with the actual rectangle
+ *                the destination surface, or NULL to fill the entire destination surface.
- *                used after clipping.
  * \param scaleMode the SDL_ScaleMode to be used.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
@@ -1044,7 +1041,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src, const SDL_Rect
  *
  * \sa SDL_BlitSurface
  */
-extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, SDL_Rect *dstrect, SDL_ScaleMode scaleMode);
+extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode);
 
 /**
  * Perform low-level surface scaled blitting only.

src/dynapi/SDL_dynapi_procs.h

@@ -68,8 +68,8 @@ SDL_DYNAPI_PROC(SDL_JoystickID,SDL_AttachVirtualJoystick,(const SDL_VirtualJoyst
 SDL_DYNAPI_PROC(SDL_bool,SDL_AudioDevicePaused,(SDL_AudioDeviceID a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_BindAudioStream,(SDL_AudioDeviceID a, SDL_AudioStream *b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_BindAudioStreams,(SDL_AudioDeviceID a, SDL_AudioStream **b, int c),(a,b,c),return)
-SDL_DYNAPI_PROC(int,SDL_BlitSurface,(SDL_Surface *a, const SDL_Rect *b, SDL_Surface *c, SDL_Rect *d),(a,b,c,d),return)
+SDL_DYNAPI_PROC(int,SDL_BlitSurface,(SDL_Surface *a, const SDL_Rect *b, SDL_Surface *c, const SDL_Rect *d),(a,b,c,d),return)
-SDL_DYNAPI_PROC(int,SDL_BlitSurfaceScaled,(SDL_Surface *a, const SDL_Rect *b, SDL_Surface *c, SDL_Rect *d, SDL_ScaleMode e),(a,b,c,d,e),return)
+SDL_DYNAPI_PROC(int,SDL_BlitSurfaceScaled,(SDL_Surface *a, const SDL_Rect *b, SDL_Surface *c, const SDL_Rect *d, SDL_ScaleMode e),(a,b,c,d,e),return)
 SDL_DYNAPI_PROC(int,SDL_BlitSurfaceTiled,(SDL_Surface *a, const SDL_Rect *b, SDL_Surface *c, const SDL_Rect *d),(a,b,c,d),return)
 SDL_DYNAPI_PROC(int,SDL_BlitSurfaceTiledWithScale,(SDL_Surface *a, const SDL_Rect *b, float c, SDL_ScaleMode d, SDL_Surface *e, const SDL_Rect *f),(a,b,c,d,e,f),return)
 SDL_DYNAPI_PROC(int,SDL_BlitSurfaceUnchecked,(SDL_Surface *a, const SDL_Rect *b, SDL_Surface *c, const SDL_Rect *d),(a,b,c,d),return)

src/video/SDL_surface.c

@@ -874,7 +874,7 @@ int SDL_BlitSurfaceUnchecked(SDL_Surface *src, const SDL_Rect *srcrect,
 }
 
 int SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect,
-                  SDL_Surface *dst, SDL_Rect *dstrect)
+                  SDL_Surface *dst, const SDL_Rect *dstrect)
 {
     SDL_Rect r_src, r_dst;
 
@@ -905,7 +905,7 @@ int SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect,
     if (srcrect) {
         SDL_Rect tmp;
         if (SDL_GetRectIntersection(srcrect, &r_src, &tmp) == SDL_FALSE) {
-            goto end;
+            return 0;
         }
 
         /* Shift dstrect, if srcrect origin has changed */
@@ -924,7 +924,7 @@ int SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect,
     {
         SDL_Rect tmp;
         if (SDL_GetRectIntersection(&r_dst, &dst->internal->clip_rect, &tmp) == SDL_FALSE) {
-            goto end;
+            return 0;
         }
 
         /* Shift srcrect, if dstrect has changed */
@@ -937,28 +937,22 @@ int SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect,
         r_dst = tmp;
     }
 
+    if (r_dst.w <= 0 || r_dst.h <= 0) {
+        /* No-op. */
+        return 0;
+    }
+
     /* Switch back to a fast blit if we were previously stretching */
     if (src->internal->map.info.flags & SDL_COPY_NEAREST) {
         src->internal->map.info.flags &= ~SDL_COPY_NEAREST;
         SDL_InvalidateMap(&src->internal->map);
     }
 
-    if (r_dst.w > 0 && r_dst.h > 0) {
-        if (dstrect) { /* update output parameter */
-            *dstrect = r_dst;
-        }
     return SDL_BlitSurfaceUnchecked(src, &r_src, dst, &r_dst);
 }
 
-end:
-    if (dstrect) { /* update output parameter */
-        dstrect->w = dstrect->h = 0;
-    }
-    return 0;
-}
-
 int SDL_BlitSurfaceScaled(SDL_Surface *src, const SDL_Rect *srcrect,
-                          SDL_Surface *dst, SDL_Rect *dstrect,
+                          SDL_Surface *dst, const SDL_Rect *dstrect,
                           SDL_ScaleMode scaleMode)
 {
     SDL_Rect *clip_rect;
@@ -1106,10 +1100,6 @@ int SDL_BlitSurfaceScaled(SDL_Surface *src, const SDL_Rect *srcrect,
     /* Clip again */
     SDL_GetRectIntersection(clip_rect, &final_dst, &final_dst);
 
-    if (dstrect) {
-        *dstrect = final_dst;
-    }
-
     if (final_dst.w == 0 || final_dst.h == 0 ||
         final_src.w <= 0 || final_src.h <= 0) {
         /* No-op. */