[pygame] new additions

["Pete Shinners" <pete@visionart.com>]

i've added a couple of new features that could really
effect the way you use pygame. everything is backwards
compatible here, so no need to worry. let me go over what
is new.

Firstly. One scary thing about the SDL surfaces is that you
must be very careful about your Lock/Unlock calls. This has
made pygame development a little scary, since an improper
order/set of calls to Surface.lock() Surface.unlock() could
easily crash the program. (Parachute style)
I had finally started adding the ability for functions to
temporarily lock surfaces if they needed it, but that was
just piling on more special cases. anyways...

At this point i'm proud to announce that pygame's surface new
surface locking mechanism is really robust. It implements a
smart reference counting mechanism. This means that all/any
calls to Surface.lock(), Surface.unlock() are entirely 
optional. Pygame will no longer segfault if you use improper
surface locking. Pygame can manage it all for you.
(although, you may still eventually want to block of certain
functions inside their own lock()/unlock() calls for efficiency)
For example. In the surfarray module you can get Numeric arrays
that directly reference a surface's pixels. With the new locking,
the original surface will remain locked as long as any pixel
reference arrays are "alive". So there should be no way to cause
a segfault by sloppy lock handling. wooohooo

ok, most of you probably aren't that excited for smarter surface
locking. (i can't blame you), just realize this is a very good thing.

the other new feature is a new function;
"Surface.subsurface(rect) -> Surface"
this will return a new surface that shares the pixel data
with the original surface. Note that only the pixel data
is shared. so things like clipping, colorkeys, etc are
independent.

this actually has a lot more functionality than you might think.
the first thing it will help with are multiple sprite images on
a single surface. You can now easily tile the main surface into
a set of smaller ones representing different frames of animation.
i've found it much easier for my sprites to just hang onto a
single surface, instead of a surface and subrectangle.

another exciting use would be to break the display surface into
different sections. for example, my game has a small HUD on the
right edge of the screen. i could create a new surface as a
destination for this hud.
"hud_area = screen.subsurface((700, 0, 100, 600))"
now i can just draw my hud elements into this surface instead
of offsetting them in the main window.

What are the advantages of that then? well, for one i can then
set my main window clipping area to not overlap with the hud,
and not have to worry about managing that overlap.
i could also move the hud around the screen by only changing
the area that my HUD is referencing the main screen. so i could
move the HUD to the left side of the screen by simply changing
"hud_area = screen.subsurface((0, 0, 100, 600))"
and be done with it.

i've been thinking of other keen uses for this subsurface
referencing. it is mainly possible because of the new smart
surface locking. also, just so you know, the subsurfacing
will work also work on any surface, so HWSURFACE and RLEACCEL
should not be a problem.

anyways, this might be a little too technical for some folks
on the list. not to worry, since you could still do an entire
game and not bother with these details (although it will only
help). in fact the good news now is you don't even need to 
worry about the lock() and unlock() calls.

i've tested it pretty well, it's all in cvs now.



____________________________________
pygame mailing list
pygame-users@seul.org
http://pygame.seul.org