Boron-GL User Manual

Version: 0.2.4
Date: 2014-01-05

Contents

1   Overview

Boron-GL extends the Boron scripting language with datatypes and functions for working with OpenGL 2.1.

Features include:

  • Garbage collected GL datatypes.
  • Texture-based fonts loaded from TrueType files.
  • Loading PNG images.
  • Plays audio from WAV and OGG formats.

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

-a Disable audio
-e "exp" Evaluate expression
-h Show help and exit
-p Disable prompt and exit on exception
-s Disable security

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

Type Name Description
draw-prog! Compiled draw program
raster! Pixel image in main memory
texture! OpenGL texture
font! Texture-based font
shader! OpenGL shader
fbo! OpenGL frame buffer object
vbo! OpenGL vertex buffer object
quat! Quaternion
widget! Widget

3.1   Draw-Prog!

A draw program is a list of display operations compiled to byte-code. It is reminiscent of the GL display list (now deprecated in OpenGL 3.0).

Note

The terms "draw program" and "draw list" are used interchangeably.

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
]

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

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
Mode Function
on glEnable( GL_BLEND )
off glDisable( GL_BLEND )
add glBlendFunc( GL_SRC_ALPHA, GL_ONE )
burn glBlendFunc( GL_ONE, GL_ONE_MINUS_SRC_ALPHA )
trans glBlendFunc( GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA )

4.3   Buffer

Calls glBindBuffer and sets pointer offsets using glVertexPointer, glNormalPointer, etc.

4.4   Camera

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

camera
    which   context!

4.5   Call

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.6   Clear

Calls glClear ( GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT ).

4.7   Color

Sets the gl_Color for shaders.

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

The following all set the color to red:

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

4.8   Color-Mask

Calls glColorMask with all GL_TRUE or GL_FALSE arguments.

color-mask on/off

4.9   Cull

Calls glEnable/glDisable with GL_CULL_FACE.

cull on/off

4.10   Depth-Mask

Calls glDepthMask with GL_TRUE/GL_FALSE.

depth-mask on/off

4.11   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.12   Image

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

image texture!
image coord!/vec3! texture!

4.13   Light

Controls lights.

4.15   Point-Size

point-size on/off

4.16   Point-Sprite

point-sprite on/off

4.18   Rotate

Rotate around axis or by quaternion.

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

4.19   Scale

scale
    value   decimal!/get-word!

4.20   Shader

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

shader
    which   shader!

4.21   Sphere

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

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

4.22   Text

Draws quads for each character.

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

4.22.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.23   Translate

Translate the model view matrix.

translate
    distance    vec3!/get-word!

4.25   Framebuffer

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

framebuffer
    which   fbo! or 0