DD::Image::Iop Class Referenceabstract

Iop is the base class for all the image operators. More...

Inherits DD::Image::Op, and DD::Image::IopInfoOwner.

Inherited by DD::Image::Black, DD::Image::Blur, DD::Image::BufferIop, DD::Image::Convolve, DD::Image::DownRez, DD::Image::FileIop, DD::Image::HConvolve, DD::Image::Material, DD::Image::MetaDataOp, DD::Image::MultiTileIop, DD::Image::NoIop, DD::Image::NukeWrapper, DD::Image::PixelIop, DD::Image::PlanarIop, DD::Image::Render, DD::Image::SolidShader, DD::Image::Transform, DD::Image::WireframeShader, and TextureSampler.


class  PixelCallbackI
struct  TextureImage

Public Member Functions

void fetchPlane (ImagePlane &imagePlane)
virtual PlanarIgetPlanarI ()
void force_validate (bool for_real=true) override
IopImpl * pImpl ()
virtual void engine (int y, int x, int r, ChannelMask, Row &)=0
Iopiop () override
 Cast to an Iop. This is much cheaper and safer than using dynamic_cast.
const Iopiop () const override
virtual ~Iop ()
bool test_input (int, Op *) const override
Opdefault_input (int) const override
Iopinput (int n) const
Iopinput (int n, int m) const
Iopinput0 () const
Iopinput1 () const
Cache * cache () const
bool cached () const
void cached (bool b)
virtual void in_channels (int, ChannelSet &) const
ChannelMask out_channels () const
int raw_channels_from () const
virtual bool pass_transform () const
void request (int x, int y, int r, int t, ChannelMask channels, int count)
void request (DD::Image::Box box, ChannelMask channels, int count)
void request (ChannelMask channels, int count)
void _copyState (Iop *input)
const BoxrequestedBox () const
const BoxunclampedRequestedBox () const
ChannelMask requested_channels () const
ChannelMask multi_requested_channels () const
ChannelMask unclamped_requested_channels () const
int requested_count () const
virtual void get (int y, int x, int r, ChannelMask, Row &)
void at (int x, int y, Pixel &out)
float at (int x, int y, Channel)
ChannelSet peek (int x, int y, int r, int t, Pixel &out)
bool peek (int x, int y, int w, int h, ChannelMask pixelChannels, PixelCallbackI &callback)
virtual TransformgetTransform ()
virtual bool set_texturemap (ViewerContext *, bool gl=true)
virtual TextureImage get_texturemap (ViewerContext *ctx)
virtual void unset_texturemap (ViewerContext *)
virtual bool shade_GL (ViewerContext *, GeoInfo &)
virtual void vertex_shader (VertexContext &)
virtual void fragment_shader (const VertexContext &, Pixel &out)
virtual void displacement_shader (const VertexContext &vtx, VArray &out)
virtual float displacement_bound () const
virtual void blending_shader (const Pixel &in, Pixel &out)
virtual void render_state (GeoInfoRenderState &state)
virtual void sample (float cx, float cy, float w, float h, Filter *, Pixel &out)
void sample (float cx, float cy, float w, float h, Pixel &out)
virtual void sample (const Vector2 &center, const Vector2 &dU, const Vector2 &dV, Filter *filter, Pixel &out)
void sample (const Vector2 &center, const Vector2 &dU, const Vector2 &dV, Pixel &out)
virtual float sample_shadowmap (Iop *map, bool map_is_one_over_z, float cx, float cy, float W, float H, Filter *filter, float Pz)
void build_handles (ViewerContext *) override
virtual void inputsAttached ()
virtual void gpuEngine_useTextureTransform (bool useTransform)
 GPU support code. More...
virtual void gpuEngine_setupTextureTransform (const Matrix4 &postOpTransform)
virtual const char * gpuEngine_decl () const
virtual const char * gpuEngine_body () const
virtual Hash gpuEngine_shader_hash_at (double time)
virtual int gpuEngine_getNumRequiredTexUnits () const
virtual void gpuEngine_GL_begin (GPUContext *context)
virtual void gpuEngine_GL_end (GPUContext *context)
virtual IopviewerPassThrough () const
OpHints opHints () const override
 Return hints to control when and how this op will be evaluated by the top-down system.
- Public Member Functions inherited from DD::Image::Op
PrevalidateResult preValidate (ViewerContext *ctx=nullptr, PreValidateContext *=nullptr)
OprootOp () const
bool preValidateAborted (int treeStartingVersion, PrevalidateResult &result) const
const OutputSetgetOutputs () const
 return all the outputs of this node
virtual void setInputsValid (bool nowValid)
 set whether the input ops are valid (are for the right context)
bool inputsValid () const
 return whether the input ops are valid (are for the right context)
virtual bool can_clone () const
 returns whether or not an op can be cloned in the dag
bool haveHash () const
 return true if the hash() value is meaningful and globally unique
virtual std::vector< DD::Image::OutputContextgetPrevVersionsWanted () const
virtual const MetaData::Bundle_fetchMetaData (const char *keyname)
const MetaData::BundlefetchMetaData (const char *keyname)
Node * node () const
DD::Image::NodeI * getNode () const
void node (Node *v)
OpfirstOp () const
void firstOp (Op *v)
Opparent () const
void parent (Op *lpOp)
virtual void detach ()
 node has been deleted in DAG
virtual void attach ()
 node has been created in DAG
virtual void pre_write_knobs ()
virtual void knobs (Knob_Callback)
int replace_knobs (Knob *afterthis, int n, void(*f)(void *, Knob_Callback), void *, const char *fileExt=nullptr)
int add_knobs (void(*f)(void *, Knob_Callback), void *, Knob_Callback)
void set_unlicensed ()
Knobknob (const char *name) const
Knobknob (int) const
bool pushed () const
bool panel_visible () const
bool node_disabled () const
bool node_selected () const
unsigned node_gl_color () const
void * field (const char *name)
void * field (const char *name, int &type)
void * set_field (const char *name, const void *source, int size)
void * get_field (const char *name, void *dest, int size)
void beginHandle (HandleType command, ViewerContext *ctx, EventCallback *cb, int index, float x=0, float y=0, float z=0, ViewerContext::Cursor cursor=ViewerContext::kNoCursor)
void endHandle (ViewerContext *ctx)
virtual int knob_changed (Knob *)
virtual int knob_change_finished (Knob *knob, bool changedByUser=true)
void addTime (OpTimer::Category category, long long microsecondsCPU, long long microsecondsWall, bool isTopLevel=true)
void getPerformanceInfo (OpTimer::Category category, OpTimer::PerformanceInfo &info) const
 return the amount of CPU time taken by this op
virtual bool inputs_clockwise () const
 whether unconnected inputs on the DAG should be arranged clockwise or anticlockwise (default)
virtual std::vector< int > input_order () const
virtual int inputArrows (int nodeInputs) const
bool script_command (const char *command, bool py=true, bool eval=true) const
bool script_expand (const char *str) const
HandlesMode anyHandles (ViewerContext *ctx)
void add_draw_handle (ViewerContext *)
virtual void draw_handle (ViewerContext *)
virtual void add_input_handle (int input, ViewerContext *)
void add_op_handle (ViewerContext *ctx)
void add_knob_handle (Knob *, ViewerContext *)
virtual int getViewableModes () const
virtual int optional_input () const
virtual int minimum_inputs () const
virtual int maximum_inputs () const
int inputs () const
int node_inputs () const
Opnode_input (int, GenerateType=OUTPUT_OP) const
Opnode_input (int, GenerateType, const DD::Image::OutputContext *outputContext) const
Opinput_op (int n=0) const
virtual void inputs (int n)
Opinput (int) const
int inputNumber (int input, int offset) const
Opinput (int input, int offset) const
Opinput0 () const
 return the primary input More...
Opinput1 () const
 return the second input, if it exists More...
const std::vector< Op * > & getInputs () const
const std::vector< Op * > & getChildren () const
virtual void set_input (int i, Op *op, int input, int offset)
void set_input0 (Op *op)
void set_input (int i, Op *op)
void set_input (int i, Op &op)
void set_input (int input, int offset, Op *op)
const OutputContextoutputContext () const
virtual void setOutputContext (const OutputContext &c)
virtual void append (Hash &)
virtual float uses_input (int) const
virtual void build_splits ()
virtual int split_input (int) const
virtual const OutputContextinputContext (int n, int offset, OutputContext &) const
virtual const OutputContextinputUIContext (int n, OutputContext &) const
const Hashhash () const
virtual bool frameTransformImplemented () const
virtual bool frameTransformDownstream (const OutputContext &context, unsigned int input, float inFrame, float &outFrame) const
virtual bool frameTransformUpstream (const OutputContext &context, unsigned int input, float outFrame, float &inFrame) const
virtual DopeItemFlags::Mask getDopeItemFlags () const
virtual bool shouldHideInDopeSheet (Knob *knob) const
virtual DD::Image::KnobgetDopeItemKnob () const
virtual ViewSet viewsProduced () const
virtual ViewSet viewsWantOn (int i) const
virtual ViewSet splitForViews () const
bool requested () const
void setRequested ()
void forgetRequestShallow ()
void forget_request ()
void forget_request (std::set< Op * > &forgotten)
virtual const char * node_shape () const
DD::Image::Hash curveHash () const
bool opCurrent () const
virtual unsigned node_color () const
virtual const char * node_help () const =0
virtual const char * input_label (int, char *) const
virtual std::string input_longlabel (int) const
void node_redraw ()
void print_name (std::ostream &o) const
NodeContext nodeContext () const
std::string node_name () const
void invalidateSameHash ()
bool invalidate ()
bool invalidate (const Hash &hash)
bool update (const Box *=nullptr)
void asapUpdate ()
void asapUpdate (const Box &box, int direction=0)
void validate (bool for_real=true)
void update_handles () const
bool valid () const
 Returns true if it has been validated - including if there was an error. More...
bool real_valid () const
 Returns true if it has been real-validated - including if there was an error. More...
bool inErrorState () const
bool inInvalidState () const
bool opened () const
void open ()
void unopen ()
bool running () const
void running (bool v)
bool not_closed () const
void close ()
void callCloseAfter (double seconds)
void copyState (Op *input)
bool cached () const
void cached (bool b)
virtual Executableexecutable ()
void setKnobsToContext (const OutputContext &)
void gotoContext (const OutputContext &, bool update)
void progressFraction (double fraction, StatusFlags flags=StatusNone)
void progressFraction (int a, int b, StatusFlags flags=StatusNone)
void progressMessage (const char *fmt,...)
void progressModalMessage (const char *fmt,...)
void progressDismiss ()
int slowness () const
void slowness (int newval)
virtual bool firstEngineRendersWholeRequest () const
virtual bool updateUI (const OutputContext &context)
const Formatinput_format () const
const OutputContextuiContext () const
void error (const char *fmt,...)
void warning (const char *fmt,...)
void critical (const char *fmt,...)
void debug (const char *fmt,...)
void abort () const
 Abort all trees the op is in.
bool aborted () const
 True if one of the trees the op is in was aborted; ops should check this while processing and return quickly when true.
void cancel () const
 Cancel all trees the op is in. Make sure you also call abort() to stop processing.
bool cancelled () const
 True if one of the trees the op is in was cancelled (by user interaction)
bool addToTree (OpTree *lpTree)
 Returns true if the op was added to the tree, or false if its reference count increased.
bool removeFromTree (OpTree *lpTree)
 Returns false if the op was removed from the tree, or true if its reference count decreased.
bool isInTree (OpTree *lpTree) const
 Checks if an op is in a particular tree, for debugging purposes.
bool isInAnyTree () const
 Checks if an op is in any tree at all.
OpTreeHandlergetTreeHandler () const
 Returns the treeHandler for a given Op.
bool hasError () const
bool opOrChildHasError () const
const OpgetErroredOp () const
void setPopUpScheme (PopUpScheme lScheme)
PopUpScheme getPopUpScheme () const
bool arePopUpsEnabled ()
 Returns whether a pop-up should be enabled for the next message, modifying internal data when necessary.
OpMessageHandlergetMsgHandler ()
const OpMessageHandlergetMsgHandler () const
std::string getDebugInfo () const
 Returns a string of debug information about the op. For internal use.
std::string getDetailedDebugInfo () const
bool tryValidate (bool for_real=true)
virtual GeoOpgeoOp ()
 Cast to a GeoOp. This is much cheaper and safer than using dynamic_cast.
virtual const GeoOpgeoOp () const
virtual ParticleOpparticleOp ()
 Cast to a ParticleOp. This is much cheaper and safer than using dynamic_cast.
virtual const ParticleOpparticleOp () const
virtual DeepOnlyOpdeepOnlyOp ()
 Cast to a DeepOnlyOp. This is much cheaper and safer than using dynamic_cast.
virtual const DeepOnlyOpdeepOnlyOp () const
virtual std::string getLibraryName () const
 Return a label and version string to display library version info for the Node.
virtual VersionInfo getLibraryVersion () const
virtual const char * Class () const =0
const std::string libraryDisplayName () const
virtual const char * displayName () const
virtual std::string docsPath () const
virtual bool onAction (const ViewerContext *c, const DD::Image::Flags f, void *d)
Opget (const Description *description)
- Public Member Functions inherited from DD::Image::IopInfoOwner
const Infoinfo () const
int x () const
int y () const
int r () const
int t () const
int w () const
int h () const
bool is_constant () const
int clampx (int x) const
int clampy (int y) const
const Formatformat () const
const Formatfull_size_format () const
int ydirection () const
bool black_outside () const
ChannelMask channels () const
const GeneralInfogeneralInfo () const
const Info2Dinfo2D () const
int first_frame () const
int last_frame () const
void format (const Format &f)
void full_size_format (const Format &f)

Static Public Member Functions

static Iopdefault_input (const OutputContext &)
static Opdefault_input (const Op *op)
static Channel channel (const char *name)
static const char * channel_name (Channel c)
- Static Public Member Functions inherited from DD::Image::Op
static int treeVersion ()
 get the current tree version
static bool nukeBusy ()
 is nuke processing something on a parallel thread?
static Opcreate (Node *node, const char *name, Op *p_op)
static Opcreate (const char *name, Op *p_op)
static void resetTimers ()
 reset all the performance timers
static void setTimingEnabled (bool enabled)
 turn performance timing on or off
static bool isTimingEnabled ()
 return whether performance timing is on or not
static const char * script_result (bool py=false)
static void script_unlock ()
static void all_forget_request ()
static void new_request_pass ()
static double callPendingClose (double seconds)
static void clearPendingClose ()
static Operror_op ()
static const char * error_message ()
static void clearAbortAndError ()
 To be removed.
static void SetDefaultPopUpEnable (bool lEnable)
 This is used by Nuke to indicate when ops using the default pop-up scheme should show pop-ups. Not recommended for customisation.
static std::string getVersionInfoStr (const VersionInfo &versionInfo)
static const Descriptionfind_description (const char *name, const Op *op_)
static int message_f (char t, const char *,...)
static int message_vf (char t, const char *, va_list)
static void add_timeout (float t, TimeoutHandler, void *v=nullptr)
static void repeat_timeout (float t, TimeoutHandler, void *=nullptr)
static bool has_timeout (TimeoutHandler, void *=nullptr)
static void remove_timeout (TimeoutHandler, void *=nullptr)

Static Public Attributes

static bool sPreserveCaches
- Static Public Attributes inherited from DD::Image::Op
static unsigned current_request_pass
static void(* node_redraw_cb )(const Op *)
static void(* print_name_cb )(std::ostream &, const Op *)
static void(* status_callback )(const Op *, float, float, const char *, StatusFlags)
static constexpr int kInvalidVersion
static constexpr VersionInfo kUnsetVersion

Protected Member Functions

 Iop (Node *node)
virtual void _invalidate () override
virtual void _validate (bool for_real) override
virtual void _request (int x, int y, int r, int t, ChannelMask, int count)
virtual void _open () override
virtual void _close () override
virtual void doFetchPlane (ImagePlane &imagePlane)
bool inUse () const override
void copy_info (int input)
void copy_info (int input, ChannelMask)
void copy_info ()
void clear_info ()
void merge_info (int input=0)
void merge_info (int input, ChannelMask)
void mergeFrameRange (int input)
void set_out_channels (ChannelMask m)
void set_out_channels (ChannelSetInit m)
void set_out_channels (Channel z)
void raw_channels_from (int n)
void set_out_channels (ChannelMask m, int n)
IopasIop (Op *op) const
TransformgetDefaultTransform () const
template<class TileType >
void doSample (float cx, float cy, float w, float h, Filter *, Pixel &out)
template<class TileType >
float do_sample_shadowmap (Iop *map, bool map_is_one_over_z, float cx, float cy, float W, float H, Filter *filter, float Pz)
- Protected Member Functions inherited from DD::Image::Op
 Op (Node *node)
 The constructor is protected so only subclasses can create the base class.
Opcreate (Node *node, const char *name)
Opcreate (const char *name)
HandlesMode anyInputHandles (ViewerContext *)
 return if any of the inputs (recursively) wish to draw handles More...
HandlesMode anyKnobHandles (ViewerContext *)
 return if any of the knobs on this node wish to draw handles More...
void build_input_handles (ViewerContext *)
void build_knob_handles (ViewerContext *)
void disallowNoTrees ()
 Call this to tell the op that it should always have op trees for normal behaviour (for internal use)
virtual HandlesMode doAnyHandles (ViewerContext *ctx)
virtual PrevalidateResult doPreValidate (ViewerContext *ctx=nullptr, PreValidateContext *=nullptr)

Protected Attributes

ChannelSet out_channels_
 protected so validate() can directly modify it
int raw_channels_from_
- Protected Attributes inherited from DD::Image::Op
bool _haveHash
 whether the _hash actually has been set by a call to invalidate(Hash) ever.
- Protected Attributes inherited from DD::Image::IopInfoOwner
Info info_


class Cache
class Interest
class GeneralTile
template<SampleFunction , typename , typename... >
struct MultiTileCallDelegate
std::ostream & operator<< (std::ostream &, const Iop &)

Additional Inherited Members

- Public Types inherited from DD::Image::Op
enum  HandlesMode { eNoHandles, eHandlesUncooked, eHandlesCooked, eHandlesMax }
enum  PrevalidateResult { eFinished, eCancelled, eAbandoned }
 This is a tribool return value. Do not extend.
enum  HandleType {
  eNone, eMouseLeftClick, eMouseRightClick, eMouseMove,
  eMouseDrag, eMouseRelease, eSelectionChanged, eSelectionChangeFinished,
  eHandleDragTranslate, eHandleDragRotate, eHandleDragScale, eHandleDragPivot,
enum  ViewableModes { eViewableMode2D, eViewableMode3D, eViewableMode3D_2DReference }
enum  GenerateType {
enum  NodeContext { eNodeGraph, eTimeline, eOpGraph }
enum  StatusFlags { StatusNone, StatusModal, StatusUseCallback }
enum  PopUpScheme {
  ePU_Never, ePU_Done, ePU_Once, ePU_Default,
 Pop-up schemes determine when pop-up messages are displayed for op errors. More...
enum  VersionComponents { eMajor, eMinor, ePoint, eRevision }
typedef std::pair< int, DD::Image::Op * > Output
 Combination of input number and pointer to Op.
typedef std::set< OutputOutputSet
 Set of all outputs from this Op.
typedef std::map< Hash, std::vector< unsigned int > > ItemSelectionList
typedef bool( EventCallback) (Op *op, EventContext eventCtx)
using VersionInfo = std::tuple< int, int, int, int >
- Public Types inherited from DD::Image::IopInfoOwner
typedef IopInfo Info
- Public Attributes inherited from DD::Image::Op
const MetaData::BundlemetaCache
Hash metaCacheHash

Detailed Description

Iop is the base class for all the image operators.

The base class is not usable. Several pure virtual functions must be defined by a subclass to make an operator that works.

Constructor & Destructor Documentation

Iop::Iop ( Node *  node)

The constructor is protected so only subclasses can create the base class. The info() is filled in with default values for an empty image with no channels and format Format::None.

References DD::Image::Op::disallowNoTrees(), DD::Image::GeneralInfo::first_frame(), DD::Image::Info2D::full_size_format(), DD::Image::IopInfoOwner::info_, DD::Image::GeneralInfo::last_frame(), DD::Image::Mask_All, DD::Image::Format::None, out_channels_, DD::Image::Box::set(), and DD::Image::Op::slowness().

Iop::~Iop ( )

The destructor destroys the cache if there is one.

Member Function Documentation

void Iop::fetchPlane ( ImagePlane imagePlane)

Fetch an image plane. Ops that want an image plane should pass an empty image plane with the appropriate size and channels, and then this will be filled. This is a relatively low-level function. See PlanarI and PlanarIop for a larger structure built around this.

Note that the area must be a subset of the region of definition as specified in info().

This function may perform caching, and calls doFetchPlane() to fetch the actual.

References doFetchPlane(), DD::Image::IopInfoOwner::info(), DD::Image::Op::open(), DD::Image::Box::r(), DD::Image::Box::t(), DD::Image::Box::x(), and DD::Image::Box::y().

Referenced by DD::Image::NukeWrapper::doFetchPlane(), and DD::Image::GeneralTile::load_range().

virtual PlanarI* DD::Image::Iop::getPlanarI ( )

whether this Iop prefers planar or row-based access.

if it prefers planar access return a pointer to the interface to do planar size queries

Reimplemented in DD::Image::NukeWrapper, and DD::Image::Read.

Referenced by DD::Image::MultiTileIop::force_validate(), and DD::Image::NukeWrapper::getPlanarI().

void Iop::force_validate ( bool  for_real = true)

Acts as though valid() is off and does validate(). Thus you can be certain that _validate() is called.

This is re-implemnted from Op, and calls the base class version, as well as doing some extra Iop-specific work to propagate Info from input to output when the Op is in error.

Reimplemented from DD::Image::Op.

Reimplemented in DD::Image::MultiTileIop.

References copy_info(), DD::Image::Op::force_validate(), and DD::Image::Op::input0().

Referenced by DD::Image::MultiTileIop::force_validate().

void Iop::engine ( int  y,
int  x,
int  r,
ChannelMask  channels,
Row row 
pure virtual

Calculate the image for this line and write the result to the row.

y, x, r, and channels have already been clipped to the requested() box and requested_channels() (which also means they are clipped to the box and channels set by _validate()).

This is not called if the intersection of channels() and out_channels() is Mask_None.

You must fill all the requested channels. If your operator does not modify a channel then you should copy it unchanged from input0().

The default version prints an error. Unless your operator sets out_channels to none always (this is true in some cases) you have to implement this.

Implemented in DD::Image::NukeWrapper, DD::Image::Read, DD::Image::Render, DD::Image::PlanarIop, DD::Image::Write, DD::Image::Material, DD::Image::MultiTileIop, DD::Image::NoIop, and DD::Image::PixelIop.

References DD::Image::Op::debug().

void Iop::_validate ( bool  for_real)

The subclass-dependent portion of validate(). This is called by validate() after checking to see if it is needed.

This must set the contents of info_. Usually this is done by calling validate() on some input and then assigning that to info_, and then possibly modifying that information. You should use the copy_info(), merge_info(), and init_merge_info() methods if possible to set the info, or maybe Iop::Info::clear(), and then modify the results as needed:

\\ sample modifications of data, see plugin source code for more:

An operator can also detect that it will not do anything to some channels and call set_out_channels(). If you set this to Mask_None then this will prevent _request(), _open() and engine() from being called. Besides being faster this often makes coding a plugin easier because you don't have to worry about the degenerate cases except in _validate():

if (gain == 1) {
} else {

If something is wrong you can call error(). This will throw an exception and _validate() will not be called again until invalidate() is done.

for_real is true if Nuke is going to ask for image data from the operator. Otherwise it is only doing this to get the frame range, format or other information from the info_. If it is false you should try very hard to avoid anything expensive such as opening files and you must avoid producing errors that don't happen on every frame since that would prevent dissolves operators from fading out inputs during the time they produce errors.

For many operators the action is the same whether for_real is true or false. If you don't use any inputs and cannot avoid opening a file and want to avoid opening it twice, recursively call yourself like this. This is what Read operators do if they don't have the format and channels set yet:

if (!for_real) {validate(true); return;}

The default version merges the info from all the inputs and then turns on the channels in out_channels() if it is not Mask_All.

Reimplemented from DD::Image::Op.

Reimplemented in DD::Image::Read, DD::Image::Render, DD::Image::NukeWrapper, DD::Image::Write, DD::Image::Transform, DD::Image::IllumShader, DD::Image::DrawIop, DD::Image::RenderScene, DD::Image::NoIop, and DD::Image::UpRez.

References DD::Image::ChannelSet::all(), copy_info(), DD::Image::IopInfoOwner::info_, DD::Image::Op::inputs(), merge_info(), and out_channels_.

void Iop::_request ( int  x,
int  y,
int  r,
int  t,
ChannelMask  channels,
int  count 

The subclass-dependent portion of request(). This is called by request() if the new request is larger than what has already been requested this pass. _validate(true) will already have been called.

This should call request() on any inputs that are going to be used. Usually it will modify the arguments slightly:

input0().request(x-1, y-1, r+1, t+1, channels, count);

If you are going to randomly access the input, you should request it's entire bounding box:

input0().request(channels, count);

count indicates approximately how many times engine() will be called for each value of y. You should pass it unchanged or multiply it by a value greater or equal to 1 if your engine() asks for more than one input line. This is used to set up caching by knowing how many times a line will be needed. count may be zero to indicate that a previous request is being expanded with more area or more channels.

The default implementation requests the same area from each input. You will need to change this if your operator does random access, possibly to call the request() method that takes no area and thus accesses the format. It uses in_channels() to figure out what channels to ask for.

Reimplemented in DD::Image::NukeWrapper, DD::Image::Render, DD::Image::PlanarIop, DD::Image::Write, DD::Image::IllumShader, DD::Image::RenderScene, DD::Image::NoIop, DD::Image::UpRez, and DD::Image::DownRez.

References DD::Image::IopInfoOwner::channels(), in_channels(), input(), DD::Image::Op::inputs(), out_channels(), and request().

Referenced by request().

void Iop::_open ( )

This used to do something but does not now. It is still recommended that any subclasses call this in their _open().

Reimplemented from DD::Image::Op.

Reimplemented in DD::Image::Read, DD::Image::PlanarIop, and DD::Image::NukeWrapper.

Referenced by DD::Image::NukeWrapper::_open().

void Iop::_close ( )

At one time this destroyed the cache. That's no good anymore as it throws away data when the automatic file close is done by nuke. Instead it only deletes it if valid is false.

Reimplemented from DD::Image::Op.

Reimplemented in DD::Image::Read, and DD::Image::NukeWrapper.

References DD::Image::Op::valid().

Referenced by DD::Image::NukeWrapper::_close().

void Iop::doFetchPlane ( ImagePlane imagePlane)

Fetch an image plane. This is the function that Iops that should override. This can be called for any plane with any arbitrary bounds, channel. Either implement all of these (ImagePlane::copyIntersection helps here), or call the default implementation for a fallback.

By default this is not cached, so that multiple identical calls to fetchPlane will result in multiple identical calls to doFetchPlane. Use PlanarIop if you want a base class to manage caching of these for you.

no data from src, set to zero

Reimplemented in DD::Image::NukeWrapper, DD::Image::Read, and DD::Image::PlanarIop.

References DD::Image::Op::aborted(), DD::Image::ImagePlane::chanStride(), DD::Image::ChannelSet::contains(), DD::Image::Row::get(), DD::Image::Box::h(), DD::Image::IopInfoOwner::info(), DD::Image::Box::r(), DD::Image::ImagePlane::rowStride(), DD::Image::Box::t(), DD::Image::IopInfoOwner::w(), DD::Image::Box::w(), DD::Image::ImagePlane::writable(), DD::Image::Box::x(), and DD::Image::Box::y().

Referenced by DD::Image::NukeWrapper::doFetchPlane(), and fetchPlane().

void Iop::copy_info ( int  input)

Same as copy_info(n, Mask_All), indicating you are interested in all the channels the operator provides.

References DD::Image::IopInfoOwner::info(), DD::Image::IopInfoOwner::info_, input(), DD::Image::Op::real_valid(), and DD::Image::Op::validate().

void Iop::copy_info ( int  input,
ChannelMask  channels 

Most validate() functions can call this to get the information from one of their inputs. They can then modify the info (such as changing the bounding box or adding or removing channels) or use merge_info() to get information from other inputs.

channels is what channels of this input you use. The bounding box and ydirection are only changed if these intersect the channels available from the input. Also if it is none it will avoid opening files or testing for errors on that input.

Equivalent code that you can put into _validate() is:

input(n)->validate(channels && for_real);
channels = intersect(channels, info_.channels());
if (!channels) {

References DD::Image::IopInfo::black_outside(), DD::Image::IopInfoOwner::channels(), DD::Image::IopInfoOwner::info(), DD::Image::IopInfoOwner::info_, input(), DD::Image::Op::real_valid(), DD::Image::Box::set(), DD::Image::Op::validate(), and DD::Image::IopInfo::ydirection().

void Iop::clear_info ( )

If you call this, then the first merge_info() you call will instead do a copy_info(). This is useful for an operator that has to iterate through all its inputs and is not sure which ones it is using. Warning: the value in info_ is bad after this call; you must call copy_info(), merge_info(), or assign some new value to info_ before your _validate() function returns.

References DD::Image::IopInfoOwner::info_, and DD::Image::Box::set().

void Iop::merge_info ( int  input,
ChannelMask  channels 

Merge the info from input n into this info. This is for use by _validate() in operators that take several inputs.

This will call validate() on the input, passing true if for_real is on and channels in non-zero.

If the output of that input intersects channels it will merge those channels and the bounding box and ydirection in.

The formats are unchanged.

If you have called clear_info() this instead does copy_info(). This is for conveniece for writing a loop that merges a large number of inputs.

References DD::Image::IopInfo::accessPreference(), DD::Image::IopInfo::black_outside(), DD::Image::IopInfoOwner::channels(), copy_info(), DD::Image::IopInfoOwner::info(), DD::Image::IopInfoOwner::info_, input(), DD::Image::Box::merge(), DD::Image::Op::real_valid(), DD::Image::Op::validate(), DD::Image::Box::w(), and DD::Image::IopInfo::ydirection().

void Iop::mergeFrameRange ( int  input)

Union the current and this input's frame ranges (ignoring either one if they are "empty" which is indicated by the last frame being less or equal to the first). This is the normal action by Nuke operators when merging sequences of different frame ranges.

References DD::Image::GeneralInfo::first_frame(), DD::Image::IopInfoOwner::first_frame(), DD::Image::IopInfoOwner::info(), DD::Image::IopInfoOwner::info_, input(), DD::Image::GeneralInfo::last_frame(), and DD::Image::IopInfoOwner::last_frame().

Transform* DD::Image::Iop::getDefaultTransform ( ) const

Ops which shouldn't break transform concatenation could call this to propagate input0's transform to the output Ops. See the documentation for getTransform() for more details.

References getTransform().

Referenced by DD::Image::NoIop::getTransform().

bool Iop::test_input ( int  n,
Op op 
) const

By default Iops only allow other Iops to be hooked to the input. You can override this if you have an image operation that takes data other than images as input. Make sure you cast back after calling input0() or other things that assume the inputs are Iops.

Reimplemented from DD::Image::Op.

Reimplemented in DD::Image::NukeWrapper.

Referenced by DD::Image::NukeWrapper::test_input().

Op * Iop::default_input ( int  n) const

Returns a Black operator with the format set to the Nuke user's choice for default format. This means that by default an Iop with a disconnected input gets a black image of the expected size.

If the library is used by a program other than Nuke this will return null! Most operators assume inputs are not null, so you must connect them yourself.

Reimplemented from DD::Image::Op.

Reimplemented in DD::Image::NukeWrapper.

References DD::Image::Op::outputContext().

Referenced by DD::Image::IllumShader::default_input(), DD::Image::NukeWrapper::default_input(), DD::Image::Write::execute(), and DD::Image::Op::getViewableModes().

Iop * Iop::default_input ( const OutputContext context)

This static function returns the same op that default_input(int) returns. This is useful so that non-Iop subclasses can get the same Black iop, which is mostly useful for finding out the user's default format or frame range settings.

Op * DD::Image::Iop::default_input ( const Op op)

Returns default_input(op->outputContext()). Provided for back-compatibility.

References default_input(), and DD::Image::Op::outputContext().

Referenced by default_input().

void Iop::input1 ( ) const

Fast inline method of getting input(1). This casts on the assumption that the input is another Iop. Also notice that this returns a reference rather than a pointer, this is for back compatibility. Note: This function potentially derefences a null pointer. In C++ standard that is considered as an Undefined Behaviour. If the input(1) can be null pointer, do not use this function!

Fast inline method of setting input(1,i).

References DD::Image::Op::input1().

Referenced by DD::Image::IllumShader::_request(), DD::Image::IllumShader::_validate(), DD::Image::DrawIop::_validate(), and DD::Image::DrawIop::pixel_engine().

DD::Image::Cache DD::Image::Iop::cache ( ) const

Return a pointer to the cache object being used by the Iop, or null if there is not cache object. This object is created automatically by open() if cached() is true or if there are multiple requests for data, or by at() or Tile or Interest objects.

Calling invalidate() does not destroy the Cache object, but does destroy all the stored pixels. This is the majority of the memory used by a Cache, but the object itself is approximately the size of one row of pixels and should be destroyed if you really are done using the Iop.

The Cache object is destroyed and the pointer cleared when the Iop is destroyed, or when _close() is called.

Referenced by at(), get(), and peek().

bool DD::Image::Iop::cached ( ) const

Returns the last value sent to cached(bool).

Referenced by get(), and request().

void DD::Image::Iop::cached ( bool  b)

If this is true then a cache is created by _open() when the first pixel is requested. The cache is modified so lines are never thrown away (?).

If you turn this off the old data will remain in the cache and may still be returned, but new data will not be added and lines in the cache may be thrown away when the memory is needed. To free it either call invalidate() or call close().

void Iop::in_channels ( int  input,
ChannelSet mask 
) const

Return the set of channels needed from input n to output the channels in mask. This is done by modifying mask in-place to the new value. This is only used by PixelIop and by the default versions of _request() currently, though it is recommended that an Iop implement it.

To make it easier to write, you can assume that at least one of the channels in out_channels() is set in mask.

The default version returns mask unchanged. This is only correct for operators where there is not cross-talk between channels. A typical case is where the red output depends on all three of red, green, and blue, and same for green and blue. In this case you would implement it like this:

void MyIop::in_channels(int, ChannelSet& mask) const {
mask += (Mask_RGB);

If you completely replace a channel, you don't need it from the input, so turn it off in the mask. For instance if you write your own rgb channels, do this:

void MyIop::in_channels(int, ChannelSet& mask) const {
mask -= (Mask_RGB);

Reimplemented in DD::Image::NukeWrapper, and DD::Image::ColorLookup.

Referenced by DD::Image::RenderScene::_request(), _request(), DD::Image::PixelIop::engine(), DD::Image::NukeWrapper::engine(), and DD::Image::NukeWrapper::in_channels().

ChannelMask DD::Image::Iop::out_channels ( ) const

This is the set of channels that the operator modifies, all other channels are assumed to be copied unchanged from the raw_channels_from() input. Nuke will skip calling engine() if the requested channels does not intersect this set. Note that it will call engine() with channels that are not in this set, as long as some channels are in it.

Subclasses use set_out_channels() to change this. They can either do it in the constructor, or in _validate().

By default this returns Mask_All.

Referenced by DD::Image::NukeWrapper::_open(), _request(), DD::Image::NukeWrapper::_validate(), at(), DD::Image::PixelIop::engine(), get(), DD::Image::Interest::inputIop(), DD::Image::opHints(), peek(), and request().

bool Iop::pass_transform ( ) const

Return true if it is okay to move a transformation that is before this operator to after it. This is true of color correctors or any other operator where pixels don't move and the calculation does not depend on the position of pixels. Nuke may use this to concatenate multiple TransformIop into a single one.

This must work without _validate() being called! It probably should return a constant true or false.

The base class returns false.

Reimplemented in DD::Image::NoIop.

void Iop::request ( int  x,
int  y,
int  r,
int  t,
ChannelMask  channels,
int  count 

Call this to indicate the area that will be requested from this Iop. This calls validate(), and then calls _request() which will usually recursively call request() on each input.

All calls to request() are unioned together and intersected with the info() produced by validate(). All subsequent calls to get pixels (by get(), Tile and Interest constructors, or by calling at()) are clamped to this area. Missing channels return zero, positions outside the box return the pixel from the nearest edge of the box.

Although usually you want the request box to cover everything you will ask for, an operator may limit the size to avoid causing huge amounts of data to be cached. For instance some transforms request extremely large areas but reduce them to smaller than a single pixel, limiting the sampled area to only the non-scaled part of the input image and replicating the edge pixels will not degrade the transformed image significantly and will use far less memory.

This is used to set up the automatic caching. The region is used to determine how much data to store in the cache. The count argument is used to indicate that engine() will be called more than once for a given y value. A count of N and calling request() N times have identical behavior. A count of zero indicates that a previous request() call is being expanded in area (zero acts like 1 if this is the first call). Caches are placed by analyizing the slowness() and resulting counts of all the Iops (the current algorithim is simple and just turns on the cache on all operators with a count greater than one).

Calling Op::forget_request() will make the next request() reset the accumulated area. You may also want to call cache_new_pass() to indicate that all caches can be reused even if the data in them is still good.

References _request(), DD::Image::Op::aborted(), cached(), DD::Image::IopInfoOwner::channels(), DD::Image::Memory::clipToCacheLimit(), DD::Image::Op::debug(), DD::Image::Op::error(), DD::Image::Box::h(), DD::Image::IopInfoOwner::info_, input(), iop(), MAX(), MIN(), out_channels(), DD::Image::Op::print_name(), DD::Image::IopInfoOwner::r(), DD::Image::Box::r(), DD::Image::Op::real_valid(), request(), DD::Image::Op::requested(), DD::Image::Box::set(), DD::Image::Op::setRequested(), DD::Image::IopInfoOwner::t(), DD::Image::Box::t(), DD::Image::Op::validate(), DD::Image::Box::w(), DD::Image::Op::warning(), DD::Image::IopInfoOwner::x(), DD::Image::Box::x(), DD::Image::IopInfoOwner::y(), and DD::Image::Box::y().

Referenced by _copyState(), DD::Image::DownRez::_request(), DD::Image::UpRez::_request(), DD::Image::NoIop::_request(), DD::Image::RenderScene::_request(), DD::Image::IllumShader::_request(), DD::Image::Write::_request(), DD::Image::Render::_request(), DD::Image::NukeWrapper::_request(), _request(), DD::Image::Scene::evaluate_lights(), request(), DD::Image::ToBuffer::to_buffer(), and DD::Image::Scene::validate().

void Iop::request ( ChannelMask  channels,
int  count 

Use this to request that you will be randomly-accessing the input image and don't really know the area needed yet.

The current version will request a rectangle of the size of the format, but it will be moved to contain the bounding box if possible. This seems to match what is expected from random access in most cases. If you know you need a larger area you can calculate it yourself and call the other version of request().

References DD::Image::Format::height(), DD::Image::IopInfoOwner::info_, DD::Image::IopInfoOwner::r(), DD::Image::Box::r(), DD::Image::Op::real_valid(), request(), DD::Image::IopInfoOwner::t(), DD::Image::Box::t(), DD::Image::Op::validate(), DD::Image::Format::width(), DD::Image::IopInfoOwner::x(), DD::Image::Box::x(), DD::Image::IopInfoOwner::y(), and DD::Image::Box::y().

void Iop::_copyState ( Iop input)
const Box & DD::Image::Iop::requestedBox ( ) const

The union of all the boxes passed to request(), intersected with the box from info(). This is the area that will be stored in a cache, also the engine() will never be called for data outside this box.

Referenced by DD::Image::GeneralTile::getRequestBox(), DD::Image::Interest::Interest(), DD::Image::GeneralTile::load_range(), and DD::Image::BufferIopTile::makeTile().

ChannelMask DD::Image::Iop::requested_channels ( ) const

The union of all channels passed to request() intersected with the channels reported in info(). These are the channels that will be stored in a cache.

Referenced by DD::Image::BufferIopTile::makeTile().

int DD::Image::Iop::requested_count ( ) const

The sum of all the count arguments passed to request().

void Iop::get ( int  y,
int  x,
int  r,
ChannelMask  channels,
Row row 

Fill the row with the output of the Iop. At least the range x through r of each of channels is set to the output of the operator.

WARNING: the other channels, and data outside x..r, may change!!! The implementation can change pointers to point at cached data, reuse the row to read input data, and the row may be reallocated to make it's space larger. Do not assume any data, or any pointers to data, is preserved or valid after calling this. THIS IS NOT A MERGE!!! If you wish to merge data you must use a second row and then copy the data yourself.

If possible, buffer pointers are changed to point at the cached data, so no copying is done. If this is not possible, writable() is called for each channel needed and the data is calculated and written to these locations (note that writable() will reuse any buffer already assigned there).

The region is clamped to the requested() box before being passed to the engine, and the pixels at the edges of this area are replicated to fill the rest of the region.

If aborted() is true this clears the row to zero and returns quickly.

References DD::Image::Op::aborted(), DD::Image::IopInfoOwner::black_outside(), cache(), cached(), DD::Image::IopInfoOwner::channels(), DD::Image::Op::Class(), DD::Image::ChannelSet::contains(), DD::Image::Row::erase(), DD::Image::IopInfoOwner::format(), get(), DD::Image::Row::holdsCacheLine(), DD::Image::IopInfoOwner::info_, input(), input0(), DD::Image::Format::name(), DD::Image::Row::offset(), out_channels(), DD::Image::Op::print_name(), DD::Image::IopInfoOwner::r(), DD::Image::Box::r(), DD::Image::Row::range(), DD::Image::Row::read(), DD::Image::Row::release(), DD::Image::Row::setCacheLine(), DD::Image::Op::slowness(), DD::Image::Box::t(), DD::Image::Row::writable(), DD::Image::IopInfoOwner::x(), DD::Image::Box::x(), DD::Image::IopInfoOwner::y(), and DD::Image::Box::y().

Referenced by DD::Image::PixelIop::engine(), DD::Image::NoIop::engine(), DD::Image::Write::engine(), DD::Image::NukeWrapper::engine(), DD::Image::Row::get(), get(), DD::Image::Write::inputnget(), and DD::Image::DrawIop::pixel_engine().

void Iop::at ( int  x,
int  y,
Pixel out 

Returns several channels of a pixel in the image. The channels to compute are specified in the Pixel object. Unrequested channels (including Chan_Black) are unchanged.

The x and y are clamped to the requested() area, and any channels not in requested_channels() will return zero.

It can be faster to create and reuse an Interest object for this, as that avoids the overhead of locking/unlocking the cache for each call.

It may be faster to use sample() as some operators, such as Transform, implement their own versions that back-translate the coordinates and call their input directly.

References DD::Image::Op::aborted(), at(), cache(), DD::Image::Box::clampx(), DD::Image::Box::clampy(), input(), out_channels(), DD::Image::IopInfoOwner::x(), and DD::Image::IopInfoOwner::y().

Referenced by at(), do_sample_shadowmap(), doSample(), DD::Image::LightOp::get_shadowing(), and DD::Image::Transform::sample().

float Iop::at ( int  x,
int  y,
Channel  channel 

Return a single channel of a pixel in the image.

The x and y are clamped to the requested() area, and any channels not in requested_channels() will return zero.

This is the slowest method of getting data from the image, but it is easy to call and does not require any range checks. For faster methods use get() to read an entire row, or use an Interest() for random access.

References DD::Image::Op::aborted(), at(), cache(), channel(), DD::Image::Box::clampx(), DD::Image::Box::clampy(), input(), out_channels(), and DD::Image::IopInfoOwner::y().

ChannelSet Iop::peek ( int  x,
int  y,
int  r,
int  t,
Pixel out 

Return the average of any cached pixels found in the specified rectangle. This is used by the viewer color-sampling code. The passed array is indexed by channel number and filled in with the values from the image. Unrequested channels are not changed.

If the operator has been executed recently this will return the average of any pixels that were produced by the last execution. If it has not been executed recently then older pixel values may still be located in memory and the average of these are returned. If it was never executed or the cache memory has been freed or the requested box does not intersect the cache memory then the output value is set to zero and the corresponding bit in the return value is turned off.

The return value is channels with any channels that had no pixels found turned off.

References cache(), input(), out_channels(), and peek().

Referenced by peek().

bool Iop::peek ( int  x,
int  y,
int  w,
int  h,
ChannelMask  pixelChannels,
PixelCallbackI callback 

For every pixel found in the specified rectangle call the given interface's process function. Return true of at least one pixel was given to the callback.

This is used by the viewer color-sampling code for more-expensive image pixels analysis such as

  • min color
  • max color
  • median
  • mode

References cache(), input(), out_channels(), and peek().

virtual Transform* DD::Image::Iop::getTransform ( )

If this image operation involves a transformation, return a pointer to the object that represents it.

This is used by transform nodes to enable transform concatenation so that e.g. scaling down and then up an image doesn't result in quality loss to aliasing artefacts and repeated application of filtered sampling.

If an Op doesn't generate or modify a transform, and it's safe to propagate the Op's input transform to the Op's output, then the Op should override getTransform() and pass the appropriate input transform.

For Ops with multiple inputs, this will depend on the use case. For example, if one input represents the image and another input represents some additional data (e.g. extra metadata) then you would pass the transform from the image input.

For Ops with single inputs, you could just call the getDefaultTransform() function.

Reimplemented in DD::Image::NoIop.

Referenced by getDefaultTransform(), and DD::Image::Transform::updateConcat().

bool Iop::set_texturemap ( ViewerContext ctx,
bool  gl = true 

Set the OpenGL current 2D texture map to draw a reduced-resolution version of this image. Returns false if the texture map cannot be created or is not yet available, in which case you should draw your OpenGL preview some other way, such as with solid colors.

The first time this is called this will probably return false. However this will signal Nuke to produce the down-rez image needed by the texture map using parallel threads. When this image is done, Nuke will redraw the viewer, and your drawing code can call this and it will get the texture map.

If gl is false, this tests for the existence and triggers the generation of the texturemap, but does not do any OpenGL calls. This can be used to test if the texture will work or to trigger the generation of the texture before it is actually needed.

To allow arbitrary bounding boxes and the output of Transform to be texturemapped, this function may mess with the OpenGL texture matrix. Be sure to reset this and disable texture mapping by calling unset_texturemap(). To reproduce the treatment of edge pixels by Iop, this will set GL_CLAMP_TO_BORDER (GL_CLAMP on Windows, unfortunately).

If DDImage is not linked with Nuke, this will return false always.

Reimplemented in DD::Image::Transform.

Referenced by DD::Image::Transform::build_handles(), DD::Image::Render::build_handles(), DD::Image::Transform::draw_handle(), and DD::Image::Transform::set_texturemap().

Iop::TextureImage Iop::get_texturemap ( ViewerContext ctx)

Retrieves the texture map created by set_texturemap. Returns nullptr if the texturemap is not yet available or if DDImage is not linked with Nuke.

See also
void Iop::unset_texturemap ( ViewerContext ctx)

Undo anything set_texturemap did. The default one turns off texturemapping and resets the texture matrix to the identity.

Reimplemented in DD::Image::IllumShader.

Referenced by DD::Image::Transform::draw_handle(), and DD::Image::IllumShader::unset_texturemap().

bool Iop::shade_GL ( ViewerContext ctx,
GeoInfo geo 

Shade the provided geometry object using this Iop as a material. Return false if it cannot correctly draw this object in OpenGL, in which case a solid-shaded version will be drawn.

This function is usually only overridden by the Material subclass, but it is a method on Iop so that an Iop can be used as a shader to texture-map it's image on the object.

The default version does:

if (set_texturemap(ctx)) {
return true;
} else {
return false;
See also
set_texturemap, vertex_shader, fragment_shader

Reimplemented in DD::Image::Material, DD::Image::Black, and DD::Image::IllumShader.

void Iop::vertex_shader ( VertexContext vtx)

Modify the vertex of any 3D geometry that this image is being applied as a shader to. This can change channels such as uv and xyz to achieve special effects like point displacement, uv projection, normal warping, etc. Or it can add extra channels to interpret by the fragment_shader.

This function is usually only overridden by the Material subclass, but it is a method on Iop so that an Iop can be used as a shader to texture-map it's image on the object. The default version does nothing.

See also
shade_GL, fragment_shader

Reimplemented in DD::Image::SolidShader, DD::Image::Material, and DD::Image::IllumShader.

References DD::Image::Box3::expand(), DD::Image::CameraOp::LENS_ORTHOGRAPHIC, DD::Image::Scene::lights, DD::Image::Matrix4::transform(), and DD::Image::VertexContext::vP.

Referenced by DD::Image::ParticlesSprite::tessellateSprite(), and DD::Image::IllumShader::vertex_shader().

void Iop::fragment_shader ( const VertexContext vtx,
Pixel out 

Change the value of the out Pixel as though the result of the surface shading.

This function is usually only overridden by the Material subclass, but it is a method on Iop so that an Iop can be used as a shader to texture-map its image on the object. The default version takes the UV, if any, scales it to the format, and calls sample(). If any lights exist in the scene, a default diffuse shading is applied.

See also
shade_GL, vertex_shader

Reimplemented in DD::Image::SolidShader, DD::Image::Material, and DD::Image::Black.

References DD::Image::VertexContext::blending_shader, DD::Image::VertexContext::sample(), and DD::Image::VertexContext::texture_sampling.

void Iop::displacement_shader ( const VertexContext vtx,
VArray out 

Do the displacement...

References DD::Image::VertexContext::vP.

float Iop::displacement_bound ( ) const
void Iop::blending_shader ( const Pixel in,
Pixel out 

Perform the composition of the surface sample over the background pixel. This function is called for every sample from the back to the front sample.

The default version implement the pre-multiplied alpha compositing (Pixel::over).

void Iop::sample ( float  cx,
float  cy,
float  w,
float  h,
Filter filter,
Pixel out 

Sample a rectangular area. Note that cx,cy is the center of the rectangle, not the corner.

Reimplemented in DD::Image::Transform.

Referenced by DD::Image::RenderScene::projection_matrix(), DD::Image::VertexContext::sample(), DD::Image::Transform::sample(), and sample().

void Iop::sample ( float  cx,
float  cy,
float  w,
float  h,
Pixel out 

Same except the filter argument is a default Cubic filter.

References sample().

void Iop::sample ( const Vector2 center,
const Vector2 dU,
const Vector2 dV,
Filter filter,
Pixel out 

Sample a parallelogram. It is centered on center and the length of the two axis are given by dU and dV. The channels requested by channels are put into out.

Note that the Transform subclass has its own implementation that skips any motion blur. This is so that the 3D renderer can add motionblur and it does not get doubled.

The default implementation turns the parallelogram into a rectangle of the same area and calls the rectangle sample() function.

Reimplemented in DD::Image::Transform.

References sample().

void Iop::sample ( const Vector2 center,
const Vector2 dU,
const Vector2 dV,
Pixel out 

Same except the filter argument is a default Cubic filter.

References sample().

Channel DD::Image::Iop::channel ( const char *  name)

Same as DD::Image::getChannel(), this method is provided for back-compatibility.

References DD::Image::getChannel().

Referenced by at(), DD::Image::Reader::channel(), and DD::Image::DrawIop::pixel_engine().

const char * DD::Image::Iop::channel_name ( Channel  c)

Same as DD::Image::getName(Channel), this method is provided for back-compatibility.

References DD::Image::getName().

Referenced by DD::Image::Reader::channel_name().

virtual void DD::Image::Iop::gpuEngine_useTextureTransform ( bool  useTransform)

GPU support code.

Interface to tell the op whether to transform texture coordinates if it happens to sample any textures in its fragment shader.

The base class implementation is empty, it's up to derived classes that might want to do this to provide an implementation appropriate to them (which may just mean setting some flag).

See also
virtual void DD::Image::Iop::gpuEngine_setupTextureTransform ( const Matrix4 postOpTransform)

Interface for setting up the optional texture coordinate transform. This provides a matrix that's assumed to contain the concatenation of any transforms that exist in the op tree after this op.

The base class implementation is empty, it's up to derived classes that might want to use texture coordinate transforms to provide an appropriate implementation.

See also
const char * Iop::gpuEngine_decl ( ) const

Return the declaration portion of the OpenGL implementation. Returning NULL is the same as empty string. When this string is used, the sequence "$$" is replaced by a prefix to de-clash the string against other instances of the same Op class (or instances of other classes that happen to use the same name for a uniform, etc).

The sequence $name$ is replaced with the value of the knob of that name (currently only single floating point values are supported, or $name.x$ for a single field of a multi-value knob).

const char * Iop::gpuEngine_body ( ) const

Return the body portion of the OpenGL implementation. This is a modified version of GLSL. Returning NULL means the Op has no GPU implementation and has to be run on the main processor. When this string is used, the sequence "$$" is replaced by a prefix to de-clash the string against other instances of the same Op class (or instances of other classes that happen to use the same name for a uniform, etc).

The sequence $name$ is replaced with the value of the knob of that name (currently only single floating point values are supported, or $name.x$ for a single field of a multi-value knob).

There are also two custom variables: IN and OUT. IN is a sampler containing the data computed in the main processor. OUT is the cumulative result of all GPU operations and the effective output of the Op (gl_FragColor will be overwritten). An example is "OUT = OUT * $gain$;".

Hash Iop::gpuEngine_shader_hash_at ( double  time)

Returns a hash dependent on the shader source code, for the specified time. Note that this is not necessarily a hash of the source code, the guarantee is merely that it varies deterministically as the source code varies. In practice, the shader source may depend on some of the Op's knobs, so the hash may just be of those knob values, evaluated at the specified time, and the function will not in general need to generate/know the full source.

The default implementation just returns a default constructed Hash object, sub-classes should override this appropriately.

Ideally, for performance reasons, the source shouldn't be time or even knob dependent and knob values should be handled with GL uniforms. However, there are situations where that's impractical and may even harm render performance merely to cater for knobs that in practice are rarely animated. Hence this function's support for time dependence.

For an example override see the Grade plugin code in the NDK examples.

int Iop::gpuEngine_getNumRequiredTexUnits ( ) const

This method returns the number of texture units that the iop requires for GPU processing. The base class version is zero; override if your op uses more. Note that not setting this value correctly can result in the GPU processing unexpectedly running out of texture units and causing rendering problems.

void Iop::gpuEngine_GL_begin ( GPUContext context)

Called before rendering this node when the gpuEngine_body() will be used. This can be used to bind textures, etc. If an error occurs in this method, it can throw an exception, which will be caught by the GPU setup code.

void Iop::gpuEngine_GL_end ( GPUContext context)

Called after rendering this node when the gpuEngine_body() will be used. This can be used to unbind textures, etc.

virtual Iop* DD::Image::Iop::viewerPassThrough ( ) const

override this to return input0() if you want your Iop to be disregarded when directly connected to a Viewer. The Viewer will follow the chain of Iops until it reaches one that returns NULL. For implementation by the DiskCache node etc.

Friends And Related Function Documentation

std::ostream& operator<< ( std::ostream &  ,
const Iop  

Not implemented in the library but you can define it

©2022 The Foundry Visionmongers, Ltd. All Rights Reserved.