Sprite

Defines

BINOCLE_SPRITE_MAX_FRAMES

BINOCLE_SPRITE_MAX_ANIMATIONS

Typedefs

typedef enum binocle_sprite_sort_mode binocle_sprite_sort_mode: The sort mode used when running through the sprite batcher

typedef struct binocle_sprite_frame binocle_sprite_frame: The single frame of a sprite, mainly used within animations

typedef struct binocle_sprite_animation_frame_mapping binocle_sprite_animation_frame_mapping: The mapping of a frame within an animation

typedef struct binocle_sprite_animation binocle_sprite_animation: A sprite animation

typedef struct binocle_sprite binocle_sprite: A sprite

typedef struct binocle_sprite_batch_item binocle_sprite_batch_item: An item of the sprite batch

typedef struct binocle_sprite_batcher binocle_sprite_batcher: The sprite batcher

typedef struct binocle_sprite_batch binocle_sprite_batch: A sprite batch

Enums

enum binocle_sprite_sort_mode

The sort mode used when running through the sprite batcher

Values:

enumerator BINOCLE_SPRITE_SORT_MODE_DEFERRED

All sprites gets drawn when

See also

binocle_sprite_batch_end is being invoked, in order of draw call sequence. Depth is ignored.

enumerator BINOCLE_SPRITE_SORT_MODE_IMMEDIATE

Each sprite is being drawn with an individual draw call, instead of.

See also

binocle_sprite_batch_end. Depth is ignored.

enumerator BINOCLE_SPRITE_SORT_MODE_TEXTURE

Same as.

See also

binocle_sprite_batch_end, except sprites are sorted by texture prior to drawing. Depth is ignored.

enumerator BINOCLE_SPRITE_SORT_MODE_BACK_TO_FRONT

Same as.

See also

binocle_sprite_batch_end, except sprites are sorted by depth in back-to-front order prior to drawing.

enumerator BINOCLE_SPRITE_SORT_MODE_FRONT_TO_BACK

Same as.

See also

binocle_sprite_batch_end, except sprites are sorted by depth in front-to-back order prior to drawing.

Functions

binocle_sprite *binocle_sprite_from_material(struct binocle_material *material)

Creates a sprite from a material.

Parameters:: material – the material
Returns:: the sprite

void binocle_sprite_destroy(struct binocle_sprite *sprite)

Releases all the resources of a sprite.

Parameters:: sprite – the sprite

void binocle_sprite_draw(binocle_sprite *sprite, struct binocle_gd *gd, int64_t x, int64_t y, kmAABB2 *viewport, float rotation, kmVec2 *scale, struct binocle_camera *camera, float depth, sg_color *color)

Draws a sprite in immediate mode. The sprite gets drawn as soon as this function is called.

Parameters:

sprite – the sprite
gd – the graphics device instance
x – the X coordinate
y – the Y coordinate
viewport – the viewport to apply
rotation – the rotation
scale – the scale
camera – the camera to apply

void binocle_sprite_draw_with_sprite_batch(binocle_sprite_batch *sprite_batch, binocle_sprite *sprite, struct binocle_gd *gd, int64_t x, int64_t y, kmAABB2 *viewport, float rotation, kmVec2 *scale, struct binocle_camera *camera, float depth)

void binocle_sprite_add_frame(binocle_sprite *sprite, binocle_sprite_frame frame)

Adds a frame of an animation to a sprite.

Parameters:

sprite – the sprite
frame – the frame of the animation to add

void binocle_sprite_add_animation(binocle_sprite *sprite, int id, int frame)

Adds an animation with just one frame to a sprite.

Parameters:

sprite – the sprite
id – the ID of the animation
frame – the frame

void binocle_sprite_add_animation_with_frames(binocle_sprite *sprite, int id, bool looping, float delay, int frames[], int frames_count)

Adds an animation with more than one frame to a sprite.

Parameters:

sprite – the sprite
id – the ID of the animation
looping – true if the animation is looping
delay – the delay between each frame
frames – the frames IDs
frames_count – the number of frames

void binocle_sprite_play(binocle_sprite *sprite, int id, bool restart)

Plays an animation.

Parameters:

sprite – the sprite
id – the ID of the animation
restart – true if the animation should restart from the beginning if it’s already running

void binocle_sprite_play_from_frame(binocle_sprite *sprite, int id, int start_frame, bool restart)

Plays an animation starting from the given frame.

Parameters:

sprite – the sprite
id – the ID of the animation
start_frame – the index of the frame to start from
restart – true if the animation should restart from the beginning if it’s already running

void binocle_sprite_stop(binocle_sprite *sprite)

Stops playing any animation if running.

Parameters:: sprite – the sprite

void binocle_sprite_update(binocle_sprite *sprite, float dt)

Updates the animation internals This advances the animation as needed, given the time that has passed since the last update.

Parameters:

sprite – the sprite
dt – the delta time passed since the last call, in seconds

int binocle_sprite_get_current_frame(binocle_sprite *sprite)

Gets the index of the current frame being played.

Parameters:: sprite – the sprite
Returns:: the index of the current frame

void binocle_sprite_set_current_frame(binocle_sprite *sprite, int frame)

Sets the current frame to display.

Parameters:

sprite – the sprite
frame – the index of the frame

void binocle_sprite_set_current_frame_by_name(binocle_sprite *sprite, const char *name)

Sets the current frame to display by name.

Parameters:

sprite – the sprite
name – the name of the frame as set in its subtexture

int binocle_sprite_get_current_animation(binocle_sprite *sprite)

Gets the ID of the current animation.

Parameters:: sprite – the sprite
Returns:: the ID of the current animation

void binocle_sprite_set_current_animation(binocle_sprite *sprite, int id)

Force sets the current animation.

Parameters:

sprite – the sprite
id – the ID of the animation

void binocle_sprite_clear_animations(binocle_sprite *sprite)

Removes all the animations of the sprite.

Parameters:: sprite – the sprite

void binocle_sprite_clear_frames(binocle_sprite *sprite)

Removes all the frames of the sprite.

Parameters:: sprite – the sprite

void binocle_sprite_create_animation(binocle_sprite *sprite, char *name, char *subtextures_names, char *sequence_code, bool loop, binocle_subtexture *subtextures, size_t subtextures_count)

Creates a new animation.

sequence code format: startFrame-endFrame:time(chance) time: also be set to “forever” - this will loop the sequence indefinitely chance: float value from 0-1, chance that the sequence will play (if not played, it will be skipped) time and chance can both be ignored, this will mean the sequence plays through once

sequence code examples: TV: 0-1:3, 2-3:3, 4-5:4, 6-7:4, 8:3, 9:3 Idle animation with random fidgets: 0-59, 60-69, 10-59, 0-59(.25), 70-129(.75) Jump animation with looping finish: 0-33, 20-33:forever

Parameters:

sprite – the sprite
name – the name of the animation
subtextures_names – the names of the subtextures
sequence_code – the sequence to follow
loop – true if the animation is looping
subtextures – the array of subtextures
subtextures_count – the number of subtextures

void binocle_sprite_play_animation(binocle_sprite *sprite, char *name, bool restart)

Plays an animation given the name of the animation.

Parameters:

sprite – the sprite
name – the name of the animation to play
restart – true if the animation should restart from the beginning if it’s already running

bool binocle_sprite_has_animation(binocle_sprite *sprite, const char *animation_name)

Checks if an animation with a given name exists for the specified sprite.

Parameters:

sprite – the sprite
animation_name – the name of the animation to check

Returns:

true if the animation exists

bool binocle_sprite_is_playing_any_animation(binocle_sprite *sprite)

Returns true if any animation is playing. You can use this function to check if any animation is currently playing.

Parameters:: sprite – the sprite
Returns:: true if any animation is playing

bool binocle_sprite_is_playing_animation(binocle_sprite *sprite, const char *name)

Returns true if the animation is playing.

Parameters:

sprite – the sprite
name – the name of the animation

Returns:

true if any animation is playing

binocle_sprite_frame binocle_sprite_frame_from_subtexture(struct binocle_subtexture *subtexture)

Creates a sprite frame from a subtexture The frame will be the same as the subtexture.

Parameters:: subtexture – the subtexture
Returns:: the frame

binocle_sprite_frame binocle_sprite_frame_from_subtexture_and_origin(struct binocle_subtexture *subtexture, kmVec2 origin)

Creates a sprite frame from a subtexture and assigns an origin The frame will have the same size as the subtexture but its origin will be set to the one passed as parameter.

Parameters:

subtexture – the subtexture
origin – the origin of the sprite

Returns:

the frame

binocle_sprite_batch_item binocle_sprite_batch_item_new()

Creates a new sprite batch item.

Returns:: the sprite batch item

void binocle_sprite_batch_item_set(binocle_sprite_batch_item *item, float x, float y, float dx, float dy, float w, float h, float sin, float cos, sg_color color, kmVec2 tex_coord_tl, kmVec2 tex_coord_br, float depth, struct binocle_material *material)

Sets the values of a sprite batch item.

Parameters:

item – the sprite batch item
x – the X position
y – the Y position
dx – the delta X position
dy – the delta Y position
w – the width
h – the height
sin – the sin component of the rotation
cos – the cos component of the rotation
color – the color
tex_coord_tl – the texture coordinates of the top-left corner
tex_coord_br – the texture coordinates of the bottom-right corner
depth – the depth of the sprite
material – the material

binocle_sprite_batcher binocle_sprite_batcher_new()

Creates a new sprite batcher.

Returns:: the sprite batcher

binocle_sprite_batch_item *binocle_sprite_batcher_create_batch_item(binocle_sprite_batcher *batcher)

Creates a new sprite batch item within the given sprite batcher.

Parameters:: batcher – the sprite batcher
Returns:: the sprite batch item

void binocle_sprite_batcher_ensure_array_capacity(binocle_sprite_batcher *batcher, uint64_t num_batch_items)

Makes sure that the sprite batcher has enough room for the given number of sprite batch items. If there’s not enough room, it will allocate the necessary memory and initialize it as needed.

Parameters:

batcher – the sprite batcher
num_batch_items – the number of sprite batch items

void binocle_sprite_batcher_draw_batch(binocle_sprite_batcher *batcher, binocle_sprite_sort_mode sort_mode, struct binocle_render_state *render_state, struct binocle_gd *gd)

Tells the sprite batcher to draw its batch of items.

See also

binocle_sprite_sort_mode

Parameters:

batcher – the sprite batcher
sort_mode – the sorting mode
render_state – the current render state
gd – the graphics device

void binocle_sprite_batcher_flush_vertex_array(binocle_sprite_batcher *batcher, uint64_t start, uint64_t end, struct binocle_material *material, struct binocle_render_state *render_state, struct binocle_gd *gd, float depth)

Tells the sprite batcher to flush an array of vertices.

Parameters:

batcher – the sprite batcher
start – the index of the vertex to start from
end – the index of the last vertex
material – the material to use
render_state – the current render state
gd – the graphics device
depth – the depth of the layer being flushed

binocle_sprite_batch binocle_sprite_batch_new()

Creates a new sprite batch.

Returns:: the sprite batch

void binocle_sprite_batch_compute_cull_rectangle(binocle_sprite_batch *batch, kmAABB2 viewport)

Computes the cull rectangle of a prite batch.

Parameters:

batch – the sprite batch
viewport – the viewport

void binocle_sprite_batch_begin(binocle_sprite_batch *batch, kmAABB2 viewport, binocle_sprite_sort_mode sort_mode, struct sg_shader *shader, kmMat4 *transform_matrix)

Starts the sprite batch This should be called before adding any sprite to the batcher.

Parameters:

batch – the sprite batch
viewport – the viewport
sort_mode – the sorting mode
shader – the shader
transform_matrix – the transformation matrix

void binocle_sprite_batch_end(binocle_sprite_batch *batch, kmAABB2 viewport)

Ends a sprite batch.

Parameters:

batch – the sprite batch
viewport – the viewport

void binocle_sprite_batch_setup(binocle_sprite_batch *batch, kmAABB2 viewport)

Performs the setup of a sprite batch.

Parameters:

batch – the sprite batch
viewport – the viewport

void binocle_sprite_batch_draw_internal(binocle_sprite_batch *batch, struct binocle_material *material, kmAABB2 *source_rectangle, sg_color color, float rotation, float depth, bool auto_flush)

Draws a sprite (Used internally)

Parameters:

batch – the sprite batch
material – the material
source_rectangle – the source rectangle
color – the color
rotation – the rotation angle
depth – the depth of the sprite
auto_flush – true if this should be flushed as soon as the draw call is issued

void binocle_sprite_batch_flush_if_needed(binocle_sprite_batch *batch)

Flushes the batch if the requirements are met.

Parameters:: batch – the sprite batch

void binocle_sprite_batch_draw(binocle_sprite_batch *batch, struct binocle_material *material, kmVec2 *position, kmAABB2 *destination_rectangle, kmAABB2 *source_rectangle, kmVec2 *origin, float rotation, kmVec2 *scale, sg_color color, float layer_depth)

Draws a sprite in the batch.

Parameters:

batch – the sprite batch
material – the material
position – the position
destination_rectangle – the destination rectangle
source_rectangle – the source rectangle
origin – the origin position
rotation – the rotation angle
scale – the scale
color – the color
layer_depth – the depth of the sprite

void binocle_sprite_batch_draw_vector_scale(binocle_sprite_batch *batch, struct binocle_material *material, kmVec2 *position, kmAABB2 *source_rectangle, sg_color color, float rotation, kmVec2 origin, kmVec2 scale, float layer_depth)

Draws a sprite to the batch.

Parameters:

batch – the sprite batch
material – the material
position – the position
source_rectangle – the source rectangle
color – the color
rotation – the rotation angle
origin – the origin
scale – the scale
layer_depth – the depth of the sprite

void binocle_sprite_batch_draw_float_scale(binocle_sprite_batch *batch, struct binocle_material *material, kmVec2 position, kmAABB2 source_rectangle, sg_color color, float rotation, kmVec2 origin, float scale, float layer_depth)

Draws a sprite to the batch.

Parameters:

batch – the sprite batch
material – the material
position – the position
source_rectangle – the source rectangle
color – the color
rotation – the rotation angle
origin – the origin
scale – the scale
layer_depth – the depth of the sprite

void binocle_sprite_batch_draw_position(binocle_sprite_batch *batch, struct binocle_material *material, kmVec2 position)

Draws a sprite to the batch.

Parameters:

batch – the sprite batch
material – the material
position – the position

void binocle_sprite_batch_draw_noscale(binocle_sprite_batch *batch, struct binocle_material *material, kmAABB2 destination_rectangle, kmAABB2 *source_rectangle, sg_color color, float rotation, kmVec2 origin, float layer_depth)

Draws a sprite to the batch.

Parameters:

batch – the sprite batch
material – the material
destination_rectangle – the destination rectangle
source_rectangle – the source rectangle
color – the color
rotation – the rotation angle
origin – the origin
layer_depth – the depth of the sprite

void binocle_sprite_draw_dst_src_color(binocle_sprite_batch *batch, struct binocle_material *material, kmAABB2 destination_rectangle, kmAABB2 source_rectangle, sg_color color)

Draws a sprite to the batch.

Parameters:

batch – the sprite batch
material – the material
destination_rectangle – the destination rectangle
source_rectangle – the source rectangle
color – the color

void binocle_sprite_batch_set_sort_mode(binocle_sprite_batch *batch, binocle_sprite_sort_mode mode)

Set the sorting mode of the sprite batch.

Parameters:

batch – the sprite batch
mode – the sorting mode

struct binocle_sprite_frame

#include <binocle_sprite.h>

The single frame of a sprite, mainly used within animations

Public Members

binocle_subtexture *subtexture: The rectangle of the texture that contains the frame

kmVec2 origin: The origin of this frame which can be different from the origin of the sprite

struct binocle_sprite_animation_frame_mapping

#include <binocle_sprite.h>

The mapping of a frame within an animation

Public Members

char *name

int original_frame

int real_frame

struct binocle_sprite_animation

#include <binocle_sprite.h>

A sprite animation

Public Members

int frames[BINOCLE_SPRITE_MAX_FRAMES]: The array of indexes of the frames into the frames array on the owning sprite

float delays[BINOCLE_SPRITE_MAX_FRAMES]: The array with the delay of each animation frame (how long each frame will be drawn in ???uom???)

bool looping: If true, the animation should be played in a loop

int frames_number: The number of frames that make up the animation

char *name

The name of the animation. This is used both for display purposes and to look up the animation when playing using the name instead of the id.

TODO: the lookup algorithm could be replaced with a hash lookup rather than string comparison for performance reasons

binocle_sprite_animation_frame_mapping frame_mapping[BINOCLE_SPRITE_MAX_FRAMES]: The array with the mappings of the frames of animation to the frames stored in the sprite

int frame_mapping_number: The count of frame mappings

struct binocle_sprite

#include <binocle_sprite.h>

A sprite

Public Members

binocle_subtexture subtexture: The default subtexture used to draw the sprite when there are no animations associated

struct binocle_material *material: The material being used by this sprite

kmVec2 origin: The origin of the sprite (normalized 0.0 -> 1.0 in both axis). (0, 0) is the bottom left of the subtexture.

binocle_sprite_animation *animations: The array with all the animations available for this sprite

int animations_number: The count of animations defined or this sprite and stored in the animations array

binocle_sprite_frame *frames

The array with all the frames that are being used by the animations. One animation can refer to more than one frame and one frame can be used by more than one animation.

This is stored on the sprite to avoid duplicating the same frames on each animation that shares the same frame(s).

int frames_number: The number of frames in the frames array

bool playing: Whether the animation is currently playing

bool finished: Whether the animation has finished playing

float rate: The rate multiplier used to speed up or slow down the animation being played. By default this is set to 1.

int current_frame: The index of the current frame of the animation being displayed (index on the frames array)

binocle_sprite_animation *current_animation: The pointer to the animation that is being played (if any)

int current_animation_id: The id of the animation currently being played

int current_animation_frame: The index of the current frame of animation (index on the frames array inside the animations array)

float timer: The internal timer used to keep the animation in sync and track the updates

binocle_subtexture *subtextures: Array with all the subtextures that will be used by animations

struct binocle_sprite_batch_item

#include <binocle_sprite.h>

An item of the sprite batch

Public Members

struct binocle_material *material

binocle_vpct vertex_tl

binocle_vpct vertex_tr

binocle_vpct vertex_bl

binocle_vpct vertex_br

float sort_key

struct binocle_sprite_batcher

#include <binocle_sprite.h>

The sprite batcher

Public Members

uint64_t initial_batch_size

uint64_t max_batch_size

uint64_t initial_vertex_array_size

binocle_sprite_batch_item *batch_item_list

uint64_t batch_item_list_size

uint64_t batch_item_list_capacity

uint64_t *index

uint64_t index_size

uint64_t index_capacity

binocle_vpct *vertex_array

uint64_t vertex_array_size

uint64_t vertex_array_capacity

struct binocle_sprite_batch

#include <binocle_sprite.h>

A sprite batch

Public Members

binocle_sprite_batcher batcher

binocle_render_state render_state

struct binocle_gd *gd

bool begin_called

kmMat4 matrix

kmAABB2 temp_rect

kmVec2 tex_coord_tl

kmVec2 tex_coord_br

kmVec2 scaled_origin

kmAABB2 origin_rect

binocle_sprite_sort_mode sort_mode

kmAABB2 cull_rect

kmVec2 vertex_to_cull_tl

kmVec2 vertex_to_cull_tr

kmVec2 vertex_to_cull_bl

kmVec2 vertex_to_cull_br