Canvas API

A 2D Vector Graphics API.

Types

oc_surface

typedef struct oc_surface
{
    u64 h;
} oc_surface;

An opaque handle to a graphics surface.

oc_canvas_renderer

typedef struct oc_canvas_renderer
{
    u64 h;
} oc_canvas_renderer;

An opaque handle representing a rendering engine for the canvas API.

oc_canvas_context

typedef struct oc_canvas_context
{
    u64 h;
} oc_canvas_context;

An opaque handle to a canvas context. Canvas contexts are used to hold contextual state about drawing commands, such as the current color or the current line width, and to record drawing commands. Once commands have been recorded, they can be rendered to a surface using oc_canvas_render().

oc_font

typedef struct oc_font
{
    u64 h;
} oc_font;

An opaque font handle.

oc_image

typedef struct oc_image
{
    u64 h;
} oc_image;

An opaque image handle.

oc_gradient_blend_space

typedef enum oc_gradient_blend_space
{
    OC_GRADIENT_BLEND_LINEAR = 0,
    OC_GRADIENT_BLEND_SRGB = 1
} oc_gradient_blend_space;

This enum describes possible blending modes for color gradient.

Enum Constants

  • OC_GRADIENT_BLEND_LINEAR The gradient colors are interpolated in linear space.
  • OC_GRADIENT_BLEND_SRGB The gradient colors are interpolated in sRGB space.

oc_color_space

typedef enum oc_color_space
{
    OC_COLOR_SPACE_RGB = 0,
    OC_COLOR_SPACE_SRGB = 1
} oc_color_space;

An enum identifying possible color spaces.

Enum Constants

  • OC_COLOR_SPACE_RGB A linear RGB color space.
  • OC_COLOR_SPACE_SRGB An sRGB color space.

oc_color

typedef struct oc_color
{
    union
    {
        struct
        {
            f32 r;
            f32 g;
            f32 b;
            f32 a;
        };
        f32 c[4];
    };
    oc_color_space colorSpace;
} oc_color;

A struct representing a color.

Fields

  • colorSpace The color space of that color.

oc_joint_type

typedef enum oc_joint_type
{
    OC_JOINT_MITER = 0,
    OC_JOINT_BEVEL = 1,
    OC_JOINT_NONE = 2
} oc_joint_type;

Stroke joint types.

Enum Constants

  • OC_JOINT_MITER Miter joint.
  • OC_JOINT_BEVEL Bevel joint.
  • OC_JOINT_NONE Don't join path segments.

oc_cap_type

typedef enum oc_cap_type
{
    OC_CAP_NONE = 0,
    OC_CAP_SQUARE = 1
} oc_cap_type;

Cap types.

Enum Constants

  • OC_CAP_NONE Don't draw caps.
  • OC_CAP_SQUARE Square caps.

oc_font_metrics

typedef struct oc_font_metrics
{
    f32 ascent;
    f32 descent;
    f32 lineGap;
    f32 xHeight;
    f32 capHeight;
    f32 width;
} oc_font_metrics;

A struct describing the metrics of a font.

Fields

  • ascent The ascent from the baseline to the top of the line (a positive value means the top line is above the baseline).
  • descent The descent from the baseline to the bottom line (a positive value means the bottom line is below the baseline).
  • lineGap The gap between two lines of text.
  • xHeight The height of the lowercase character 'x'.
  • capHeight The height of capital letters.
  • width The maximum character width.

oc_glyph_metrics

typedef struct oc_glyph_metrics
{
    oc_rect ink;
    oc_vec2 advance;
} oc_glyph_metrics;

A struct describing the metrics of a single glyph.

Fields

  • advance The default amount from which to advance the cursor after drawing this glyph.

oc_text_metrics

typedef struct oc_text_metrics
{
    oc_rect ink;
    oc_rect logical;
    oc_vec2 advance;
} oc_text_metrics;

A struct describing the metrics of a run of glyphs.

Fields

  • ink The bounding box of the inked portion of the text.
  • logical The logical bounding box of the text (including ascents, descents, and line gaps).
  • advance The amount from which to advance the cursor after drawing the text.

oc_rect_atlas

typedef struct oc_rect_atlas
{
} oc_rect_atlas;

An opaque struct representing a rectangle atlas. This is used to allocate rectangular regions of an image to make texture atlases.

oc_image_region

typedef struct oc_image_region
{
    oc_image image;
    oc_rect rect;
} oc_image_region;

A struct describing a rectangular sub-region of an image.

Fields

  • image The image handle.
  • rect The rectangular region of the image.

Functions

oc_surface_nil

oc_surface oc_surface_nil();

Returns a nil surface handle.

oc_surface_is_nil

bool oc_surface_is_nil(oc_surface surface);

Check if a surface handle is nil.

oc_surface_destroy

void oc_surface_destroy(oc_surface surface);

Destroy a graphics surface.

oc_surface_get_size

oc_vec2 oc_surface_get_size(oc_surface surface);

Get a surface's size.

The size is returned in device-independent "points". To get the size in pixels, multiply the size in points by the scaling factor returned by oc_surface_contents_scaling().

Return

The size of the surface, in points.

oc_surface_contents_scaling

oc_vec2 oc_surface_contents_scaling(oc_surface surface);

Get the scaling factor of a surface.

Return

The scaling factor for each axis.

oc_surface_bring_to_front

void oc_surface_bring_to_front(oc_surface surface);

Bring a surface to the foreground, rendering it on top of other surfaces.

oc_surface_send_to_back

void oc_surface_send_to_back(oc_surface surface);

Send a surface to the background, rendering it below other surfaces.

oc_surface_get_hidden

bool oc_surface_get_hidden(oc_surface surface);

Checks if a surface is hidden.

oc_surface_set_hidden

void oc_surface_set_hidden(oc_surface surface, bool hidden);

Set the hidden status of a surface.

oc_color_rgba

oc_color oc_color_rgba(f32 r, f32 g, f32 b, f32 a);

Create a color using RGBA values.

oc_color_srgba

oc_color oc_color_srgba(f32 r, f32 g, f32 b, f32 a);

Create a current color using sRGBA values.

oc_color_convert

oc_color oc_color_convert(oc_color color, oc_color_space colorSpace);

Convert a color from one color space to another.

Parameters

  • color The color to convert
  • colorSpace The color space of the new color.

oc_canvas_renderer_nil

oc_canvas_renderer oc_canvas_renderer_nil();

Returns a nil canvas renderer handle.

oc_canvas_renderer_is_nil

bool oc_canvas_renderer_is_nil(oc_canvas_renderer renderer);

Checks if a canvas renderer handle is nil.

oc_canvas_renderer_create

oc_canvas_renderer oc_canvas_renderer_create();

Create a canvas renderer.

oc_canvas_renderer_destroy

void oc_canvas_renderer_destroy(oc_canvas_renderer renderer);

Destroy a canvas renderer.

oc_canvas_render

void oc_canvas_render(oc_canvas_renderer renderer, oc_canvas_context context, oc_surface surface);

Render canvas commands onto a surface.

Parameters

  • renderer The canvas renderer.
  • context The canvas context containing the drawing commands to render.
  • surface The destination surface.

oc_canvas_present

void oc_canvas_present(oc_canvas_renderer renderer, oc_surface surface);

Present a canvas surface to the display.

Parameters

  • renderer The canvas renderer.
  • surface The surface to present.

oc_canvas_surface_create

oc_surface oc_canvas_surface_create(oc_canvas_renderer renderer);

Create a surface for rendering vector graphics.

Parameters

  • renderer A canvas renderer.

Return

A handle to the created surface.

oc_canvas_context_nil

oc_canvas_context oc_canvas_context_nil();

Returns a nil canvas context handle.

oc_canvas_context_is_nil

bool oc_canvas_context_is_nil(oc_canvas_context context);

Checks if a canvas context handle is nil.

oc_canvas_context_create

oc_canvas_context oc_canvas_context_create();

Create a canvas context.

Return

A handle to the created canvas context.

oc_canvas_context_destroy

void oc_canvas_context_destroy(oc_canvas_context context);

Destroy a canvas context

oc_canvas_context_select

oc_canvas_context oc_canvas_context_select(oc_canvas_context context);

Make a canvas context current in the calling thread. Subsequent canvas commands will refer to this context until another context is made current.

Return

The canvas context that was previously selected (or a nil handle if none was selected).

oc_canvas_context_set_msaa_sample_count

void oc_canvas_context_set_msaa_sample_count(oc_canvas_context context, u32 sampleCount);

Set the multisample anti-aliasing sample count for the commands of a context.

Parameters

  • context The canvas context.
  • sampleCount The number of samples to use for anti-aliasing when rendering commands from this context.

oc_font_nil

oc_font oc_font_nil();

Return a nil font handle.

oc_font_is_nil

bool oc_font_is_nil(oc_font font);

Check if a font handle is nil.

oc_font_create_from_memory

oc_font oc_font_create_from_memory(oc_str8 mem, u32 rangeCount, oc_unicode_range* ranges);

Create a font from in-memory TrueType data.

Parameters

  • mem A block of memory containing TrueType data (e.g. as loaded from a ttf file).
  • rangeCount The number of unicode ranges to load.
  • ranges An array of unicode ranges to load.

Return

A handle to the created font.

oc_font_create_from_file

oc_font oc_font_create_from_file(oc_file file, u32 rangeCount, oc_unicode_range* ranges);

Create a font from a TrueType font file.

Parameters

  • file A handle to a TrueType font file.
  • rangeCount The number of unicode ranges to load.
  • ranges An array of unicode ranges to load.

Return

A handle to the created font.

oc_font_create_from_path

oc_font oc_font_create_from_path(oc_str8 path, u32 rangeCount, oc_unicode_range* ranges);

Create a font from a TrueType font file path.

Parameters

  • path The path of a ttf file.
  • rangeCount The number of unicode ranges to load.
  • ranges An array of unicode ranges to load.

Return

A handle to the created font.

oc_font_destroy

void oc_font_destroy(oc_font font);

Destroy a font.

oc_font_get_glyph_indices

oc_str32 oc_font_get_glyph_indices(oc_font font, oc_str32 codePoints, oc_str32 backing);

Get the glyph indices of a run of unicode code points in a given font.

Parameters

  • font The font handle.
  • codePoints A slice of unicode code points.
  • backing Backing memory for the result indices.

Return

A slice of glyph indices.

oc_font_push_glyph_indices

oc_str32 oc_font_push_glyph_indices(oc_arena* arena, oc_font font, oc_str32 codePoints);

Get the glyph indices of a run of unicode code points in a given font and push them on an arena.

Parameters

  • arena A memory arena on which to allocate the result indices.
  • font The font handle
  • codePoints A slice of unicode code points.

Return

A slice of glyph indices, allocated on arena.

oc_font_get_glyph_index

u32 oc_font_get_glyph_index(oc_font font, oc_utf32 codePoint);

Get the glyp index of a single codepoint in a given font.

Parameters

  • font The font handle.
  • codePoint A unicode codepoint.

Return

The glyph index for that codepoint.

oc_font_get_metrics

oc_font_metrics oc_font_get_metrics(oc_font font, f32 emSize);

Get a font's metrics for a given font size.

Parameters

  • font The font handle
  • emSize The desired size of an m character, in points.

oc_font_get_metrics_unscaled

oc_font_metrics oc_font_get_metrics_unscaled(oc_font font);

Get a font's unscaled metrics.

oc_font_get_scale_for_em_pixels

f32 oc_font_get_scale_for_em_pixels(oc_font font, f32 emSize);

Get a scale factor to apply to unscaled font metrics to obtain a given 'm' size.

Parameters

  • font The font handle.
  • emSize The desired size for the 'm' character.

oc_font_text_metrics_utf32

oc_text_metrics oc_font_text_metrics_utf32(oc_font font, f32 fontSize, oc_str32 codepoints);

Get text metrics for a run of unicode code points.

Parameters

  • font The font handle.
  • fontSize The desired font size.
  • codepoints A slice of unicode code points.

Return

The text metrics.

oc_font_text_metrics

oc_text_metrics oc_font_text_metrics(oc_font font, f32 fontSize, oc_str8 text);

Get the text metrics for a utf8 string.

Parameters

  • font The font handle.
  • fontSize The desired font size.
  • text A utf8 encoded string.

Return

The text metrics.

oc_image_nil

oc_image oc_image_nil();

Returns a nil image handle.

oc_image_is_nil

bool oc_image_is_nil(oc_image a);

Check if an image handle is nil.

oc_image_create

oc_image oc_image_create(oc_canvas_renderer renderer, u32 width, u32 height);

Create an uninitialized image.

Parameters

  • renderer The canvas renderer.
  • width Width of the image, in pixels.
  • height Height of the image, in pixels.

Return

A handle to the created image.

oc_image_create_from_rgba8

oc_image oc_image_create_from_rgba8(oc_canvas_renderer renderer, u32 width, u32 height, u8* pixels);

Create an image from an array of 8 bit per channel rgba values.

Parameters

  • renderer The canvas renderer.
  • width Width of the image, in pixels.
  • height Height of the image, in pixels.
  • pixels An array of packed rgba color values, with 8 bits per channel.

oc_image_create_from_memory

oc_image oc_image_create_from_memory(oc_canvas_renderer renderer, oc_str8 mem, bool flip);

Create an image from in-memory png, jpeg or bmp data.

Parameters

  • renderer The canvas renderer.
  • mem A block of memory containing the image data.
  • flip If true, flip the y-axis of the image while loading.

Return

A handle to the created image.

oc_image_create_from_file

oc_image oc_image_create_from_file(oc_canvas_renderer renderer, oc_file file, bool flip);

Create an image from an image file. Supported formats are: png, jpeg or bmp.

Parameters

  • renderer The canvas renderer.
  • file A handle to the image file.
  • flip If true, flip the y-axis of the image while loading.

Return

A handle to the create image.

oc_image_create_from_path

oc_image oc_image_create_from_path(oc_canvas_renderer renderer, oc_str8 path, bool flip);

Create an image from an image file path. Supported formats are: png, jpeg or bmp.

Parameters

  • renderer The canvas renderer
  • path A path to the image file.
  • flip If true, flip the y-axis of the image while loading.

Return

A handle to the created image.

oc_image_destroy

void oc_image_destroy(oc_image image);

Destroy an image.

oc_image_upload_region_rgba8

void oc_image_upload_region_rgba8(oc_image image, oc_rect region, u8* pixels);

Upload pixels to an image.

Parameters

  • image The image handle.
  • region The rectangular region of the image to update.
  • pixels A buffer containing the pixel values to upload. Each pixel value is a packed 8-bit per channel RGBA color. The buffer must hold region.w * region.h pixel values.

oc_image_size

oc_vec2 oc_image_size(oc_image image);

Get the size of an image.

oc_rect_atlas_create

oc_rect_atlas* oc_rect_atlas_create(oc_arena* arena, i32 width, i32 height);

Create a rectangle atlas.

Parameters

  • arena A memory arena on which to allocate the atlas.
  • width The width of the atlas.
  • height The height of the atlas.

oc_rect_atlas_alloc

oc_rect oc_rect_atlas_alloc(oc_rect_atlas* atlas, i32 width, i32 height);

Allocate a rectangular region from an atlas.

Parameters

  • atlas A pointer to the atlas.
  • width The width of the rectangle to allocate.
  • height The height of the rectangle to allocate.

Return

The allocated rectangle.

oc_rect_atlas_recycle

void oc_rect_atlas_recycle(oc_rect_atlas* atlas, oc_rect rect);

Recycle a rectangular region that was previously allocated from an atlas.

Parameters

  • atlas A pointer to the atlas.
  • rect The rectangular region to recycle.

oc_image_atlas_alloc_from_rgba8

oc_image_region oc_image_atlas_alloc_from_rgba8(oc_rect_atlas* atlas, oc_image backingImage, u32 width, u32 height, u8* pixels);

Allocate an image region from an atlas and upload pixels to that region.

Parameters

  • atlas A pointer to the texture atlas.
  • backingImage The backing image from which to allocate a region.
  • width The width of the region to allocate.
  • height The height of the region to allocate.
  • pixels A buffer containing pixels values to upload to the allocated region. Each pixel value is a packed 8-bit per channel RGBA color. The buffer must hold region.w * region.h pixel values.

Return

The allocated image region

oc_image_atlas_alloc_from_memory

oc_image_region oc_image_atlas_alloc_from_memory(oc_rect_atlas* atlas, oc_image backingImage, oc_str8 mem, bool flip);

Allocate an image region from an atlas and upload an image to it.

Parameters

  • atlas A pointer to the atlas.
  • backingImage The backing image from which to allocate an image region.
  • mem A block of memory containing the image data. Supported format are the same as oc_image_create_from_memory().
  • flip If true, flip the y-axis of the image while loading.

Return

The allocated image region

oc_image_atlas_alloc_from_file

oc_image_region oc_image_atlas_alloc_from_file(oc_rect_atlas* atlas, oc_image backingImage, oc_file file, bool flip);

Allocate an image region from an atlas and upload an image to it.

Parameters

  • atlas A pointer to the atlas.
  • backingImage The backing image from which to allocate an image region.
  • file The image file.
  • flip If true, flip the y-axis of the image while loading.

Return

The allocated image region

oc_image_atlas_alloc_from_path

oc_image_region oc_image_atlas_alloc_from_path(oc_rect_atlas* atlas, oc_image backingImage, oc_str8 path, bool flip);

Allocate an image region from an atlas and upload an image to it.

Parameters

  • atlas A pointer to the atlas.
  • backingImage The backing image from which to allocate an image region.
  • path The path to the image file.
  • flip If true, flip the y-axis of the image while loading.

Return

The allocated image region

oc_image_atlas_recycle

void oc_image_atlas_recycle(oc_rect_atlas* atlas, oc_image_region imageRgn);

Recycle an image region allocated from an atlas.

Parameters

  • atlas A pointer to the atlas.
  • imageRgn The image region

oc_matrix_push

void oc_matrix_push(oc_mat2x3 matrix);

Push a matrix on the transform stack.

oc_matrix_multiply_push

void oc_matrix_multiply_push(oc_mat2x3 matrix);

Multiply a matrix with the top of the transform stack, and push the result on the top of the stack.

oc_matrix_pop

void oc_matrix_pop();

Pop a matrix from the transform stack.

oc_matrix_top

oc_mat2x3 oc_matrix_top();

Get the top matrix of the transform stack.

oc_clip_push

void oc_clip_push(f32 x, f32 y, f32 w, f32 h);

Push a clip rectangle to the clip stack.

oc_clip_pop

void oc_clip_pop();

Pop from the clip stack.

oc_clip_top

oc_rect oc_clip_top();

Get the clip rectangle from the top of the clip stack.

oc_set_color

void oc_set_color(oc_color color);

Set the current color.

oc_set_color_rgba

void oc_set_color_rgba(f32 r, f32 g, f32 b, f32 a);

Set the current color using linear RGBA values.

oc_set_color_srgba

void oc_set_color_srgba(f32 r, f32 g, f32 b, f32 a);

Set the current color using sRGBA values.

oc_set_gradient

void oc_set_gradient(oc_gradient_blend_space blendSpace, oc_color bottomLeft, oc_color bottomRight, oc_color topRight, oc_color topLeft);

Set the current color gradient.

Parameters

  • blendSpace The color space in the gradient's colors are blended.
  • bottomLeft Color at the bottom left of the fill region.
  • bottomRight Color at the bottom right of the fill region.
  • topRight Color at the top right of the fill region.
  • topLeft Color at the top left of the fill region.

oc_set_width

void oc_set_width(f32 width);

Set the current line width.

oc_set_tolerance

void oc_set_tolerance(f32 tolerance);

Set the current tolerance for the line width. Bigger values increase performance but allow more inconsistent stroke widths along a path.

Parameters

  • tolerance The width tolerance, in pixels.

oc_set_joint

void oc_set_joint(oc_joint_type joint);

Set the current joint style.

oc_set_max_joint_excursion

void oc_set_max_joint_excursion(f32 maxJointExcursion);

Set the maximum joint excursion. If a joint would extend past this threshold, the renderer falls back to a bevel joint.

oc_set_cap

void oc_set_cap(oc_cap_type cap);

Set the current cap style.

oc_set_font

void oc_set_font(oc_font font);

The the current font.

oc_set_font_size

void oc_set_font_size(f32 size);

Set the current font size.

oc_set_text_flip

void oc_set_text_flip(bool flip);

Set the current text flip value. true flips the y-axis of text rendering commands.

oc_set_image

void oc_set_image(oc_image image);

Set the current source image.

oc_set_image_source_region

void oc_set_image_source_region(oc_rect region);

Set the current source image region.

oc_get_color

oc_color oc_get_color();

Get the current color

oc_get_width

f32 oc_get_width();

Get the current line width.

oc_get_tolerance

f32 oc_get_tolerance();

Get the current line width tolerance.

oc_get_joint

oc_joint_type oc_get_joint();

Get the current joint style.

oc_get_max_joint_excursion

f32 oc_get_max_joint_excursion();

Get the current max joint excursion.

oc_get_cap

oc_cap_type oc_get_cap();

Get the current cap style.

oc_get_font

oc_font oc_get_font();

Get the current font.

oc_get_font_size

f32 oc_get_font_size();

Get the current font size.

oc_get_text_flip

bool oc_get_text_flip();

Get the current text flip value.

oc_get_image

oc_image oc_get_image();

Get the current source image.

oc_get_image_source_region

oc_rect oc_get_image_source_region();

Get the current image source region.

oc_get_position

oc_vec2 oc_get_position();

Get the current cursor position.

oc_move_to

void oc_move_to(f32 x, f32 y);

Move the cursor to a given position.

oc_line_to

void oc_line_to(f32 x, f32 y);

Add a line to the path from the current position to a new one.

oc_quadratic_to

void oc_quadratic_to(f32 x1, f32 y1, f32 x2, f32 y2);

Add a quadratic Bézier curve to the path from the current position to a new one.

oc_cubic_to

void oc_cubic_to(f32 x1, f32 y1, f32 x2, f32 y2, f32 x3, f32 y3);

Add a cubic Bézier curve to the path from the current position to a new one.

oc_close_path

void oc_close_path();

Close the current path with a line.

oc_glyph_outlines

oc_rect oc_glyph_outlines(oc_str32 glyphIndices);

Add the outlines of a glyph run to the path, using glyph indices.

Parameters

  • glyphIndices A slice of glyph indices.

oc_codepoints_outlines

void oc_codepoints_outlines(oc_str32 string);

Add the outlines of a glyph run to the path, using unicode codepoints.

Parameters

  • string A slice of unicode code points.

oc_text_outlines

void oc_text_outlines(oc_str8 string);

Add the outlines of a glyph run to the path, using a utf8 string.

Parameters

  • string A utf8 string.

oc_clear

void oc_clear();

Clear the canvas to the current color.

oc_fill

void oc_fill();

Fill the current path.

oc_stroke

void oc_stroke();

Stroke the current path.

oc_rectangle_fill

void oc_rectangle_fill(f32 x, f32 y, f32 w, f32 h);

Draw a filled rectangle.

oc_rectangle_stroke

void oc_rectangle_stroke(f32 x, f32 y, f32 w, f32 h);

Draw a stroked rectangle.

oc_rounded_rectangle_fill

void oc_rounded_rectangle_fill(f32 x, f32 y, f32 w, f32 h, f32 r);

Draw a filled rounded rectangle.

oc_rounded_rectangle_stroke

void oc_rounded_rectangle_stroke(f32 x, f32 y, f32 w, f32 h, f32 r);

Draw a stroked rounded rectangle.

oc_ellipse_fill

void oc_ellipse_fill(f32 x, f32 y, f32 rx, f32 ry);

Draw a filled ellipse.

oc_ellipse_stroke

void oc_ellipse_stroke(f32 x, f32 y, f32 rx, f32 ry);

Draw a stroked ellipse.

oc_circle_fill

void oc_circle_fill(f32 x, f32 y, f32 r);

Draw a filled circle.

oc_circle_stroke

void oc_circle_stroke(f32 x, f32 y, f32 r);

Draw a stroked circle.

oc_arc

void oc_arc(f32 x, f32 y, f32 r, f32 arcAngle, f32 startAngle);

Add an arc to the path.

oc_text_fill

void oc_text_fill(f32 x, f32 y, oc_str8 text);

Draw a text line.

oc_image_draw

void oc_image_draw(oc_image image, oc_rect rect);

Draw an image.

oc_image_draw_region

void oc_image_draw_region(oc_image image, oc_rect srcRegion, oc_rect dstRegion);

Draw a sub-region of an image.