Writing a GeoOp — NDK Developers Guide

### Navigation

- index
- next |
- previous |
- NDK Dev Guide »
- 3D »

# Writing a GeoOp

A GeoOp node creates or modifies 3D data. The output is visible in NUKE’s built-in 3D Viewer, can be saved out to an OBJ or FBX file via the WriteGeo node, or rendered into a 2D image using (for example) the `ScanlineRender` node.

Writing a 3D Op is similar to writing a 2D Op. You need to override many of the same functions to describe the Op to nuke: `Class()`, `knobs`, `test_input`, and so on. Refer to the section on implementing 2D Ops for details about these. The main differences are:

- Your Op inherits from a different base class
- You override a different method to do the work of the Op (e.g. `create_geometry` instead of `pixel_engine`). Obviously the implementation of this method is quite different to what you would have in a 2D Op
- As well as the overall Op hash, 3D Ops have separate hashes for each data group. You’ll need to implement the `get_geometry_hash()` method to calculate each of these

To write a GeoOp you should, broadly, follow these steps:

1. Pick a base class to inherit from.
2. Override the appropriate method, depending on the base class you chose, to do the work of the Op.
3. Override the `get_geometry_hash()` method, to calculate a hash for each of the data groups.
4. Override whichever of the standard Op functions you need. The `Class()` method must always be overridden; all the others are optional. If you override the `knobs()` method, remember to call the method from the base class as well; otherwise, you’re likely to get some crashes.

The GeoOp class has a method, `geometry_engine`, which does the bulk of the geometry processing work. Both SourceGeo and ModifyGeo override this method to provide simpler interfaces for creating or modifying geometry respectively.

## Base Classes for GeoOps

All GeoOps inherit ultimately from the `DD::Image::GeoOp` class. There are two additional subclasses which you can inherit from instead, `DD::Image::SourceGeo` and `DD::Image::ModifyGeo`; these take care of some extra details for you.

Deciding which Op to inherit from depends on what you want your Op to do. Some examples to help guide you:

Purpose | Base Class to Inherit From
--- | ---
Create new geometry from scratch | `DD::Image::SourceGeo`
Create new geometry based on 2D inputs
Transform or distort existing geometry | `DD::Image::ModifyGeo`
Produce a more finely tessellated version of some existing geometry
Calculations based on analysis of the whole scene, rather than just one object at a time | `DD::Image::GeoOp`
Filter existing objects

A common reason for inheriting from `GeoOp` rather than `ModifyGeo` is that the latter provides an interface which operates on one 3D object at a time. If you are doing calculations which depend on having access to all the objects at once, it may be easier to inherit from `GeoOp`. You can still access information about other 3D objects in `ModifyGeo`; it just comes down to convenience.

## Extending SourceGeo

`SourceGeo` provides a simplified interface for creating geometry. It also provides some useful default behaviour:

- It takes a single input, which must be a subclass of `DD::Image::Iop`. This gets used as the default material on all 3D objects created by this Op.
- It overrides `get_geometry_hash`, appending the hash of the input Op to Group_Object. There’s special handling for when the input Op is a subclass of `DD::Image::Material`.
- It overrides `geometry_engine` to ensure that the 3D object cache is properly synchronized and that any created objects get filled in with some sensible default values.

The actual creation of 3D geometry is delegated to the `create_geometry` function, which you must override in your subclass:

void `DD::Image::SourceGeo::``create_geometry`(Scene& scene, GeometryList& out)

  Fills the `out` parameter with newly created geometry. This is called to create geometry for the first time, or to rebuild it after something has changed.

If you want to change the default values which are set up for each 3D object, you can override the `init_geoinfo_parms` method:

void `DD::Image::SourceGeo::``init_geoinfo_parms`(Scene& scene, GeometryList& out)

  Sets up the default values for created objects, including the transform matrix and the material.

There are further things which are common to all GeoOps that you can do. See the Common Parts of All GeoOps section for details.

The NDK includes `Sphere.cpp` as an example of how to implement a `SourceGeo` subclass.

## Extending ModifyGeo

The `ModifyGeo` class provides a single method that you must override:

void `DD::Image::ModifyGeo::``modify_geometry`(int obj, DD::Image::Scene& scene, DD::Image::GeometryList& out)

  This function is called once per GeoInfo from the input node. The `obj` parameter is the index of the input object to process.

  The data for the object to process is already populated in the `out` parameter. Your implementation of this function should modify the data in place by calling (e.g.) `out.writable_points(obj)` and overwriting the entries in the list it returns.

There are further things which are common to all GeoOps that you can do. See the Common Parts of All GeoOps section for details.

The NDK includes `LogGeo.cpp` as an example of how to implement a `ModifyGeo` subclass.

## Extending GeoOp Directly

The GeoOp base class does most of it’s work in a single method which you can override:

void `DD::Image::GeoOp::``geometry_engine`(DD::Image::Scene& scene, DD::Image::GeometryList& out)

  Creates or modifies geometry and ensures the Op’s geometry cache is up to date.

  Your implementation of this function should ensure that it calls `out.synchronize_objects()` to get the Op’s geometry cache up to date. Calling this more than once is relatively cheap, because it exits quickly if the cache is up to date. It must be called at least once after all the geometry creation or modification.

There are further things which are common to all GeoOps that you can/must do. See the Common Parts of All GeoOps section for details.

The NDK includes `UVProject.cpp` as an example of how to implement a `GeoOp` subclass.

## Common Parts of All GeoOps

Generally speaking, all GeoOps should calculate suitable hashes for each of the groups by overriding this method:

void `DD::Image::GeoOp::``get_geometry_hash`()

  Recalculates and updates the stored hashes for each group.

  This function is called by NUKE to get the hashes up to date, so it can use them to check which groups need to be rebuilt and set the appropriate rebuild flags.

All GeoOps have a few features in common:

- They store a separate hash for each group

- They perform caching

- Operations to implement (what, when and why)

- Geometry hashes

  Updates the stored hashes for each of the groups.

## GeoOp Call Order for Rendering

The call order for a GeoOp is different depending on whether it’s being rendered through a ScanlineRender (or similar) node, or being viewed in the 3D Viewer.

When rendering a GeoOp, most of the work happens inside the renderers own `_validate(bool)` method (the renderer itself is a subclass of Iop, following the usual Iop call sequence):

1. `GeoOp::_validate(bool)`
2. `GeoOp::get_geometry_hash()` (called by the `_validate` method)
3. `GeoOp::build_scene()`
4. `GeoOp::get_geometry()` (called by `build_scene`)
5. `GeoOp::geometry_engine()` (called by `get_geometry`)
6. `Scene::validate()`
7. `GeoInfo::validate()` for each `GeoInfo` in the scene
8. `Iop::validate()` for each material used by a `GeoInfo` in the scene
9. `Scene::evaluate_lights()`

In terms of the functions you’ll be overriding:

- `get_geometry_hash()` is called first to ensure the hashes are up to date;
- then `geometry_engine()` is called to produce the geometry.

In the case of a `SourceGeo` Op, that will instead look like:

- `get_geometry_hash()` is called first, as above;
- then `create_geometry(Scene& scene, GeometryList& out)` is called, to create the geometry.
- finally `init_geoinfo_parms(Scene& scene, GeometryList& out)` is called to setup some default values for various `GeoInfo` parameters. This includes providing a default material, when none was specified.

And for a `ModifyGeo` Op:

- `get_geometry_hash()` is called first, as above;
- then `modify_geometry(int obj, Scene& scene, GeometryList& out)` gets called once for each `GeoInfo` in the scene.

## GeoOp Call Order for Viewing

When you’re viewing the output of a GeoOp node in NUKE’s 3D Viewer, the call order is different to that shown above. Geometry is generated first, without any materials; then textures are generated in a background thread for each of the materials and the Viewer is updated as they complete.

Another difference between rendering 3D and viewing 3D is the amount that gets drawn. For rendering, it’s the connected inputs only; for the Viewer, it’s the connected inputs and also anything which has a panel open in the Properties bin.

The call order in the 3D Viewer looks like this for every Op connected to the Viewer’s primary input and for every Op with an open panel in the Properties bin:

1. `_validate(false)`
2. `get_geometry_hash()` (called by the `_validate` method)
3. `geometry_engine(Scene& scene, GeometryList& out)`
4. `GeoOp::build_handles(ViewerContext* ctx)` is called first. If this returns `true`, a draw_handles callback is added for the Op
5. `Knob::build_handles(ViewerContext* ctx)` is called for every knob on the Op. If it returns `true`, a draw_handles callback is added for the knob

This gathers the information necessary for NUKE to do its drawing. Next we do a series of render passes; for each pass we set the ViewerContext’s event to a different value then, after drawing all the geometry, invoke the draw_handles callbacks:

1. `draw_handle(ViewerContext* ctx)` with `ctx->event() == DRAW_SOLID`
2. `draw_handle(ViewerContext* ctx)` with `ctx->event() == DRAW_LINES`

If your Op doesn’t draw any custom handles, `build_handles` should return `false` and you can ignore the `draw_handle` function. Likewise, if you’re not using any custom knobs you can ignore the knob `build_handles` and `draw_handle` functions; the built-in knobs already have suitable implementations of these.

## Creating Geometry

To create a new 3D object, you’ll need to follow these steps:

1. Add an object
2. Add points for the object
3. Add primitives
4. Set attributes

It may not always be necessary to rebuild all of the geometry data; only some of the data groups may have been affected. The implementation should check the state of the rebuild flags to determine which groups need to be rebuilt. You can do this using (for example):

    if (rebuild(Mask_Points)) {
      ...
    }

Note that it’s possible to set the rebuild flags explicitly by calling `set_rebuild()`; but you should avoid doing this while inside your geometry_engine, create_geometry or modify_geometry method as it could lead to a memory leak.

Call out.add_object(obj) to make space for the new object in the geometry list.

### Navigation

- index
- next |
- previous |
- NDK Dev Guide »
- 3D »