[Pysdl-devel] Rectangle Class Plan

[Pete S. <pe...@sh...>]

ok, you're thinking.. a "rectangle" class? how basic is that?
Ha! well, here is what I'm gonna be writing starting tomorrow.
You might as well get your advice and good ideas in now while
the gettin's good.

i wrote up a dizzying document to organize my thoughts and
make it clear to you guys what's coming. i plan to fully release
this and get it embedded into pysdl once it's ready.

here it comes. probably not best to include the whole thing
in replies to the list :]

-----------------------------------------------------------------

 sdl.Rect class proposal

Purpose: Now that I've gotten a good deal of pysdl developing
 under my belt. I've noticed my strong need for a helpful
 rectangle class. I was going to code it up in python,
 (which is still a possibility). The idea to do it in
 C struck me as a benefit, mainly because of optimizations.
 I'm going to start coding it up soon, but thought I'd
 iron out all my ideas, as well as present it for peer
 review

Features: The most important feature will be for the class
 to deal back and forth with lists and tuples seamlessly.
 The other benefit will be that data is stored in the
 SDL_Rect structure. so passing back and forth with
 the SDL calls will require no conversions. Finally,
 built in calls for collision detection and rectangle
 merging will run much quicker in C than in python.
 Also can make blitting more like C SDL_Blit, where
 the blit() call will adjust the size of the destination
 rect to the clipping area. (a feature we don't have now)

Cons: The only other option is to write the class in python.
 Writing the class in python makes it easy to inherit from
 and makes the code more accessible to other developers.

Finally: Well, in the long run, I feel i can take better advantage
 of things and provide a more feature-full rectangle class
 if it is done in C. (and more speed to boot) This is the
 plan i'll be starting soon. I'm still open to outside wisdom
 and advice, so get it in now.


The Class: Here's a list of methods and interfaces I'm planning
 for. Here's where I'm hoping for the most peer-review :]


Rect(x, y, w, h) -> RectInstance
Rect((x, y), (w, h)) -> RectInstance
Rect((x, y, w, h)) -> RectInstance
Rect(RectInstance) -> RectInstance
 Creating a new rectangle instance has a variety of
 methods. This makes it most flexible in taking any
 type of storage schemes

rect.top, rect.bottom, rect.left, rect.right -> Int
rect.width, rect.height -> Int
rect.topleft, rect.topright -> (Int, Int)
rect.bottomleft, rect.bottomright -> (Int, Int)
rect.center, rect.size -> (Int, Int)
 the rectangle will contain a set of "virtual members"
 which can be retreived and assigned to. this is one
 of the features I really look forward too. assigning
 one of these fields will move that field to the given
 position (except for center, which will move the whole
 rect, and size which will 'inflate' the whole rect)

<slicing, assignment, indexing, comparison>
 the rectangle will be able to act and behave like a
 standard list of 4 numeric elements. so you'll be able
 to slice, index, and abuse it as if it were a standard
 list object. (no append, insert, delete, etc) this will
 allow you to pass a Rect where a function is expecting
 a list or tuple of dimensions (fill_rect for instance). 
 indexing/slicing the rectangle will return results like
 it was a list of [x, y, w, h]

__nonzero__ -> boolean
isempty() -> boolean
 returns true if the rectangle size is (0, 0)
 this will be the same result if the rectangle
 is checked for nonzero ("if rect1 and not rect2:")
 

union(RectInstance) -> new RectInstance
 returns a new rectangle that surrounds the current
 and given rectangle

intersect(RectInstance) -> new RectInstance
 returns a new rectangle of the overlapping area between
 the current and given rectangle. returns an empty rect
 if no overlap

cleanup(RectInstance) -> list of RectInstances
 will return a list of all the rectangles needed to
 fill the area of the two rectangles with no overlapping
 parts (will always be at least 1 rect, usually 2, max of 3)

normalize() -> none
 if the dimensions of the rectangle are negative, this will
 swap things around, so the width and height are positive.
 note that none of the pysdl or rectangle functions will
 return a rectangle with negative size, although if passed
 a negative sized rectangle the results are undefined.
 i've never 'accidentally' created a negative sized rect,
 but if you start doin some whacky math and aren't sure,
 this makes an easy way to guarantee things are ok.

collidepoint((x, y)) -> boolean
 returns true if the given position is inclusively inside
 the rectangle

colliderect(RectInstance) -> boolean
 returns true if the given rectangle overlaps this
 rectangle. remember, you will be able to pass any
 form of rectangle constructor, so you could easily
 compare it to a list or tuple of rectangle values

collidelist([RectInstance, ...]) -> index int (-1 if nothing)
 will return the index of the first rectangle that
 intersects the current rectangle. having the rectangle
 check against a list is better than looping over
 a list of rectangles in a slower python loop.
 (still trying to decide if i should allow for an
 optional start/end range, i'm thinking so)

collidelistall([RectInstance, ...] -> [index, index, ...]
 returns a list of all the indexes for the rectangles
 the intersect with the current rectangle.
 (same thing here with the start/end range)


well, thats it (or is it?) at first thought a rectangle class
may sound a bit trivial. but i've used good ones in the past
(in C, not python) and they can make life amazingly simple

i'm at the point where i'm really wanting one now, so i
figured i'd throw this all out there before coding it up
in my closet.