OpenGL Functions

GL function names follow a standardized scheme

All begin with "gl", followed by the basic name of the command

When there's only one possible form of arguments:

OpenGL Functions

When arguments can take multiple forms:

e.g. the Color function has the forms:

• glColor3f - 3 floating point arguments
• glColor3i - 3 integer arguments
• glColor3ub - 3 unsigned byte arguments
• glColor3fv - 1 argument, a vector of 3 floating point numbers
• etc.

OpenGL Constants

Constants are defined for certain function arguments

Constant names are all in capital letters, in the form:

e.g. possible arguments for glBegin() are:

• GL_POINTS
• GL_LINES
• GL_TRIANGLES
• GL_TRIANGLE_STRIP
• etc.

GLUT

OpenGL Utility Toolkit

GLUT provides a simple interface for opening & managing windows, and getting input from the keyboard & mouse.

It also defines a basic program structure - an event loop, with callback functions.

GLUT documentation

GLUT Framework

GLUT Events

Events in GLUT include:

• Key pressed
• Key released
• Mouse button pressed
• Mouse button released
• Mouse moved
• Mouse entered/left window
• Window resized
• Window needs redrawing
• Menu selection
• Special devices - tablet, spaceball, dial/buttonbox
• Timer elapsed
• Idle (no events pending)

GLUT Functions - Setup

glutInit(sys.argv)

Initialize GLUT
sys.argv is the command-line arguments

glutInitDisplayMode(mode)

Tell GLUT what GL-related options the window should have
mode is a bitwise-or'ed (the | operator) subset of:

• GLUT_SINGLE - single-buffered
• GLUT_DOUBLE - double-buffered
  
  
• GLUT_RGB - use RGB color
• GLUT_INDEX - use color indexing
  
  
• GLUT_DEPTH - allow depth-buffering

(other options exist, but we won't be using them in this class)

glutInitWindowSize(x,y)

Set the initial size of the window (in pixels)

glutInitWindowPosition(x,y)

Set the window's initial location on the screen (in pixels, from the upper left corner)

glutCreateWindow(title)

Tell GLUT to create the window. The window will not actually appear immediately.
title is the name of the window.

GLUT Functions - Callbacks

glutDisplayFunc(function)

Gives the name of a function to call whenever the graphics must be drawn.

glutKeyboardFunc(function)

Gives the name of a function to call whenever a key is pressed.
function takes 3 arguments - key, x, y. key is the key that was pressed; x & y are the position of the mouse when the key was pressed.

glutKeyboardUpFunc(function)

Gives the name of a function to call whenever a key is released.
function takes 3 arguments - key, x, y. key is the key that was released; x & y are the position of the mouse when the key was pressed.

glutSpecialFunc(function)

Gives the name of a function to call whenever a 'special' key is pressed.
function takes 3 arguments - key, x, y. key is the key that was pressed, e.g. GLUT_KEY_UP, GLUT_KEY_HOME; x & y are the position of the mouse when the key was pressed.

glutMouseFunc(function)

Gives the name of a function to call whenever a mouse button is pressed or released.
function takes 4 arguments - button, state, x, y. button is the button that was pressed - GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON, GLUT_RIGHT_BUFFON; state is either GLUT_DOWN or GLUT_UP; x & y are the position of the mouse when the button's state changed.

glutTimerFunc(msecs, function, value)

Gives the name of a function to call when msecs (or more) milliseconds have elapsed. value is an argument to pass to function.

glutIdleFunc(function)

Gives the name of a function to call when there are no events left to be handled.

GLUT Functions - Other

glutMainLoop()

Starts GLUT's event loop. This function never returns, so code after it will not be executed.

glutPostRedisplay()

Generates a "window needs redrawing" event, forcing GLUT to call your draw function
This can be called from an event callback function, to force redrawing when something changes. If called from the idle function, the window will be constantly redrawn.

GLUT Example

# Minimal program to open & clear a window.
import sys
from OpenGL.GLUT import *
from OpenGL.GL import *
from OpenGL.GLU import *

def draw():
    glClear(GL_COLOR_BUFFER_BIT)
    glFlush()

def keyboard(key, x, y):
    if key == 'q':
        sys.exit(0)
    elif key == ' ':
        print 'Mouse is at', x, y

glutInit([])
glutInitDisplayMode(GLUT_SINGLE | GLUT_RGB)
glutInitWindowSize(200, 200)
glutInitWindowPosition(0,0)
glutCreateWindow(sys.argv[0])
glutDisplayFunc(draw)
glutKeyboardFunc(keyboard)
glutMainLoop()

Geometry

OpenGL Geometry

OpenGL includes functions to draw points, lines, and polygons.

All other shapes are made up of these elements.

A basic shape is entirely described by its vertices, which are connected by straight edges.

The graphics hardware fills in all the necessary pixels.

OpenGL Geometry

The basic method for drawing a shape is:

glBegin(...)
glVertex(...)
glVertex(...)
glVertex(...)
...

glEnd()

Always be sure to have a matching glEnd() for each glBegin()

OpenGL Geometry

GL_POINTS	GL_LINES	GL_LINE_STRIP	GL_LINE_LOOP
GL_TRIANGLES	GL_TRIANGLE_STRIP	GL_TRIANGLE_FAN
GL_QUADS	GL_QUAD_STRIP	GL_POLYGON

OpenGL Geometry

    glColor3f(1, 0.5, 0)
    glBegin(GL_TRIANGLES)
    glVertex2f(0, 0)
    glVertex2f(1, 0)
    glVertex2f(0.5, 0.5)
    glEnd()

Coordinate Systems

Coordinate Systems

A coordinate system is needed for measuring objects' positions

It allows us to describe any location by a set of numbers - 2 numbers when working in 2 dimensions, 3 numbers for 3 dimensions.

A coordinate system has an origin (a reference point) and coordinate axes

In 2D we have an X axis and a Y axis. In 3D, we add a Z axis.

The axes are perpendicular - they are independent

Coordinate Systems

Coordinate Systems

Some coordinate systems used:

• Desktop coordinates
  • Origin at upper left corner of screen
  • +X points right, +Y points down
  • 1 unit = 1 pixel
  
  
• GLUT pointer coordinates
  • Origin at upper left corner of window
  • +X right, +Y down
  • 1 unit = 1 pixel
  
  
• Default OpenGL drawing coordinates
  • Origin at center of window
  • +X right, +Y up
  • 1 unit = 1/2 width or height of window

Coordinate Systems

Drawing commands that specify locations:

glutInitWindowPosition

Position to open a new window at, given in "desktop pixel coordinates"

glRasterPos

Position for glDrawPixels, given in "drawing coordinates"

glWindowPos

Position for glDrawPixels, given in "window pixel coordinates"

glVertex

Position of a shape's vertex, given in "drawing coordinates"

gluOrtho2D

The default drawing coordinate system can be changed with the function gluOrtho2D

e.g.:

    glMatrixMode(GL_PROJECTION)
    glLoadIdentity()
    gluOrtho2D(0.0, 10.0, 0.0, 5.0)
    glMatrixMode(GL_MODELVIEW)

gluOrtho2D

gluOrtho2D is typically used either in the drawing function, or in GLUT's reshape callback.

The reshape callback is called whenever the window changes size.

e.g., to make the window always span -10 to +10 in X, while keeping the aspect ratio 1:1, the coordinate range in Y will depend on the window size:

def reshape(w, h):
    glViewport(0, 0, w, h)
    glMatrixMode(GL_PROJECTION)
    glLoadIdentity()
    gluOrtho2D(-10.0, 10.0, -10.0*h/w, 10.0*h/w)
    glMatrixMode(GL_MODELVIEW)

glutReshapeFunc(reshape)

Homework

Programs will be reviewed in class next week - Tuesday, 11 September.

This document is by Dave Pape, and is released under a Creative Commons License.