Skip to content

Compiler Reference

Overview

The renderlet compiler (rlc) takes a YAML-based file, called a renderspec, that provides a declarative definition of graphics pipelines.

rlc generates backing C++ code from the renderspec, and uses LLVM to link together all code, library modules, and graphics data into a renderlet - a self-contained WebAssembly binary.

Format

A renderspec is a YAML container for multiple formal grammars - each grammar providing a series of attributes (data) and rules (code), each made up of a list of operators:

---
  grammars: 
    version: "0.1"
    grammar: 
      - 
        attr: 
          - 
            name: "height"
            value: "28.0"
        rule: 
          - 
            name: "Start"
            op:
              -
                extrude: 
                  height: "height"

Objects:

  • version: The current renderspec version: 0.1

  • grammar: A list of grammars, link-time bound to modules. Each grammar is translated to an exported Wasm function / graphics object to be called.

  • attr: attribute with a default values, and optionally ranges, that can be overriden at runtime based on the input data (see the documentation in the wander SDK)

    • name: Attribute name
    • value: Attribute initial value
    • range (optional): Attribute value range ("<min>, "<max>")
  • rule A named list of operators that may be referenced from other rules in the tree
    • name: Rule name
    • op: Operator list (run sequentially)

Modules

renderlet includes 5 modules by default:

  • Pipeline
  • 2D
  • 3D
  • Vector
  • Procedural

Only Procedural is currently exposed to the renderspec in the renderlet playground. Assumptions are made about the pipeline state, and 2D and 3D geometry are implicitiy

We are working on an SDK to add your own modules with C++ or Rust.

Please check back frequently as we expand the features of the renderspec and the wander runtime library.

Procedural Operators

Procedural: Version 0.1

This module provides a library for procedural modeling of geometry using a shape grammar, heavily inspired both by CityEngine's CGA and the work of Gen Nishida at Purdue.

The Procedural package exports the following operators:

center

Centers the scope of the object about an axis or axes.

Parameters:

  • axesSelector (EAxesSelector): The axis or axes to center about, one of:
    • XYZ
    • X
    • Y
    • Z
    • XY
    • XZ

Example:

center:
    axesSelector: "X"

color

Sets the color of the object to a static value using rgb components or hex codes.

Components are in the range of 0.0f - 255.0f, hex string is #RRGGBB.

Parameters:

  • r (float (expression)): The red color component

  • g (float (expression)): The green color component

  • b (float (expression)): The blue color component

  • s (string (expression)): Must evaluate to a string of (#RRGGBB) format, sets all rgb components

Example:

color:
    r: "32"
    g: "128"
    b: "64"
color:
    s: "#a3875e"

comp

Splits a piece of geometry into its components.

Currently only face splits are supported, and the face selector is implied.

Each face is then pushed into the render tree and passed to another rule

More details are available in the CGA documentation.

Parameters:

  • - (list): list of component splits

    • name (ESelector): Component to split by, one of:

      • front
      • back
      • left
      • right
      • top
      • bottom
      • side

    • value (string): Rule name to evaluate the split geometry

Example:

comp: 
  - 
    name: "side"
    value: "Facade"
  - 
    name: "top"
    value: "Top"

...

name: "Top"
op:
  -

copy

Copies another rule in the render tree into this location.

Parameters:

  • name (string): The rule name to copy

Example:

copy:
    name: "Rule2"

...

rule: 
  - 
    name: "Rule2"
    op:
      -

cornerCut

Symmetrically cuts the corner off of a rectangular surface, generating a chamfer or fillet.

Parameters:

  • name (ECornerCut): Component to split by, one of:
    • straight - generate a chamfer
    • curve - generate an external fillet
    • negativeCurve - generate an inner fillet
  • length (float (expression)): Distance from corner (horizontal and vertical) to generate the cut

Example:

cornerCut:
    type: "straight"
    length: "12.0"

extrude

Performs a geometric extrustion, transforming a 2D shape into a 3D shape.

Parameters:

  • height (float (expression)): Amount to extrude by

Example:

extrude:
    height: "10.0"

hemisphere

Extrudes a circular shape into a hemisphere / cap.

When applied to non-circular shapes, generates a pyramid with a height bounded by the shape's scope.

Parameters:

  • None

Example:

hemisphere:

innerCircle

Replaces a rectangle/square with the circumscribed ellipse/circle.

Parameters:

  • None

Example:

innerCircle:

innerSemiCircle

Replaces a rectangle/square with the circumscribed semi-ellipse/semi-circle.

Parameters:

  • None

Example:

innerSemiCircle:

insert

!! Not currently supported through YAML interface !!

Inserts static 3D geometry from a supported parser into the render tree

Parameters:

  • path (string): Path to geometry file(s)

Example:

insert:
    path: "/files/teapot.obj"

offset

Grows (or shrinks) a shape by a positive (or negative) value.

The resulting shape is passed to two (optional) rules for further processing: border and inside. Inside is the new shape, and border is the delta (positive or negative faces) from the starting shape.

More details are available in the CGA documentation.

Parameters:

  • distance (float (expression)): Amount to scale every edge's normal by
  • border: (string, optional): Rule name to evaluate the delta geometry
  • inside: (string, optional): Rule name to evaluate the scaled geometry

Example:

offset: 
  distance: "-2.0"
  border: "Wall"
  inside: "AwningInside"

pyramid

Performs a geometric extrustion to a pyramid, forming a volume with a line drawn from every point of the shape to its centroid at a given height.

Parameters:

  • height (float (expression)): Amount to extrude by

Example:

pyramid:
    height: "10.0"

rotate

Rotate the shape around an axis or axes.

Parameters:

  • x (float (expression), optional): Amount to rotate around x axis, degrees
  • y (float (expression), optional): Amount to rotate around y axis, degrees
  • z (float (expression), optional): Amount to rotate around z axis, degrees

Example:

rotate: 
    x: "-45.0"
    y: "yAmount"

setupProjection

Setup texture projection to UV coordinates across the object's scope.

The coordinates are maintained/recalculated across the shape's lifecycle in the shape tree unless another setupProjection applies later in the tree.

More details are available in the CGA documentation.

Parameters:

  • axesSelector (EAxesSelector): The axis or axes to center about, one of:
    • XY
    • XZ
  • width (Object): Projection in the width (U) direction
    • value (float (expression)): Width of texture in world units
    • type (Size::Type): Type of value, one of:
      • absolute - absolute world units
      • relative - relative to the scope of the object
  • height (Object): Projection in the height (V) direction
    • value (float (expression))
    • type (Size::Type)

Example:

setupProjection: 
  axes: "scope.xy"
  width: 
    value: "1"
    type: "relative"
  height: 
    value: "1"
    type: "relative"

shapeL

Replaces a rectangle/square with the circumscribed "L" shaped polygon.

Parameters:

  • frontWidth (float (expression)): Width of the vertical part of the "L"
  • rightWidth (float (expression)): Height of the bottom part of the "L"

Example:

shapeL:
    frontWidth: "3.0"
    rightWidth: "2.0"

shapeU

Replaces a rectangle/square with the circumscribed "U" shaped polygon.

Parameters:

  • frontWidth (float (expression)): Width of the vertical parts of the "U"
  • backDepth (float (expression)): Height of the bottom part of the "U"

Example:

shapeU:
    frontWidth: "4.0"
    backDepth: "2.0"

size

Resize a shape's scope vector.

Parameters:

  • centered (bool, optional): Center the output along all axes
  • x (float (expression), optional): Size of X axis
    • value (float (expression)): New size
    • type (Size::Type): Type of value, one of:
      • absolute - absolute world units
      • relative - relative to the scope of the object
  • y (float (expression), optional): Size of Y axis
    • value (float (expression))
    • type (Size::Type)
  • z (float (expression), optional): Size of Z axis
    • value (float (expression))
    • type (Size::Type)

Example:

size: 
  centered: "true"
  x: 
    value: "width"
    type: "absolute"
  y: 
    value: "depth"
    type: "absolute"
  z: 
    value: "0"
    type: "absolute"

split

Splits a piece of geometry into mutliple geometric objects.

For example, a rectangle can be split into a series of component rectangles of specified horizontal or vertical sizes.

Each new shape is inserted into the tree and further processed by the specified rule.

More details are available in the CGA documentation.

Parameters:

  • axis (EAxis): Axis to split by, one of:
    • X
    • Y
    • Z
  • sizes (list): List of sizes for each component
    • value (float (expression)): Size of the split
    • name (string): Rule name to evaluate the split geometry
    • repeat (bool, optional): Whether this split continues until scope is filled
    • type (Size::Type): Type of value, one of:
      • absolute - absolute size
      • relative - relative size to the scope of the object
      • floating - size is adjusted to fill remaining space

Example:

split: 
  axis: "y"
  sizes: 
    - 
      value: "FloorHeight"
      name: "Floor"
      repeat: "true"
      type: "floating"
    - 
      value: "DividerHeight"
      name: "Wall"
      type: "floating"

taper

Performs a geometric extrustion to a taper.

Logically, a taper is like a pyramid with the top sliced off, forming a shape similar to a mesa, with a chamfer on every edge.

A volume is formed from a line drawn from every point of the shape to its centroid at a given angle, up to a given height. A top surface is added of the starting shape scaled to the remaining area to close the volume.

Parameters:

  • height (float (expression)): Height of the extruded volume
  • angle (float (expression)): Angle of the volume from all points, extruded up to height, degrees Example:
taper: 
  height: "10"
  angle: "45.0"

texture

Sets a texture on a face with a path to a file linked into the renderlet.

!! Note for YAML interface !!

Until the per-user cloud storage system is online, it is not yet possible to upload a custom texture.

Several royalty-free textures are provided that you can use in the playground:

  • bricks.jpg
  • brickwall.jpg
  • wall.png
  • window_glass.png
  • roof2.png

In the interim, when building your own renderlets, you can use any path you want. The filename will be copied to the material properties (.mtl file for server-side rendering, metadata in the .rlt wire format), and one can load and attach on the host side.

Parameters:

  • path (string): Path to texture file

Example:

texture: 
  path: "window_glass.png"

translate

Translate an object in 3D space.

Translations can be performed on any axis, relative to absolute world space, relative world space, or relative object space.

Additionally, translation of each axis can be performed in absolute units, or relative to an object's scope.

Parameters:

  • mode (EMode): Sets how translation is applied
    • abs - Sets absolute position to value
    • rel - Moves position by value
  • coordSystem (ECoordSystem): Sets coordinate system for translations
    • object - Object space (origin of scope vector)
    • world - World space (origina of world vector)
  • x (float (expression), optional): Position on X axis
    • value (float (expression)): Amount
    • type (Size::Type): Type of value, one of:
      • absolute - absolute world units
      • relative - relative to the scope of the object
  • y (float (expression), optional): Position on Y axis
    • value (float (expression))
    • type (Size::Type)
  • z (float (expression), optional): Position on Z axis
    • value (float (expression))
    • type (Size::Type)

Example:

translate: 
  mode: "rel"
  coordSystem: "object"
  x: 
    value: "12.0"
    type: "absolute"
  z: 
    value: "0.5"
    type: "relative"