The Engine Module

Engine is the core library: everything except the GUI. This chapter is a functional reference to its main subsystems and the files that implement them.

Nodes and the graph

  • Node (Node.cpp — the largest file in the project, with NodeInputs.cpp, NodeName.cpp, NodeMain.cpp, NodeOverlay.cpp, NodePrivate.h): the graph vertex. Owns inputs/outputs, name/label, knobs container, the NodeGuiI back-pointer, and the EffectInstance. Node creation goes through CreateNodeArgs and the AppInstance / AppManager factory path.

  • NodeCollection and NodeGroup (NodeGroup.cpp): containers of nodes. NodeGroup is both an effect and a collection, giving Natron recursive sub-graphs and PyPlugs. GroupInput/GroupOutput are the group’s I/O proxies.

  • Project (Project.cpp, ProjectPrivate.*): the document root, a NodeCollection and a KnobHolder. Owns project format, frame range, frame rate, views and color settings, plus autosave.

Effects

  • EffectInstance (EffectInstance.cpp, EffectInstanceRenderRoI.cpp, EffectInstancePrivate.*): the abstract behavior of a node and the entry point to rendering (Rendering, Threading and Caching). Defines the actions an effect supports — region of definition, region of interest, frames needed, get metadata, and render.

  • OutputEffectInstance: base for effects that drive a render (writers, the viewer).

  • OpenFX effects: OfxEffectInstance wraps a plug-in; see Natron as an OpenFX Host.

  • Built-in effects: ViewerInstance, RotoPaint, TrackerNode, ReadNode/WriteNode (which themselves dispatch to OFX reader/writer plug-ins), Backdrop, Dot, PrecompNode, DiskCacheNode, OneViewNode, JoinViewsNode, NoOpBase subclasses.

Parameters: the Knob system

Knobs are Natron’s animated, expression-driven parameters. The hierarchy is:

  • KnobI (Knob.h) — the interface.

  • KnobHelper — the base implementation (animation, expressions, listeners, cloning). KnobImpl.h provides the templated value machinery.

  • Concrete knobs (KnobTypes.h/KnobTypes.cpp, KnobFile.*): KnobInt, KnobDouble, KnobBool, KnobChoice, KnobColor, KnobString, KnobPath, KnobFile, KnobOutputFile, KnobGroup, KnobPage, KnobButton, KnobSeparator, KnobParametric, KnobTable, KnobLayers.

  • KnobHolder — anything that owns knobs (every EffectInstance, and Settings). KnobFactory (KnobFactory.cpp) constructs them.

  • KnobSignalSlotHandler — the QObject companion that emits a knob’s signals (knobs are not QObject).

  • Related: Curve (Curve.cpp) and KeyFrame for animation; Interpolation.cpp for keyframe interpolation; StringAnimationManager for animating string values.

Rendering, scheduling and caching

Covered in depth in Rendering, Threading and Caching. Key files: EffectInstanceRenderRoI.cpp, ParallelRenderArgs.*, OutputSchedulerThread.*, GenericSchedulerThread.*, ThreadPool.*, AbortableRenderInfo.*, RenderStats.*, and the cache (Cache.h, CacheEntry.h, LRUHashTable.h, MemoryFile.*, FrameEntry.* for the viewer texture cache).

Images and color

  • Image (Image.cpp, ImageConvert.cpp, ImageCopyChannels.cpp, ImageMaskMix.cpp): the tiled floating-point image buffer, the fundamental data the pipeline moves around. ImageParams, ImageKey and ImagePlaneDesc describe an image and its layer/channel layout.

  • RectI / RectD: integer and double rectangles (regions).

  • Color management: Lut.cpp (color-space lookup tables) and the Color::Lut API, feeding into OpenColorIO integration.

  • Texture / TextureRect: GL textures for the viewer.

Roto and paint

Vector shapes and paint strokes: RotoContext (RotoContext.cpp), RotoItem/RotoLayer/RotoDrawableItem, Bezier/BezierCP (cubic Bézier shapes and control points), RotoStrokeItem (paint strokes), RotoPaint (the effect), RotoPaintInteract (viewer interaction), RotoSmear, FeatherPoint and CoonsRegularization (feathering). Rasterization uses cairo. RotoUndoCommand implements undo for roto edits.

Tracking

The planar/point tracker: TrackerContext (TrackerContext.cpp, TrackerContextPrivate.*), TrackMarker, TrackerNode + TrackerNodeInteract (the built-in node and its overlay), and TrackerFrameAccessor (feeds pixels to the solver). The heavy lifting is done by the bundled libmv (mv::AutoTrack), ceres and openMVG libraries.

Application services

  • AppManager (AppManager.cpp, AppManagerPrivate.*): the singleton; plug-in discovery/registry, OFX host, global cache, settings, factories.

  • AppInstance (AppInstance.cpp): one document/session.

  • Settings (Settings.cpp — very large): the user preferences, themselves modeled as a KnobHolder so the preferences panel is built from knobs.

  • Plugin / LibraryBinary: plug-in metadata and dynamic loading.

  • CLArgs (CLArgs.cpp): command-line parsing shared by both executables.

  • TimeLine: the current-frame model.

  • StandardPaths, ProcInfo, MemoryInfo, Log: environment, process and logging utilities.

  • OSGLContext (+ _mac/_win/_x11/_wayland backends, with the _xdg helper on Linux): off-screen OpenGL contexts for GPU rendering (on Linux the X11 and Wayland backends use the internal OSGLContext_glx_data / OSGLContext_egl_data structures). GPUContextPool pools them.

The Python API

The classes prefixed Py (PyNode, PyParameter, PyRoto, PyTracker, PyAppInstance, PyNodeGroup, PyGlobalFunctions, PyExprUtils) are the C++ side of Natron’s Python API. They are thin, scripting-friendly facades over the engine objects, exposed to Python through Shiboken using typesystem_engine.xml. See Python Bindings (Shiboken / PySide).