Skip to content

API.md

Latest commit

 

History

History
651 lines (486 loc) · 10.4 KB

API.md

File metadata and controls

651 lines (486 loc) · 10.4 KB
Raw

Piper Framework API Reference

Complete API documentation for the Piper game framework.

Table of Contents

  1. Core Framework
  2. Graphics
  3. Input
  4. Text Rendering
  5. Math Utilities
  6. Constants

Core Framework

Initialization and Lifecycle

InitGame

bool InitGame(int width, int height, const char* title);

Initializes the game window and framework systems.

Parameters:

  • width - Window width in pixels
  • height - Window height in pixels
  • title - Window title string

Returns: true on success, false on failure

Example:

if (!InitGame(800, 600, "My Game")) {
    return -1;
}

GameShouldClose

bool GameShouldClose(void);

Checks if the window should close (user clicked X or pressed ESC).

Returns: true if window should close

BeginFrame

void BeginFrame(void);

Starts a new frame. Call this at the beginning of your game loop.

  • Processes input events
  • Updates delta time
  • Sets up 2D rendering context

EndFrame

void EndFrame(void);

Finishes the current frame and presents it to the window.

CloseGame

void CloseGame(void);

Cleans up and closes the game. Call before exiting.

Time

GetDeltaTime

float GetDeltaTime(void);

Gets the time in seconds since the last frame.

Returns: Time in seconds (float)

Example:

float speed = 200.0f; // pixels per second
float dt = GetDeltaTime();
x += speed * dt; // Frame-independent movement

Screen

GetScreenWidth

int GetScreenWidth(void);

Gets the screen width in pixels.

GetScreenHeight

int GetScreenHeight(void);

Gets the screen height in pixels.

Graphics

Colors

Color Structure

typedef struct {
    float r, g, b, a; // Range: 0.0 to 1.0
} Color;

MakeColor

Color MakeColor(int r, int g, int b, int a);

Creates a color from 0-255 RGB values.

Parameters:

  • r, g, b, a - Color components (0-255)

MakeColorF

Color MakeColorF(float r, float g, float b, float a);

Creates a color from 0.0-1.0 float values.

SetDrawColor

void SetDrawColor(Color color);

Sets the current drawing color for shapes.

Background

ClearBackground

void ClearBackground(Color color);

Clears the screen with the specified color.

Shape Drawing (Filled)

DrawRectangle

void DrawRectangle(float x, float y, float width, float height);

Draws a filled rectangle.

Parameters:

  • x, y - Top-left corner position
  • width, height - Rectangle dimensions

DrawCircle

void DrawCircle(float x, float y, float radius);

Draws a filled circle.

Parameters:

  • x, y - Center position
  • radius - Circle radius

DrawTriangle

void DrawTriangle(float x1, float y1, float x2, float y2, float x3, float y3);

Draws a filled triangle.

Parameters:

  • x1, y1 - First vertex
  • x2, y2 - Second vertex
  • x3, y3 - Third vertex

DrawPolygon

void DrawPolygon(float* points, int numPoints);

Draws a filled polygon.

Parameters:

  • points - Array of x,y coordinates [x1, y1, x2, y2, ...]
  • numPoints - Number of vertices

Shape Drawing (Lines)

DrawLine

void DrawLine(float x1, float y1, float x2, float y2, float thickness);

Draws a line between two points.

DrawRectangleLines

void DrawRectangleLines(float x, float y, float width, float height, float thickness);

Draws a rectangle outline.

DrawCircleLines

void DrawCircleLines(float x, float y, float radius, float thickness);

Draws a circle outline.

Textures

Texture Structure

typedef struct {
    unsigned int id;
    int width;
    int height;
} Texture;

LoadTexture

Texture* LoadTexture(const char* filename);

Loads a texture from file (PNG, JPG, BMP, TGA supported).

Returns: Pointer to texture or NULL on failure

DrawTexture

void DrawTexture(Texture* texture, float x, float y);

Draws texture at position with original size.

DrawTextureEx

void DrawTextureEx(Texture* texture, float x, float y, float width, float height, 
                   float rotation, Color tint);

Draws texture with transformations.

Parameters:

  • rotation - Rotation in degrees
  • tint - Color tint to apply

DrawTexturePart

void DrawTexturePart(Texture* texture, 
                     float srcX, float srcY, float srcWidth, float srcHeight,
                     float destX, float destY, float destWidth, float destHeight);

Draws a portion of a texture (for sprite sheets).

UnloadTexture

void UnloadTexture(Texture* texture);

Frees texture memory.

Camera

Camera2D Structure

typedef struct {
    float x, y;         // Position
    float zoom;         // Scale factor (1.0 = normal)
    float rotation;     // Rotation in degrees
} Camera2D;

BeginCamera

void BeginCamera(Camera2D camera);

Begins 2D camera mode.

EndCamera

void EndCamera(void);

Ends camera mode.

Example:

Camera2D cam = {0, 0, 1.0f, 0};
BeginCamera(cam);
// Draw world objects
EndCamera();
// Draw UI (not affected by camera)

Input

Keyboard

IsKeyDown

bool IsKeyDown(int key);

Checks if key is currently held down.

IsKeyPressed

bool IsKeyPressed(int key);

Checks if key was just pressed this frame.

Key Constants

KEY_SPACE, KEY_ESCAPE
KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT
KEY_W, KEY_S, KEY_A, KEY_D

Mouse

GetMousePosition

void GetMousePosition(int* x, int* y);

Gets current mouse cursor position.

Example:

int mx, my;
GetMousePosition(&mx, &my);

IsMouseButtonDown

bool IsMouseButtonDown(int button);

Checks if mouse button is currently held.

IsMouseButtonPressed

bool IsMouseButtonPressed(int button);

Checks if mouse button was just pressed this frame.

IsMouseButtonReleased

bool IsMouseButtonReleased(int button);

Checks if mouse button was just released this frame.

Mouse Button Constants

MOUSE_LEFT   (0)
MOUSE_MIDDLE (1)
MOUSE_RIGHT  (2)

Text Rendering

Font Management

Font Structure

typedef struct Font Font; // Opaque

LoadFont

Font* LoadFont(const char* fontPath, float fontSize);

Loads a TrueType font from file.

Parameters:

  • fontPath - Path to .ttf font file
  • fontSize - Font size in pixels

Returns: Pointer to font or NULL on failure

LoadFontFromMemory

Font* LoadFontFromMemory(unsigned char* fontData, int dataSize, float fontSize);

Loads font from memory buffer.

UnloadFont

void UnloadFont(Font* font);

Frees font memory.

Text Drawing

RenderText

void RenderText(Font* font, const char* text, float x, float y, Color color);

Renders text at position.

RenderTextEx

void RenderTextEx(Font* font, const char* text, float x, float y, float spacing, Color color);

Renders text with custom spacing.

Parameters:

  • spacing - Additional space between characters

Text Measurement

MeasureText

float MeasureText(Font* font, const char* text);

Returns the width of text in pixels.

GetTextHeight

float GetTextHeight(Font* font);

Returns the line height for the font.

Math Utilities

Vector2

Type Definition

typedef vec2 Vector2; // float[2]

Vector2Make

void Vector2Make(Vector2 result, float x, float y);

Creates a 2D vector.

Example:

Vector2 pos;
Vector2Make(pos, 100, 200);

Vector2 Operations

float Vector2Length(Vector2 v);              // Length/magnitude
float Vector2Distance(Vector2 a, Vector2 b); // Distance between points
float Vector2Dot(Vector2 a, Vector2 b);      // Dot product
float Vector2Angle(Vector2 v);               // Angle in radians

void Vector2Normalize(Vector2 result, Vector2 v);           // Normalize to unit length
void Vector2Rotate(Vector2 result, Vector2 v, float angle); // Rotate by angle
void Vector2Lerp(Vector2 result, Vector2 a, Vector2 b, float t); // Linear interpolation

Linmath Operations

You also have access to all vec2 functions from linmath.h:

vec2_add(r, a, b);      // Add vectors
vec2_sub(r, a, b);      // Subtract vectors
vec2_scale(r, v, s);    // Scale by scalar
vec2_mul_inner(a, b);   // Dot product

Transform2D

Structure

typedef struct Transform2D {
    Vector2 position;
    float rotation;  // Radians
    Vector2 scale;
} Transform2D;

Transform2DMake

Transform2D Transform2DMake(float x, float y, float rotation, 
                            float scaleX, float scaleY);

Transform2DApply

void Transform2DApply(Vector2 result, Transform2D const* transform, Vector2 point);

Applies transformation to a point.

Utility Functions

float Clamp(float value, float min, float max);
float Lerp(float a, float b, float t);
float MapRange(float value, float inMin, float inMax, float outMin, float outMax);
float ToRadians(float degrees);
float ToDegrees(float radians);

Constants

Pre-defined Colors

COLOR_WHITE
COLOR_BLACK
COLOR_RED
COLOR_GREEN
COLOR_BLUE
COLOR_YELLOW
COLOR_CYAN
COLOR_MAGENTA
COLOR_ORANGE
COLOR_PURPLE
COLOR_GRAY
COLOR_DARKGRAY
COLOR_LIGHTGRAY

Math Constants

PI      = 3.14159265358979323846
DEG2RAD = PI / 180.0
RAD2DEG = 180.0 / PI

Usage Examples

Complete Game Loop

#define PIPER_IMPLEMENTATION
#define RGFWDEF
#include "piper.h"

int main() {
    InitGame(800, 600, "Game");
    
    while (!GameShouldClose()) {
        BeginFrame();
        
        ClearBackground(COLOR_BLACK);
        
        // Your game code here
        
        EndFrame();
    }
    
    CloseGame();
    return 0;
}

Movement with Vectors

Vector2 position, velocity;
Vector2Make(position, 400, 300);
Vector2Make(velocity, 100, 0);

// In game loop:
Vector2 vel;
vec2_scale(vel, velocity, GetDeltaTime());
vec2_add(position, position, vel);

For more examples, see the examples/ directory and TUTORIAL.md.