A QwSpriteField is a 2D graphic area upon which QwSpriteFieldGraphic objects are drawn. More...
#include <QwSpriteField.h>
Inherited by QwImageSpriteField.
The QwSpriteField and related classes (primarily QwSpriteFieldView and QwSprite, but also the other sprite abstractions) provide for multiple concurrent views of a 2D area containing moving graphical objects.
The QwSpriteField is also an indexing mechanism to the sprites it contains, providing 2D-area-based iteration and pixelwise collision detection.
Most of the methods in QwSpriteField are mainly used by the existing QwSpriteFieldGraphic classes, so will only be interesting if you intend to add a new type of QwSpriteFieldGraphic class. The methods of primary interest to the typical user are, in approximate order of decreasing usefulness:
This class provides for very high redraw efficiency. The properties of the mechanism are:
For example, it is quite feasible to have thousands of sprites used to create background scenery, and even animate pieces of that scenery occasionally. It is less feasible to have views where the entire scene is in continous motion, such as a continously scrolling background. You will be suprised how little animation is required to make a scene look `alive'.
The various sprite abstractions are:
QwVirtualSprite is the base class, from which is derived QwPositionedSprite, and from that is derived the QwSprite and QwRealSprite classes. This hierarchy provides you with multiple points at which to adapt to your requirements.
For the purpose of simplified description, we use the term sprite to refer to all these and derived classes.
Constructs a QwSpriteField with size w
wide and h
high, measured
in world coordinates (by default, world coordinates equal pixel coordinates).
The values maxclusters
and chunksize
effect the grouping heuristics
used when redrawing the QwSpriteField.
chunksize
is the size of square chunk used to break up the
QwSpriteField into area to be considered for redrawing. It
should be about the average size of graphics in the QwSpriteField.
Chunks too small increase the amount of calculation required
when drawing. Chunks too large increase the amount of drawing
that is needed.
maxclusters
is the number of rectangular groups of chunks that
will be separately drawn. If the QwSpriteField has a large number
of small, dispersed graphics, this should be about that number.
If the QwSpriteField is fully active, use a small number (say, 1).
The more clusters the slower the redraw, but also the bigger
clusters are the slower the redraw, so a balance is needed.
[virtual]
Destruct the field. Does nothing. Does not destroy QwSpriteFieldGraphic objects in the field.
This method adds a QwSpriteFieldGraphic to the list of those which need to be drawn if the given chunk is redrawn. Like SetChangedChunk and SetChangedChunkContaining, this method marks the chunk as `dirty'.
This method adds a QwSpriteFieldGraphic to the list of those which need to be drawn if the chunk containging the given pixel is redrawn. Like SetChangedChunk and SetChangedChunkContaining, this method marks the chunk as `dirty'.
This method adds an element to the list of QwSpriteFieldView objects viewing this QwSpriteField. The QwSpriteFieldView class calls this, so you should not need it.
Returns the QwSpriteFieldGraphic for a given point in a traversal.
See also: topAt(int,int) and lookIn(int,int,int,int).
Returns the chunk size of the sprite field as set at construction.
See also: QwSpriteField::QwSpriteField(...).
[virtual protected]
This method is called for all updates of the QwSpriteField. It renders any background graphics. The default is to simply clear it in the background colour of the QWidget.
Note that you should not put dynamic graphics on this background. If the graphics for a region change, call forceRedraw(const QRect&). Such a change should be done only very occasionally, as the redraw is inefficient. See the main notes for this class for a discussion of redraw efficiency.
See also: forceRedraw(QRect&).
Reimplemented in QwImageSpriteField.
[virtual protected]
This method is called for all updates of the QwSpriteField. It renders any foreground graphics. In general, it is more efficient to use additional QwSpriteFieldGraphic objects on the QwSpriteField rather than adding rendering at this point, as this method is always called, whereas QwSpriteFieldGraphic objects are only redrawn if they are in the area of change.
The same warnings regarding change apply to this method as given in drawBackground(QPainter&, const QRect&).
The default is to do nothing.
See also: forceRedraw(QRect&).
This should be called if you want to terminate a traversal without looking at all results. It frees memory used for the iteration.
Test to see if the QwSpriteFieldGraphic which at(Pix) indicates is in a traversal truly is in that traversal.
The QwSpriteFieldGraphic returned by at(Pix) is very approximate, but is found very efficiently. It should be used as a first-cut to ignore QwSpriteFieldGraphic objects you are not interested in.
[protected]
Forces the given area to be redrawn. This is useful when the foreground or background are changed.
Returns the height of the sprite field, in world coordinates.
Returns the sorted list of chunks at the given chunk. You should not need this method - it is used internally for collision detection.
See also: QwSpriteField::topAt(int,int).
QwSpriteFieldGraphic objects in an area can be traversed using:
for (Pix p=lookIn(x,y,w,h); p; next(p)) { QwSpriteFieldGraphic* the_graphic = at(p); ... }
This traverses at least all the graphics in the given rectangle at least once.
See also: topAt(int,int) and at(Pix).
Look to the next QwSpriteFieldGraphic in the traversal.
See also: topAt(int,int) and lookIn(int,int,int,int).
[static]
Returns the position precision for all coordinates in the QwSpriteField.
See also: setPositionPrecision(int).
During the traversal, the QwSpriteField must not be modified. If you wish to modify it, call this method on the Pix. This will allow the QwSpriteField to be subsequently modified without damaging the list of hits.
This method removes a QwSpriteFieldGraphic from the list of those which need to be drawn if the given chunk is redrawn. Like SetChangedChunk and SetChangedChunkContaining, this method marks the chunk as `dirty'.
This method removes a QwSpriteFieldGraphic from the list of those which need to be drawn if the chunk containging the given pixel is redrawn. Like SetChangedChunk and SetChangedChunkContaining, this method marks the chunk as `dirty'.
(internal) This method removes an element from the list of QwSpriteFieldView objects viewing this QwSpriteField. The QwSpriteFieldView class calls this, so you should not need it.
Change the size of the QwSpriteField. THIS IS CURRENTLY ONLY PARTIALLY IMPLEMENTED. DO NOT USE.
Tells if the points (x1,y1) and (x2,y2) are within the same chunk.
This method to informs the QwSpriteField that a given chunk is `dirty' and needs to be redrawn in the next Update.
(x,y) is a chunk location.
The sprite classes call this. Any new derived class of QwSpriteFieldGraphic must do so too. SetChangedChunkContaining can be used instead.
This method to informs the QwSpriteField that the chunk containging a given pixel is `dirty' and needs to be redrawn in the next Update.
(x,y) is a pixel location.
The sprite classes call this. Any new derived class of QwSpriteFieldGraphic must do so too. SetChangedChunk can be used instead.
[static]
The precision of QwSpriteFieldGraphic positions (and collisions - see sprite) can be set. A positive precision means world co-ordinates will be bit-shifted that many places higher. So, if the precision is 1, world co-ordinate (50,100) is the pixel co-ordinate (25,50); for precision 3, (50,100) is pixel (6,12). Negative positions are also allowed, and they imply that world-coordinates are lower resolution than pixel co-ordinates. IF ANYONE FINDS A USE FOR NEGATIVES, LET ME KNOW, OR I MIGHT REMOVE IT.
By default, pixel and world coordinates are the same.
QwSpriteFieldGraphic objects at a point can be traversed from top to bottom using:
for (Pix p=topAt(x,y); p; next(p)) { QwSpriteFieldGraphic* the_graphic = at(p); if (you_are_interested_in_collisions_with(the_graphic) && exact(p)) { // Collision! ... } }
This traverses at least all the graphics at pixel position (x,y).
The QwSpriteFieldGraphic returned by at(Pix) is very approximate, but is found very efficiently. It should be used as a first-cut to ignore QwSpriteFieldGraphic objects you are not interested in.
exact(Pix) should be used to further examine the QwSpriteFieldGraphic, as depicted above.
During the traversal, the QwSpriteField must not be modified unless protectFromChange(Pix) is first called on the iterator. This is for efficiency reasons (protecting the list of hits requires extra work).
Warning: Currently, the collision model is not quite correct at this level of abstraction, because it cannot check collision exactness beyond the rectangular level. This will change in futures versions. For now, you should perhaps use the QwVirtualSprite::neighbourhood(...) methods instead.
See also: QwSpriteFieldGraphic::rtti().
This method causes all QwSpriteFieldView objects currently viewing this QwSpriteField to be refreshed in all areas of the QwSpriteField which have changed since the last call to this method.
In a continuously animated QwSpriteField, this method should be called at a regular rate. The best way to accomplish this is to use the QTimer class of the Qt toolkit, or the startTimer method of QObject. It would not be useful to call this method excessively (eg. whenever a sprite is moved) as the efficiency of the system is derived from a clustering and bulk-update mechanism.
(internal) This method causes a specific area of a QwSpriteField to be completely redrawn in a given QwSpriteFieldView. This is called by QwSpriteFieldView to effect repaint events.
Returns the width of the sprite field, in world coordinates.
[static]
Convert a coordinate from world to pixel coordinates.
See also: setPositionPrecision(int).
[static]
Convert a coordinate from pixel to world coordinates.
See also: setPositionPrecision(int).
This file is part of a class set, copyright © 1995-96 Warwick Allison
It was generated from the following files: