Home

SpriteVideo plugin overview

"SpriteVideo" plugin features display of arbitrary sprites with various transformations in your game, and playing OGG Theora videos on these sprites in a non-blocking manner.

WARNING: at the moment videos are played without any sound, plugin only displays video frames.

General features:

• Supports only 32-bit games.
• Supports Direct3D and OpenGL game renderers. Cannot be used in Software mode (fails to start).
• May be built and run on multiple platforms where OpenGL is supported. Currently configured to be built on Windows and Linux, but may be updated to build on e.g. BSD, MacOSX and Android.

Sprite features:

• Sprites are created at will, and don't depend on any built-in AGS objects (you may think of them as your own custom objects).
• Sprites may be created based on the game sprites, or loaded from PNG files on disk in the game's directory.
• Sprites may be repositioned, scaled and rotated, applied color effects and have partial transparency (alpha).
• Sprites may be attached to other sprites in a parent-child relationship.
• Sprites are displayed on several layers, in-between engine's own render layers: over the room background, over the whole room, over GUI, and finally over the mouse cursor.

Video features:

• Supports OGG Theora (*.ogv) video format.
• Plays video in a non-blocking manner on a special placeholder sprite.
• Video sprite acts precisely like the regular sprite: may be repositioned, scaled, rotated, attached to other sprites, and so on.
• Playing sound track is not supported at the moment.

"SpriteVideo" plugin is a successor of the older "Direct3D" plugin, made by Aki Ahonen (aka AJA). The difference between at this moment are:

• "SpriteVideo" supports Direct3D and OpenGL renderers, while "Direct3D" was limited to Direct3D renderer (hence the title).
• Potentially cross-platform, while "Direct3D" was Windows-only.

This plugin currently maintains 100% script compatibility with "Direct3D" plugin, so that the games made with the old plugins could work with the new one even without recompilation.

See also: SpriteVideo API

Basic usage

Sprites and video objects are stored in pointers: as D3D_Sprite* and D3D_Video*. They are acting precisely like any other AGS pointers. They may be either local or global variables, and objects will be held in memory until all pointers that are pointing to them are lost.

Sprites are created like:

D3D_Sprite* sprite = D3D.OpenSprite(SPRITE_NUM); // create from the game sprite SPRITE_NUM

and deleted explicitly by nullifying every pointer that points to it, like:

sprite = null;

Sprite will be deleted automatically if their only remaining pointer is destroyed. For example, if you declare a local D3D_Sprite* variable in a function, and you do not save the pointer in a global variable, neither return it from function, then the sprite will be deleted as soon as the function ends. (This is the basic pointer behavior in AGS.)

After you created your sprite, you may configure it using the pointer, for example:

sprite.SetPosition(100, 100); // set at x=100, y=100
sprite.scaling = 2.5; // scale x2.5 times
sprite.rotation = 45.0; // rotate by 45 degrees clockwise
sprite.alpha = 0.5; // make half-transparent

Check out the list of all available sprite functions and properties further below.

The video is created with D3D.OpenVideo function:

D3D_Video* video = D3D.OpenVideo("test.ogv");

D3D_Video object has the same behavior as D3D_Sprite, and inherits all of its parameters. But it also adds several functions and properties of its own.

Now, let's look at the couple of quick script examples.

Displaying a sprite at the current mouse position

// room script file
D3D_Sprite* sprite;
bool scaleSpriteUp = true;

function room_Load() {        
    // Sprite from slot 2000
    sprite = D3D.OpenSprite(2000);

    // Safety test (optional)
    if (sprite == null) {
        Display("Couldn't open sprite.");
        return;
    }
    
    // Draw over cursor
    sprite.renderStage = eD3D_StageScreen;
    // Use screen coordinates
    sprite.relativeTo = eD3D_RelativeToScreen;
    // Show only in this room
    sprite.room = player.Room;
}

function repeatedly_execute_always() {
    if (sprite) {
        // Follow the cursor
        sprite.SetPosition(mouse.x, mouse.y);
        // Keep rotating clockwise
        sprite.rotation = sprite.rotation + 1.0;
        if (sprite.rotation > 360.0) {
            sprite.rotation = -360.0; // let's keep it within +/-360
        }
        // Keep scaling up and down
        if (scaleSpriteUp) {
            sprite.scaling += 0.01;
            if (sprite.scaling > 3.0) {
                scaleSpriteUp = false;
            }
        } else {
            sprite.scaling -= 0.01;
            if (sprite.scaling < 0.3) {
                scaleSpriteUp = true;
            }
        }
    }
}

Playing a video over the background

// room script file
D3D_Video* video;

function room_Load() {
    // Required for autoplay
    D3D.SetLoopsPerSecond(GetGameSpeed());

    // Open video file
    video = D3D.OpenVideo("test.ogv");

    if (!video) {
        Display("Couldn't open video.");
        return;
    }

    // Draw over room background
    sprite.renderStage = eD3D_StageBackground;
    // Use room coordinates
    video.relativeTo = eD3D_RelativeToRoom;        
    // Anchor point to top left corner
    video.SetAnchor(-0.5, -0.5);
    // Play!
    video.Autoplay();
}

function room_Leave()
{
    // Free memory when leaving the room
    video = null;
}

Please continue to the SpriteVideo API description.