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.

Mogwai API

Global functions

Function Description
help() Print global help.
help(object) Print help of a specific object.

Global variables

Variable Description
m Instance of Renderer.
t Instance of Clock. DEPRECATED: Use m.clock instead.
fc Instance of FrameCapture. DEPRECATED: Use m.frameCapture instead.
vc Instance of VideoCapture. DEPRECATED: Use m.videoCapture instead.
tc Instance of TimingCapture. DEPRECATED: Use m.timingCapture instead.

Renderer

class falcor.Renderer

Property Type Description
scene Scene Active scene (readonly).
activeGraph RenderGraph Active render graph (readonly).
ui bool Show/hide the UI.
clock Clock Clock.
profiler Profiler Profiler.
frameCapture FrameCapture Frame capture.
videoCapture VideoCapture Video capture.
timingCapture TimingCapture Timing capture.
Method Description
script(filename) Run a script.
loadScene(filename, buildFlags=SceneBuilderFlags.Default) Load a scene. See available build flags below.
unloadScene() Explicitly unload the scene to free memory.
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.
resizeSwapChain(width, height) Resize the window/swapchain.

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.

Profiler

class falcor.Profiler

Property Type Description
enabled bool Enable/disable profiler.
events dict Profiler events (readonly).
Method Description
clearEvents() Clear the profiler events.

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 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 str Capture output directory.
baseFilename str 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.

Example: Capture list of frames with clock running and then exit

m.clock.exitFrame = 101
m.frameCapture.outputDir = "../../../Output"
m.frameCapture.baseFilename = "Mogwai"
m.frameCapture.addFrames(m.activeGraph, [20, 50, 100])

Example: Capture frames with clock paused and then exit

m.clock.pause()
m.frameCapture.outputDir = "../../../Output"

frames = [20, 50, 100]
for i in range(101):
    renderFrame()
    if i in frames:
        m.frameCapture.baseFilename = f"Mogwai-{i:04d}"
        m.frameCapture.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 str Capture output directory.
baseFilename str 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.

Example:

# Video Capture
m.videoCapture.outputDir = "."
m.videoCapture.baseFilename = "Mogwai"
m.videoCapture.codec = Codec.H264
m.videoCapture.fps = 60
m.videoCapture.bitrate = 4.0
m.videoCapture.gopSize = 10
m.videoCapture.addRanges(m.activeGraph, [[30, 300]])

TimingCapture

class falcor.TimingCapture

Method Description
captureFrameTime(filename) Start writing frame times to the given filename.

Example:

# Timing Capture
m.timingCapture.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 str 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

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.

AABB

class falcor.AABB

Property Type Description
minPoint float3 Minimum point.
maxPoint float3 Maximum point.
valid bool True if AABB is valid (readonly).
center float3 Center point (readonly).
extent float3 Extents (readonly).
area float Total area (readonly).
volume float Total volume (readonly).
radius float Radius of an enclosing sphere (readonly).
Method Description
invalidate() Invalidate the AABB.
include(p) Include a point in the AABB.
include(b) Include another AABB in the AABB.
intersection(b) Intersect with another AABB.

Scene API

SceneRenderSettings

class falcor.SceneRenderSettings

Property Type Description
useEnvLight bool Enable/disable lighting from environment map.
useAnalyticLights bool Enable/disable lighting from analytic lights.
useEmissiveLights bool Enable/disable lighting from emissive lights.
useVolumes bool Enable/disable rendering of heterogeneous volumes.

Scene

class falcor.Scene

Property Type Description
stats dict Dictionary containing scene stats.
bounds AABB World space scene bounds (readonly).
animated bool Enable/disable scene animations.
loopAnimations bool Enable/disable globally looping 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.
animations list(Animation) List of animations.
cameras list(Camera) List of cameras.
lights list(Light) List of lights.
materials list(Material) List of materials.
volumes list(Volume) List of volumes.
Method Description
setEnvMap(filename) Load an environment map from an image.
getLight(index) Return a light by index.
getLight(name) Return a light by name.
getMaterial(index) Return a material by index.
getMaterial(name) Return a material by name.
getVolume(index) Return a volume by index.
getVolume(name) Return a volume by name.
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.

Camera

class falcor.Camera

Property Type Description
name str Name of the camera.
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, Displacement

class falcor.Material

Property Type Description
name str Name of the material.
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.

Grid

class falcor.Grid

Property Type Description
voxelCount int Total number of active voxels in the grid (readonly).
minIndex int3 Minimum index stored in the grid (readonly).
maxIndex int3 Maximum index stored in the grid (readonly).
minValue float Minimum value stored in the grid (readonly).
maxValue float Maximum value stored in the grid (readonly).
Method Description
getValue(ijk) Access the value of a voxel in the grid (index space).
Static method Description
createSphere(radius, voxelSize, blendRange=2.0) Create a sphere grid.
createBox(width, height, depth, voxelSize, blendRange=2.0) Create a box grid.
createFromFile(filename, gridname) Create a grid from an OpenVDB/NanoVDB file.

Volume

enum falcor.Volume.GridSlot

Density, Emission

enum falcor.Volume.EmissionMode

Direct, Blackbody

class falcor.Volume

Property Type Description
name str Name of the volume.
gridFrame int Current frame in the grid sequence.
gridFrameCount int Total number of frames in the grid sequence (readonly).
densityGrid Grid Density grid.
densityScale float Density scale factor.
emissionGrid Grid Emission grid.
emissionScale float Emission scale factor.
albedo float3 Scattering albedo.
anisotropy float Phase function anisotropy (g).
emissionMode EmissionMode Emission mode (Direct, Blackbody).
emissionTemperature float Emission base temperature (K).
Method Description
loadGrid(slot, filename, gridname) Load a grid slot from an OpenVDB/NanoVDB file.
loadGridSequence(slot, filenames, gridname) Load a grid slot from a sequence of OpenVDB/NanoVDB files.
loadGridSequence(slot, path, gridname) Load a grid slot from a sequence of OpenVDB/NanoVDB files contained in a directory.

Light

class falcor.Light

Property Type Description
name str Name of the light.
active bool Enable/disable light.
animated bool Enable/disable light animation.
intensity float3 Intensity of the light.

class falcor.PointLight : falcor.Light

Property Type Description
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.DirectionalLight : falcor.Light

Property Type Description
direction float3 Direction of the light in world space.

class falcor.DistantLight : falcor.Light

Property Type Description
direction float3 Direction of the light in world space.
angle float Half-angle subtended by the light in radians.

class falcor.AnalyticAreaLight : falcor.Light

class falcor.RectLight : falcor.AnalyticAreaLight

class falcor.DiscLight : falcor.AnalyticAreaLight

class falcor.SphereLight : falcor.AnalyticAreaLight

Transform

class falcor.Transform

Property Type Description
translation float3 Translation.
rotationEuler float3 Euler rotation angles around XYZ (radians).
rotationEulerDeg float3 Euler rotation angles around XYZ (degrees).
scaling float3 Scaling.
matrix float4x4 Transformation matrix (readonly).
Method Description
lookAt(position, target, up) Set up a look-at transformation.

Animation

enum falcor.Animation.InterpolationMode

Linear, Hermite

enum falcor.Animation.Behavior

Constant, Linear, Cycle, Oscillate

class falcor.Animation

Property Type Description
name str Name of the animation (readonly).
nodeID int Animated scene graph node (readonly).
duration float Duration in seconds (readonly).
interpolationMode InterpolationMode Interpolation mode (linear, hermite).
preInfinityBehavior Behavior Behavior before the first keyframe (constant, linear, cycle, oscillate).
postInfinityBehavior Behavior Behavior after the last keyframe (constant, linear, cycle, oscillate).
enableWarping bool Enable/disable warping, i.e. interpolating from last to first keyframe.
Method Description
addKeyframe(time, transform) Add a transformation keyframe at given time.

TriangleMesh

class falcor.TriangleMesh.Vertex

Field Type Description
position float3 Vertex position.
normal float3 Vertex normal.
texCoord float2 Vertex texture coordinate.

class falcor.TriangleMesh

Property Type Description
name str Name of the triangle mesh.
vertices list(Vertex) List of vertices (readonly).
indices list(int) List of indices (readonly).
Method Description
addVertex(position, normal, texCoord) Add a vertex to the mesh. Returns the vertex index.
addTriangle(i0, i1, i2) Add a triangle to the mesh.
Class Method Description
createQuad(size=1) Creates a quad mesh, centered at the origin with normal pointing in positive Y direction.
createCube(size=1) Creates a cube mesh, centered at the origin.
createSphere(radius=1, segmentsU=32, segmentsV=16) Creates a UV sphere mesh, centered at the origin with poles in positive/negative Y direction.
createFromFile(filename,smoothNormals=False) Creates a triangle mesh from a file. If no normals are defined in the file, smoothNormals can be used generate smooth instead of facet normals.

SceneBuiler

enum falcor.SceneBuilderFlags

Enum Description
Default Use the default flags (0).
DontMergeMaterials Don't merge materials that have the same properties. Use this option to preserve the original material names.
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.
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.
Force32BitIndices Force 32-bit indices for all meshes. By default, 16-bit indices are used for small meshes.
RTDontMergeStatic For raytracing, don't merge all static meshes into single pre-transformed BLAS.
RTDontMergeDynamic For raytracing, don't merge all dynamic meshes with identical transforms into single BLAS.

class falcor.SceneBuilder

Property Type Description
flags SceneBuilderFlags Scene builder flags (readonly).
renderSettings SceneRenderSettings Settings to determine how the scene is rendered.
materials list(Material) List of materials (readonly).
volumes list(Volume) List of volumes (readonly).
lights list(Light) List of lights (readonly).
cameras list(Camera) List of cameras (readonly).
animations list(Animation) List of animations (readonly).
envMap EnvMap Environment map.
selectedCamera Camera Default selected camera.
cameraSpeed float Speed of the interactive camera.
Method Description
importScene(filename, dict, instances) Load a scene from an asset file. dict contains optional data. instances is an optional list of Transform.
addTriangleMesh(triangleMesh, material) Add a triangle mesh to the scene and return its ID.
addMaterial(material) Add a material and return its ID.
getMaterial(name) Return a material by name. The first material with matching name is returned or None if none was found.
loadMaterialTexture(material, slot, filename) Request loading a material texture asynchronously. Use Material.loadTexture for synchronous loading.
addVolume(volume) Add a volume and return its ID.
getVolume(name) Return a volume by name. The first volume with matching name is returned or None if none was found.
addLight(light) Add a light and return its ID.
addCamera(camera) Add a camera and return its ID.
addAnimation(animation) Add an animation.
createAnimation(animatable, name, duration) Create an animation for an animatable object. Returns the new animation or None if one already exists.
addNode(name, transform, parent) Add a node and return its ID.
addMeshInstance(nodeID, meshID) Add a mesh instance.

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





Add Discussion as Guest

Log in