Skip to content

API Reference

Jump to bottom
NtinosTheGamer2324 edited this page Mar 7, 2026 · 1 revision

BlitEngine API Reference

Complete reference for all BlitEngine functions.

Table of Contents

Engine Core

blit_init

Initialize the BlitEngine.

int blit_init(BlitEngine *engine);

Parameters:

  • engine - Pointer to BlitEngine structure to initialize

Returns:

  • 0 on success
  • -1 on failure

Example:

BlitEngine engine;
if (blit_init(&engine) != 0) {
    printf("Failed to initialize!\n");
    return 1;
}

Notes:

  • Call this once at program start
  • Initializes NodGL, opens input devices, gets screen resolution
  • Must call blit_shutdown() when done

blit_shutdown

Shutdown the BlitEngine and clean up resources.

void blit_shutdown(BlitEngine *engine);

Parameters:

  • engine - Engine to shut down

Example:

blit_shutdown(&engine);

Notes:

  • Call this once at program end
  • Releases NodGL resources and closes input devices

blit_update_input

Update input state for the current frame.

void blit_update_input(BlitEngine *engine);

Parameters:

  • engine - Engine instance

Example:

while (blit_is_running(&engine)) {
    blit_update_input(&engine);  // Always first in loop!
    // ... game logic ...
}

Notes:

  • Call once per frame at the start of your game loop
  • Reads keyboard and mouse events
  • Updates engine.input structure

blit_is_running

Check if the engine should keep running.

int blit_is_running(BlitEngine *engine);

Parameters:

  • engine - Engine instance

Returns:

  • 1 if running
  • 0 if should exit

Example:

while (blit_is_running(&engine)) {
    // Game loop
}

blit_begin_frame

Begin a new frame and clear the screen.

void blit_begin_frame(BlitEngine *engine, uint32_t clear_color);

Parameters:

  • engine - Engine instance
  • clear_color - Color to clear screen to (ARGB format: 0xAARRGGBB)

Example:

blit_begin_frame(&engine, 0xFF000020);  // Dark blue

Notes:

  • Call once per frame before drawing
  • Clears the entire screen to the specified color

blit_end_frame

End the current frame and present to screen.

void blit_end_frame(BlitEngine *engine);

Parameters:

  • engine - Engine instance

Example:

blit_end_frame(&engine);

Notes:

  • Call once per frame after all drawing
  • Presents the frame to the screen
  • Increments frame counter
  • Yields CPU to other processes

Sprites

blit_sprite_create

Create a sprite from pixel data.

Sprite* blit_sprite_create(BlitEngine *engine, int width, int height, uint32_t *pixels);

Parameters:

  • engine - Engine instance
  • width - Sprite width in pixels
  • height - Sprite height in pixels
  • pixels - Pixel data array (ARGB format)

Returns:

  • Pointer to created sprite, or NULL on failure

Example:

uint32_t pixels[32 * 32];
// Fill pixels array...
Sprite *sprite = blit_sprite_create(&engine, 32, 32, pixels);

blit_sprite_create_color

Create a solid color sprite.

Sprite* blit_sprite_create_color(BlitEngine *engine, int width, int height, uint32_t color);

Parameters:

  • engine - Engine instance
  • width - Sprite width
  • height - Sprite height
  • color - Fill color (ARGB: 0xAARRGGBB)

Returns:

  • Pointer to created sprite, or NULL on failure

Example:

Sprite *red_square = blit_sprite_create_color(&engine, 32, 32, 0xFFFF0000);

blit_sprite_create_circle

Create a circular sprite.

Sprite* blit_sprite_create_circle(BlitEngine *engine, int radius, uint32_t color);

Parameters:

  • engine - Engine instance
  • radius - Circle radius in pixels
  • color - Circle color (ARGB)

Returns:

  • Pointer to created sprite, or NULL on failure

Example:

Sprite *blue_ball = blit_sprite_create_circle(&engine, 16, 0xFF0000FF);

Notes:

  • Creates a sprite of size radius*2 x radius*2
  • Areas outside circle are transparent

blit_sprite_free

Free a sprite and release its resources.

void blit_sprite_free(BlitEngine *engine, Sprite *sprite);

Parameters:

  • engine - Engine instance
  • sprite - Sprite to free

Example:

blit_sprite_free(&engine, my_sprite);

blit_sprite_draw

Draw a sprite at a position.

void blit_sprite_draw(BlitEngine *engine, Sprite *sprite, int x, int y);

Parameters:

  • engine - Engine instance
  • sprite - Sprite to draw
  • x - X position (top-left)
  • y - Y position (top-left)

Example:

blit_sprite_draw(&engine, player_sprite, 100, 200);

Entities

blit_entity_create

Create a game entity.

Entity* blit_entity_create(float x, float y, int width, int height, Sprite *sprite);

Parameters:

  • x - Initial X position
  • y - Initial Y position
  • width - Width for collision (not visual size)
  • height - Height for collision
  • sprite - Visual appearance (can be NULL)

Returns:

  • Pointer to created entity, or NULL on failure

Example:

Entity *player = blit_entity_create(100, 100, 32, 32, player_sprite);

blit_entity_free

Free an entity.

void blit_entity_free(Entity *entity);

Parameters:

  • entity - Entity to free

Example:

blit_entity_free(player);

Notes:

  • Does NOT free the entity's sprite (free that separately)

blit_entity_update

Update entity position based on velocity.

void blit_entity_update(Entity *entity);

Parameters:

  • entity - Entity to update

Example:

entity->vx = 5;
entity->vy = -2;
blit_entity_update(entity);  // Moves entity by (5, -2)

Notes:

  • Adds vx to x and vy to y

blit_entity_draw

Draw an entity.

void blit_entity_draw(BlitEngine *engine, Entity *entity);

Parameters:

  • engine - Engine instance
  • entity - Entity to draw

Example:

blit_entity_draw(&engine, player);

Notes:

  • Only draws if entity is active and has a sprite

blit_entity_collides

Check if two entities collide.

int blit_entity_collides(Entity *a, Entity *b);

Parameters:

  • a - First entity
  • b - Second entity

Returns:

  • 1 if colliding
  • 0 if not colliding

Example:

if (blit_entity_collides(player, enemy)) {
    printf("Hit!\n");
}

blit_entity_on_screen

Check if entity is visible on screen.

int blit_entity_on_screen(BlitEngine *engine, Entity *entity);

Parameters:

  • engine - Engine instance
  • entity - Entity to check

Returns:

  • 1 if on screen
  • 0 if off screen

Example:

if (blit_entity_on_screen(&engine, bullet)) {
    blit_entity_draw(&engine, bullet);
}

blit_entity_clamp_to_screen

Keep entity within screen bounds.

void blit_entity_clamp_to_screen(BlitEngine *engine, Entity *entity);

Parameters:

  • engine - Engine instance
  • entity - Entity to clamp

Example:

blit_entity_clamp_to_screen(&engine, player);

Drawing

blit_draw_rect

Draw a filled rectangle.

void blit_draw_rect(BlitEngine *engine, int x, int y, int w, int h, uint32_t color);

Parameters:

  • engine - Engine instance
  • x, y - Position
  • w, h - Size
  • color - Fill color (ARGB)

Example:

blit_draw_rect(&engine, 50, 50, 100, 80, 0xFFFF0000);

blit_draw_rect_outline

Draw a rectangle outline.

void blit_draw_rect_outline(BlitEngine *engine, int x, int y, int w, int h, uint32_t color, int thickness);

Parameters:

  • engine - Engine instance
  • x, y - Position
  • w, h - Size
  • color - Line color (ARGB)
  • thickness - Line thickness in pixels

Example:

blit_draw_rect_outline(&engine, 50, 50, 100, 80, 0xFF00FF00, 3);

blit_draw_line

Draw a line.

void blit_draw_line(BlitEngine *engine, int x0, int y0, int x1, int y1, uint32_t color, int thickness);

Parameters:

  • engine - Engine instance
  • x0, y0 - Start point
  • x1, y1 - End point
  • color - Line color (ARGB)
  • thickness - Line thickness

Example:

blit_draw_line(&engine, 0, 0, 100, 100, 0xFFFFFFFF, 2);

blit_draw_circle

Draw a filled circle.

void blit_draw_circle(BlitEngine *engine, int cx, int cy, int radius, uint32_t color);

Parameters:

  • engine - Engine instance
  • cx, cy - Center point
  • radius - Circle radius
  • color - Fill color (ARGB)

Example:

blit_draw_circle(&engine, 200, 200, 30, 0xFF0000FF);

blit_draw_text

Draw simple text.

void blit_draw_text(BlitEngine *engine, const char *text, int x, int y, uint32_t color);

Parameters:

  • engine - Engine instance
  • text - Text string to draw
  • x, y - Position
  • color - Text color (ARGB)

Example:

blit_draw_text(&engine, "Score: 100", 10, 10, 0xFFFFFFFF);

Notes:

  • Simple bitmap font (6x12 pixels per character)
  • Each character is drawn as a small rectangle

Collision & Math

blit_rects_overlap

Check if two rectangles overlap.

int blit_rects_overlap(int x1, int y1, int w1, int h1, int x2, int y2, int w2, int h2);

Returns:

  • 1 if overlapping
  • 0 if not overlapping

blit_point_in_rect

Check if a point is inside a rectangle.

int blit_point_in_rect(int px, int py, int rx, int ry, int rw, int rh);

Returns:

  • 1 if inside
  • 0 if outside

blit_distance

Calculate distance between two points.

float blit_distance(float x1, float y1, float x2, float y2);

Returns:

  • Approximate distance (Manhattan distance)

blit_clamp

Clamp a value between min and max.

float blit_clamp(float value, float min, float max);

Example:

health = blit_clamp(health, 0, 100);

blit_random_int

Get a random integer.

int blit_random_int(int min, int max);

Parameters:

  • min - Minimum value (inclusive)
  • max - Maximum value (inclusive)

Returns:

  • Random integer between min and max

Example:

int dice = blit_random_int(1, 6);

blit_random_float

Get a random float between 0 and 1.

float blit_random_float(void);

Returns:

  • Random float between 0.0 and 1.0

Example:

if (blit_random_float() < 0.1) {  // 10% chance
    spawn_powerup();
}

Input

blit_key_down

Check if a key is currently held down.

int blit_key_down(BlitEngine *engine, int keycode);

Returns:

  • 1 if key is down
  • 0 if key is up

Example:

if (blit_key_down(&engine, KEY_W)) {
    player_y -= 3;
}

blit_key_pressed

Check if a key was just pressed this frame.

int blit_key_pressed(BlitEngine *engine, int keycode);

Returns:

  • 1 if just pressed
  • 0 otherwise

Example:

if (blit_key_pressed(&engine, KEY_SPACE)) {
    fire_weapon();  // Only fires once per press
}

blit_mouse_down

Check if mouse button is held down.

int blit_mouse_down(BlitEngine *engine, int button);

Parameters:

  • button - MOUSE_LEFT, MOUSE_RIGHT, or MOUSE_MIDDLE

Returns:

  • 1 if button is down
  • 0 if button is up

blit_mouse_clicked

Check if mouse button was just clicked.

int blit_mouse_clicked(BlitEngine *engine, int button);

Returns:

  • 1 if just clicked
  • 0 otherwise

Constants

Key Codes

KEY_ESC     // Escape key
KEY_SPACE   // Space bar
KEY_ENTER   // Enter/Return

KEY_W, KEY_A, KEY_S, KEY_D  // WASD keys
KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT  // Arrow keys

KEY_1, KEY_2, KEY_3  // Number keys

Mouse Buttons

MOUSE_LEFT    // Left mouse button
MOUSE_RIGHT   // Right mouse button
MOUSE_MIDDLE  // Middle mouse button

BlitEngine Structure

typedef struct {
    NodGL_Device device;      // Graphics device
    NodGL_Context ctx;        // Graphics context
    uint32_t screen_width;    // Screen width in pixels
    uint32_t screen_height;   // Screen height in pixels
    int event_queue_fd;       // Input event file descriptor
    Input input;              // Current input state
    int running;              // Is engine running?
    uint32_t frame_count;     // Total frames rendered
} BlitEngine;

Accessing Engine Data

int w = engine.screen_width;
int h = engine.screen_height;
int mx = engine.input.mouse_x;
int my = engine.input.mouse_y;
int buttons = engine.input.mouse_buttons;
uint32_t frames = engine.frame_count;

Entity Structure

typedef struct {
    float x, y;          // Position
    float vx, vy;        // Velocity
    int width, height;   // Size (for collision)
    Sprite *sprite;      // Visual appearance
    int active;          // Is entity active?
    void *user_data;     // Custom game data
} Entity;

Back to: BlitEngine Introduction

Clone this wiki locally