Ambiguous recomendation for SDL_LockSurface

[mikrosk]

Yes, I know that I'm like 10 years late :) but I have found out an interesting problem while porting an older game (still using SDL 1.2). The game explicitly asks for SDL_SWSURFACE in SDL_SetVideoMode. And since its wish is granted, its author didn't need to worry about surface locking: https://github.com/libsdl-org/SDL-1.2/blob/2a0b7429ac1624e45b155e3f27822595e9ef686c/include/SDL_video.h#L572-L574

Therefore the game doesn't lock surfaces neither checks SDL_MUSTLOCK. Now, this all works nice if the returned surface is the same dimension as requested. However what if isn't?

Then there's a big problem: SDL_UpdateRects tries to do the right thing and take the offset into consideration: https://github.com/libsdl-org/SDL-1.2/blob/2a0b7429ac1624e45b155e3f27822595e9ef686c/src/video/SDL_video.c#L1096-L1106

However the game author doesn't care / know anything about offsets, he just accesses pixels and rightfully so as documentation explicitly discourages him to use MUSTLOCK / SDL_LockSurface. Outcome is clear, the game fills first 200 lines of the software surface while SDL_UpdateRects offers pixels to backends from an offset, leading to a shifted display.

So my question is ... if we were in 2010, what would have been your recommendation as fix?

• documentation update, i.e. encourage developers to always call SDL_MUSTLOCK and tell the author to suck it up and fix his code?
• when requesting software surfaces, always return the requested dimensions and do the offsetting in the backend?
  • this would imply that SDL_LockSurface and SDL_UpdateRects wouldn't need to worry about offsets for software surfaces in general
• use the internal SDL_ShadowSurface if dimensions do not match ? (this looks like the cleanest solution to me as it is very similar to the situation when we request a software surface and get a hardware one however currently we take dimensions from SDL_VideoSurface which is the one with "bad" dimensions)
• ?

Of course, I'm at the liberty to choose any approach as both the game and SDL are open source but still, I'd appreciate some input and reasoning behind the current state.