DrawSpriteBlock

The DrawSpriteBlock() API allows you to draw multiple sprites to the screen in a single call. This works similar to DrawSprite(), except you define the first sprite (upper left corner) then the widthand height(in sprites) to sample from SpriteChip’s memory. For example, if you passed in an ID of 0 which is the first sprite, then a widthand heightof 2 the DrawSpriteBlock() API would combine all 4 sprites into a single draw call.

image alt text

The DrawSpriteBlock() API also supports flipping the sprite and color offsets like DrawSprite() but adds some additional arguments to help make it easier to work with multiple sprites as a single sprite.

The first argument, onScreen, determines what should happen to the sprites when they go off-screen. The second argument, useScrollPos, will apply the current scroll position value to the sprite’s X and Y values for you. And the final argument, bounds, allows you to define a custom rectangle that acts similar to a mask.

Usage

DrawSpriteBlock ( id, x, y, width, height, flipH, flipV, drawMode, colorOffset, onScreen, useScrollPos, bounds )

Arguments

Name

Value

Description

id

int

The top left sprite to start with.

x

int

An int value representing the X position to place the sprites on the display. If set to 0, it renders on the far left-hand side of the screen.

y

int

An int value representing the Y position to place sprite on the display. If set to 0, it renders on the top of the screen.

width

int

The width, in sprites, of the grid. A value of 2 renders 2 sprites wide.

height

int

The height, in sprites, of the grid. A value of 2 renders 2 sprites height.

flipH

bool

This is an optional argument which accepts a bool. The default value is set to false but passing in true flips the pixel data horizontally.

flipV

bool

This is an optional argument which accepts a bool. The default value is set to false but passing in true flips the pixel data vertically.

drawMode

DrawMode

This argument accepts the DrawMode enum. You can use Sprite, SpriteBelow, and TilemapCache to change where the pixel data is drawn to. By default, this value is DrawMode.Sprite.

colorOffset

int

This optional argument accepts an int that offsets all the color IDs in the pixel data array. This value is added to each int, in the pixel data array, allowing you to simulate palette shifting.

onScreen

bool

This flag defines if the sprites should not render when they are off the screen. Use this in conjunction with overscan border control what happens to sprites at the edge of the display. If this value is false, the sprites wrap around the screen when they reach the edges of the screen.

useScrollPos

bool

This will automatically offset the sprite's x and y position based on the scroll value.

bounds

Rectangle

A custom mask to constrain the sprite. Moving the sprites outside of the rectangle will hide them when onScreen is set to false.

Draw Modes

The DrawSpriteBlock() API supports the following draw modes:

DrawMode

Layer ID

Supported

TilemapCache

-1

Yes

Background

0

No

SpriteBelow

1

Yes

Tile

2

Yes

Sprite

3

Yes

UI

4

Yes

SpriteAbove

5

Yes

Attempting to use an unsupported draw mode will cancel the draw request. When using DrawMode.TilemapCache or DrawMode.Tile, the tilemap’s coordinate space will be used. In the case of DrawMode.Tile, the X and Y values will become Column and Row. For DrawMode.TilemapCache you can use X and Y to place the sprite on the tilemap itself. That means that wrapping for the sprite’s coordinates will switch from the screen boundaries to the tilemap itself.

Example

For this example, we are going to render two blocks of sprites to the display. The first group will hide when their X value goes past the screen and the second group will wrap when their Y value is offscreen similar to using the DrawSprite() API. To do this, we need the first sprite’s ID which you can find by using Pixel Vision OS’s Sprite Tool.

image alt text

To help get an idea of what the sprite will look like, we can use the Sprite Tool’s size button to increase or decrease the sprites displayed on the canvas. To calculate a sprite’s ID by hand, you can find the first sprite at the top left part of the sprites.png file. Once we have the sprite’s ID we can use the following code example to draw it:

Lua
C#
Lua
local speed = 5
local nextPos = 0
function Update(timeDelta)
-- Calculate the next position
nextPos = nextPos + (speed * (timeDelta / 100))
end
function Draw()
-- Redraw the display
RedrawDisplay()
-- Draw sprite block moving horizontally and hide when it goes offscreen
DrawSpriteBlock(168, nextPos, 8, 2, 2)
-- Draw flipped sprite block moving vertically but render when offscreen
DrawSpriteBlock(168, 36, nextPos, 2, 2, true, false, DrawMode.Sprite, 0, false)
-- Draw the x,y position of each sprite
DrawText("("..math.floor(nextPos)..",8)", nextPos + 20, 8, DrawMode.Sprite, "large", 15)
DrawText("(36,"..math.floor(nextPos)..")", 56, nextPos, DrawMode.Sprite, "large", 15)
end
C#
class DrawSpriteBlock : GameChip
{
// Use floats to store the subpixel position
private float speed = 5;
private float nextPos;
// Use this point to position the sprites
private Point pos;
public override void Update(int timeDelta)
{
// Calculate the next position
nextPos = nextPos + (speed * (timeDelta / 100f));
// Need to convert the nextPoint to an int, so we'll save it in a point
pos.X = (int)nextPos;
pos.Y = (int)nextPos;
}
public override void Draw()
{
// Redraw the display
RedrawDisplay();
// Draw sprite block moving horizontally and hide when it goes offscreen
DrawSpriteBlock(168, pos.X, 8, 2, 2);
// Draw flipped sprite block moving vertically but render when offscreen
DrawSpriteBlock(168, 36, pos.Y, 2, 2, true, false, DrawMode.Sprite, 0, false);
// Draw the x,y position of each sprite
DrawText("(" + MathUtil.FloorToInt(nextPos) + ",8)", pos.X + 20, 8, DrawMode.Sprite, "large", 15);
DrawText("(36," + MathUtil.FloorToInt(nextPos) + ")", 56, pos.Y, DrawMode.Sprite, "large", 15);
}
}

Running this code will output the following:

image alt text

When the horizontal sprite moves past the boundary of the screen, it will stop rendering even though the X value continues to increase.

image alt text