libgls  1.0.1
Stereoscopic Rendering with OpenGL
Typedefs | Enumerations
gls.h File Reference

The libgls interface. More...

Typedefs

typedef struct GLS_context GLScontext
 The GLS context. More...
 

Enumerations

enum  GLSmode {
  GLS_MODE_QUAD_BUFFER_STEREO = 0, GLS_MODE_ALTERNATING = 1, GLS_MODE_MONO_LEFT = 2, GLS_MODE_MONO_RIGHT = 3,
  GLS_MODE_LEFT_RIGHT = 4, GLS_MODE_TOP_BOTTOM = 5, GLS_MODE_HDMI_FRAME_PACK = 6, GLS_MODE_EVEN_ODD_ROWS = 7,
  GLS_MODE_EVEN_ODD_COLUMNS = 8, GLS_MODE_CHECKERBOARD = 9, GLS_MODE_RED_CYAN_MONOCHROME = 10, GLS_MODE_RED_CYAN_HALF_COLOR = 11,
  GLS_MODE_RED_CYAN_FULL_COLOR = 12, GLS_MODE_RED_CYAN_DUBOIS = 13, GLS_MODE_GREEN_MAGENTA_MONOCHROME = 14, GLS_MODE_GREEN_MAGENTA_HALF_COLOR = 15,
  GLS_MODE_GREEN_MAGENTA_FULL_COLOR = 16, GLS_MODE_GREEN_MAGENTA_DUBOIS = 17, GLS_MODE_AMBER_BLUE_MONOCHROME = 18, GLS_MODE_AMBER_BLUE_HALF_COLOR = 19,
  GLS_MODE_AMBER_BLUE_FULL_COLOR = 20, GLS_MODE_AMBER_BLUE_DUBOIS = 21, GLS_MODE_RED_GREEN_MONOCHROME = 22, GLS_MODE_RED_BLUE_MONOCHROME = 23
}
 GLS stereoscopic display modes. More...
 
enum  GLSview { GLS_VIEW_LEFT = 0, GLS_VIEW_RIGHT = 1 }
 GLS stereoscopic view. More...
 

Functions

Version information
const char * glsVersion (GLint *major, GLint *minor, GLint *patch)
 Get the libgls version. More...
 
Manage GLS contexts
GLScontextglsCreateContext ()
 Create a new GLS context. More...
 
void glsDestroyContext (GLScontext *ctx)
 Destroy a GLS context. More...
 
Stereoscopic scene setup
void glsFrustum (GLdouble left, GLdouble right, GLdouble bottom, GLdouble top, GLdouble zNear, GLdouble zFar, GLdouble focalLength, GLdouble eyeSeparation, GLSview view)
 Stereoscopic variant of glFrustum(). More...
 
void glsPerspective (GLdouble fovy, GLdouble aspect, GLdouble zNear, GLdouble zFar, GLdouble focalLength, GLdouble eyeSeparation, GLSview view)
 Stereoscopic variant of gluPerspective(). More...
 
void glsLookAt (GLdouble eyeX, GLdouble eyeY, GLdouble eyeZ, GLdouble centerX, GLdouble centerY, GLdouble centerZ, GLdouble upX, GLdouble upY, GLdouble upZ, GLdouble eyeSeparation, GLSview view)
 Stereoscopic variant of gluLookAt(). More...
 
Set GLS options
void glsSetViewportScreenCoords (GLScontext *ctx, GLint x, GLint y)
 Set the screen coordinates of the viewport. More...
 
void glsSetCrosstalkGhostbusting (GLScontext *ctx, GLfloat r, GLfloat g, GLfloat b, GLfloat ghostbust)
 Set crosstalk levels for the display device. More...
 
Stereoscopic Display
void glsClear (GLScontext *ctx)
 Start a new frame. More...
 
GLboolean glsIsViewRequired (GLScontext *ctx, GLSmode mode, GLboolean swapViews, GLSview view)
 Check if a view is required for the given mode. More...
 
void glsSubmitView (GLScontext *ctx, GLSview view)
 Submit a view to the current frame. More...
 
void glsDrawSubmittedViews (GLScontext *ctx, GLSmode mode, GLboolean swapViews)
 Displays the submitted views in stereoscopic mode. More...
 
void glsDrawViews (GLScontext *ctx, GLSmode mode, GLboolean swapViews, GLuint leftViewTexture, GLuint rightViewTexture)
 Displays the given views in stereoscopic mode. More...
 
void glsDrawDLP3dReadySyncMarker (GLScontext *ctx, GLSmode mode)
 Draw optional DLP 3D Ready Sync markers. More...
 

Detailed Description

The libgls interface.

This document describes the interface of libgls.

Typedef Documentation

typedef struct GLS_context GLScontext

The GLS context.

All functions require a GLS context. See glsCreateContext() and glsDestroyContext().

Enumeration Type Documentation

enum GLSmode

GLS stereoscopic display modes.

See http://www.site.uottawa.ca/~edubois/anaglyph/ for more information about the Dubois anaglyph modes.

Enumerator
GLS_MODE_QUAD_BUFFER_STEREO 

OpenGL quad buffered stereo. This mode can only be used if the application created an OpenGL context with quad buffered stereo support.

GLS_MODE_ALTERNATING 

Left and right view alternating for each display output frame. This allows to use active stereo displays without OpenGL quad buffer support. Note that this requires that you can render your scene at the display framerate, which is at least at 120 Hz for active stereo displays. Note also that this mode may be unreliable and may swap left/right eyes occasionally, depending on your system, graphics hardware, and driver.

GLS_MODE_MONO_LEFT 

Left view only.

GLS_MODE_MONO_RIGHT 

Right view only.

GLS_MODE_LEFT_RIGHT 

Left view in left half of viewport, right view in right half. Used by some 3D TVs and displays.

GLS_MODE_TOP_BOTTOM 

Left view in top half of viewport, right view in bottom half. Used by some 3D TVs and displays.

GLS_MODE_HDMI_FRAME_PACK 

HDMI Frame packing (left view in top half, right view in bottom half, separated by 1/49 of the viewport height).

This mode only makes sens if you are forcing your display into the corresponding HDMI 3D mode. A description how to do this on GNU/Linux can be found here: http://lists.nongnu.org/archive/html/bino-list/2011-03/msg00033.html

GLS_MODE_EVEN_ODD_ROWS 

Left view in even pixel rows, right view in odd pixel rows. Used by some 3D TVs and displays.

GLS_MODE_EVEN_ODD_COLUMNS 

Left view in even pixel columns, right view in odd pixel columns. Used by some 3D TVs and displays.

GLS_MODE_CHECKERBOARD 

Left and right view pixels in a checkerboard pattern. Used by some 3D TVs and displays.

GLS_MODE_RED_CYAN_MONOCHROME 

Red/cyan anaglyph glasses, monochrome method.

GLS_MODE_RED_CYAN_HALF_COLOR 

Red/cyan anaglyph glasses, half color method.

GLS_MODE_RED_CYAN_FULL_COLOR 

Red/cyan anaglyph glasses, full color method.

GLS_MODE_RED_CYAN_DUBOIS 

Red/cyan anaglyph glasses, high quality Dubois method (recommended).

GLS_MODE_GREEN_MAGENTA_MONOCHROME 

Green/magenta anaglyph glasses, monochrome method.

GLS_MODE_GREEN_MAGENTA_HALF_COLOR 

Green/magenta anaglyph glasses, half color method.

GLS_MODE_GREEN_MAGENTA_FULL_COLOR 

Green/magenta anaglyph glasses, full color method.

GLS_MODE_GREEN_MAGENTA_DUBOIS 

Green/magenta anaglyph glasses, high quality Dubois method (recommended).

GLS_MODE_AMBER_BLUE_MONOCHROME 

Amber/blue anaglyph glasses, monochrome method.

GLS_MODE_AMBER_BLUE_HALF_COLOR 

Amber/blue anaglyph glasses, half color method.

GLS_MODE_AMBER_BLUE_FULL_COLOR 

Amber/blue anaglyph glasses, full color method.

GLS_MODE_AMBER_BLUE_DUBOIS 

Amber/blue anaglyph glasses, high quality Dubois method (recommended).

GLS_MODE_RED_GREEN_MONOCHROME 

Red/green anaglyph glasses, monochrome method.

GLS_MODE_RED_BLUE_MONOCHROME 

Red/blue anaglyph glasses, monochrome method.

enum GLSview

GLS stereoscopic view.

Enumerator
GLS_VIEW_LEFT 

Left view.

GLS_VIEW_RIGHT 

Right view.

Function Documentation

const char* glsVersion ( GLint *  major,
GLint *  minor,
GLint *  patch 
)

Get the libgls version.

Parameters
majorBuffer for the major version number, or NULL.
minorBuffer for the minor version number, or NULL.
patchBuffer for the patch version number, or NULL.
Returns
The libgtls version string.

This function returns the version string "MAJOR.MINOR.PATCH". If the pointers major, minor, patch are not NULL, the requested version number will be stored there.

GLScontext* glsCreateContext ( )

Create a new GLS context.

Returns
The GLS context.

Creates a new GLS context. If you use multiple OpenGL contexts, you need a GLS context for each of them. If something goes wrong, this function returns a NULL pointer.

void glsDestroyContext ( GLScontext ctx)

Destroy a GLS context.

Parameters
ctxThe GLS context.

Destroys a GLS context and frees all of its resources.

void glsFrustum ( GLdouble  left,
GLdouble  right,
GLdouble  bottom,
GLdouble  top,
GLdouble  zNear,
GLdouble  zFar,
GLdouble  focalLength,
GLdouble  eyeSeparation,
GLSview  view 
)

Stereoscopic variant of glFrustum().

Parameters
leftLeft clipping plane.
rightRight clipping plane.
bottomBottom clipping plane.
topTop clipping plane.
zNearNear plane.
zFarFar plane.
focalLengthFocal length.
eyeSeparationEye separation, typically 1/30 of focal length.
viewThe view.

This is a stereoscopic drop-in replacement for glFrustum(). It sets up an asymmetric viewing frustum to render the given view. In addition, you need to shift your scene sideways by half the eye separation (shift left for the left view and right for the right view); glsLookAt() will do that automatically for you.

See http://www.opengl.org/sdk/docs/man/xhtml/glFrustum.xml for a description of the glFrustum() parameters left , right, bottom, top, zNear, and zFar.

The focalLength parameter is the distance to the zero parallax plane. It is often chosen roughly as the distance between the viewer and the scene center. Objects nearer to the viewer are in front of the zero parallax plane and have a negative parallax. Note that objects should not be nearer than half the focal length, otherwise the stereoscopic effect suffers. Objects farther from the viewer are behind the zero parallax plane and have a positive parallax.

The eyeSeparation parameter is the distance between the left and the right eye. This is often chosen to be 1/30 of the focal length.

The view parameter selects the left or right view.

See http://paulbourke.net/miscellaneous/stereographics/stereorender/ for more information on how to set up stereoscopic views.

void glsPerspective ( GLdouble  fovy,
GLdouble  aspect,
GLdouble  zNear,
GLdouble  zFar,
GLdouble  focalLength,
GLdouble  eyeSeparation,
GLSview  view 
)

Stereoscopic variant of gluPerspective().

Parameters
fovyField of view angle, in degrees.
aspectAspect ratio of window.
zNearNear plane.
zFarFar plane.
focalLengthFocal length.
eyeSeparationEye separation, typically 1/30 of focal length.
viewThe view.

This is a stereoscopic drop-in replacement for gluPerspective(). It sets up an asymmetric viewing frustum to render the given view. In addition, you need to shift your scene sideways by half the eye separation (shift left for the left view and right for the right view); glsLookAt() will do that automatically for you.

See http://www.opengl.org/sdk/docs/man/xhtml/gluPerspective.xml for a description of the gluPerspective() parameters fovy, aspect, zNear, and zFar.

The focalLength parameter is the distance to the zero parallax plane. It is often chosen roughly as the distance between the viewer and the scene center. Objects nearer to the viewer are in front of the zero parallax plane and have a negative parallax. Note that objects should not be nearer than half the focal length, otherwise the stereoscopic effect suffers. Objects farther from the viewer are behind the zero parallax plane and have a positive parallax.

The eyeSeparation parameter is the distance between the left and the right eye. This is often chosen to be 1/30 of the focal length.

The view parameter selects the left or right view.

See http://paulbourke.net/miscellaneous/stereographics/stereorender/ for more information on how to set up stereoscopic views.

void glsLookAt ( GLdouble  eyeX,
GLdouble  eyeY,
GLdouble  eyeZ,
GLdouble  centerX,
GLdouble  centerY,
GLdouble  centerZ,
GLdouble  upX,
GLdouble  upY,
GLdouble  upZ,
GLdouble  eyeSeparation,
GLSview  view 
)

Stereoscopic variant of gluLookAt().

Parameters
eyeXX coordinate of the eye.
eyeYY coordinate of the eye.
eyeZZ coordinate of the eye.
centerXX coordinate of the reference point.
centerYY coordinate of the reference point.
centerZZ coordinate of the reference point.
upXX component of the up vector.
upYY component of the up vector.
upZZ component of the up vector.
eyeSeparationEye separation, typically 1/30 of focal length.
viewThe view.

This is a stereoscopic drop-in replacement for gluLookAt(). It shifts your scene sidewise by half the eye separation, depending on the view. In addition, you need to set up an off-axis, asymmetric viewing frustum; glsPerspective() will do that automatically for you.

See http://www.opengl.org/sdk/docs/man/xhtml/gluLookAt.xml for a description of the gluLookAt() parameters eyeX, eyeY, eyeZ, centerX, centerY, centerZ, upX, upY, and upZ.

The eyeSeparation parameter is the distance between the left and the right eye. This is often chosen to be 1/30 of the focal length; see glsPerspective().

The view parameter selects the left or right view.

See http://paulbourke.net/miscellaneous/stereographics/stereorender/ for more information on how to set up stereoscopic views.

void glsSetViewportScreenCoords ( GLScontext ctx,
GLint  x,
GLint  y 
)

Set the screen coordinates of the viewport.

Parameters
ctxThe GLS context.
xThe x coordinate of the bottom left corner.
yThe y coordinate of the bottom left corner.

Sets the current screen coordinates of the OpenGL viewport.

This information is used by the modes GLS_MODE_EVEN_ODD_ROWS, GLS_MODE_EVEN_ODD_COLUMNS, and GLS_MODE_CHECKERBOARD, because these modes operate on absolute pixel coordinates and not on viewport-relative pixel coordinates. All other modes ignore this.

Note that lines are counted from bottom to top, and that the bottom left corner coordinates are required.

void glsSetCrosstalkGhostbusting ( GLScontext ctx,
GLfloat  r,
GLfloat  g,
GLfloat  b,
GLfloat  ghostbust 
)

Set crosstalk levels for the display device.

Parameters
ctxThe GLS context.
rRed color channel crosstalk, from 0 to 1.
gGreen color channel crosstalk, from 0 to 1.
bBlue color channel crosstalk, from 0 to 1.
ghostbustGhostbusting level, from 0 to 1.

Set the crosstalk levels for this display device, and the level of ghostbusting that will be applied. By default, ghostbusting is disabled (ghostbust = 0).

Many stereoscopic display devices suffer from crosstalk between the left and right view. This results in ghosting artifacts that can degrade the viewing quality, depending on the stereoscopic content.

Libgls can optionally reduce the ghosting artifacts. For this, it needs two know

  • the amount of crosstalk of the display device and
  • the amount of ghostbusting that is adequate for the stereoscopic content.

To measure the display crosstalk, do the following:

You now have three crosstalk values for the red, green, and blue channels. Use these values as the crosstalk parameters r, g, and b of this function.

Furthermore, you can adjust the amount of ghostbusting that libgls should apply using the ghostbust parameter. This will vary depending on the stereoscopic contenty. Very dark scenes should be viewed with at least 50% ghostbusting (ghostbust is 0.5), whereas overall bright scenes, where crosstalk is less disturbing, could be viewed with a lower level (e.g. ghostbust 0.1).

Please note that ghostbusting does not work with anaglyph glasses.

void glsClear ( GLScontext ctx)

Start a new frame.

Parameters
ctxThe GLS context.

This function must always be called when starting a new frame, before calling any other GLS function.

GLboolean glsIsViewRequired ( GLScontext ctx,
GLSmode  mode,
GLboolean  swapViews,
GLSview  view 
)

Check if a view is required for the given mode.

Parameters
ctxThe GLS context.
modeThe stereoscopic display mode.
swapViewsWhether to swap left and right view.
viewThe view.
Returns
Whether the given view is required for the given mode.

This function can be used to avoid rendering the left or right view if that view is not required by the given mode. This is mainly useful for the GLS_MODE_ALTERNATING mode, which needs only either the left or the right view and requires rendering with at least 120 fps, but it can also be useful for the GLS_MODE_MONO_LEFT and GLS_MODE_MONO_RIGHT modes.

void glsSubmitView ( GLScontext ctx,
GLSview  view 
)

Submit a view to the current frame.

Parameters
ctxThe GLS context.
viewThe view.

Submit a view to the current frame. Before displaying the current frame in a stereoscopic mode, you need to submit left view and/or right view.

The view is taken from the current viewport inside the current GL_READ_BUFFER.

void glsDrawSubmittedViews ( GLScontext ctx,
GLSmode  mode,
GLboolean  swapViews 
)

Displays the submitted views in stereoscopic mode.

Parameters
ctxThe GLS context.
modeThe stereoscopic display mode.
swapViewsWhether to swap left and right view.

Takes the views that were submitted for this frame and renders them in the given mode.

The frame is rendered into the current GL_DRAW_BUFFER.

void glsDrawViews ( GLScontext ctx,
GLSmode  mode,
GLboolean  swapViews,
GLuint  leftViewTexture,
GLuint  rightViewTexture 
)

Displays the given views in stereoscopic mode.

Parameters
ctxThe GLS context.
modeThe stereoscopic display mode.
swapViewsWhether to swap left and right view.
leftViewTextureThe texture containing the left view.
rightViewTextureThe texture containing the right view.

Renders the given views in the given mode. If a view is not available, its texture can be zero. In this case, libgls will simply use the other texture for both views if required by the display mode.

The result is rendered into the current GL_DRAW_BUFFER.

void glsDrawDLP3dReadySyncMarker ( GLScontext ctx,
GLSmode  mode 
)

Draw optional DLP 3D Ready Sync markers.

Parameters
ctxThe GLS context.
modeThe stereoscopic display mode.

Draws DLP 3D Ready Sync markers. Display devices can use these markers to identify certain stereoscopic modes automatically.

This only makes sense if

  • mode is one of GLS_MODE_LEFT_RIGHT, GLS_MODE_TOP_BOTTOM, or GLS_MODE_ALTERNATING,
  • and the application renders in fullscreen mode,
  • and the connected display device supports this feature.

Use this function after glsDrawSubmittedViews() / glsDrawViews().