DoDevice(3D)

NAME
DoDevice - Open a device

SYNOPSIS
C:
DtObject DoDevice(devicetype, argstring)
DtPtr devicetype;
DtPtr argstring;

FORTRAN:
INTEGER*4 DOD(DEVTYP, LDEV, ARGSTR, LARG)
INTEGER*4 LDEV, LARG
CHARACTER*LDEV DEVTYP
CHARACTER*LARG ARGSTR

DESCRIPTION
DoDevice opens and initializes a Dore device of the indicated type. A device is an output mechanism used to display a frame. DoDevice returns an object handle to be used for further references to the device.

devicetype is a string that specifies the type of device to create.

argstring is a string with embedded device options. The options specify optional initialization values for the device. Options not specified will default to reasonable values. An option takes one of the following forms:

-optionflag optionvalue
    for options requiring values.

-optionflag
    for boolean flags where the presence of "-optionflag" means true and the absence of "-optionflag" means false.

Numeric option values must be specified by their decimal ASCII representations. Multiple options within argstring must be separated by at least one blank, tab, or comma, though all legal options may occur in any order within argstring. If the same option is specified more than once in argstring, then only the last value for that option is used. The legal options in argstring depend upon the devicetype parameter.

The following two examples list the allowable device options for two different devices. The first example lists the options for a generic raster Dore device, and the second example lists the options for a Standard X11 Dore device. For a list of Dore-supported devices on your system, and for information regarding these devices, see the Dore System Guide for your particular system.

``rasterfile'' - a simple file format for full-color pixel data output. The options are:

	``-filename name''
		where name is a string that specifies the
		name of the file into which the image should be
		stored.
	``-width pixwidth''
		where pixwidth is the width in pixels of the
		image to be saved.  The default width is 512
		pixels if this parameter is not specified.

	``-height pixheight''
		where pixheight is the height in pixels of
		the image to be saved.  The default height is
		512 pixels if this parameter is not specified.
``stdx11'' - a standard X11 window device. The options are:
	``-noautosize''
		This option prevents the device viewport from
		automatically being set to the device extent when the
		device extent changes.  By default, autosizing is on.
	``-screen'' number
		The X11 window will be opened on screen number.
	``-depth'' depth
		The driver will use a window of depth depth. The
		depth is determined from the available X visuals matching
		the other parameters if it is not specified.
	``-defaultmap''
		The driver will use the X11 default color map when it
		creates the X11 window.
	``-trueramp'' red green blue
		The driver will use red values for red, green
		values for green, and blue values for blue when it
		uses the shade mode DcComponent or DcRange.
	``-singlebuffered''
		Requests a single buffered window.
	``-geometry geomstring''
		Requests a window with a particular position
		and size.  The format for geomstring is ``WxH+X+Y''
		or ``WxH'' (where W, H, X, and Y are the integer
		values for width, height, and the X,Y position
		of the upper left corner of the window).  If
		the ``WxH'' format is used, X and Y are assumed
		to be zero.
	``-visualtype vtype''
		Requests a window of the given visual type
		(where vtype is DcDirectColor, DcPseudoColor,
		etc.).
	``-window xwindow''
		Requests that the x window handle xwindow
		that was opened by the application be the
		window in which Dore draws. When this option
		is included, options of the previous three
		types will be ignored.
	``-display xdisplay''
		If a window option was specified, that window on
		the display xdisplay is used. Otherwise, Dore
		opens a window on xdisplay.
	``-zbuffer
		The device will use the software z-buffer.
	``-dither
		Dithering will be enabled when using the z-buffer.

After a call to DoDevice and until the device object is deleted, the device handle may be used by subsequent device functions to alter the characteristics of the actual device (such as causing it to display). Dore devices use right-handed 3-D floating point coordinate systems with the origin in the back, lower, left corner of the actual device.

FORTRAN SPECIFIC

DEVTYP is a string LDEV bytes long containing the type of device to create.

ARGSTR is a string LARG bytes long containing device options.

ERRORS
DoDevice will fail if the specified device is unavailable or an illegal device type or option is specified.

[SEVERE - unable to allocate device]

DoDevice will fail if enough memory for the device cannot be allocated

[SEVERE - unable to allocate memory]

SEE ALSO
DdUpdate(3D), DoFrame(3D), DdSetOptions(3D)