Programming Reference:3D API

From BCI2000 Wiki
Jump to: navigation, search


The 3D API uses OpenGL to display 3-dimensional objects in a scene. Additionally, a 2D overlay may be displayed on top of the scene. The API was originally created by Shidong Zheng. 3D API source files are located at src/extlib/3DAPI.

The CursorTask uses the 3D API to display its workspace, cursor, and targets.

Graphical Environment

The 3D Environment

Predefined Graphic Primitives

The 3D environment supports any number of predefined graphic primitives. Each graphic primitive can be assigned a number of different properties. These are:

  • Primitive-specific properties
  • Generic properties
    • Brightness (0-255)
    • Transparency (0-255)
    • Color (RGB)
    • Texture

Currently implemented primitives are spheres, cuboids, and infinite planes. The position of a sphere is defined by midpoint (XYZ) and radius. Textures are mapped using circular mapping using arbitrary alignment. The position of a cuboid is defined by a midpoint (XYZ) and a width, height, and depth (to define the extent in X, Y, and Z, respectively). Texture mapping is defined by the orientation and size of a texture. The only supported mapping type is parallel mapping. Infinite planes are defined by a point in XYZ coordinates, and a normal vector. The only supported texture mapping type is parallel mapping with the texture being parallel to the plane.

Once created, there are certain functions that can be applied to any element.

  • Change properties
  • Turn visibility on/off
  • Move midpoint to XYZ
  • Test for collision with another element
  • Rotate element with rotation defined by
    • Angles in X, Y, Z
    • Reference point in X, Y, Z

Custom Graphic Primitives

In addition to built-in primitives, the system also supports custom graphic primitives. These primitives can be defined by loading their 3D structure from a file and they support the same methods as the predefined primitives except collision detection.

3D Text

The system supports any number of 3D text elements. Each text element is defined by

  • Font
  • Font size
  • Caption
  • Brightness (0-255)
  • Transparency (0-255)
  • Color (RGB)
  • Origin (XYZ)
  • Direction (XYZ)

The text elements support methods to modify their properties and to turn them on or off.


The 3D environment supports one camera with the following properties:

  • Camera View Point (XYZ)
  • Aim Point (XYZ)
  • Focal Length
  • Camera Orientation (what is "up" for the camera) (angle)

Light Source

The 3D environment supports one omni-directional light source. The features that describe this light source are:

  • Position (XYZ)
  • Brightness (0-255)
  • Color (RGB)

In addition, the brightness of white ambient background lighting can be defined.

The 2D Overlay

The 3D display can be overlayed by a 2D display (see figure above). This overlay supports a picture with alpha channel (i.e., transparency map), 2D text and a 2D cursor.

Overlay Picture

An overlay picture can be defined by loading it from disc. This picture is stretched to match the window size. Optionally, a transparency map can be defined (i.e., in essence, another picture) whose brightness level defines the s transparency of the overlay. This can create an effect as shown in the figure. Once defined, an overlay image can be turned on or off.

2D Text

The system supports any number of 2D text elements. Text elements are always displayed on top of the overlay picture. The texts' background is transparent and the text itself does not destroy the overlay picture. For each 2D text element, the following properties can be defined:

  • Position (XY)
  • Font
  • Size
  • Color (RGB)

2D Cursor

The system supports one 2D cursor that is always presented as a circle that is filled with a particular color. Specifically, a 2D cursor has the following properties:

  • Position (XY)
  • Size
  • Color (RGB)

See also

User Reference:CursorTask