***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.

[Starbuck5]

We should make this not allowed: pygame.Surface((20,20)).get_at((((((3,4),),),),))

Almost every piece of the API that takes a sequence of two numbers allows unlimited-depth tuple-ception, because they have a centralized implementation in pg_TwoIntsFromObj.

[ooiiredq]

I need Apple Metal api support that SDL3 have. Thats all I need to make myself happy

[Starbuck5]

Why do you need metal? What do you plan on doing? What does this have to do with SDL3, are there new SDL functions you’re referring to?

[damusss]

Looks like SDL3 is going to add SDL_(Get|Set)WindowSurfaceVSync, so if pygame3 arrives with sdl3, pygame.Window.vsync should be added. The value allowed for the setter should be True (=1), False/0 (=disabled) or an integer that SDL supports (-1 for adaptive, 1, 2, 3, 4 etc for the frame delayed sync). Vsync should also be added to the window kwargs (pygame.Window(vsync=-1))

[damusss]

assuming pygame3=SDL3

as suggested by @ankith26, SDL_GetSystemTheme, can be adapted as pygame.system.get_theme.

Also, if this PR is merged and added to the new features, SDL_tray could be implemented as pygame.tray.

[bigwhoopgames]

I'd love to see the following supported:

1. Native Vector4 support for use cases in graphics programming / shaders / you get the idea.

2. Ability to define Rects as supporting vectors, possibly a "VRect" or an option when creating an (F)Rect(1, 1, 1, 1, use_vectors = True) so that it will return things like topleft etc. in vector form by default.

3. Quick way to get Vector xyz values as Ints.

4. Add a clamp option to the remap function so it auto clamps to the output range if the input it smaller or larger than the defined input range.

5. Removal of either Vector2/3 length or magnitude function, they are the same thing. (I prefer to keep length).

6. Expansion of the pygame.system module to include more functions for system information gathering such as: temperature (CPU/GPU), more detailed CPU and GPU information like make, model, bandwidth, cache sizes, etc., usage stats (CPU/GPU/RAM %), enabling / disabling support for file types or disk reads / writes, network interface stats and settings, get the system's current accessibility settings, ability to set some sort of automatic crash report creation hook.

7. Performance Improvements working with Sprite and Group (I ended up rewriting my own since the python logic in these uses try/except and supports any manner of arguments slowing them down).

8. Custom hook support for things like events, blits, changes to rects, etc. For instance you could register a function to be called automatically when certain events are posted / polled or when Sprites/Groups/Surfaces/Rects are altered in different ways. Could also make mapping inputs and keys to functions easier.

9. Timers that are as accurate as the system can handle.

10. Improvements to the audio playback to support effects like reverb, pitch, distortion per channel / sound / speaker.

11. Better multithreading / multiprocessing support.

12. Support for sets. Currently many functions are limited to using indexable data structures like lists. It would be nice to see native set support.

13. Expand geometry to support basic 3D shapes like 3d points, rays, spheres, cubes, and planes.

14. Basic animation module to define image/surface sequences, timing. Built in support for spritesheet loading. Allowing custom hooks on frame change, animation reset, keyframe to keyframe transformations, triggered sfx / events, etc.

15. Support for gif animations.

16. Video file loading and playback? basic filters, stretching / zoom.

Maybe some of this already exists in some way shape or form. Just some ideas I had some easier said than done but long story short we should have more hooks/insertion points for custom functions and calls as well as finer grained control over some lower level things like hardware, events, timers, loaded files, and the main pygame objects themselves like Rects and Vectors.

[bilhox]

Removal of either Vector2/3 length or magnitude function, they are the same thing. (I prefer to keep length).

I would prefer to keep it, but you gave me another idea, what about turning some functions of Vector into properties instead ?

Custom hook support for things like events, blits, changes to rects, etc. For instance you could register a function to be called automatically when certain events are posted / polled or when Sprites/Groups/Surfaces/Rects are altered in different ways. Could also make mapping inputs and keys to functions easier.

I'm not particularly a big fan of this proposal, Imo it should be to the user to implement this system with decorators.

Expand geometry to support basic 3D shapes like 3d points, rays, spheres, cubes, and planes.

This idea was mentionned last month, but currently we don't see its benefit as not many people play with 3D physics with pygame.

Basic animation module to define image/surface sequences, timing. Built in support for spritesheet loading. Allowing custom hooks on frame change, animation reset, keyframe to keyframe transformations, triggered sfx / events, etc.

The idea is amazing, it would be written in python directly for example.

Support for gif animations.

If I remember, there is someone who was working on loading gif files in pygame, I don't know the current work progress state.

Video file loading and playback? basic filters, stretching / zoom.

Good question.

[DonPolettone]

Hi again community !

• I would love to see the clock being fixed to more accurately display smooth movement without hickups, even with vsync set to False. On Windows, I prefer to use my own clock object for pygame since it's just more accurate than the built-in one. It uses time.perf_counter() to calculate when the next tick is due. Works like a breeze and the code is very short and simple:

import time
timestamp = time.perf_counter

class Clock:
    """Clock(fps=60) -> Game Clock object.

    method tick():      returns None after [self.dt] seconds have passed since the last call to tick().
    property wait_time: returns nr of milliseconds remaining until the next tick is due.
    method warmup():    has the clock tick() for 1 second to get consistent.
    """

    def __init__(self, fps=60):

        self.fps = fps
        self.dt = 1/fps
        self.sleep_time = 0.001
        self.max_sleep = 0.002
        t = timestamp()
        self.t = t
        self.next_tick = t + self.dt
        
        self.warmup()

    def tick(self):

        t = timestamp()
        while t < self.next_tick - self.max_sleep:
            time.sleep(self.sleep_time)
            t = timestamp()
        while t < self.next_tick:
            t = timestamp()
        self.next_tick += self.dt

    @property
    def wait_time(self):
        """returns how many milsecs remain until the next tick is due"""

        t = timestamp()
        return int((self.next_tick-t) * 1000)

    @property
    def time_passed(self):

        return timestamp() - self.t
    
    def warmup(self):

        duration = 1
        ticks = int(duration / self.dt)
        for n in range(ticks):
            self.tick()
        
        
clock = Clock()

• Also I would appreciate if the built-in Rect class was reworked to just support floats (instead of an additional FRect class), and additionally also rework pygame's drawing / blitting behaviour to support floats in order to make the Rect class compatible with all of those routines. I even think the code would be mostly backwards compatible if the Rect was changed to simply support floats.

[Starbuck5]

also rework pygame's drawing / blitting behaviour to support floats

This is already done, no?

[bigwhoopgames]

Forgot to mention I'd like to see pygame.time.set_timer() support multiple events of the same type. I forget what exactly I was trying to do but it was along the lines of using the same event type but with different dict values and I was extremely disappointed when I couldn't do it. For a moment my name was big sad.

[ankith26]

set_timer already supports posting Event objects with arbitrary dict attributes since pygame 2.0.1

Before that, yes, one could post events by id only.

[gresm]

If my PR gets ever merged, posting by event objects would be possible.

[damusss]

With the addition in SDL3 of TTF_DrawSurfaceText the API Font.render_to will have a purpose (will also support wraplength) and should be added.

Additionally, TTF_DrawRendererText will exist too meaning rendering text using the GPU won't be a bottleneck anymore and should be implemented as a Renderer method or Font method.

[damusss]

pygame 3 should also have the goal to

• unify pygame.draw and pygame.gfxdraw in favor of the first, deprecating/removing the other
• unify pygame.font, pygame.ftfont and pygame.freetype in favor of idk