The Null0 API is exposed to several languages, but we try to keep the syntax mostly the same. See docs/templates for individual languages for exact syntax. This page is more about what you can do with null0. I will use C-like pseudo-code to describe everything here.
defines
These are pre-defined constants you can use
#define SCREEN 0
#define SCREEN_WIDTH 640
#define SCREEN_HEIGHT 480
#define FONT_DEFAULT 0
// some pre-defined colors
Color LIGHTGRAY = (Color){.r = 200, .g = 200, .b = 200, .a = 255};
Color GRAY = (Color){.r = 130, .g = 130, .b = 130, .a = 255};
Color DARKGRAY = (Color){.r = 80, .g = 80, .b = 80, .a = 255};
Color YELLOW = (Color){.r = 253, .g = 249, .b = 0, .a = 255};
Color GOLD = (Color){.r = 255, .g = 203, .b = 0, .a = 255};
Color ORANGE = (Color){.r = 255, .g = 161, .b = 0, .a = 255};
Color PINK = (Color){.r = 255, .g = 109, .b = 194, .a = 255};
Color RED = (Color){.r = 230, .g = 41, .b = 55, .a = 255};
Color MAROON = (Color){.r = 190, .g = 33, .b = 55, .a = 255};
Color GREEN = (Color){.r = 0, .g = 228, .b = 48, .a = 255};
Color LIME = (Color){.r = 0, .g = 158, .b = 47, .a = 255};
Color DARKGREEN = (Color){.r = 0, .g = 117, .b = 44, .a = 255};
Color SKYBLUE = (Color){.r = 102, .g = 191, .b = 255, .a = 255};
Color BLUE = (Color){.r = 0, .g = 121, .b = 241, .a = 255};
Color DARKBLUE = (Color){.r = 0, .g = 82, .b = 172, .a = 255};
Color PURPLE = (Color){.r = 200, .g = 122, .b = 255, .a = 255};
Color VIOLET = (Color){.r = 135, .g = 60, .b = 190, .a = 255};
Color DARKPURPLE = (Color){.r = 112, .g = 31, .b = 126, .a = 255};
Color BEIGE = (Color){.r = 211, .g = 176, .b = 131, .a = 255};
Color BROWN = (Color){.r = 127, .g = 106, .b = 79, .a = 255};
Color DARKBROWN = (Color){.r = 76, .g = 63, .b = 47, .a = 255};
Color WHITE = (Color){.r = 255, .g = 255, .b = 255, .a = 255};
Color BLACK = (Color){.r = 0, .g = 0, .b = 0, .a = 255};
Color BLANK = (Color){.r = 0, .g = 0, .b = 0, .a = 0};
Color MAGENTA = (Color){.r = 255, .g = 0, .b = 255, .a = 255};
Color RAYWHITE = (Color){.r = 245, .g = 245, .b = 245, .a = 255};types
There are a few types that are used:
// I like shorter type-names
typedef int8_t i8;
typedef int16_t i16;
typedef int32_t i32;
typedef int64_t i64;
typedef uint8_t u8;
typedef uint16_t u16;
typedef uint32_t u32;
typedef uint64_t u64;
typedef float f32;
// these are resource-counters
typedef u32 Image;
typedef u32 Font;
typedef u32 Sound;
// the "size of something"
typedef struct {
u32 width;
u32 height;
} Dimensions;
// the "2D position of something"
typedef struct {
i32 x;
i32 y;
} Vector;
// a rectangle coordinate: "size and position of something"
typedef struct {
i32 x;
i32 y;
i32 width;
i32 height;
} Rectangle;
// an RGBA color
typedef struct {
u8 r;
u8 g;
u8 b;
u8 a;
} Color;
// enum: Filtering operations for resize/etc
typedef enum ImageFilter {
FILTER_NEARESTNEIGHBOR = 0,
FILTER_BILINEAR,
FILTER_SMOOTH
} ImageFilter;
// enum: a key
typedef enum Key {
KEY_INVALID = 0,
KEY_SPACE = 32,
KEY_APOSTROPHE = 39,
KEY_COMMA = 44,
KEY_MINUS = 45,
KEY_PERIOD = 46,
KEY_SLASH = 47,
KEY_0 = 48,
KEY_1 = 49,
KEY_2 = 50,
KEY_3 = 51,
KEY_4 = 52,
KEY_5 = 53,
KEY_6 = 54,
KEY_7 = 55,
KEY_8 = 56,
KEY_9 = 57,
KEY_SEMICOLON = 59,
KEY_EQUAL = 61,
KEY_A = 65,
KEY_B = 66,
KEY_C = 67,
KEY_D = 68,
KEY_E = 69,
KEY_F = 70,
KEY_G = 71,
KEY_H = 72,
KEY_I = 73,
KEY_J = 74,
KEY_K = 75,
KEY_L = 76,
KEY_M = 77,
KEY_N = 78,
KEY_O = 79,
KEY_P = 80,
KEY_Q = 81,
KEY_R = 82,
KEY_S = 83,
KEY_T = 84,
KEY_U = 85,
KEY_V = 86,
KEY_W = 87,
KEY_X = 88,
KEY_Y = 89,
KEY_Z = 90,
KEY_LEFT_BRACKET = 91,
KEY_BACKSLASH = 92,
KEY_RIGHT_BRACKET = 93,
KEY_GRAVE_ACCENT = 96,
KEY_WORLD_1 = 161,
KEY_WORLD_2 = 162,
KEY_ESCAPE = 256,
KEY_ENTER = 257,
KEY_TAB = 258,
KEY_BACKSPACE = 259,
KEY_INSERT = 260,
KEY_DELETE = 261,
KEY_RIGHT = 262,
KEY_LEFT = 263,
KEY_DOWN = 264,
KEY_UP = 265,
KEY_PAGE_UP = 266,
KEY_PAGE_DOWN = 267,
KEY_HOME = 268,
KEY_END = 269,
KEY_CAPS_LOCK = 280,
KEY_SCROLL_LOCK = 281,
KEY_NUM_LOCK = 282,
KEY_PRINT_SCREEN = 283,
KEY_PAUSE = 284,
KEY_F1 = 290,
KEY_F2 = 291,
KEY_F3 = 292,
KEY_F4 = 293,
KEY_F5 = 294,
KEY_F6 = 295,
KEY_F7 = 296,
KEY_F8 = 297,
KEY_F9 = 298,
KEY_F10 = 299,
KEY_F11 = 300,
KEY_F12 = 301,
KEY_F13 = 302,
KEY_F14 = 303,
KEY_F15 = 304,
KEY_F16 = 305,
KEY_F17 = 306,
KEY_F18 = 307,
KEY_F19 = 308,
KEY_F20 = 309,
KEY_F21 = 310,
KEY_F22 = 311,
KEY_F23 = 312,
KEY_F24 = 313,
KEY_F25 = 314,
KEY_KP_0 = 320,
KEY_KP_1 = 321,
KEY_KP_2 = 322,
KEY_KP_3 = 323,
KEY_KP_4 = 324,
KEY_KP_5 = 325,
KEY_KP_6 = 326,
KEY_KP_7 = 327,
KEY_KP_8 = 328,
KEY_KP_9 = 329,
KEY_KP_DECIMAL = 330,
KEY_KP_DIVIDE = 331,
KEY_KP_MULTIPLY = 332,
KEY_KP_SUBTRACT = 333,
KEY_KP_ADD = 334,
KEY_KP_ENTER = 335,
KEY_KP_EQUAL = 336,
KEY_LEFT_SHIFT = 340,
KEY_LEFT_CONTROL = 341,
KEY_LEFT_ALT = 342,
KEY_LEFT_SUPER = 343,
KEY_RIGHT_SHIFT = 344,
KEY_RIGHT_CONTROL = 345,
KEY_RIGHT_ALT = 346,
KEY_RIGHT_SUPER = 347,
KEY_MENU = 348,
} Key;
// enum: a gamepad button
typedef enum GamepadButton {
GAMEPAD_BUTTON_UNKNOWN = 0, // Unknown button, just for error checking
GAMEPAD_BUTTON_UP = 1, // Gamepad left DPAD up button
GAMEPAD_BUTTON_RIGHT = 2, // Gamepad left DPAD right button
GAMEPAD_BUTTON_DOWN = 3, // Gamepad left DPAD down button
GAMEPAD_BUTTON_LEFT = 4, // Gamepad left DPAD left button
GAMEPAD_BUTTON_Y= 5, // Gamepad right button up (i.e. PS3: Triangle, Xbox: Y)
GAMEPAD_BUTTON_B = 6, // Gamepad right button right (i.e. PS3: Square, Xbox: X)
GAMEPAD_BUTTON_A = 7, // Gamepad right button down (i.e. PS3: Cross, Xbox: A)
GAMEPAD_BUTTON_X = 8, // Gamepad right button left (i.e. PS3: Circle, Xbox: B)
GAMEPAD_BUTTON_LEFT_SHOULDER = 9, // Gamepad top/back trigger left (first), it could be a trailing button
GAMEPAD_BUTTON_LEFT_TRIGGER = 10, // Gamepad top/back trigger left (second), it could be a trailing button
GAMEPAD_BUTTON_RIGHT_SHOULDER = 11, // Gamepad top/back trigger right (one), it could be a trailing button
GAMEPAD_BUTTON_RIGHT_TRIGGER = 12, // Gamepad top/back trigger right (second), it could be a trailing button
GAMEPAD_BUTTON_SELECT = 13, // Gamepad center buttons, left one (i.e. PS3: Select)
GAMEPAD_BUTTON_MENU = 14, // Gamepad center buttons, middle one (i.e. PS3: PS, Xbox: XBOX)
GAMEPAD_BUTTON_START = 15, // Gamepad center buttons, right one (i.e. PS3: Start)
GAMEPAD_BUTTON_LEFT_THUMB = 16, // Gamepad joystick pressed button left
GAMEPAD_BUTTON_RIGHT_THUMB = 17, // Gamepad joystick pressed button right
} GamepadButton;
// enum: a mouse button
typedef enum MouseButton {
MOUSE_BUTTON_UNKNOWN = 0,
MOUSE_BUTTON_LEFT = 1,
MOUSE_BUTTON_RIGHT = 2,
MOUSE_BUTTON_MIDDLE = 3,
} MouseButton;utilities
current_time
Get system-time (ms) since unix epoch
u64 current_time()delta_time
Get the change in time (seconds) since the last update run
f32 delta_time()random_int
Get a random integer between 2 numbers
i32 random_int(i32 min, i32 max)random_seed_get
Get the random-seed
u64 random_seed_get()random_seed_set
Set the random-seed
void random_seed_set(u64 seed)sound
load_sound
Load a sound from a file in cart
Sound load_sound(string filename)play_sound
Play a sound
void play_sound(Sound sound, bool loop)stop_sound
Stop a sound
void stop_sound(Sound sound)unload_sound
Unload a sound
void unload_sound(Sound sound)input
key_pressed
Has the key been pressed? (tracks unpress/read correctly)
bool key_pressed(Key key)key_down
Is the key currently down?
bool key_down(Key key)key_released
Has the key been released? (tracks press/read correctly)
bool key_released(Key key)key_up
Is the key currently up?
bool key_up(Key key)gamepad_button_pressed
Has the button been pressed? (tracks unpress/read correctly)
bool gamepad_button_pressed(i32 gamepad, GamepadButton button)gamepad_button_down
Is the button currently down?
bool gamepad_button_down(i32 gamepad, GamepadButton button)gamepad_button_released
Has the button been released? (tracks press/read correctly)
bool gamepad_button_released(i32 gamepad, GamepadButton button)mouse_position
Get current position of mouse
Vector mouse_position()mouse_button_pressed
Has the button been pressed? (tracks unpress/read correctly)
bool mouse_button_pressed(MouseButton button)mouse_button_down
Is the button currently down?
bool mouse_button_down(MouseButton button)mouse_button_released
Has the button been released? (tracks press/read correctly)
bool mouse_button_released(MouseButton button)mouse_button_up
Is the button currently up?
bool mouse_button_up(MouseButton button)graphics
new_image
Create a new blank image
Image new_image(i32 width, i32 height, Color color)image_copy
Copy an image to a new image
Image image_copy(Image image)image_subimage
Create an image from a region of another image
Image image_subimage(Image image, i32 x, i32 y, i32 width, i32 height)clear
Clear the screen
void clear(Color color)draw_point
Draw a single pixel on the screen
void draw_point(i32 x, i32 y, Color color)draw_line
Draw a line on the screen
void draw_line(i32 startPosX, i32 startPosY, i32 endPosX, i32 endPosY, Color color)draw_rectangle
Draw a filled rectangle on the screen
void draw_rectangle(i32 posX, i32 posY, i32 width, i32 height, Color color)draw_triangle
Draw a filled triangle on the screen
void draw_triangle(i32 x1, i32 y1, i32 x2, i32 y2, i32 x3, i32 y3, Color color)draw_ellipse
Draw a filled ellipse on the screen
void draw_ellipse(i32 centerX, i32 centerY, i32 radiusX, i32 radiusY, Color color)draw_circle
Draw a filled circle on the screen
void draw_circle(i32 centerX, i32 centerY, i32 radius, Color color)draw_polygon
Draw a filled polygon on the screen
void draw_polygon(Vector[] points, i32 numPoints, Color color)draw_arc
Draw a filled arc on the screen
void draw_arc(i32 centerX, i32 centerY, f32 radius, f32 startAngle, f32 endAngle, i32 segments, Color color)draw_rectangle_rounded
Draw a filled round-rectangle on the screen
void draw_rectangle_rounded(i32 x, i32 y, i32 width, i32 height, i32 cornerRadius, Color color)draw_image
Draw an image on the screen
void draw_image(Image src, i32 posX, i32 posY)draw_image_tint
Draw a tinted image on the screen
void draw_image_tint(Image src, i32 posX, i32 posY, Color tint)draw_image_rotated
Draw an image, rotated, on the screen
void draw_image_rotated(Image src, i32 posX, i32 posY, f32 degrees, f32 offsetX, f32 offsetY, ImageFilter filter)draw_image_flipped
Draw an image, flipped, on the screen
void draw_image_flipped(Image src, i32 posX, i32 posY, bool flipHorizontal, bool flipVertical, bool flipDiagonal)draw_image_scaled
Draw an image, scaled, on the screen
void draw_image_scaled(Image src, i32 posX, i32 posY, f32 scaleX, f32 scaleY, f32 offsetX, f32 offsetY, ImageFilter filter)draw_text
Draw some text on the screen
void draw_text(Font font, string text, i32 posX, i32 posY, Color color)save_image
Save an image to persistant storage
void save_image(Image image, string filename)load_image
Load an image from a file in cart
Image load_image(string filename)image_resize
Resize an image, return copy
Image image_resize(Image image, i32 newWidth, i32 newHeight, ImageFilter filter)image_scale
Scale an image, return copy
Image image_scale(Image image, f32 scaleX, f32 scaleY, ImageFilter filter)image_color_replace
Replace a color in an image, in-place
void image_color_replace(Image image, Color color, Color replace)image_color_tint
Tint a color in an image, in-place
void image_color_tint(Image image, Color color)image_color_fade
Fade a color in an image, in-place
void image_color_fade(Image image, f32 alpha)font_copy
Copy a font to a new font
Font font_copy(Font font)font_scale
Scale a font, return a new font
Font font_scale(Font font, f32 scaleX, f32 scaleY, ImageFilter filter)load_font_bmf
Load a BMF font from a file in cart
Font load_font_bmf(string filename, string characters)load_font_bmf_from_image
Load a BMF font from an image
Font load_font_bmf_from_image(Image image, string characters)measure_text
Measure the size of some text
Dimensions measure_text(Font font, string text, i32 textLength)measure_image
Meaure an image (use 0 for screen)
Dimensions measure_image(Image image)load_font_tty
Load a TTY font from a file in cart
Font load_font_tty(string filename, i32 glyphWidth, i32 glyphHeight, string characters)load_font_tty_from_image
Load a TTY font from an image
Font load_font_tty_from_image(Image image, i32 glyphWidth, i32 glyphHeight, string characters)load_font_ttf
Load a TTF font from a file in cart
Font load_font_ttf(string filename, i32 fontSize)image_color_invert
Invert the colors in an image, in-place
void image_color_invert(Image image)image_alpha_border
Calculate a rectangle representing the available alpha border in an image
Rectangle image_alpha_border(Image image, f32 threshold)image_crop
Crop an image, in-place
void image_crop(Image image, i32 x, i32 y, i32 width, i32 height)image_alpha_crop
Crop an image based on the alpha border, in-place
void image_alpha_crop(Image image, f32 threshold)image_color_brightness
Adjust the brightness of an image, in-place
void image_color_brightness(Image image, f32 factor)image_flip
Flip an image, in-place
void image_flip(Image image, bool horizontal, bool vertical)image_color_contrast
Change the contrast of an image, in-place
void image_color_contrast(Image image, f32 contrast)image_alpha_mask
Use an image as an alpha-mask on another image
void image_alpha_mask(Image image, Image alphaMask, i32 posX, i32 posY)image_rotate
Create a new image, rotating another image
Image image_rotate(Image image, f32 degrees, ImageFilter filter)image_gradient
Create a new image of a gradient
Image image_gradient(i32 width, i32 height, Color topLeft, Color topRight, Color bottomLeft, Color bottomRight)unload_image
Unload an image
void unload_image(Image image)unload_font
Unload a font
void unload_font(Font font)clear_image
Clear an image
void clear_image(Image destination, Color color)draw_point_on_image
Draw a single pixel on an image
void draw_point_on_image(Image destination, i32 x, i32 y, Color color)draw_line_on_image
Draw a line on an image
void draw_line_on_image(Image destination, i32 startPosX, i32 startPosY, i32 endPosX, i32 endPosY, Color color)draw_rectangle_on_image
Draw a filled rectangle on an image
void draw_rectangle_on_image(Image destination, i32 posX, i32 posY, i32 width, i32 height, Color color)draw_triangle_on_image
Draw a filled triangle on an image
void draw_triangle_on_image(Image destination, i32 x1, i32 y1, i32 x2, i32 y2, i32 x3, i32 y3, Color color)draw_ellipse_on_image
Draw a filled ellipse on an image
void draw_ellipse_on_image(Image destination, i32 centerX, i32 centerY, i32 radiusX, i32 radiusY, Color color)draw_circle_on_image
Draw a circle on an image
void draw_circle_on_image(Image destination, i32 centerX, i32 centerY, i32 radius, Color color)draw_polygon_on_image
Draw a filled polygon on an image
void draw_polygon_on_image(Image destination, Vector[] points, i32 numPoints, Color color)draw_rectangle_rounded_on_image
Draw a filled round-rectangle on an image
void draw_rectangle_rounded_on_image(Image destination, i32 x, i32 y, i32 width, i32 height, i32 cornerRadius, Color color)draw_image_on_image
Draw an image on an image
void draw_image_on_image(Image destination, Image src, i32 posX, i32 posY)draw_image_tint_on_image
Draw a tinted image on an image
void draw_image_tint_on_image(Image destination, Image src, i32 posX, i32 posY, Color tint)draw_image_rotated_on_image
Draw an image, rotated, on an image
void draw_image_rotated_on_image(Image destination, Image src, i32 posX, i32 posY, f32 degrees, f32 offsetX, f32 offsetY, ImageFilter filter)draw_image_flipped_on_image
Draw an image, flipped, on an image
void draw_image_flipped_on_image(Image destination, Image src, i32 posX, i32 posY, bool flipHorizontal, bool flipVertical, bool flipDiagonal)draw_image_scaled_on_image
Draw an image, scaled, on an image
void draw_image_scaled_on_image(Image destination, Image src, i32 posX, i32 posY, f32 scaleX, f32 scaleY, f32 offsetX, f32 offsetY, ImageFilter filter)draw_text_on_image
Draw some text on an image
void draw_text_on_image(Image destination, Font font, string text, i32 posX, i32 posY, Color color)draw_rectangle_outline
Draw a outlined (with thickness) rectangle on the screen
void draw_rectangle_outline(i32 posX, i32 posY, i32 width, i32 height, i32 thickness, Color color)draw_triangle_outline
Draw a outlined (with thickness) triangle on the screen
void draw_triangle_outline(i32 x1, i32 y1, i32 x2, i32 y2, i32 x3, i32 y3, i32 thickness, Color color)draw_ellipse_outline
Draw a outlined (with thickness) ellipse on the screen
void draw_ellipse_outline(i32 centerX, i32 centerY, i32 radiusX, i32 radiusY, i32 thickness, Color color)draw_circle_outline
Draw a outlined (with thickness) circle on the screen
void draw_circle_outline(i32 centerX, i32 centerY, i32 radius, i32 thickness, Color color)draw_polygon_outline
Draw a outlined (with thickness) polygon on the screen
void draw_polygon_outline(Vector[] points, i32 numPoints, i32 thickness, Color color)draw_arc_outline
Draw a outlined (with thickness) arc on the screen
void draw_arc_outline(i32 centerX, i32 centerY, f32 radius, f32 startAngle, f32 endAngle, i32 segments, i32 thickness, Color color)draw_rectangle_rounded_outline
Draw a outlined (with thickness) round-rectangle on the screen
void draw_rectangle_rounded_outline(i32 x, i32 y, i32 width, i32 height, i32 cornerRadius, i32 thickness, Color color)draw_rectangle_outline_on_image
Draw a outlined (with thickness) rectangle on an image
void draw_rectangle_outline_on_image(Image destination, i32 posX, i32 posY, i32 width, i32 height, i32 thickness, Color color)draw_triangle_outline_on_image
Draw a outlined (with thickness) triangle on an image
void draw_triangle_outline_on_image(Image destination, i32 x1, i32 y1, i32 x2, i32 y2, i32 x3, i32 y3, i32 thickness, Color color)draw_ellipse_outline_on_image
Draw a outlined (with thickness) ellipse on an image
void draw_ellipse_outline_on_image(Image destination, i32 centerX, i32 centerY, i32 radiusX, i32 radiusY, i32 thickness, Color color)draw_circle_outline_on_image
Draw a outlined (with thickness) circle on an image
void draw_circle_outline_on_image(Image destination, i32 centerX, i32 centerY, i32 radius, i32 thickness, Color color)draw_polygon_outline_on_image
Draw a outlined (with thickness) polygon on an image
void draw_polygon_outline_on_image(Image destination, Vector[] points, i32 numPoints, i32 thickness, Color color)draw_rectangle_rounded_outline_on_image
Draw a outlined (with thickness) round-rectangle on an image
void draw_rectangle_rounded_outline_on_image(Image destination, i32 x, i32 y, i32 width, i32 height, i32 cornerRadius, i32 thickness, Color color)colors
color_tint
Tint a color with another color
Color color_tint(Color color, Color tint)color_fade
Fade a color
Color color_fade(Color color, f32 alpha)color_brightness
Change the brightness of a color
Color color_brightness(Color color, f32 factor)color_invert
Invert a color
Color color_invert(Color color)color_alpha_blend
Blend 2 colors together
Color color_alpha_blend(Color dst, Color src)color_contrast
Change contrast of a color
Color color_contrast(Color color, f32 contrast)color_bilinear_interpolate
Interpolate colors
Color color_bilinear_interpolate(Color color00, Color color01, Color color10, Color color11, f32 coordinateX, f32 coordinateY)