API proposal: publicizing Window

[Starbuck5]

I'd like to turn _sdl2.video.Window into a public API in 2.4.0

Firstly, where should it live? I see two contenders.

• pygame.display.Window
• pygame.window.Window (like pygame.surface.Surface, primarily advertised as pygame.Window)

Yunline has successfully convinced me it should live at pygame.window.Window. If you disagree, this is the issue to speak out on.

Steps to making this thing public:

• Make the class public at its final address
• Extricate Window docs from _sdl2.video docs and publicize them in its final namespace
• Keep _sdl2.video.Window / _sdl2.Window as an alias for old code
• Make sure tests are good
• Make sure nothing will bite us with it in SDL3. (Like fullscreen vs fullscreen desktop is going away in SDL3, so we probably shouldn't expose that...)
• Window class example that shows off cool new functionality while only using software rendering
• Can we make private or remove things that are iffy?
  • Sharing a surface with pygame.display can be suspect
  • Every SDL display flag is exposed, but not all of them will work. We don't support OPENGL on these for example. And what would HIGHDPI actually do? (also will change in SDL3?)
• Polish up documentation

[MyreMylar]

I agree with pygame.window.Window. Keep window in it's own submodule as it is a new and slightly less confusing paradigm that will likely become the dominant way to create windows for desktop pygame usages going forward.

We could probably make good use of 'undocumented' code for dubious flag features that are currently in SDL2 but may or may not be in SDL3, but if it is straight up not working at all yet then let's pop up a NotImplementedError or something similar.

There is already a Window Example, but I agree it should be revamped once the code has stabilised to it's final location.

Like fullscreen vs fullscreen desktop is going away in SDL3

In what sense? I see this in the SDL3 docs: https://wiki.libsdl.org/SDL3/SDL_SetWindowFullscreenMode which implies you can still set a 'native fullscreen' or a 'desktop fullscreen' mode for a window.

I'm not sure there is a good reason for a programmer to interop between windows created by display.set_mode() and windows created by window.Window(). I'd be in favour of warning or erroring if we detect this happening and telling people to stick to one lane or the other, especially if it will reduce bugs.

[Starbuck5]

In what sense? I see this in the SDL3 docs: https://wiki.libsdl.org/SDL3/SDL_SetWindowFullscreenMode which implies you can still set a 'native fullscreen' or a 'desktop fullscreen' mode for a window.

Oh, I didn't know about that. What I was referring to is that the flag SDL_WINDOW_FULLSCREEN_DESKTOP for window creation has been removed.

I'm not sure there is a good reason for a programmer to interop between windows created by display.set_mode() and windows created by window.Window(). I'd be in favour of warning or erroring if we detect this happening and telling people to stick to one lane or the other, especially if it will reduce bugs.

I'm happy you bring this up, I think this will be a pain to support, it'll just keep getting bug reports in increasingly strange situations and contributors will keep adding more code to patch it up (I expect). It's redundant now that you can use get_surface() and flip() on Window. I think the way forward would be to undocument it and start it raising a deprecation warning.

[Starbuck5]

I've done an audit of all the SDL symbols used in Window.c for SDL3 compatibility, using the current state of SDL3's README-migration.

• Fullscreen vs fullscreen desktop. We should be fine, our current API can be emulated on top of SDL3. We won't expose the new fullscreen mode directly, but our fullscreen function will continue to take a "desktop" arg, which can set the fullscreen mode internally.
• SDL_SetWindowSize, SDL_SetWindowPosition, SDL_MinimizeWindow, SDL_MaximizeWindow, SDL_RestoreWindow, SDL_SetWindowFullscreen are all now asynchronous requests that are launched. There will also be a SDL_SyncWindow if you absolutely need things to go after each other. I think real code won't really notice this, we can update our docs to reflect this upon SDL3 migration-- and port SDL_SyncWindow then. I think this is fine as well.
• SDL_GetWindowDisplayIndex is being replaced with SDL_GetDisplayForWindow, which returns an SDL_DisplayID instead of a display index. I think we should make this safe for us by removing Window.display_index.
• SDL_WINDOW_TOOLTIP and SDL_WINDOW_POPUP_MENU are supported more broadly than just x11 in SDL3, but they need to go through a special window creation. Easy solution, remove these from our end for now.
• SDL3 notes that SDL2's SDL_WINDOW_SKIP_TASKBAR is replaced by SDL_WINDOW_UTILITY, but SDL_WINDOW_UTILITY exists in SDL2 as well. Rather than deal with this, I say we remove them both for now. They are x11 only, so of limited use to a majority of folks.

[Starbuck5]

We decided to push this out of 2.4.0 (#2627) in order to maintain a nice end of year release for 2.4.0. I'm happy that we've made significant progress on Window in the last two weeks and I hope we can gain enough confidence to call it a public API in the next release.