output_scene(3G)

NAME

output_scene − output a global rendering to a given output device

SYNOPSIS

C Syntax:

void output_scene(fildes,scene_id,output_type,output_fildes);
int fildes,scene_id,output_type,output_fildes;

FORTRAN77 Syntax:

subroutine output_scene(fildes,scene_id,output_type,
output_fildes)
integer*4 fildes,scene_id,output_type,output_fildes

Pascal Syntax:

procedure output_scene(fildes,scene_id,output_type,
output_fildes:integer);

DESCRIPTION

Input Parameters

fildes Integer file descriptor returned by gopen when an I/O path to a graphics device is opened.

scene_id Scene identifier; as returned by create_scene.

output_type Type of output desired: OUTPUT_RAY_IMAGE or OUTPUT_RADIOSITY. DONT_DEFINE_TEXTURES may be ORed together with OUTPUT_RADIOSITY.

output_fildes Integer file descriptor returned by gopen when an I/O path to a graphics device is opened.

Discussion

output_scene sends a global rendering of the scene specified by scene_id to the output_fildes output device. The output_type parameter determines which type of global rendering (ray tracing or radiosity) is output. In order for any rendering to be output, however, the requested scene must have first been processed through render_scene. Attempting to output a rendering that has not yet been calculated results in an error.

An output_type of OUTPUT_RAY_IMAGE causes the ray traced RGB bitmap produced by render_scene for the scene identified by scene_id (or by the global environment variable, USR_TMP_SBRR) to be output to the output_fildes output device. The view of the image will correspond to the view that was in force when render_scene was executed. The ray traced image will be centered within the current viewport and may be clipped by the current clip rectangle if clip_indicator is set accordingly. Shade_mode will be set to (and left at) CMAP_FULL | INIT whenever output_scene actually outputs a ray traced image. If the display is an 8-bit device, the ray tracing output will be dithered according to the dither_scheme established by set_ray_dither_parms.

An output_type of OUTPUT_RADIOSITY causes the list of polygons and/or mesh primitives produced by render_scene for the given scene_id to be output to the output_fildes output device. Each vertex of each output primitive contains an rgb value representing the radiosity computed by render_scene. The radiosity values are scaled according to set_rad_scale prior to output. Radiosity primitives are output in world coordinates. Since the output consists simply of a set of Starbase primitives, the view of the rendered image depends on the current Starbase viewing parameters. For the primitives to be rendered correctly, the following Starbase calls should usually be made immediately before calling output_scene:

hidden_surface( fildes, FALSE, FALSE ) ;
shade_mode( fildes, CMAP_FULL, FALSE ) ;
hidden_surface( fildes, TRUE, TRUE ) ;

If, however, specular highlighting data was included in the radiosity output stream via the RAD_SPECULAR flag in render_scene, shade_mode1 should be called with shading set to TRUE instead. This allows Starbase to calculate the specular effects in the output image.

If texture mapping was employed in the radiosity model, output_scene will output the necessary texturing commands and *_with_data primitives to ensure that texturing appears in the output image. If DONT_DEFINE_TEXTURES is ORed with OUTPUT_RADIOSITY however, all define_texture calls in the radiosity image will be stripped from the output stream. What this does is to reduce the size of the radiosity image and force the texture_index calls in the output stream to reference textures that are defined in the Starbase state at output time. This capability can be useful if you want to change the textures used in a radiosity image at output time without recomputing the image itself.

For radiosity, a shade_mode of CMAP_MONOTONIC may be used to produce gray-scale radiosity output. output_scene will exit with an error if hidden_surface and shade_mode are not set correctly when it is called.

If a display list segment is open on the output_fildes device, then the radiosity output polygons will be output to that segment. Once this segment is closed, the captured radiosity image can be effectively manipulated (viewed from different positions, etc.) just like any other segment.

NOTES

It is important to keep in mind that radiosity output is simply a list of shaded Starbase primitives that are displayed according to the current state of Starbase.

If textures were defined with define_texture in a radiosity model and are output along with the model (i.e., DONT_DEFINE_TEXTURES is not used), then those define_texture calls will overwrite textures that may exist in the Starbase state at output time if their indices correspond with those in the model.

The global environment variable, USR_TMP_SBRR, can be used to cause output_scene to display ray traced images that have been “stored” in user-defined files (see the description of render_scene). If USR_TMP_SBRR is set to a readable ray traced bitmap file and no bitmap file exists for the given scene_id, then output_scene will display the image pointed to by USR_TMP_SBRR. If a ray trace exists for scene_id, that image will be displayed, regardless of the status of USR_TMP_SBRR. If no ray trace exists for scene_id and USR_TMP_SBRR is non-existent or points to an unreadable file, an error is generated and no output occurs. USR_TMP_SBRR is ignored when output_type is set to OUTPUT_RADIOSITY.

This command cannot be stored in a segment.

ERRORS

Invalid file descriptor.
Invalid scene_id.
Invalid output_type.
Invalid output_fildes.
Ray image does not exist for given scene.
Radiosity data does not exist for given scene.
Cannot perform this operation while color map mode is NORMAL.
Cannot perform this operation while hidden surface removal is off.

Museum

Related Articles