R: GIR Simple View Utilities

GIR View {gir}

R Documentation

GIR Simple View Utilities

Description

Utility functions, including a simple view framework for rapid prototyping.

Usage

girCreateView(width = 640, height = 480, input, repaintHandler, hfov = 90, zoom = 1, nearPlane = 0.1, farPlane = 20, zoomFactor = 1, translation = FALSE, caption="GIR Window")
girEventLoop(idleHandler = NULL, isDone = function(){girGetCurrentWindow()==0})
girSetupGL()
girSize(width, height, hfov, nearPlane, farPlane)
girSize2D(width, height)

Arguments

`width, height`	integers specifying the size of the window.
`input`	list containing two functions, named `init` and `input`. Should be one of the predefined values `girElevationAzimuth` or `girArcball`
`repaintHandler`	function that is called when the window needs repainting. May be NULL.
`hfov`	integer; the initial horizontal field of view of the camera, in degrees.
`zoom`	the distance from the origin at which the camera should be initially positioned.
`nearPlane`	the distance from the viewpoint to the near clipping plane.
`farPlane`	the distance from the viewpoint to the far clipping plane.
`zoomFactor`	multiplier for zoom sensitivity.
`translation`	logical; whether translation of the camera focus is enabled.
`caption`	string to use as caption for window.
`idleHandler`	function that is called every iteration of the event loop. May be NULL.
`isDone`	function that is called to determine whether to exit the event loop. Should return TRUE if the event loop should exit, FALSE otherwise.

Details

A 'view' is a wrapper around a GIR window which handles input and repainting on demand and more or less automatically. When used in conjunction with the girEventLoop function, creating a simple application requires very little user code.

To create a view, call girCreateView and assign the returned object to a new variable. girCreateView will create a new window and set up input handlers depending on the value of the input parameter, which should be one of girElevationAzimuth or girArcball. These implement an elevation/azimuth input model and a modified version of Ken Shoemake's ARCBALL input model, respectively. Both interfaces react in a similar fashion to user input (see below).

The view object returned by girCreateView is a list that includes several useful functions.

view$repaint(): Invokes the view's repaint handler.
view$destroy(): Immediately destroys the view window and sets the view's done flag to TRUE.
view$setCurrent(): Sets the current window to the view window.
view$getWindow(): Returns the view's window index, to be passed to other GIR functions.
view$isDone(): Returns whether the view's done flag is set.
view$setDone(d): Sets the view's done flag to the specified logical value.
view$draw2d(): Calls girSize2D.
view$draw3d(): Calls girSize.
view$drawArcball(): If input was girArcball, this function will draw the outline of the arcball controller in the current viewport. Calling view\$draw2d beforehand is recommended.

After creating a view and doing any required initialisation, call girEventLoop. This loops over girProcessEvents and executes the user-supplied idleHandler function, until the isDone function returns TRUE.

girSetupGL sets some (hopefully) sensible default GL state in the context of the current window.

girSize resets the GL viewport and projection matrix so that the specified horizontal field of view is maintained. girSize2D sets an orthographic projection matrix such that (0,0) is the lower left of the window and (width, height) is the upper right. Neither of these alter the modelview matrix.

Even if you don't use the other view functions, these can come in handy.

Value

girCreateView returns the newly created view object.
All other functions return NULL, and are invoked for their side effects.

User Interface

The girAxisAzimuth and girArcball input models present similar interfaces to the end user.

Left mouse button

: While held down, moving the mouse will rotate the viewpoint according to the specific input model.

girElevationAzimuth first rotates the camera around the scene (azimuth) according to horizontal mouse input, then rotates this camera orientation above or below the scene (elevation) according to vertical mouse input.

girArcball implements a virtual trackball based on Ken Shoemake's ARCBALL design (see Ken Shoemake, ARCBALL: a user interface for specifying three-dimensional orientation using a mouse, Proceedings of the conference on Graphics interface '92, 1992, Vancouver, British Columbia, Canada

Middle mouse button

: While held down, moving the mouse vertically will zoom the camera in (up) and out (down) from the scene.

Mouse wheel

: Rotating the mouse wheel towards and away from the user will zoom the camera in and out, respectively.

Right mouse button

: If the translate argument of girCreateView was TRUE, holding the right mouse button and moving the mouse horizontally and vertically will translate the camera focus horizontally and vertically in the view plane.

The view window can be closed in the platform-specific default manner, or by pressing Escape when the window has the keyboard focus.

Closing the view window will set the view's done flag to TRUE.

Examples

## Not run: 
        paint<-function()
        {
                glClear(GL_COLOR_BUFFER_BIT+GL_DEPTH_BUFFER_BIT)
                # draw an axis triple
                glBegin(GL_LINES)
                glColor3f(1,0,0)
                glVertex3f(0,0,0); glVertex3f(1,0,0)

                glColor3f(0,1,0)
                glVertex3f(0,0,0); glVertex3f(0,1,0)

                glColor3f(0,0,1)
                glVertex3f(0,0,0); glVertex3f(0,0,1)
                glEnd()
                girSwapBuffers()
        }

        # create the view
        view<-girCreateView(640, 480, girArcball, paint)

        # enter the event loop, stopping when the view is closed
        girEventLoop(NULL,view$isDone)
## End(Not run)

[Package gir version 0.3-2 Index]