Jsvx

The Building Blocks

Before we dive in, we need to discuss the basic building blocks of an application in Jsvx.

Vx_world

A vx_world is a collection of objects that can be rendered in the same scene. Most simple applications only need one vx_world, but nothing says you can’t have more. You can think of a vx_world as a setting, a scene, or a room. If objects can appear in the same camera frame, they need to be in the same vx_world. A vx_world is created with a call to vx_world_create:

vx_world_t *vw = vx_world_create();

Vx Objects

We said that a vx_world is a collection of objects. But what is an object in Jsvx? // TODO

Vx_buffer

A vx_buffer is a collection of objects in a vx_world that are rendered together. They represent a group of objects that can be “turned on and off”, similar to a "layer" in many photo editing applications. Vx_buffers are also the only way to render objects in Jsvx. To render an object, or collection of objects, you follow these steps.

• Ask the vx_world for a named buffer. (if a buffer with that name exists, the vx_world will return a pointer to the existing buffer)

vx_buffer_t *vb = vx_world_get_buffer(vw, "buffer_name");

• Add objects to the back of the buffer (vx_buffers implement double buffering to prevent tears and jitters during rendering.) https://docs.oracle.com/javase/tutorial/extra/fullscreen/doublebuf.html

vx_buffer_add_back(vb, obj);

• Swap the buffer.

vx_buffer_swap(vb);

WebVx

WebVx is a web server. It manages connections between your application and clients (web browsers). It's job is to send objects that you draw with vx_objects and vx_buffers along to the clients to view them. It does this by creating websocket connections for each incoming client, creating appropriate per-client resources, and calling callbacks that you provide whenever a new client connects. You create a webvx server with a call to webvx_create.

webvx_t *webvx = webvx_create_server(port, "/path/to/webvx_html", "index.html");

The webvx_html directory contains all of the client_side code necessary to communicate with your application, including WebGL code, javascript event handlers, default camera controls, and lots of other stuff. The vast majority of applications will be able to use the provided default directory(magic2/src/jsvx/webvx_html), but if you feel that you need special functionality, feel free to create a copy of this directory and edit anything you'd like. Just remember to point your server at your new copy.

Vx_canvas

A Vx_canvas represents a portion of a literal display device such as a computer monitor or a phone screen. (XXx: Does it? It seems like it could just be a per-client resource, representing a screen? I guess that's the same?). Webvx will create a canvas for each client that connects and pass it to on_create_canvas and on_destroy_canvas. Each vx_canvas is connected to a vx_world, and will "see" the objects you draw into that world through vx_buffers.

Vx_layer

A vx_layer represents a “view” into a vx_world. It acts like a moveable camera that inspects the scene (the vx_world). Vx_layers are also responsible for communicating user-initiated events such as mouse clicks and keystrokes to the server system. Much like vx_buffers with vx_worlds, you ask a vx_canvas for a named vx_layer.

vx_layer_t *vl = vx_canvas_get_layer(vc, "layer_name");

Putting it all Together

Now that we've got the basics covered, we can put everything together into a working example.