[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

Re: Surface batch methods... Re: [pygame] API draft for vector type


On Apr 28, 2009, at 11:09 PM, René Dudfield wrote:

[..]


fill_multi might look like this:

Surface.fill_multi(color, rects, special_flags=0)
Basically the same as the fill() except the first two arguments accept buffer objects that are arrays of colors and rects respectively. I think it would be best if color accepted both a single color value or an array of RGBA values. I think supporting only RGBA (as 4-byte words) is good enough and the alpha would just be ignored if the surface did not support it. Though this would preclude indexed color surfaces. I'm open to opinion on 
this.
If color is an array, it would need to be the same length as rects to keep 
things simple. Otherwise it would raise an exception (ValueError?).

blit_multi would be:

Surface.blit_multi(source, dests, area=None, special_flags=0)
source is a single surface, dests is an buffer array of x, y coordinate ints, or maybe a RectArray, see below. Area is a single rect, for now, but I could imagine supporting an array of rects for advanced use (sprite- sheet, 
etc).
Seems like we would want a RectArray object to allow creation and some manipulation and passing of rectangles en-masse from python, though maybe 
that's overkill for a first rev.
I'm going to check out 1.9 now and see how it looks. I remember looking at doing something similar in pygame from the lepton side and deciding it was not too practical from an outside library. But, given these apis it would be easy. I suspect the fill_multi() implementation will be more complex, we'll 
see.

-Casey




Sounds pretty good.

A common use case for blit_multi would be when you are blitting a
whole group of sprites to the screen.  But you don't necessarily have
to complete each use case to start with... as long as the interface
raises exceptions when people try, and mention it in the docs.
I think it would be relatively easy to let source be a sequence of surfaces whose length must equal dests. OTOH, I'm not exactly sure if this is more or less convenient then just batching your sprites by surface and calling blit_multi for each batch. OTOOH, it would be very useful for mass blitting many animated sprites, a feature I just added to the OpenGL Lepton renders that would be very cool to also be able to do efficiently in pygame. So, I think it would be worth it. 


One issue might be...
Surface.fill_multi(color, rects, special_flags=0)

With color it can be a single int, or (0,0,0) or (0,0,0,0).   So I
think the sequences would have to be len(rects) == len(color)

Except if you have 3-4 colors + rects...   ([1,2,3], [r1,r2,r3])
then the color argument has an ambiguity of either 3 colors, or 1
color.

So perhaps explicit length of arguments?  Or a separate color and
colors argument?
I was thinking this would be determined by if the color value passed supported the buffer protocol, but that may be too magical and ambiguous. I think the one color for all rects use-case is worth supporting for convenience. perhaps changing the signature to all keywords would suffice:
Surface.fill_multi(color=None, rect_array=None, color_array=None, special_flags=0)
The crummy part being that rect_array is not really optional and one of color or color_array must be specified. This would of course be enforced by the api, but is a bit unintuitive. Then again calling it with positional args would work more or less as expected and it would only get slightly more verbose when you used a color_array.
We would basically have the same problem with the blit_multi, if it accepted both a single source surface and a sequence. So it would be good to make them consistent.
Also, I was assuming that color_array (aka colors) and rect_array (aka rects) would only accept array buffers and not arbitrary sequences of Color, Rect or tuple, but you seem to be implying support for the latter. Is that right? 

-Casey