Index | Usage | Scripting
Mogwai Scripting Reference
Sample API
Global functions
| Function | Description |
|---|---|
loadRenderPassLibrary(name) |
Load a render pass library. |
createPass(name, dict) |
Create a new render pass with configuration options in dict. |
renderFrame() |
Render a frame. If the clock is not paused, it will advance by one tick. |
setWindowPos(x, y) |
Set the window's position in pixels. |
resizeSwapChain(width, height) |
Resize the window/swapchain. |
exit(errorCode=0) |
Terminate the application with the given error code. |
cls() |
Clear the console. |
Global variables
| Variable | Description |
|---|---|
m |
Instance of Renderer. |
Mogwai API
Global functions
| Function | Description |
|---|---|
help() |
Print global help. |
help(object) |
Print help of a specific object. |
Global variables
| Variable | Description |
|---|---|
t |
Instance of Clock. |
fc |
Instance of FrameCapture. |
vc |
Instance of VideoCapture. |
tc |
Instance of TimingCapture. |
Renderer
class falcor.Renderer
| Property | Type | Description |
|---|---|---|
scene |
Scene |
Active scene (readonly). |
activeGraph |
RenderGraph |
Active render graph (readonly). |
ui |
bool |
Show/hide the UI. |
| Method | Description |
|---|---|
script(filename) |
Run a script. |
loadScene(filename, buildFlags=SceneBuilderFlags.Default) |
Load a scene. See available build flags below. |
saveConfig(filename) |
Save the current state to a config file. |
addGraph(graph) |
Add a render graph. |
removeGraph(graph) |
Remove a render graph. graph can be a render graph or a name. |
getGraph(name) |
Get a render graph by name. |
graph(name) |
DEPRECATED: Use getGraph instead. |
resizeSwapChain(width, height) |
DEPRECATED: Use global resizeSwapChain instead. |
enum falcor.SceneBuilderFlags
| Enum | Description |
|---|---|
Default |
Use the default flags (0). |
RemoveDuplicateMaterials |
Deduplicate materials that have the same properties. The material name is ignored during the search. |
UseOriginalTangentSpace |
Use the original bitangents that were loaded with the mesh. By default, we will ignore them and use MikkTSpace to generate the tangent space. We will always generate bitangents if they are missing. |
AssumeLinearSpaceTextures |
By default, textures representing colors (diffuse/specular) are interpreted as sRGB data. Use this flag to force linear space for color textures. |
DontMergeMeshes |
Preserve the original list of meshes in the scene, don't merge meshes with the same material. |
BuffersAsShaderResource |
Generate the VBs and IB with the shader-resource-view bind flag. |
UseSpecGlossMaterials |
Set materials to use Spec-Gloss shading model. Otherwise default is Spec-Gloss for OBJ, Metal-Rough for everything else. |
UseMetalRoughMaterials |
Set materials to use Metal-Rough shading model. Otherwise default is Spec-Gloss for OBJ, Metal-Rough for everything else. |
NonIndexedVertices |
Convert meshes to use non-indexed vertices. This requires more memory but may increase performance. |
Clock
class falcor.Clock
| Property | Type | Description |
|---|---|---|
time |
float |
Current time in seconds. |
frame |
int |
Current frame number. |
framerate |
int |
Frame rate in frames per second. |
timeScale |
float |
Time scale factor. |
exitTime |
float |
Time in seconds at which to terminate the application. Set to 0 to disable. |
exitFrame |
int |
Frame at which to terminate the application. Set to 0 to disable. |
| Method | Description |
|---|---|
pause() |
Pause the clock. |
play() |
Resume the clock. |
stop() |
Stop the clock (pause and reset) |
step(frames=1) |
Step forward or backward in time. |
FrameCapture
The frame capture will always dump the marked graph output. You can use graph.markOutput() and graph.unmarkOutput() to control which outputs to dump.
The frame counter starts at zero in Falcor (it starts by default at one in Maya, so the frame numbers may be offset by one frame).
By default, the captures frames are stored to the executable directory. This can be changed by setting fc.outputDir.
Note: The frame counter is not advanced when time is paused. If you capture with time paused, the captured frame will be overwritten for every rendered frame. The workaround is to change the base filename between captures with fc.capture(), see example below.
class falcor.FrameCapture
| Property | Type | Description |
|---|---|---|
outputDir |
string |
Capture output directory. |
baseFilename |
string |
Capture base filename. The frameID and output name will be appended to this. |
ui |
bool |
Show/hide the UI. |
| Method | Description |
|---|---|
reset(graph) |
Reset frame capturing for the given graph (or all graphs if set to None). |
capture() |
Capture the current frame. |
addFrames(graph, frames) |
Add a list of frames to capture for the given graph. |
print() |
Print the requested frames to capture for all available graphs. |
print(graph) |
Print the requested frames to capture for the specified graph. |
frames(graph, frames) |
DEPRECATED: Use addFrames instead. |
Example: Capture list of frames with clock running and then exit
t.exitFrame(101)
fc.outputDir = "../../../Output"
fc.baseFilename = "Mogwai"
fc.addFrames(m.activeGraph, [20, 50, 100])
Example: Capture frames with clock paused and then exit
t.pause()
fc.outputDir = "../../../Output"
frames = [20, 50, 100]
for i in range(101):
renderFrame()
if i in frames:
fc.baseFilename = f"Mogwai-{i:04d}"
fc.capture()
exit()
VideoCapture
The video capture will always capture the marked graph output. You can use graph.markOutput() and graph.unmarkOutput() to control which outputs to dump.
enum falcor.Codec
Raw, H264, HVEC, MPEG2, MPEG4
class falcor.VideoCapture
| Property | Type | Description |
|---|---|---|
outputDir |
string |
Capture output directory. |
baseFilename |
string |
Capture base filename. The output name will be appended to this. |
ui |
bool |
Show/hide the UI. |
codec |
Codec |
Video codec (Raw, H264, HVEC, MPEG2, MPEG4). |
fps |
int |
Video frame rate. |
bitrate |
float |
Video bitrate in Mpbs. |
gopSize |
int |
Video GOP size. |
| Method | Description |
|---|---|
reset(graph) |
Reset video capturing for the given graph (or all graphs if set to None). |
addRanges(graph, ranges) |
Add a list of frame ranges to capture for a given graph. ranges is a list of (start, end) tuples. |
print() |
Print the requested ranges to capture for all available graphs. |
print(graph) |
Print the requested ranges to capture for the specified graph. |
ranges(graph, ranges) |
DEPRECATED: Use addRanges instead. |
Example:
# Video Capture
vc.outputDir = "."
vc.baseFilename = "Mogwai"
vc.codec = Codec.H264
vc.fps = 60
vc.bitrate = 4.0
vc.gopSize = 10
vc.addRanges(m.activeGraph, [[30, 300]])
TimingCapture
class falcor.TimingCapture
| Method | Description |
|---|---|
captureFrameTime(filename) |
Start writing frame times to the given filename. |
Example:
# Timing Capture
tc.captureFrameTime("timecapture.csv")
Core API
module falcor
Global Functions
| Function | Description |
|---|---|
loadRenderPassLibrary(name) |
Load a render pass library. |
cls |
Clear the console. |
ResourceFormat
enum falcor.ResourceFormat
Unknown, R8Unorm, R8Snorm, R16Unorm, R16Snorm, RG8Unorm, RG8Snorm, RG16Unorm, RG16Snorm, RGB16Unorm, RGB16Snorm, R24UnormX8, RGB5A1Unorm, RGBA8Unorm, RGBA8Snorm, RGB10A2Unorm, RGB10A2Uint, RGBA16Unorm, RGBA8UnormSrgb, R16Float, RG16Float, RGB16Float, RGBA16Float, R32Float, R32FloatX32, RG32Float, RGB32Float, RGBA32Float, R11G11B10Float, RGB9E5Float, R8Int, R8Uint, R16Int, R16Uint, R32Int, R32Uint, RG8Int, RG8Uint, RG16Int, RG16Uint, RG32Int, RG32Uint, RGB16Int, RGB16Uint, RGB32Int, RGB32Uint, RGBA8Int, RGBA8Uint, RGBA16Int, RGBA16Uint, RGBA32Int, RGBA32Uint, BGRA8Unorm, BGRA8UnormSrgb, BGRX8Unorm, BGRX8UnormSrgb, Alpha8Unorm, Alpha32Float, R5G6B5Unorm, D32Float, D16Unorm, D32FloatS8X24, D24UnormS8, BC1Unorm, BC1UnormSrgb, BC2Unorm, BC2UnormSrgb, BC3Unorm, BC3UnormSrgb, BC4Unorm, BC4Snorm, BC5Unorm, BC5Snorm, BC6HS16, BC6HU16, BC7Unorm, BC7UnormSrgb
RenderGraph
class falcor.RenderGraph
| Property | Type | Description |
|---|---|---|
name |
string |
Name of the render graph. |
| Method | Description |
|---|---|
RenderGraph(name) |
Create a new render graph. |
addPass(pass, name) |
Add a render pass to the graph. |
removePass(name) |
Remove a render pass from the graph. |
updatePass(name, dict) |
Update a render pass with new configuration options in dict. |
getPass(name) |
Get a pass by name. |
addEdge(src, dst) |
Add an edge to the render graph. |
removeEdge(src, dst) |
Remove an edge from the render graph. |
autoGenEdges(executionOrder) |
TODO document |
markOutput(name) |
Mark an output to be selectable in Mogwai and writing files when capturing frames. |
unmarkOutput(name) |
Unmark an output. |
getOutput(index) |
Get an output by index. |
getOutput(name) |
Get an output by name. |
RenderPass
class falcor.RenderPass
| Method | Description |
|---|---|
RenderPass(name, dict) |
DEPRECATED: Use global createPass function instead. |
Texture
class falcor.Texture
| Property | Type | Description |
|---|---|---|
width |
int |
Width in pixels (readonly). |
height |
int |
Height in pixels (readonly). |
depth |
int |
Depth in pixels/layers (readonly). |
mipCount |
int |
Number of mip levels (readonly). |
arraySize |
int |
Size of array (readonly). |
samples |
int |
Number of samples (readonly). |
format |
ResourceFormat |
Texture format (readonly). |
| Method | Description |
|---|---|
data(index) |
Returns raw data of given sub resource index. |
Scene API
SceneRenderSettings
class falcor.SceneRenderSettings
| Property | Type | Description |
|---|---|---|
useEnvLight |
bool |
Enable/disable distant lighting from environment map. |
useAnalyticLights |
bool |
Enable/disable lighting from analytic lights. |
useEmissiveLights |
bool |
Enable/disable lighting from emissive lights. |
Scene
class falcor.Scene
| Property | Type | Description |
|---|---|---|
animated |
bool |
Enable/disable scene animations. |
renderSettings |
SceneRenderSettings |
Settings to determine how the scene is rendered. |
camera |
Camera |
Camera. |
cameraSpeed |
float |
Speed of the interactive camera. |
envMap |
EnvMap |
Environment map. |
materials |
list(Material) |
List of materials |
| Method | Description |
|---|---|
animate(enable) |
DEPRECATED: Use animated instead. |
animateCamera(enabled) |
DEPRECATED: Use animated on Camera instead. |
animateLight(index, enabled) |
DEPRECATED: Use animated on Light instead. |
setEnvMap(filename) |
Load an environment map from an image. |
getLight(index) |
Return a light by index. |
getLight(name) |
Return a light by name. |
light(index) |
DEPRECATED: Use getLight instead. |
light(name) |
DEPRECATED: Use getLight instead. |
getMaterial(index) |
Return a material by index. |
getMaterial(name) |
Return a material by name. |
material(index) |
DEPRECATED: Use getMaterial instead. |
material(name) |
DEPRECATED: Use getMaterial instead. |
addViewpoint() |
Add current camera's viewpoint to the viewpoint list. |
addViewpoint(position, target, up) |
Add a viewpoint to the viewpoint list. |
removeViewpoint() |
Remove selected viewpoint. |
selectViewpoint(index) |
Select a specific viewpoint and move the camera to it. |
viewpoint() |
DEPRECATED: Use addViewpoint instead. |
viewpoint(index) |
DEPRECATED: Use selectViewpoint instead. |
Camera
class falcor.Camera
| Property | Type | Description |
|---|---|---|
name |
str |
Name of the camera (readonly). |
animated |
bool |
Enable/disable camera animation. |
aspectRatio |
float |
Image aspect ratio. |
focalLength |
float |
Focal length in millimeters. |
frameHeight |
float |
Frame height in millimeters. |
focalDistance |
float |
Focal distance in scene units. |
apertureRadius |
float |
Apeture radius in scene units. |
shutterSpeed |
float |
Shutter speed in seconds (not implemented). |
ISOSpeed |
float |
Film speed (not implemented). |
nearPlane |
float |
Near plane distance in scene units. |
farPlane |
float |
Far plane distance in scene units. |
position |
float3 |
Camera position in world space. |
target |
float3 |
Camera target in world space. |
up |
float3 |
Camera up vector in world space. |
EnvMap
class falcor.EnvMap
| Property | Type | Description |
|---|---|---|
filename |
str |
Filename of loaded environment map (readonly). |
rotation |
float3 |
Rotation angles in degrees (XYZ). |
intensity |
float |
Intensity (scalar multiplier). |
Material
enum falcor.MaterialTextureSlot
BaseColor, Specular, Emissive, Normal, Occlusion, SpecularTransmission
class falcor.Material
| Property | Type | Description |
|---|---|---|
name |
str |
Name of the material (readonly). |
baseColor |
float4 |
Base color (linear RGB) and opacity. |
specularParams |
float4 |
Specular parameters (occlusion, roughness, metallic). |
roughness |
float |
Roughness (0 = smooth, 1 = rough). |
metallic |
float |
Metallic (0 = dielectric, 1 = conductive). |
specularTransmission |
float |
Specular transmission (0 = opaque, 1 = transparent). |
indexOfRefraction |
float |
Index of refraction. |
emissiveColor |
float3 |
Emissive color (linear RGB). |
emissiveFactor |
float |
Multiplier for emissive color. |
alphaMode |
int |
Alpha mode (0 = opaque, 1 = masked). |
alphaThreshold |
float |
Alpha masking threshold (0-1). |
doubleSided |
bool |
Enable double sided rendering. |
nestedPriority |
int |
Nested priority for nested dielectrics. |
| Method | Description |
|---|---|
clearTexture(slot) |
Clears one of the texture slots. |
loadTexture(slot, filename, useSrgb=True) |
Load one of the texture slots from a file. |
Light
class falcor.Light
| Property | Type | Description |
|---|---|---|
name |
str |
Name of the light (readonly). |
active |
bool |
Enable/disable light. |
animated |
bool |
Enable/disable light animation. |
color |
float3 |
Color of the light. |
intensity |
float |
Intensity of the light. |
class falcor.DirectionalLight
| Property | Type | Description |
|---|---|---|
name |
str |
Name of the light (readonly). |
color |
float3 |
Color of the light. |
intensity |
float |
Intensity of the light. |
direction |
float3 |
Direction of the light in world space. |
class falcor.DistantLight
| Property | Type | Description |
|---|---|---|
name |
str |
Name of the light (readonly). |
color |
float3 |
Color of the light. |
intensity |
float |
Intensity of the light. |
direction |
float3 |
Direction of the light in world space. |
angle |
float |
Half-angle subtended by the light in radians. |
class falcor.PointLight
| Property | Type | Description |
|---|---|---|
name |
str |
Name of the light (readonly). |
color |
float3 |
Color of the light. |
intensity |
float |
Intensity of the light. |
position |
float3 |
Position of the light in world space. |
direction |
float3 |
Direction of the light in world space. |
openingAngle |
float |
Opening half-angle in radians. |
penumbraAngle |
float |
Penumbra half-angle in radians. |
class falcor.AnalyticAreaLight
| Property | Type | Description |
|---|---|---|
name |
str |
Name of the light (readonly). |
color |
float3 |
Color of the light. |
intensity |
float |
Intensity of the light. |
Render Passes
AccumulatePass
enum falcor.AccumulatePrecision
Double, Single, SingleCompensated
class falcor.AccumulatePass
| Method | Description |
|---|---|
reset() |
Reset accumulation. This is useful when the pass has been created with 'autoReset': False |
ToneMapper
enum falcor.ToneMapOp
Linear, Reinhard, ReinhardModified, HejiHableAlu, HableUc2, Aces
class falcor.ToneMapper
| Property | Type | Description |
|---|---|---|
exposureCompensation |
float |
Exposure compensation (applies in manual and auto exposure). |
autoExposure |
bool |
Enable/disable auto exposure. |
exposureValue |
float |
Exposure value in manual mode. |
filmSpeed |
float |
ISO film speed in manual mode. |
whiteBalance |
bool |
Enable/disable white balancing. |
whitePoint |
float |
White point in Kelvin. |
operator |
ToneMapOp |
Tone mapping operator. |
clamp |
bool |
Enable/disable clamping to [0..1] range. |
GaussianBlur
class falcor.GaussianBlur
| Property | Type | Description |
|---|---|---|
kernelWidth |
int |
Kernel width in pixels. |
sigma |
float |
Sigma of gaussian. |
SSAO
class falcor.SSAO
| Property | Type | Description |
|---|---|---|
kernelRadius |
int |
Kernel radius in pixels. |
sampleRadius |
float |
Sampling radius. |
distribution |
int |
Sampling distribution. |
Skybox
class falcor.SkyBox
| Property | Type | Description |
|---|---|---|
scale |
float |
Color multiplier. |
filter |
int |
Filtering mode. |
CSM
class falcor.CSM
| Property | Type | Description |
|---|---|---|
cascadeCount |
int |
|
mapSize |
uint2 |
|
visibilityBitCount |
int |
|
filter |
int |
|
sdsmLatency |
int |
|
partition |
int |
|
lambda |
float |
|
minDistance |
float |
|
maxDistance |
float |
|
cascadeThreshold |
float |
|
depthBias |
float |
|
kernelWidth |
int |
|
maxAniso |
int |
|
bleedReduction |
float |
|
positiveExp |
float |
|
negativeExp |
float |
FXAA
class falcor.FXAA
| Property | Type | Description |
|---|---|---|
qualitySubPix |
float |
|
edgeThreshold |
float |
|
edgeThresholdMin |
float |
|
earlyOut |
bool |
TAA
class falcor.TAA
| Property | Type | Description |
|---|---|---|
alpha |
float |
|
sigma |
float |