wefx

Wefx is a simple graphics library for drawing using C11, WASM (Web Assembly), and an HTML canvas. It aims to serve a similar purpose as gfx, but provide an introduction to using C and WASM. Wefx is meant to be a teaching / learning tool for C and graphics. Wefx is not using OpenGL / WebGL or anything like that. It is doing very basic pixel manipulation and has very simple functions to draw pixels and lines.

You can also download the documentation

Quick Start

If you are using Ubuntu, you can run make init to install the correct version of clang and tools. If you are on another system, you will have to install clang yourself.

Once installed, make build should compile examples/example0.c into WASM (if there are no errors). If successful, and if you have python installed, you can run make serve to start a simple HTTP server and browse to http://localhost:8000 to view wasm output.

Using The Project

The flow of the project has two steps: the build step, and the serve step:

 ⌈                    ⌉             ⌈                   ⌉
 | ./src + ./examples | ⭢  clang ⭢ | ./build/wefx.wasm |
 ⌊                    ⌋             ⌊                   ⌋
                                             ⭣
        _____________________________________/
       /
      ⭣
 ⌈          ⌉                  ⌈         ⌉    ⌈      ⌉
 | ./build/ | ⭢  web server ⭢ | browser | ⭢ | you! |
 ⌊          ⌋                  ⌊         ⌋    ⌊      ⌋

In other words, you compile the C code into a WASM, and then serve the build directory using a web server. You can then open a web browser and visit http://localhost:8000 to view the running C code.

You'll need the following programs installed:

clang
make (optional - MacOS and Linux)
(optional) python3

On MacOS or Linux these tools should be available already, or easily installed with homebrew (brew install), or Apt (apt install), or your local package manager.

Compiling

To understand what is happening (or if you do not want to use make), open the Makefile file and look at the build task. There you can see how clang is used.

If you have make available, type:

make build

on the command line. This will, assuming there are no errors, create the file ./build/wefx.wasm. Once this builds you can serve your creation by doing the following...

Serving

The gist of this is you need to serve the contents of the /build directory in a web server. You need to do this because the file that loads the newly create wasm file (index.html can only load the wasm file over http. You can not simply open the index.html file directly from your file system (this is just how wasm loading works).

If you try to open the index.html file directly you will get an error like:

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at file:///xxxxx/build/wefx.wasm. (Reason: CORS request not http).

A basic http server comes with python3, and the make file will run that server if you run:

make serve

and the python3 web server will serve the files in the build directory. You can then use your favorite browser and browse to http://localhost:8000 to see the compiled code.

Note make serve will both recompile your code and run the web server.

If you already have a favorite server (for example I use busboy), you can use that serve to serve the build directory instead, and then run the make build command to replace the wasm file as you play around.

For example in one shell I run:

busyboy --root=./build

Then, after I make changes to the C code, I run

make build

And then simply refresh the browser to see changes.

Writing Code

If just teaching / learning about graphics, you'll only need to edit the ./examples/example0.c file. There are two entry points into that file:

Function	Usage
init()	Called once at the start of the app
main_loop(time)	Called every frame with time being time since app start

You can also add your own entry files in the examples directory, and then pass them to the build script using the MAIN variable. For example:

make build MAIN=examples/example1.c

This will build the WASM file using example1.c as the entry point.

Getting Started

API

The API calls try to emulate gfx as much as possible. Here are a few currently supported functions (see the documentation for a full reference):

Function	Does
wefx_open(width, height, title)	Create a canvas on which to draw
wefx_clear_color(red, green, blue)	Set the background color
wefx_color(red, green, blue)	Set the drawing color
wefx_point(x, y)	Draw a single point
wefx_line(x1, y1, x2, y2)	Draw a line from (x1,y1) to (x2,y2)
wefx_clear()	Clear the canvas using the background color

Coordinate System

The coordinate system in newer versions has changed to reflect most other drawing styles. The system works thusly:

      +Y
       |
       |
       |
       |
 (0,0) +---------- +X

In version 1 (or earlier) of the library, the positive Y was flipped:

 (0,0) +---------- +X
       |
       |
       |
       |
      +Y

Windows OS

I have not run this on Windows, but you should be able to build it with Visual Studio. You will have to install clang as an add on, and then setup the build flags to the ones shown in the Makefile.

robrohan/wefx