Construct render tasks

Five OPAL tasks read and drive the rendering of a document: construct.render.status, construct.render.set_shading, construct.render.pause, construct.render.resume and construct.render.export. This page is their reference. For a still image from a camera that you place, see view.snapshot in OPAL view tasks.

If you only do one thing with it: read construct.render.status before you judge a path-traced image of the viewport. A path-traced view refines over time, and the status tells you whether the frame on screen is a coarse frame of a moving view, a frame that still refines, or the final one.

The viewport tasks

status, set_shading, pause and resume act on the viewport that shows the document. A document whose tab is not on screen has no such viewport, and the task fails:

construct.render.status: no viewport shows the document. Suggestion: show the document's tab. State: unchanged.

Each of the four takes the document argument of every construct task. See Construct document tasks. They are at the cad-editing tier.

construct.render.status

What the viewport renders, and how far it is. It changes nothing.

Arguments: none, apart from document.

Output keys:

Key Meaning
engine path-traced while the viewport path traces, else raster
tier The engine of the viewport: pbr, env-lit-pbr or path-traced. The viewport mode picks it (render engines)
mode The id of the viewport mode: clay, engineering, presentation or the id of a mode of your own
state navigating, refining, denoising, done, paused or updating shaders. A raster engine is done, unless its shaders are updating
samples The samples of the current view
sampleTarget The sample limit of the viewport. 0 when it has none
noise The noise level that the tracer measured last
elapsedSeconds The time since the view started to refine, or until it was done
viewVersion The version of the view of the frame on screen. It changes with each change of the camera, the size or the scene
json All of the above as one JSON object

state is navigating while a coarse frame of a moving view is on screen, denoising while the OIDN network runs over the frame on screen (the viewport denoiser "À-trous, then OIDN"), and done when every pixel has converged or the sample limit is reached.

{"task": "construct.render.status", "args": {}}

construct.render.set_shading

Choose the viewport mode of the viewport that shows the document, as the mode list on the toolbar does.

Argument Required Meaning
mode yes The id of a viewport mode: clay, engineering, presentation or the id of a mode of your own

The task writes the scene's Viewport mode setting, as the mode list does. A render keeps the scene's settings. To change the mode of new scenes, use config.set. It returns the status after the change, with the keys engine, tier, mode, state and json. The tasks construct.viewport_modes.* list, save, reset, delete and move the modes.

Fails when mode names no viewport mode:

construct.render.set_shading: 'mode' must be one of clay, engineering, presentation, not 'shaded'. State: unchanged.

{"task": "construct.render.set_shading", "args": {"mode": "presentation"}}

construct.render.pause and construct.render.resume

construct.render.pause stops the refinement of the viewport. The image and its samples stay, and the GPU rests. The camera still answers. construct.render.resume continues the same accumulation, from the samples that it kept. They do what the pause button on the toolbar does.

Arguments: none, apart from document. Output keys: state, samples and json.

Both are view state: they make no undo step, and they are safe to repeat.

construct.render.export

Queue a render of the document, as Queue render in the Rendering window does. It returns the batch job id at once, and the job renders in the background. Follow it with the batch.* tasks, such as batch.status. The document does not change.

Argument Required Meaning
path yes The file to write. See below
frames no A count of frames from frame 0, or [first, last]. One frame by default
fps no Frames per second, above 0 and up to 240
size no [width, height] in pixels, each from 16 to 16384
format no The extension of the output, when path has none
quality no A render preset: Draft, Standard or Final

path decides what the job writes:

path Output
An image, such as .png or .jpg, with one frame One image
An image with more than one frame A sequence. A %f in the name is the frame number. Without one, _%f goes before the extension
A video, such as .mp4, .mkv or .webm One video, with a container and a codec that this computer can encode

The camera, the codec and every other setting come from the Rendering window. quality sets the samples, the noise threshold and the bounce limits of the preset for this job only.

Output keys:

Key Meaning
jobId The batch job id
path The file, or the file name template of a sequence
frames The number of frames queued

The task checks every argument before it queues anything. A refused call starts no job. The refusals:

Cause Message
No path 'path' is required.
A bad frames 'frames' must be a count from 1, or [first, last] with first at most last.
A bad fps 'fps' must be a number above 0 and up to 240.
A bad size 'size' must be [width, height], each from 16 to 16384.
No extension and no format 'path' needs an extension, or give 'format'.
An unknown quality 'quality' must be Draft, Standard or Final.
No render queue no render queue is here. Open the scene in the Construct window.
No usable video codec The reason of the codec choice
The document does not resolve, or its snapshot fails The reason of the lookup or of the snapshot

Each message starts with construct.render.export: and ends with State: unchanged.

{"task": "construct.render.export", "args": {"path": "/tmp/tank.png", "size": [1280, 720], "quality": "Final"}}

The job writes files, so the task is at the cad-editing tier, as the other tasks that change something are.

See also

In this section
Topics
reference construct OPAL rendering