***DISCUSSION*** pygame-ce 3.0 API changes

[oddbookworm]

This is a tracker and discussion forum for API changes that we want to make when we are working on 3.x.x now that SDL3 is nearing prerelease (and thus release in the not-so-distant future). Want a piece of API gone or modified? Or maybe new API? Suggest it!

[oddbookworm]

Old scrap is deprecated and new scrap only supports text. SDL3 supports a range of MIME types. IMO we should wrap the SDL3 clipboard API to replace scrap completely with fancy new code that isn't as bad as old scrap, and is more reliable than I remember old scrap being

[bilhox]

With pygame 3.0, I believe dropping the support of queuing a pygame.MOUSEBUTTONDOWN when the mouse wheel is rolled would be good. It's almost not used / it should not be used, because we have pygame.MOUSEWHEEL event now. I believe according to oddbookworm it was a feature in SDL1, because no pygame.MOUSEWHEEL event.

[Starbuck5]

Things off the top of my head:

Lots of deprecated could stuff could get removed.
We need to get weird of that weird font thing where the default font's size is shrunk 66% in some cases
Sysfont should be changed to be "font weight" aware, so it can give normal fonts instead of the first thing it sees that isn't bold or italic.
Mouse and time apis should return floats.
We should get rid of "SurfaceType" and other similar things.

[robertpfeiffer]

We should really think long and hard about locking and maybe deprecate a bunch of manual locking/unlocking in favour of enforcing with-statements.

[itzpr3d4t0r]

I think we should also drop returning rects/ rects lists in functions like blit/blits since it was a thing only as an optimization for display.update(), but as @MyreMylar found out, it's no longer relevant and isn't applicable in most if not all cases anymore.

[itzpr3d4t0r]

Possibly we could also make all alphablit algorithms no longer behave as SDL1 (which to be fair it's kinda weird). This should be investigated further but i suspect it could allow us to further optimize them. This could slightly change visual results but not by a huge margin, or at least not in common usecases.

[robertpfeiffer]

Consider a "quirks mode" or "pygame 1.9 compatibility flag" to support old textbooks.

[robertpfeiffer]

We could consider deprecating the whole sprite system and write a new one.

[snowfruit]

Rename scale() to help indicate if it use scalar(s) or pixels.

pygame.transform.scale() -> pygame.transform.resize_to() # Pixels
pygame.transform.scale_by() -> pygame.transform.scale_by() # Scalar(s)

[LondonClass]

How about allowing multiple windows created within one process? Or compatible with other interface packages like Tkinter?

[robertpfeiffer]

How about allowing multiple windows created within one process?

this won't have to wait for SDL 3.0.

Or compatible with other interface packages like Tkinter?

This is unfortunately not in our hands, but it depends on implementation details of SDL, CPython, and Tk

[LondonClass]

Thanks for your reply.

This is unfortunately not in our hands, but it depends on implementation details of SDL, CPython, and Tk.

It seems that pygame can be used together with PyQt5 with some adjustments. There are some cases of using both.

[gresm]

1. Better metrics calculation for fonts - make them exactly how the text is rendered (some discussion happened here: wraplength for pygame.freetype.Font? #2587 ).
2. Basic 3d API - shaders, etc. (requires another issue, as it is a larger task).
3. Make async alternatives for some functions (like pygame.time.Clock.tick(), pygame.*.load()...).
4. Generally unify API/name conversions and remove duplicating modules/classes/functions.

[feiyuhuahuo]

Thanks for your reply.

This is unfortunately not in our hands, but it depends on implementation details of SDL, CPython, and Tk.

It seems that pygame can be used together with PyQt5 with some adjustments. There are some cases of using both.

PyQt5 seems to have some problem on commerical use, maybe PySide6 is better. We can develop some default button, menu APIs with PySide6.

[robertpfeiffer]

Far out ideas:

• allow to globally turn off returning rects for draw operations
• expand clip rects and also allow clip masks
• all draw operations for Sprite groups require a camera-view rect
• adopt tline3D from picotron
• accept numpy arrays in draw operations (automatically broadcasts, draws multiple lines/circles/polygons)

[HappyGoFishing]

will pygame-ce be switching to SDL3 when it releases? is this confirmed?

[oddbookworm]

will pygame-ce be switching to SDL3 when it releases? is this confirmed?

That's the plan! Probably two release cycles for a while until the SDL3 stuff becomes stable, then the 2.x releases will stop eventually. SDL3 adoption isn't going to be a quick process though

[oddbookworm]

Fix line drawing so that the ends are actually right angles?

[oddbookworm]

Fix pygame.math.Vector2.angle_to so that it doesn't have that super weird "doesn't cross negative x-axis" behavior?

[JiffyRob]

Looking at pygame-geometry floats are used by default for most shapes, so maybe for consistency's sake we should make pygame.Rect use floats as FRect does and have a different class name for what our current Rect class does - maybe pygame.IRect or something similar.

[oddbookworm]

Rework font API to be cleaner/more cohesive?

[damusss]

Adding this here, credits to MyreMylar, we could remove the num_buttons argument in pygame.mouse.get_pressed

Edit starbuck: Link to this proposal: #2836 (comment)

[Starbuck5]

We could get rid of our hand rolled TGA saving support for pygame.image.save, since TGA isn't a common format these days.

[Starbuck5]

I've been looking through mixer a lot over the last couple days, we could stand to reevaluate a lot of defaults there. Like it defaults to only 8 playable sounds at once. Also the audio device setting defaults are weird.

Another thing is that mixer.init()'s ALLOWED_CHANGES thing is weird. If a user explicitly asks for frequency=xyz, it's unintuitive they also need to pass another parameter flagging that as unallowed change.

[scribblecrumb]

With SDL3 making large changes to it's audio system, it would be nice to see the pygame audio system updated to utilize the changes. Specifically the ability to have multiple music streams playing at once through pygame.mixer.music

[Starbuck5]

With SDL3 making large changes to it's audio system, it would be nice to see the pygame audio system updated to utilize the changes. Specifically the ability to have multiple music streams playing at once through pygame.mixer.music

That would be a nice improvement to utilize (although it would be challenging from an API perspective). But they haven't added that to SDL3_mixer, so there's nothing new to utilize with regards to multiple music streams.

[damusss]

If SDL3 will be used by pygame 3, then in pygame 3 there should be the pygme.mixer.music.get_length() function, using the new SDL3 function Mix_MusicDuration. Just like pygame.mixer.Sound.get_length but (educated guess) you don't need to load the whole sound in memory (usually big in the case of music!) for a simple information.