1 Overview

Boron-GL extends the Boron scripting language with datatypes and functions for working with OpenGL 3.3 & ES 3.1.

Features include:

• Garbage collected GL datatypes.
• Texture-based fonts loaded from TrueType files.
• Loading PNG images.
• Plays audio from WAV and OGG formats.
• GUI system with automatic layout and styling.
• Animation system.

1.1 About This Document

This manual is largely incomplete.

There is a separate function reference available online at http://urlan.sourceforge.net/boron.

2 Running Scripts

2.1 Shell Invocation

The first line of a script may be a UNIX shell sha-bang (#!) command.

#!/usr/bin/boron-gl

2.2 Command Line Usage

Usage:

boron-gl [options] [script] [arguments]

2.2.1 Command Line Options

2.2.2 Command Line Arguments

If the interpreter is invoked with a script then the args word will be set to either a block of strings, or none if no script arguments were given.

So this command:

boron-gl -e "probe args" file1 -p 2

Will print this:

["file1" "-p" "2"]

3 GL Datatypes

3.1 Draw-Prog!

A draw program is a list of display operations compiled to byte-code. It is reminiscent of the OpenGL 1.0 display list (now deprecated in OpenGL 3.0) but operates on modern elements such as shaders and vertex buffers.

NOTE: The terms draw program and draw list are used interchangeably.

3.2 Raster!

3.3 Texture!

The simplest way to make textures is to use the load-texture function.

load-texture %skin.png

Full specification:

make texture! [
    raster!/coord!/int!
    binary!
    'mipmap 'nearest 'linear 'repeat 'clamp
    'gray 'rgb' 'rgba
    'depth
]

3.4 Font!

A texture-based font.

make font! [%font-file.ttf 20]
make font! [%font-file.ttf face 1 20 "characters" 256,128]
make font! [raster! binary!]
make font! [texture! binary!]

3.5 Shader!

make shader! [
    vertex {...}
    fragment {...}
    default []
]

3.6 Fbo!

A framebuffer object is a render target.

3.7 Vbo!

Vertex buffers hold arrays of geometry vertex attributes.

3.8 Quat!

A unit-length quaternion.

Multiply a quat! by -1.0 to conjugate (invert) it. Multiplying a quat! by a vec3! will return a transformed vec3!.

Examples quaternions::

to-quat none     ; Identity
to-quat 10,0,240 ; From euler x,y,z angles

3.9 Widget!

4 Draw Program Instructions

In addition to the following instructions, any paren! value will be evaluated as Boron code at that point in the draw list.

Some instructions accept a get-word! argument. When this is used, the word value is read each time program is run rather than using a fixed value.

4.1 Box

Draws a box given minimum and maximum extents. Internally, a vertex buffer with normals & texture coordinates is created.

box
    min   int!/decimal!/vec3!
    max   int!/decimal!/vec3!

4.2 Blend

Sets the blending mode using glBlendFunc.

blend
    mode    on/off/add/burn/trans

4.3 Buffer

Calls glBindBuffer and sets pointer offsets using glVertexAttribPointer.

Currently only a single buffer command can be used between one or more primitive draw commands (tris, points, etc.).

4.4 Buffer-inst

Binds an array buffer like buffer, but also sets the glVertexAttribDivisor to 1 for use in instanced draws.

Currently buffer-inst must follow a buffer command.

4.5 Camera

Sets the camera context. glViewport is called and the GL_PROJECTION and GL_MODELVIEW matrices are set.

camera
    which   context!

4.6 Call

Runs another draw program.

Calling a none! value does nothing and can be used to disable the display of an item.

call
    list    none!/draw-prog!/widget!/get-word!

4.7 Clear

Calls glClear ( GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT ).

4.8 Color

Sets a shader vec4 uniform at layout(location = 1).

color
    value   int!/double!/coord!/vec3!/get-word!

The following all set the color to red (with alpha 1.0)::

color 0xff0000
color 255,0,0
color 1.0,0.0,0.0

It is recommended to use vec3!.

Grey values (with alpha 1.0) can be set using int!/double!.

4.9 Color-Mask

Calls glColorMask with all GL_TRUE or GL_FALSE arguments.

color-mask on/off

4.10 Cull

Calls glEnable/glDisable with GL_CULL_FACE.

cull on/off

4.11 Depth-Mask

Calls glDepthMask with GL_TRUE/GL_FALSE.

depth-mask on/off

4.12 Font

Sets the font for text instructions. This only provides the glyph metrics needed to generate quads; it does not actually emit any data into the compiled draw-prog. The shader instruction must be used to specify the texture.

font
    which   font!

4.13 Framebuffer

Calls glBindFramebuffer with target GL_FRAMEBUFFER. Pass zero to restore rendering to the display.

framebuffer
    which   fbo! or 0

4.14 Image

Display image at 1:1 texel to pixel scale. An optional X,Y position can be specified.

image [x,y] texture!
image x,y,w,h
image/horiz xmin,xmax,ycenter texture!
image/vert  ymin,ymax,xcenter texture!

4.15 Light

Controls lights.

4.16 Lines

Draw line primitives using glDrawElements with GL_LINES.

lines
    elements    int!/vector!

4.17 Line-strip

Draw line primitives using glDrawElements with GL_LINES.

line-strip
    elements    int!/vector!

4.18 Pop

Calls the equivalent of glPopMatrix.

4.19 Points

Draw point primitives using glDrawArrays or glDrawElements with GL_POINTS.

points
    elements    int!/vector!

4.20 Point-Size

point-size on/off

4.21 Point-Sprite

point-sprite on/off

4.22 Push

Calls the equivalent of glPushMatrix on the modelview stack.

4.23 Push-Model

Push (and multiply) a matrix onto the modelview stack and also copy the original matrix into a shader uniform.

Calls the equivalent of glPushMatrix, glMultMatrix & glUniformMatrix4fv.

push-model uniform-name :matrix-variable

4.24 Push-Mul

Calls the equivalent of glPushMatrix followed by glMultMatrix on the modelview stack.

push-mul :matrix

4.25 Rotate

Rotate around axis or by quaternion.

rotate x/y/z decimal!
rotate x/y/z get-word!
rotate get-word!

4.26 Scale

scale
    value   decimal!/get-word!

4.27 Shader

Calls glUseProgram, binds and enables any textures used, and calls glUniform for any variables.

shader
    which   shader!

4.28 Sphere

Draws a sphere. Internally, a vertex buffer with normals & texture coordinates is created.

sphere
    radius          int!/decimal!
    slices,stacks   coord!

4.29 Text

Draws quads for each character.

text x,y string!
text/center/right rect [x,y] string!

4.29.1 Text Center

Using the center option centers the string horizontally and vertically within the rect argument. To center only horizontally use a width (fourth value) of zero.

4.30 Translate

Translate the model view matrix.

translate
    distance    vec3!/get-word!

4.31 Tris

Draw triangles primitives using glDrawElements with GL_TRIANGLES.

tris
    elements    int!/vector!

4.32 Tri-fan

Draw triangles primitives using glDrawElements with GL_TRIANGLE_FAN.

tri-fan
    elements    int!/vector!

4.33 Tri-strip

Draw triangles primitives using glDrawElements with GL_TRIANGLE_STRIP.

tri-strip
    elements    int!/vector!

4.34 Tris-inst

Draw triangles primitives using glDrawElementsInstanced.

tris-inst
    elements    int!/vector!
    count

4.35 Quad

Draw a single textured rectangle.

quad
    tex-size    int!/vector!
    uvs         coord!
    area        coord!

4.36 Quads

Draw quadrangle primitives (each as two triangles).

quads
    elements    int!/vector!

4.37 Uniform

Set a shader uniform variable using glUniform or glBindTexture (for textures).

uniform
    uniform-name  word!
    value         logic!/int!/double!/vec3!/texture!

4.38 View-Uniform

Transform a point into view space and assign this to a uniform using glUniform3fv.

view-uniform
    uniform-name  word!
    point         get-word! that references a vec3!.
    /dir          Treat point as a directional vector.

Using the dir option will only transform the point by the upper 3x3 portion of the view matrix.

5 Widget Make Instructions

5.1 expand

Fills as much space as possible to push other widgets against parent edges.

5.2 space

Fill some space to leave a gap.

5.3 hbox

5.4 vbox

5.5 grid

Size is colums,rows.

5.6 window

Free-floating movable window.

5.7 viewport

5.8 overlay

Place widgets over the parent area.

Layout is ’hbox or ’vbox.

5.9 button

5.10 checkbox

5.11 choice

5.12 label

5.13 line-edit

5.14 list

5.15 slider

Range is minimum,maximum.