Construct render tasks
Eight OPAL tasks read and drive the rendering of a document:
construct.render.status, construct.render.set_shading,
construct.render.pause, construct.render.resume,
construct.render.export, construct.render.capabilities,
construct.render.measure and construct.render.queue. 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.
The render job settings
The settings of a render, such as output.mediaType, output.multiplier,
output.farm and the quality rows, are config rows at the level renderjob.
Read and write them with config.get and config.set and the argument
"level": "renderjob". See the config tasks.
They are the rows that the Rendering window shows.
{"task": "config.set",
"args": {"id": "output.mediaType", "value": "image", "level": "renderjob"}}
construct.render.capabilities, construct.render.measure and
construct.render.queue read these rows. They are at the cad-editing tier.
construct.render.capabilities
What a render can write on this computer, and what a frame of the scene costs. It changes nothing, and it is safe to repeat.
Arguments: none, apart from document.
Output keys:
| Key | Meaning |
|---|---|
imageFormats |
A JSON list of the image formats, the values of output.imageFormat |
video |
true when this build has the video encoder |
probed |
false while the codec check of this computer runs. Ask again in a moment |
containers |
A JSON list of each container (output.container) with its codecs (output.codec). Each codec has id, name, tier and legacy. The tier software is listed, but an export cannot use it yet |
measure |
The scene's last construct.render.measure: msPerFrame, width, height, quality and when. Empty before the first measure |
{"task": "construct.render.capabilities"}
construct.render.measure
Render 1 to 3 frames of the scene off screen, with the renderer, the size and the quality of the render job settings. It writes no file, and it waits for its job. With more than one frame, the mean leaves out the first frame, which builds the pipeline. The result becomes the scene's last measure, which the cost line of the Rendering window shows.
| Argument | Required | Meaning |
|---|---|---|
frames |
no | How many frames to render: 1, 2 or 3. 3 by default |
Output keys: msPerFrame, secondsPerFrame, seconds (for every frame
of the range), frames (the frames measured), rangeFrames, width,
height and jobId.
{"task": "construct.render.measure"}
construct.render.queue
Queue the render of the scene, as Queue render in the Rendering window does: the frame range and the frame rate of the scene's animation clock, and the render job settings. It refuses what the button refuses, with the same message: a codec that this computer lacks, a file template with an error or with no frame token for a series, a camera that is gone, or too little disk space.
| Argument | Required | Meaning |
|---|---|---|
set |
no | A map of row id to value. The task writes it at the level renderjob first, as one undo step |
wait |
no | true waits for the files. false, the default, returns the job id at once |
farm |
no | true renders the frames on other machines that have a GPU. Without it, the row output.farm decides |
chunk |
no | With farm: the frames of one farm job. Without it, the row output.farmChunk decides, 10 by default |
Output keys: jobId, frames, path (the first file), width and
height. With wait, path, frames and bytes describe the files
written. A farm render also answers jobIds, its jobs. batch.job.cancel on
jobId stops every job of the render. Follow a job with batch.job.get.
{"task": "construct.render.queue",
"args": {"set": {"output.multiplier": 0.5}, "wait": true}}
See Render on other machines for what a farm render does.
See also
- OPAL view tasks:
view.snapshot, a still from a camera that you place, with its own sample budget. - Path-traced quality: the viewport and the final settings that these tasks read.
- Export a rendered animation: the same export from the Rendering window.
- Construct rendering modes: the viewport modes and the render engines.