Name
planar.CreateSprite -- create hardware sprite from brush (V2.0)
Synopsis
[id] = planar.CreateSprite(id, brushid)
Function
This function converts the brush specified by brushid into a hardware sprite and assigns the identifier id to it. If you specify Nil in the id argument, planar.CreateSprite() will automatically choose a vacant identifier for this sprite and return it to you.

Note that the brush you pass to this function must respect the Amiga hardware sprite limitations. This means that it must adhere to the following rules:

Also note that the Amiga hardware supports only 8 sprite DMA channels. Each channel can have a 4 color sprite. The 8 sprite DMA channels are tied to the following color registers:

Two channels can be combined to create a 16 color sprite. This means that if you use 16 color sprites, you can only have 4 instead of 8 because a 16 color sprite will block two sprite DMA channels. 16 color sprites are tied to the color registers 16 to 31 (color 16 is transparent).

Note that planar.CreateSprite() won't map the sprite to a sprite DMA channel immediately. This is the job of planar.MapSprite(). Thus, you can create more hardware sprites with planar.CreateSprite() than there are sprite DMA channels. This is useful if you want to animate sprites, for example. In that case, you could first convert all the animation frames to hardware sprites using planar.CreateSprite() and then map and unmap the single animation frames before/after displaying them with planar.MoveSprite().

Inputs
id
identifier for the hardware sprite or Nil for auto id selection
brushid
identifier of the palette brush to be converted to a hardware sprite
Results
id
optional: identifier of the hardware sprite; will only be returned if you pass Nil as argument 1 (see above)
Example
@REQUIRE "plananarama", {PaletteMode = True}
@DISPLAY {Palette = #PALETTE_AGA}
SetPaletteMode(#PALETTEMODE_PEN)
SetFillStyle(#FILLCOLOR)
CreateBrush(1, 64, 64, {Palette = #PALETTE_GRAY4})
SelectBrush(1)
For Local k = 0 To 2
   SetDrawPen(k + 1)
   Box(k * 21, 0, 21, 64)
Next
EndSelect
planar.CreateSprite(1, 1)
planar.MapSprite(1)
Repeat
   planar.MoveSprite(1, MouseX(), MouseY())
   planar.VWait()
Forever
The code above will create a 4 color 64x64 sprite, map it to a sprite DMA channel and then move it to where the mouse pointer is. Note that it doesn't matter that we pass #PALETTE_GRAY4 to CreateBrush() since the hardware sprite will use the screen's palette so we just use #PALETTE_GRAY4 as a dummy to tell CreateBrush() to give us a 16 color sprite.

Show TOC