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)¶

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

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 sg_image *texture)¶

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
texture – the texture

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 sg_image *texture, struct binocle_render_state *render_state, struct binocle_gd *gd)¶

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
texture – the texture to use
render_state – the current render state
gd – the graphics device

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 sg_image *texture, kmAABB2 *source_rectangle, sg_color color, float rotation, float depth, bool auto_flush)¶

Draws a sprite (Used internally)

Parameters

batch – the sprite batch
texture – the texture
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 sg_image *texture, 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
texture – the texture
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 sg_image *texture, 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
texture – the texture
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 sg_image *texture, 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
texture – the texture
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 sg_image *texture, kmVec2 position)¶

Draws a sprite to the batch.

Parameters

batch – the sprite batch
texture – the texture
position – the position

void binocle_sprite_batch_draw_noscale(binocle_sprite_batch *batch, struct sg_image *texture, 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
texture – the texture
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 sg_image *texture, kmAABB2 destination_rectangle, kmAABB2 source_rectangle, sg_color color)¶

Draws a sprite to the batch.

Parameters

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

struct binocle_sprite_frame

#include <binocle_sprite.h>

The single frame of a sprite, mainly used within animations

Public Members

binocle_subtexture *subtexture¶

kmVec2 origin¶

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

bool enabled¶

int frames[BINOCLE_SPRITE_MAX_FRAMES]¶

float delays[BINOCLE_SPRITE_MAX_FRAMES]¶

bool looping¶

int frames_number¶

char *name¶

binocle_sprite_animation_frame_mapping frame_mapping[BINOCLE_SPRITE_MAX_FRAMES]¶

int frame_mapping_number¶

struct binocle_sprite

#include <binocle_sprite.h>

A sprite

Public Members

binocle_subtexture subtexture¶

struct binocle_material *material¶

kmVec2 origin¶

binocle_sprite_animation *animations¶

binocle_sprite_frame *frames¶

int frames_number¶

bool playing¶

bool finished¶

float rate¶

int current_frame¶

binocle_sprite_animation *current_animation¶

int animations_number¶

int current_animation_id¶

int current_animation_frame¶

float timer¶

struct binocle_sprite_batch_item

#include <binocle_sprite.h>

An item of the sprite batch

Public Members

struct sg_image *texture¶

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¶