DoRaster(3D) — Kubota Pacfic Computer Inc. (\*(Dd)

NAME

DoRaster − Create a raster object

SYNOPSIS

DtObject DoRaster(width, height, depth, type, typestring,
data, delcallback)
DtInt width;
DtInt height;
DtInt depth;
DtRasterType type;
DtPtr typestring;
DtPtr data;
DtObject delcallback;

FORTRAN:

INTEGER∗4
DORS(WIDTH, HEIGHT, DEPTH, TYPE, TYPSTR,
TLEN, DATA, DELCBK)
INTEGER∗4 WIDTH
INTEGER∗4 HEIGHT
INTEGER∗4 DEPTH
INTEGER∗4 TYPE
INTEGER∗4 TLEN
CHARACTER∗TLEN TYPSTR
INTEGER∗4 DATA
INTEGER∗4 DELCBK

DESCRIPTION

DoRaster creates a raster object. Raster objects can, for example, be used as texture maps or as backgrounds for views.

The parameter data is a pointer to the actual raster data in memory. The data may be for a one-, two- or three-dimensional raster. The parameters width, height, and depth specify the dimensions of the raster. Note that Doré does not copy the raster data pointed to by data, but uses it from the user space. The data in user space can be modified at any time, but Doré must be notified (See DsRasterUpdate).

The parameter type indicates the type and format of the raster data. Possible values for type are:

DcRasterRGB <DCRRGB>
Each point in the raster has red, green and blue information.

DcRasterRGBA <DCRRA>
Each point in the raster has red, green, blue and alpha information.

DcRasterRGBAZ <DCRRAZ>
Each point in the raster has red, green, blue, alpha and z information.

DcRasterRGBZ <DCRRZ>
Each point in the raster has red, green, blue and z information.

DcRasterA <DCRA>
Each point in the raster has alpha information.

DcRasterABGR <DCRAR>
Each point in the raster has alpha, blue, green and red information.

DcRasterZ <DCRZ>
Each point in the raster has z information.

DcRasterSpecial <DCRSPC>
The data type is not one of the standard Doré types.

The standard Doré types assume that the data is pixel interleaved. For more information on the standard Doré raster data formats see Chapter 8: Raster File and Memory Formats in Doré Reference Manual.

If a renderer requires a format that is not one of the standard Doré ones, then the type should be set to be DcRasterSpecial <DCRSPC>. In that case, the character string typestring specifies the format of the data. The parameter typestring is ignored if the type is not DcRasterSpecial <DCRSPC>.

The parameter delcallback is a callback object. When the raster object created by DoRaster is deleted by Doré the function defined by delcallback will be invoked. A callback function takes the following form:

my_del callback_fcn (callback_data, ras_dataptr)
DtPtr callback_data;/∗ if data is a pointer to data ∗/
Dt32Bits callback_data;/∗ if data is a value ∗/
DtPtr ras_dataptr; /∗ pointer to raster data ∗/

Often an application will not need the data pointed to by data after the raster object is destroyed. Doré provides a standard callback object, DcDeleteData <DCDELD>, which will deallocate the space pointed to by data. The application can define its own callback if it does not want the data to be unconditionally deallocated when this raster object is deleted, for example, if the same data is used by other raster objects.

FORTRAN SPECIFIC

The parameter TYPSTR is an optional format string that is TLEN characters long.

ERRORS

DoRaster will fail if passed an invalid delete callback object.

[WARNING - invalid callback object ]

Museum