ctx is a small footprint vector graphics protocol and rasterizer based on the HTML5 Canvas 2D context. It can drive resolution independent antialiased interfaces on microcontrollers as well as provide color and CMYK processing capabilities as well as floating point processing needed for content authoring.
It provides both a C API and an efficient text based serialization of the canvas drawing model. Almost the full W3C rendering API is covered, currently missing is ellipse(), correct handling of path instead of using bounding box in in_fill().
Render targets handled natively are 8bit sRGBA RGBA8, floating point scRGB RGBAF 8bit and floating point grayscale with alpha. GRAYA8 and GRAYAF and floating point CMYK CMYKAF. Integration points are catered for in API and protocol for color management, which will be done with babl. The formats RGB332, RGB565, RGB565_BYTESWAPPED, CMYKA8, RGB8, BGRA8, GRAY1, GRAY2, GRAY4, GRAY8 and GRAYF are handled by converting processed scanlines back and forth to one of the supported targets.
SVG and PDF output can be generated with the cairo renderer, which becomes available if cairo.h is included before ctx.h
rendering tests
A gallery of test cases; mostly written in ctx' own syntax, some use SVG/HTML as input and an in-progress port of Microraptor GUIs SVG/HTML parser.
license and funding
ctx is currently developed under LGPLv3+ you can encourage continued development of ctx and dissimilar technologies by supporting its developer, if income through patreon and similar is above 4000USD per month for a year, or a similar amount in shorter time, I will relicense ctx under the ISC license.
standards
ctx uses the HTML5 2d context is the primary reference, The compositing is according to Compositing and Blending Level 2; though ctx permits any combination of compositing and blending mode. The core ideas for a 2d vector vocabulary is however shared with PDF, cairo, OpenVG, directdraw and others all with a basis in postscript.
protocol reference
This is a terse technical reference on the command entries stores internally when serializing drawing commands, it maps to the the C API if you ruen camelCase into snake_case, and prefixing each command with ctx_.
The ctx text format is a direct serialization of the API.
When a keyword is parsed the parser expects a series of commands of the same type, that will consume arguments until a command change. There are also short forms of the commands available, where applicable these match the SVG path data syntax thus making ctx a superset of SVG path data.
| gray | gray | sets gray source, and color model |
| graya | gray alpha | sets gray alpha source, and color model |
| rgb | r g b | sets rgb source |
| rgba | r g b a | rgb alpha color source |
| cmyk | c m y k | cmyk color source |
| cmyka | c m y k a | cmyk alpha color source |
| drgb | r g b | sets rgb source, in device space |
| drgba | r g b a | rgb alpha color source, in device space |
| dcmyk | c m y k | cmyk color source, in device space |
| dcmyka | c m y k a | cmyk alpha color source, in device space |
| a relArcTo | 5 | |
| b clip | ||
| c relCurveTo | 6 | |
| g save | ||
| e translate | x y | |
| f linearGradient | x0 y0 x1 y1 | |
| h relHorLine | x | |
| ka globalAlpha | alpha | |
| kb textBaseline | alphabetic | top | bottom | middle | hanging | ideographic | |
| kB blendMode | normal | multiply | screen | overlay | darken | lighten | colorDodge | colorBurn | hardLight | softLight | difference | exclusion | hue | saturation | color | luminosity | divide | addition | subtract | |
| kc lineCap cap | none | round | square | |
| kC shadowColor | color components | works like gradientAddStop |
| kf fontSize | font_size | |
| kj lineJoin join | bevel | round | miter | 0 1 or 2 are also valid values |
| kl miterLimit | miter_limit | |
| km compositingMode | sourceOver | copy | clear | sourceIn | sourceOut | sourceAtop | destinationOver | destination | destinationIn | destination_out | destinationAtop | xor | |
| ks shadowBlur | blur_radius | |
| kt textAlign | start | end | center | left | right | |
| kw lineWidth | line_width | |
| kx shadowOffsetX | horizontal_offset | |
| ky shadowOffsetY | vertical_offset | |
| l relLineTo | x y | |
| m relMoveTo | x y | |
| n font | "font name" | |
| o radialGradient | 6 | |
| p gradientAddStop addStop | pos R G B A | arguments depend on current color model, you can change the color model without setting a color by specifying a color without arguments. |
| q relQuadTo | cx cy x y | |
| r rectangle rect | x y width height | |
| s relSmoothTo | cx cy x y | |
| t relSmoothQuadTo | x y | |
| u strokeText | "utf8-string" | |
| v relVerLine | y | |
| w glyph | unichar | draws a single unicode character, the character no is currently passed in as decimal. (might be made internal), since a text string duplicates the API. |
| x text | "utf8-string" | kerning | Interspersed with utf8 sequences of text numbers can appear that shift the horizontal position. |
| y identity | ||
| z closePath | ||
| A arcTo | x1 y1 x2 y2 radius | |
| B arc | x y radius angle1 angle2 direction | |
| C curveTo | cx1 cy1 cx2 cy2 x y | |
| E stroke | ||
| F fill | ||
| G restore | ||
| H horLineTo | x | |
| J rotate | radians | |
| L lineTo | x y | |
| M moveTo | x y | |
| N beginPath | ||
| O scale | scale_x scale_y | |
| Q quadTo | cx cy x y | |
| S smoothTo | cx cy x y | |
| T smoothQuadTo | x y | |
| U reset | ||
| V verLineTo | y | |
| X exit | ||
| X done | ||
| Z closePath | ||
| W transform | a b c d e f | applies the transformation matrix |
| { startGroup | starts a compositing group | |
| } endGroup | ends a compositing group, and blends and composites it with the content before the group using the now current compositing mode, blending mode and global alpha. |
Detailed syntax description
The language consists of a stream of words, numbers and strings, optionally separated by white space. The characters ,=(); are also treated as white-space. Words are substrings consisting of one or more characters in the ranges a-z and A-Z. Numbers are sequenes of 0-9. Numbers can be followed by the suffixes % or @, indicating that units of percent canvas width/height should be used or a global em / cell-size. ^ is equivalent to CSS vh, and ~ vw, this can be used to override the automatic choice done by %. Strings are UTF8 contained in ' or " pairs. "\n\r" etc from C are available for escaping newlines, though they can also be directly included in the string. # introduces a comment and the rest of the line is ignored.
the code
It is early stages for ctx, more instructions on integration and use read the header file itself. A git repository with tests and examples will eventually appear.
Files
| ctx.h | 580K | browse | The singleheader library ctx. | |
| ctx-font-ascii.h | 72K | browse | Example font to use with ctx, containing only ASCII | |
| ctx-font-regular.h | 128K | browse | Example font to use with ctx | |
| ctx.elf | 168K | card10 l0dable | ||
| hello.c | 3K | Animated terminal test. | ||
| test-size.c | 3K | minimal example |
is ctx fast yet?
This table contains fills of 1024px with various fill sources for all of ctx' supported targets, along with cairo included as a frame of reference. Small changes, like changing between inlining, forced inlinging and no inlining can lead to performance fluctuations, the numbers show that performance is decent in contrast with cairo.
Ctx implements all combinations of compositing and blending modes, but normal with source over has received the most attentions, both with optional AVX256 acceleration and not.
| format | color a=1.0 | color a=0.75 | lgrad | rgrad | sAtop a=1.0 | sAtop a=0.75 | sAtop lgrad | sAtop rgrad | overlay a=1.0 | overlay a=0.75 | overlay lgrad | overlay rgrad | aTop overlay | ..lgrad | ..rgrad | |
| RGBA8 AVX2 | 3809 | 1996 | 281 | 181 | 145 | 126 | 92 | 92 | 100 | 88 | 56 | 56 | 103 | 97 | 56 | 56 |
| RGBA8 | 799 | 765 | 217 | 167 | 141 | 122 | 90 | 87 | 115 | 102 | 56 | 56 | 117 | 103 | 57 | 56 |
| cairo | 2585 | 1148 | 115 | 66 | 644 | 560 | 115 | 69 | ||||||||
| GRAYA8 | 1052 | 651 | 84 | 54 | 264 | 258 | 78 | 54 | 187 | 178 | 63 | 52 | 188 | 178 | 63 | 52 |
| GRAYAF | 506 | 506 | 74 | 73 | 594 | 596 | 73 | 72 | 229 | 229 | 55 | 55 | 231 | 229 | 54 | 54 |
| RGBAF | 513 | 671 | 214 | 160 | 507 | 537 | 176 | 148 | 129 | 126 | 52 | 50 | 119 | 117 | 50 | 48 |
| CMYKAF | 532 | 405 | 42 | 54 | 379 | 381 | 50 | 58 | 145 | 144 | 36 | 39 | 148 | 148 | 36 | 39 |
| CMYKA8 | 133 | 131 | 38 | 44 | 129 | 127 | 40 | 44 | 81 | 80 | 30 | 32 | 80 | 82 | 30 | 33 |
| GRAY1 | 268 | 240 | 58 | 45 | 157 | 154 | 55 | 45 | 126 | 122 | 46 | 43 | 126 | 122 | 46 | 43 |
some observations on the above
To know how this compares with yet other renderers, compare with the numbers in blend2d's benchmarks..
When targeting a microcontroller that has a small enough framebuffer that it is possible to keep RGBA8 instead of RGB565, one should use RGBA8 and convert on-the-fly when copying out, for best performance.
For floating point compilers do a better job of autovectorizing code, SIMD implementations for normal + source-over does however still make sense.
optimization vs binary size
ctx is designed from the beginning to act as a GPU in software for modern micontrontrollers - powerful enough to have hundres of megahertz and possibly multiple cores. Different optimization settings of the compiler give a wide range for the performance/binary size tradeoff. But the small footprint in RAM and ability to use a shared read-only display list makes the ctx rasterizer core also useful in multi-threaded rendering.
font data size: 15291 bytes (A sans font subsetted to only ASCII)
RGBA8 rasterizer: 38869 bytes (-Os ~38kb - with many features disabled ~29kb
-O0 90-631kb
-O2 57-114kb
-Ofast/-O3 76-181kb, size bump due to
SIMD tree-vectorizer)
ctx parser: 20512 bytes (not needed for direct use from C, but also
on embedded this can be useful for ease of
integration with other languages or directly
using ctx+mictrocontroller+display as a serial
display.)
Even more agressive optimization with exponential compile time has been tested by forcing inlining and separate compilation of all combinations of blend, composite and image source modes - building ctx then takes 5-6minutes and the resulting binary is close to a megabyte, performance gains exist but are near neglible.
The total RAM requirements are modest, with the most slim configuration <16kb of RAM is required when directly rendering using the default limits, if the maximum number of vertices in a path is reduced this can be below 10kb.
semi-ordered roadmap / wishlist
- reduce size and improve performance
- Document/clean up network transparent UI protocol using ctx syntax. (test, test)
- swap uses of cairo in GEGL with ctx
- point in fill/stroke, (current in_fill API uses path boundingbox)
- texture upload as part of ctx syntax
- ICC color management (provisions have been made in the API for this, but RGBtoRGB and CMYKtoRGB RGBtoCMYK conversions are currently done naively, instead of using babl.)
- glyph fallback
- faster 1d-gaussian blur for shadow blur
- gradients: use both circle centers
- bindings to a javascript engine, for running canvas js content as apps.
- stroking
- reimplement as a stroke_to_path
- miter limit (unless round joins are used, all corners are mitered now)
- dash pattern
- SVG/HTML parser renderer (in progress, from mrg)
- PDF/SVG generation (can already be done through cairo integration)
- Add API for integrating device-N with RGB/CMYK through coloritto
- 32bit float coverage from rasterizer - right now we support 32f images; but composite them with 8bit alpha masks.
- More SIMD code (the common RGBA8 cases for AVX2 are the only bit covered thus far, for floating point formats making the existing code more autovectorizer friendly is a priority.)
minimal example code
#include <stdint.h> #include "ctx-font-regular.h" #define CTX_IMPLEMENTATION #include "ctx.h" #define WIDTH 72 #define HEIGHT 24 uint8_t pixels[WIDTH*HEIGHT*4]; int main (int argc, char **argv) { char *utf8 = "hello\nctx\n"; Ctx *ctx = ctx_new_for_framebuffer ( pixels, WIDTH, HEIGHT, WIDTH*4, CTX_FORMAT_RGBA8); ctx_rgba (ctx, 0.5, 0.5, 0.5, 1); ctx_rectangle (ctx, 0, 0, 80, 24); ctx_fill (ctx); ctx_move_to (ctx, 10, 9); ctx_font_size (ctx, 12); ctx_line_width (ctx, 2); ctx_rgba (ctx, 0, 0, 0, 1); ctx_text_stroke (ctx, utf8); ctx_rgba (ctx, 1,0, 1.0, 1.0, 1.0); ctx_move_to (ctx, 10, 9); ctx_text (ctx, utf8); ctx_free (ctx); static char *utf8_gray_scale[]={" ","░","▒","▓","█","█", NULL}; int no=0; for (int y= 0; y < HEIGHT; y++) { for (int x = 0; x < WIDTH; x++, no+=4) printf ("%s", utf8_gray_scale[5-(int)CTX_CLAMP(pixels[no+1]/255.0*6.0, 0, 5)]); printf ("\n"); } return 0; }which outputs (the rightmost column of pixels is a bug):
~/src/ctx/tests$ ./test-size ▓▓▓▓▓▓▓▓▓▓▓█▓▓▓█▓▓▓▓▓▓▓▓▓▓▓▓▓▓██▓▓▓▓▓▓▓▓▓▓▓▓▓▓█▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█ ▓▓▓▓▓▓▓▓▓▓██▓▓█ █▓▓▓▓▓▓▓▓▓▓▓▓███▓▓▓▓▓▓▓▓▓▓▓▓▓███▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█ ▓▓▓▓▓▓▓▓▓██ ██████████▓██▓▓▓██▓▓██▓████▓▓█████▒███▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█ ▓▓▓▓▓▓▓▓▓█░ ░█ ██░░ ░██ █▓█ █ ▓█▒ ███ ▓▓ █▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█ ▓▓▓▓▓▓▓▓▓██ ███ ██ ▓█░██░███░█▓▓██▓░██░██░████▒███▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█ ▓▓▓▓▓▓▓▓▓▓█ █▓█ ██░██▓▓█▓▒█▒▓█▓▒██░▓██░▓█ ▓███▒██▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█ ▓▓▓▓▓▓▓▓▓▓█ █▓█ ██░██▓▓██ █ ██▓▓██░▒▓▓▓███▒░▒█▒█▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█ ▓▓▓▓▓▓▓▓▓▓█ ███ ██░██▓▓██▒░▒██▓▓██▒▒████████░█▒███▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█ ▓▓▓▓▓▓▓▓▓▓█▒░▒█ ██░██▓▓██▓ █▓██░░██░░▒░█▓░▒░▓██░░█▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█ ▓▓▓▓▓▓▓▓▓▓▓█████▓██▓▓██▓██ █▓▓████▓██████████▓████▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█▓ █▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓████▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓███▓▓▓▓▓▓▓▓▓▓▓▓▓▓███▓▓▓▓▓▓▓▓▓▓▓▓▓██▓▓▓▓▓▓▓▓▓▓▓▓▓▓█ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█ █▓▓▓▓▓▓▓▓▓▓▓▓▓██░░█▓▓▓▓▓▓▓▓▓▓▓█▒▓█▓▓▓▓▓▓▓▓▓▓▓▓▓█ ▓▓▓▓▓▓▓▓▓▓▓████▓▓▓█████ ███▓▓▓████▓▓▓▓█░███████▓▓████▓█▒▓███▓▓████▓▓████ ▓▓▓▓▓▓▓▓▓▓██▒▒▓███ ▓█ ▒ ░█▓█▒ ██▓▓█▒ ░█▓ ████ ▒██▒░ ███ ▓██ █ ▓▓▓▓▓▓▓▓▓██░██▒██▒▓████ ▓█▒▓█▓▒██░█▓▓██░███░██░██░██▒▓█▒░██░█████░██████ ▓▓▓▓▓▓▓▓▓█▓▒██▓▒█ █▓▓▓█ ███▒█░███░█▓▓▓█░██▓▓██▓▓█ ███░█▒▓██▒███▓▓░▓███░█ ▓▓▓▓▓▓▓▓▓█▓▒█████ █▓▓▓█ ███▒█░█▓█░█▓▓▓█░██▒▓██▓▓█░███░█▒▓██▒▓█ ██▒▓██░▓█ ▓▓▓▓▓▓▓▓▓█▓░█████░█████ ███▒█░▓██ █▓▓▓█░██▓░██░██ ██▓░█▒▒██░██░██░▓█▒▒██ ▓▓▓▓▓▓▓▓▓▓█▓░▒░▓██ ▒░██ ███▒██░░ ▓█▓▓▓█░█▓█▒ ▒██▓ ░░██▒░▒░▒██░░░▒▓█ ▒▒█ ▓▓▓▓▓▓▓▓▓▓▓█████▓███████▓▓██▓▓████▓▓▓▓▓██▓▓████▓▓████▓██████▓▓██████████ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█
To fetch, build, and run ctx, and an example similar to the above run the following:
mkdir foo;cd foo;wget http://ctx.graphics/{ctx.h,ctx-font-regular.h,hello.c};make hello && ./hello