Since two or three people have requested Circular Scrolling, I finally decided to spend some time working on routines that will enable this, even though I don't plan on using the routines myself (and therefore had little motivation to spend the time required to work on them). Circular scrolling allows you to scroll endlessly in any direction; when you scroll off one end of the world (such as the right end), you come back in the other end (such as the left end).
SpriteWorld's circular scrolling engine has the following limitations:
• Your virtual world's width and height must be a multiple of your offscreen area's width and height. For instance, if your offscreen area's width is 600, your virtual world can have a width of 600, 1200, 1800, etc. If your offscreen area's height is 500, your virtual world's height can be 500, 1000, 1500, etc.
• All of the standard scrolling limitations apply. So the dimensions of your offscreen areas must still be an even multiple of your tile's width and height.
• There is currently no way to mix circular scrolling with multiple views. In other words, you're stuck with one view of the world. I could probably change this if there is any interest.
• The SWRegionCollision and SWPixelCollision routines will not work when detecting collisions between sprites that are on opposite "edges" of a circular world. They may be overlapping in reality (and visibly on the screen), but these pixel-precise collision detection routines won't detect it. I could also fix this if there is enough interest, but in the mean time, the standard collision detection is accurate enough.
• SWCheckSpriteWithTiles will not properly detect collisions with tiles when the sprite is hanging off the edge of the virtual world.
• Idle sprites get redrawn every frame if they are visible on screen. (Hint: don't place a huge 640x480 idle sprite in your world!)
• SWFlagScrollingRectAsChanged probably won't work correctly if the rect is hanging off the edge of the virtual world, although this hasn't been tested, so I don't know for sure. This can be fixed if needed.
Getting Started
To use Circular Scrolling in your application, you will need to add both Scrolling.c and Circular Scrolling.c to your project. (Circular Scrolling.c is found in the SpriteWorld FIles -> Utils folder.)
Performing a Circular Scrolling animation is very similar to how you would perform a normal scrolling animation. The only difference is that you must make the offscreen areas so they multiply evenly into the width and height of your virtual world's boundaries. Additionally, you must call the Circular Scrolling routines listed in the Function Reference below instead of their standard scrolling or tiling equivalents. Also make sure to call SWSetScrollingWorldMoveBounds; this is how SpriteWorld knows the dimensions of your virtual circular world. The top and left sides of your circular world's bounds must be 0.
Also, some SpriteWorld functions, such as SWPixelCollision, SWRegionCollision, SWIsPointInSprite, and others may not work correctly when used with sprites that are part of a circular scrolling animation, since those functions are not set up to detect the wrapped parts of a sprite. (That is, the parts hanging off one edge of the world and being wrapped onto another side.)
If you use tiling, the requirements are the same as a normal scrolling SpriteWorld: the offscreen area must be evenly divisible by the tile's width and height.
Here is a list of the standard scrolling/tiling functions, and the version you should use instead in a circular scrolling animation:
The funciton reference below assumes a knowledge of the standard scrolling routines. Brief descriptions of the functions are given in many places, since these routines are almost identical to the standard scrolling routines.
SWProcessCircularSpriteWorld
void SWProcessCircularSpriteWorld(
SpriteWorldPtr spriteWorldP)
Call this function to process a circular scrolling animation.
SWAnimateCircularSpriteWorld
void SWAnimateCircularSpriteWorld(
SpriteWorldPtr spriteWorldP)
Call this function to render a circular scrolling animation on the screen.
SWUpdateCircularSpriteWorld
void SWUpdateCircularSpriteWorld(
SpriteWorldPtr spriteWorldP)
Unlike SWUpdateSpriteWorld and SWUpdateScrollingSpriteWorld, it is not necessary to call SWUpdateCircularSpriteWorld before starting your animation. That's because all this function does is copy the background to the work area, and then call SWAnimateCircularSpriteWorld to draw the sprites in the work area and update the screen. So if you don't want to call this function before starting your animation, just make sure you copy the background to the work area first.
SWUpdateScrollingWindow
SW_FUNC void SWUpdateScrollingWindow(
SpriteWorldPtr spriteWorldP)
This function is actually part of Scrolling.c, but it can also be used during a circular scrolling animation to quickly update the screen in response to an update event.
SWDrawTilesInCircularBackground
SW_FUNC OSErr SWDrawTilesInCircularBackground(
SpriteWorldPtr spriteWorldP)
Call this instead of SWDrawTilesInBackground to draw the tiles in your background if tiling is used. Just make sure your TileMap is large enough to entirely cover your virtual world (as defined by SWSetScrollingWorldMoveBounds), or this function could crash.
SWChangeCircularTileImage
SW_FUNC void SWChangeCircularTileImage(
SpriteWorldPtr spriteWorldP,
short tileID,
short newImage)
Call this instead of SWChangeTileImage to animate tiles.
SWDrawCircularTile
SW_FUNC void SWDrawCircularTile(
SpriteWorldPtr spriteWorldP,
short tileRow,
short tileCol,
short tileID)
Call this instead of SWDrawTile.
SWMoveCircularVisScrollRect
void SWMoveCircularVisScrollRect(
SpriteWorldPtr spriteWorldP,
short horizPos,
short vertPos)
This function moves the visScrollRect of a circular scrolling animation. If it is moved past the bounds of a circular scrolling world, the visScrollRect is automatically wrapped to the other side of the world.
SWOffsetCircularVisScrollRect
SW_FUNC void SWOffsetCircularVisScrollRect(
SpriteWorldPtr spriteWorldP,
short horizOffset,
short vertOffset)
This will offset the visScrollRect by horizOffset and vertOffset. If the visScrollRect is moved past the bounds of a circular scrolling world, the visScrollRect is automatically wrapped to the other side of the world.
SWCollideCircularSpriteLayer
void SWCollideCircularSpriteLayer(
SpriteWorldPtr spriteWorldP,
SpriteLayerPtr srcSpriteLayerP,
SpriteLayerPtr dstSpriteLayerP)
This function is identical to SWCollideSpriteLayer, except that it works with circular scrolling SpriteWorlds. That is, it properly detects collisions between sprites even when one or both sprites are hanging off the edge of the world (with part of the sprite being wrapped to the other side). So even the wrapped part of a sprite gets checked with the other sprites when the collision detection is performed.
When your CollideProc is called, the rect passed to it may be hanging off the edge of the right or bottom side of the circular world. It will never hang off the left or top sides.
