Name
CreateSprite -- create a sprite (V2.0)
Synopsis
[id] = CreateSprite(id, type, ...)
[id] = CreateSprite(id, #ANIM, source_id)
[id] = CreateSprite(id, #BRUSH, source_id[, width, height, frames,
                                fr_per_row, sourcex, sourcey])
[id] = CreateSprite(id, #SPRITE, source_id1, source_id2, ...)
[id] = CreateSprite(id, #TEXTOBJECT, source_id)
Function
This function creates a new sprite from the specified source. The sprite source can be an animation, a brush, a sprite or a text object. The new sprite will be stored under the specified id. If you specify Nil in the id argument, this function will choose an identifier for the new sprite automatically and return it to you. The arguments of CreateSprite() depend on what source type you specify.

If type is #ANIM, simply pass the identifier of the animation object to use in argument 3.

If type is #BRUSH, you have to specify the identifier of the source brush in argument 3. You can also make CreateSprite() extract several frames out of a brush. If you want that, you will have to pass at least the arguments width, height and frames. Width and height define the dimensions for the sprite to be created and frames specifies how many frames CreateSprite() shall read from the source brush. If the frames are aligned in multiple rows in the source brush, you will also have to pass the argument fr_per_row to tell CreateSprite() how many frames there are in every row. Finally, you can tell CreateSprite() where in the brush it should start scanning by specifying the arguments sourcex and sourcey (they both default to 0). CreateSprite() will then start off at position sourcex and sourcey and read frames number of images with the dimensions of width by height from the brush specified in source_id. After it has read fr_per_row images, it will advance to the next row. If you specify only three arguments, CreateSprite() will simply convert the brush specified in source_id to a sprite.

If type is #SPRITE, CreateSprite() will create a new sprite from an unlimited number of source sprites. You can specify as many source sprites as you want. Of course, each of the source sprites can also have multiple frames. When using #SPRITE, CreateSprite() will never copy the graphics data of the specified source sprites. For performance reasons, the source sprites will only be referenced and thus your new sprite will depend on them. By using only references to existing sprites, CreateSprite() executes very fast and with very low memory footprint. This is very convenient if you want to create various different animation sequences from always the same source sprites. Please note though that because sprites created using #SPRITE source type depend of their sub sprites, they will automatically be freed if one of the sub sprites is freed. So you should not free the sub sprites before you are done with the newly created sprite.

If type is #TEXTOBJECT, CreateSprite() will create a sprite from the specified text object. You only have to pass the identifier of the source text object.

Inputs
id
identifier for the new sprite or Nil for auto ID select
type
type of source object
...
further arguments depend on the type specified (see above)
Results
id
optional: identifier of the new sprite; will only be returned when you pass Nil as argument 1 (see above)

Show TOC