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

[René Dudfield <renesd@xxxxxxxxx>]

On Wed, Apr 29, 2009 at 2:35 PM, Casey Duncan <casey@xxxxxxxxxxx> wrote:
> On Apr 28, 2009, at 8:41 PM, René Dudfield wrote:
>
>> On Wed, Apr 29, 2009 at 2:29 AM, Casey Duncan <casey@xxxxxxxxxxx> wrote:
>>>
>>> Surface.fill_multi and Surface.blit_multi would be awesome for particle
>>> effects, in fact I could take good advantage of them in Lepton right now
>>> to
>>> make the pygame renderers mucho-faster.
>>>
>>> Would that be something that would be considered in pgreloaded (or even
>>> pygame 1.9)? If so I would be interested in helping to implement them as
>>> I
>>> would be an early adopter ;^)
>>>
>>> -Casey
>>>
>>
>> Definitely!  That would be cool.
>>
>> For pygame 1.9 it'd need to be ready within 4 weeks, with tests and
>> docs.  For 1.9.1 there's at least 4-5 months to go.
>>
>>
>> Would _multi methods work with different multiple arguments?  eg
>> multiple surfaces, multiple dst rects, multiple source rects?
>> Or you could just do one method for each multiple... or detect the
>> case based on the input arguments.
>>
>> Probably best to just do your use case... (which is multiple src
>> rects?)... then raise NotImplementedError for other combinations.
>
> 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.


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?