-
Notifications
You must be signed in to change notification settings - Fork 1
SpriteVideo API
The D3D struct contains functions for setting up global parameters and creating sprites. All of these are static, which means that you don't need to create any "D3D" object, but call them from the D3D type itself.
static void D3D.SetLoopsPerSecond(int loops)
Tells the plugin how many game loops pass in one second. The plugin needs to know the game speed, for example, when autoplaying video clips. The most frequent use is:
D3D.SetLoopsPerSecond(GetGameSpeed());
static D3D_Sprite* D3D.OpenSprite(int sprite_num)
Creates a sprite, identified by its graphic slot. Returns a pointer to the D3D_Sprite object on success, and null on failure.
NOTE: currently AGS sprites always use linear filtering.
static D3D_Sprite* D3D.OpenSpriteFile(String filename, D3D_Filtering filtering);
Creates a sprite from the image file in the game directory. Returns a pointer to the D3D_Sprite object on success, and null on failure.
Currently the only supported file format is PNG.
Filtering specifies how the sprite should be filtered when rendered to the screen (see explanation below).
static D3D_Sprite* D3D.OpenBackground(int frame)
Creates a sprite from the current room's background frame. Returns a pointer to the D3D_Sprite object on success, and null on failure.
static D3D_Video* D3D.OpenVideo(String filename)
Opens a Theora video file from the game directory. Returns a pointer to the D3D_Video object on success, and null on failure.
enum D3D_Filtering
D3D_Filtering specifies the texture filtering method used for rendering a D3D_Sprite:
- eD3D_FilterNearest
- eD3D_FilterLinear
Use FilterLinear for smooth filtering and FilterNearest if you want the texture to look sharp.
enum D3D_RenderStage
D3D_RenderStage specifies the stage at which the object should be rendered:
- eD3D_StageBackground - Rendered over the background.
- eD3D_StageScene - Rendered over characters and objects.
- eD3D_StageGUI - Rendered over overlays and GUIs.
- eD3D_StageScreen - Rendered over the mouse cursor.
enum D3D_RelativeTo
D3D_RelativeTo specifies how the coordinates of the objects should be interpreted, as relative to the room or to the screen:
- eD3D_RelativeToRoom
- eD3D_RelativeToScreen
D3D_Sprite represents a texture that can be drawn onto the screen. Attributes and methods relating to updating the sprite (isEnabled, isAutoUpdated, Update()) are not relevant for D3D_Sprite but are used in some classes that inherit these attributes and methods from D3D_Sprite (e.g. D3D_Video).
bool isEnabled
Can the sprite be automatically updated. Default: true.
NOTE: has no effect on D3D_Sprites themselves, only in derived classes (e.g. D3D_Video).
bool isVisible
Should this sprite be drawn on screen. Default: true.
bool isAutoUpdated
Will the sprite be automatically updating its image every frame. Default: true.
If you have automatic update disabled then you need to call Update function yourself whenever you like the sprite to update its image.
NOTE: has no effect on D3D_Sprites themselves, only in derived classes (e.g. D3D_Video).
bool isAutoRendered
Will the sprite be automatically rendered every frame. Default: true.
If you have automatic render disabled then you need to call Render function yourself when you want the sprite to appear on screen.
int x
X position. Default: 0.
The sprite's anchor point will be placed at this coordinate.
int y
Y position. Default: 0.
The sprite's anchor point will be placed at this coordinate.
readonly int width
Width. Will return 0 if the texture has not been created yet.
readonly int height
Height. Will return 0 if the texture has not been created yet.
float anchorX
Anchor point X, relative to the size of the sprite. Default: 0.0.
Anchor point (0, 0) is the center of the sprite. The top-left corner is (-0.5, -0.5), the bottom right corner is (0.5, 0.5), and so on.
float anchorY
Anchor point Y, relative to the size of the sprite. Default: 0.0.
Anchor point (0, 0) is the center of the sprite. The top-left corner is (-0.5, -0.5), the bottom right corner is (0.5, 0.5), and so on.
float rotation
Rotation in degrees, positive is clockwise, negative is counter-clockwise. Default: 0.0
Sprites are rotated around the anchor point. For example, if the anchor is (0.0, 0.0) then the sprite is rotated around its center, if it is (-0.5, -0.5) then around its top-left corner.
float scaling
Scaling. Default: 1.0.
float tintR
The Red component of the sprite's colorization, in range of 0.0 to 1.0. Default: 1.0.
See SetTint function's description for explanation on how colorization works.
float tintG
The Green component of the sprite's colorization, in range of 0.0 to 1.0. Default: 1.0.
See SetTint function's description for explanation on how colorization works.
float tintB
The Blue component of the sprite's colorization, in range of 0.0 to 1.0. Default: 1.0.
See SetTint function's description for explanation on how colorization works.
float alpha
The sprite's Alpha component, in range of 0.0 to 1.0. Default: 1.0.
This is essentially a measure of opacity, or transparency in reverse: 0.0 means completely transparent and 1.0 opaque. 0.5 is half-transparent.
D3D_RenderStage renderStage
At which stage will the sprite be rendered. Default: eD3D_StageBackground.
See D3D_RenderStage enum's description.
D3D_RelativeTo relativeTo
What is the object position related to. Default: eD3D_RelativeToRoom.
See D3D_RelativeTo enum's description.
int room
Which room will the object be active (enabled and visible) in. A negative value means the sprite is active in all rooms. Default: -1.
void SetPosition(int x, int y)
Sets both x and y coordinates.
void SetAnchor(float x, float y)
Sets both x and y values of the sprite's anchor. The anchor is defined in the relative range from top-left corner at (-0.5, -0.5) to bottom-right corner at (0.5, 0.5), where (0.0, 0.0) is the sprite's center.
The anchor serves two simultaneous purposes: it determines which sprite's point will be placed at the position coordinates, and what point is the sprite rotated around if the rotation is not zero.
void SetTint(float r, float g, float b)
Sets the sprite's colorization values, given three components: Red, Green and Blue.
The name "tint" is used for historical reasons here, but in reality it's not a tint, but amount of sprite's color. At (1.0, 1.0, 1.0) the sprite is rendered exactly as the original image, at (0.0, 0.0, 0.0) it's completely black. Few more examples:
sprite.SetTint(1.0, 0.0, 0.0); // completely red
sprite.SetTint(0.0, 1.0, 0.0); // completely blue
sprite.SetTint(0.0, 0.0, 1.0); // completely green
sprite.SetTint(0.5, 0.5, 0.5); // dimmed down to half
sprite.SetTint(1.0, 0.5, 0.33); // has all the original red color,
// half of its blue color and 1/3 of green
void SetParent(int parentKey)
Sets the sprite's parent, using parent sprite's key. The key may be received using GetKey() function, for example:
sprite1.SetParent(sprite2.GetKey());
The parent-child relationship has following effect:
- Position becomes relative to parent's position.
- Scaling are multiplied; that means that parent's 2.0 scaling will double whatever child's scaling is.
- Rotations are plainly summed up.
- Colorization ("tint") is multiplied, but since it defines a fraction that results in child could not be more color-ful than the parent. For example, if parent has only half of the red color (0.5), the child with 1.0 will end up having half, and the child with 0.5 red will have only a quarter (0.5 x 0.5 = 0.25).
int GetKey()
Returns this object's internal ID. This may be used to reference an object other than by its pointer. Also SetParent() function requires a sprite's key.
void Update()
Manually updates the sprite. If isAutoUpdated property is false then you have to be call this whenever you want this sprite to update its image.
NOTE: doesn't need to be called for D3D_Sprites.
void Render()
Manually schedules this sprite for render. Has to be called each game tick when you want this sprite to be displayed on screen.
Is only useful if isAutoRendered property is false.
D3D_Video represents a Theora video clip. Audio is currently not supported.
D3D_Video inherits all the attributes and methods from D3D_Sprite and provides a few extra ones that concern video playback.
bool isLooping
Will the video replay immediately after it has ended. Default: false.
float fps
Playback framerate when autoplaying, in frames per second. Default: Video file's framerate.
void Autoplay()
Plays the video automatically.
If the isAutoUpdated property is true, the video will advance at the specified framerate automatically. Otherwise you must call Update when you want it to advance.
NOTE: if the game speed is not the AGS default (40), you must set the correct speed by calling D3D.SetLoopsPerSecond(GetGameSpeed());, otherwise the video won't know how much time passes each game loop.
bool IsAutoplaying()
Tells if the video is playing automatically.
bool NextFrame()
Advances the video to the next frame. Useful if you want to display video frame by frame at your own command.
void StopAutoplay()
Stops autoplaying, pauses the video.