View Source Scenic.Primitive.Sprites (Scenic v0.12.0-rc.0)

Draw one or more sprites from a single source image.

Overview

The term "sprite" means one or more subsections of a larger image that get rendered to the screen. You can do many things with sprites including animations and zooming in and out of an image and more.

Data Format

{ source_image_id, draw_commands }

source_image_id refers to an image in the Scenic.Assets.Static library. This can be either the file name from your asset sources or an alias that you set up in your configuration scripts.

draw_commands is a list of source/destination drawing commands that are executed in order when the primitive renders.

[ {{src_x, src_y}, {src_w, src_h}, {dst_x, dst_y}, {dst_w, dst_h}} ] or [ {{src_x, src_y}, {src_w, src_h}, {dst_x, dst_y}, {dst_w, dst_h}}, alpha ]

Each draw command is an x/y position and width/height of a rectangle in the source image, followed by the x/y position and width/height rectangle in the destination space.

An optional alpha channel can be set in last position to apply a transparency effect on the sprite.

In other words, This copies rectangular images from the source indicated by image_id and draws them in the coordinate space of the graph.

The size of the destination rectangle does NOT need to be the same as the source. This allows you to grow or shrink the image as needed. You can use this to zoom in or zoom out of the source image.

Animations

Sprites are common in the game industry and can be used to create animations, manage large numbers of small images and more.

For example, in many games a character walking is built as a series of frames in an animation that all live together in a single image file. When it comes time to draw, the different frames are rendered to the screen one after the other to give the appearance that the character is animating.

A simpler example would be an image of a device with a blinking light on it. The same device would be in the source image twice. Once with the light on, and once with it off. Then you render the appropriate portion of source image on a timer.

Usage

You should add/modify primitives via the helper functions in Scenic.Primitives

This example draws the same source rectangle three times in different locations. The first is at full size, the second is expanded 10x, the third is with a 50% transparency effect.

graph
  |> sprites( { "images/my_sprites.png", [
    {{0,0}, {10, 20}, {10, 10}, {10, 20}},
    {{0,0}, {10, 20}, {100, 100}, {100, 200}},
    {{0,0}, {10, 20}, {100, 100}, {100, 200}, 0.5}
  ]})

Summary

Functions

Returns a list of styles recognized by this primitive.

Types

@type draw_cmd() ::
  {{sx :: number(), sy :: number()}, {sw :: number(), sh :: number()},
   {dx :: number(), dy :: number()}, {dw :: number(), dh :: number()},
   alpha :: number()}
@type draw_cmds() :: [draw_cmd()]
@type styles_t() :: [:hidden | :scissor]
@type t() :: {image :: Scenic.Assets.Static.id(), draw_cmds()}

Functions

@spec valid_styles() :: styles_t()

Returns a list of styles recognized by this primitive.