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.

Classes
class	PixelCallbackI

struct	TextureImage

Public Member Functions
void	fetchPlane (ImagePlane &imagePlane)

virtual PlanarI *	getPlanarI ()

void	force_validate (bool for_real=true) override

IopImpl *	pImpl ()

virtual void	engine (int y, int x, int r, ChannelMask, Row &)=0

Iop *	iop () override
	Cast to an Iop. This is much cheaper and safer than using dynamic_cast.

const Iop *	iop () const override

virtual	~Iop ()

bool	test_input (int, Op *) const override

Op *	default_input (int) const override

Iop *	input (int n) const

Iop *	input (int n, int m) const

Iop &	input0 () const

Iop &	input1 () 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 Box &	requestedBox () const

const Box &	unclampedRequestedBox () 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 Transform *	getTransform ()

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 Iop *	viewerPassThrough () 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)

Op *	rootOp () const

bool	preValidateAborted (int treeStartingVersion, PrevalidateResult &result) const

const OutputSet &	getOutputs () 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::OutputContext >	getPrevVersionsWanted () const

virtual const MetaData::Bundle &	_fetchMetaData (const char *keyname)

const MetaData::Bundle &	fetchMetaData (const char *keyname)

Node *	node () const

DD::Image::NodeI *	getNode () const

void	node (Node *v)

Op *	firstOp () const

void	firstOp (Op *v)

Op *	parent () 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 ()

Knob *	knob (const char *name) const

Knob *	knob (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

Op *	node_input (int, GenerateType=OUTPUT_OP) const

Op *	node_input (int, GenerateType, const DD::Image::OutputContext *outputContext) const

Op *	input_op (int n=0) const

virtual void	inputs (int n)

Op *	input (int) const

int	inputNumber (int input, int offset) const

Op *	input (int input, int offset) const

Op *	input0 () const
	return the primary input More...

Op *	input1 () 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 OutputContext &	outputContext () 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 OutputContext &	inputContext (int n, int offset, OutputContext &) const

virtual const OutputContext *	inputUIContext (int n, OutputContext &) const

const Hash &	hash () 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::Knob *	getDopeItemKnob () 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 Executable *	executable ()

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 Format &	input_format () const

const OutputContext &	uiContext () 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.

OpTreeHandler *	getTreeHandler () const
	Returns the treeHandler for a given Op.

bool	hasError () const

bool	opOrChildHasError () const

const Op *	getErroredOp () 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.

OpMessageHandler &	getMsgHandler ()

const OpMessageHandler &	getMsgHandler () 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 GeoOp *	geoOp ()
	Cast to a GeoOp. This is much cheaper and safer than using dynamic_cast.

virtual const GeoOp *	geoOp () const

virtual ParticleOp *	particleOp ()
	Cast to a ParticleOp. This is much cheaper and safer than using dynamic_cast.

virtual const ParticleOp *	particleOp () const

virtual DeepOnlyOp *	deepOnlyOp ()
	Cast to a DeepOnlyOp. This is much cheaper and safer than using dynamic_cast.

virtual const DeepOnlyOp *	deepOnlyOp () 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)

Op *	get (const Description *description)

Public Member Functions inherited from DD::Image::IopInfoOwner
const Info &	info () 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 Format &	format () const

const Format &	full_size_format () const

int	ydirection () const

bool	black_outside () const

ChannelMask	channels () const

const GeneralInfo &	generalInfo () const

const Info2D &	info2D () 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 Iop *	default_input (const OutputContext &)

static Op *	default_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 Op *	create (Node node, const char name, Op *p_op)

static Op *	create (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 Op *	error_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 Description *	find_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)

Iop *	asIop (Op *op) const

Transform *	getDefaultTransform () 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.

Op *	create (Node node, const char name)

Op *	create (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_

Friends
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, eAllHandles }

enum	ViewableModes { eViewableMode2D, eViewableMode3D, eViewableMode3D_2DReference }

enum	GenerateType { OUTPUT_OP, ANY_CONTEXT, INPUT_OP, INPUT_OP_PEEK, EXECUTABLE, EXECUTABLE_SKIP, EXECUTABLE_INPUT, UICONTEXT_ONLY }

enum	NodeContext { eNodeGraph, eTimeline, eOpGraph }

enum	StatusFlags { StatusNone, StatusModal, StatusUseCallback }

enum	PopUpScheme { ePU_Never, ePU_Done, ePU_Once, ePU_Default, ePU_Always }
	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< Output >	OutputSet
	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::Bundle *	metaCache

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 )

protected

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 ( )

virtual

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 ( )

inlinevirtual

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 )

overridevirtual

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 )

overrideprotectedvirtual

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:

copy_info();
\\ sample modifications of data, see plugin source code for more:
info_.turn_on(Mask_RGB);
info_.merge(*(info_.format));

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) {
 set_out_channels(Mask_None);
} else {
 set_out_channels(Mask_All);
}

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
	)

protectedvirtual

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 ( )

overrideprotectedvirtual

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 ( )

overrideprotectedvirtual

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 )

protectedvirtual

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 )

protected

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
	)

protected

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);
info_ = input0().info();
channels = intersect(channels, info_.channels());
info_.channels(channels);
if (!channels) {
 info_.set(0,0,1,1);
 info_.ydirection_(0);
}

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::copy_info ( )

protected

Same as copy_info(0, Mask_All).

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

Referenced by DD::Image::NoIop::_validate(), DD::Image::RenderScene::_validate(), DD::Image::DrawIop::_validate(), DD::Image::Render::_validate(), _validate(), force_validate(), and merge_info().

void Iop::clear_info ( )

protected

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 = 0 )

protected

Same as mergeInfo(input, Mask_All). It assumes all channels are acceptable.

References DD::Image::IopInfo::accessPreference(), DD::Image::IopInfo::black_outside(), 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().

Referenced by DD::Image::RenderScene::_validate(), and _validate().

void Iop::merge_info	(	int	input,
		ChannelMask	channels
	)

protected

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 )

protected

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().

void DD::Image::Iop::set_out_channels ( ChannelMask mask )

inlineprotected

Same as set_out_channels() = mask.

Referenced by DD::Image::UpRez::_validate(), DD::Image::NoIop::_validate(), DD::Image::RenderScene::_validate(), DD::Image::DrawIop::_validate(), DD::Image::NukeWrapper::_validate(), and DD::Image::Render::_validate().

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

inlineprotected

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().

template<class TileType >

void Iop::doSample	(	float	cx,
		float	cy,
		float	w,
		float	h,
		Filter *	filter,
		Pixel &	out
	)

protected

helper function for Iop::sample

References DD::Image::Op::aborted(), DD::Image::Filter::Coefficients::array, at(), DD::Image::IopInfoOwner::black_outside(), DD::Image::Filter::Coefficients::count, DD::Image::Filter::Coefficients::delta, DD::Image::Filter::Coefficients::first, DD::Image::Filter::get(), and DD::Image::Filter::Coefficients::normalize.

template<class TileType >

float Iop::do_sample_shadowmap	(	Iop *	map,
		bool	map_is_one_over_z,
		float	cx,
		float	cy,
		float	W,
		float	H,
		Filter *	filter,
		float	Pz
	)

protected

helper function for Iop::do_sample_shadowmap

References DD::Image::Op::aborted(), DD::Image::Filter::Coefficients::array, at(), DD::Image::Filter::Coefficients::count, DD::Image::Filter::Coefficients::delta, fast_floor(), DD::Image::Filter::Coefficients::first, DD::Image::Filter::get(), DD::Image::Filter::Coefficients::normalize, DD::Image::IopInfoOwner::r(), DD::Image::IopInfoOwner::t(), DD::Image::IopInfoOwner::x(), and DD::Image::IopInfoOwner::y().

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

overridevirtual

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

overridevirtual

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 )

static

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 )

inlinestatic

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

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

Referenced by default_input().

Iop * DD::Image::Iop::input ( int n ) const

inline

Returns Op::input(n) cast to an Iop. If you override test_input() and allow non-Iop inputs, you should be careful when using this function.

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

Referenced by DD::Image::NukeWrapper::_open(), DD::Image::IllumShader::_request(), DD::Image::Write::_request(), DD::Image::NukeWrapper::_request(), _request(), DD::Image::IllumShader::_validate(), DD::Image::DrawIop::_validate(), DD::Image::Write::_validate(), DD::Image::NukeWrapper::_validate(), at(), copy_info(), DD::Image::Write::depth(), DD::Image::Write::execute(), get(), DD::Image::Material::get_geometry_hash(), DD::Image::Interest::inputIop(), DD::Image::Write::inputnget(), merge_info(), mergeFrameRange(), peek(), request(), DD::Image::Transform::setInputsValid(), and DD::Image::ToBuffer::to_buffer().

void Iop::input0 ( ) const

inline

Fast inline method of getting input(0). 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(0) can be null pointer, do not use this function!

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

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

Referenced by DD::Image::DownRez::_request(), DD::Image::UpRez::_request(), DD::Image::NoIop::_request(), DD::Image::RenderScene::_request(), DD::Image::Render::_request(), DD::Image::NukeWrapper::_request(), DD::Image::UpRez::_validate(), DD::Image::RenderScene::_validate(), DD::Image::DrawIop::_validate(), DD::Image::Transform::_validate(), DD::Image::NukeWrapper::_validate(), DD::Image::Render::_validate(), DD::Image::Render::build_handles(), DD::Image::Render::buildGeoInfoHandle(), DD::Image::Writer::channel_mask(), DD::Image::Write::channel_written_to(), copy_info(), DD::Image::Write::depth(), DD::Image::Render::draw_primitives(), DD::Image::PixelIop::engine(), DD::Image::NoIop::engine(), DD::Image::Material::engine(), DD::Image::NukeWrapper::engine(), DD::Image::Write::execute(), get(), DD::Image::Writer::input0(), DD::Image::IllumShader::shade_GL(), DD::Image::IllumShader::unset_texturemap(), DD::Image::Transform::updateConcat(), and DD::Image::IllumShader::vertex_shader().

void Iop::input1 ( ) const

inline

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

inline

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

inline

Returns the last value sent to cached(bool).

Referenced by get(), and request().

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

inline

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

virtual

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

inline

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

virtual

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 )

do not call this, it is part of Op::copyState()

References DD::Image::Box::r(), request(), DD::Image::Op::requested(), DD::Image::Box::t(), DD::Image::Box::x(), and DD::Image::Box::y().

Referenced by DD::Image::Op::copyState().

const Box & DD::Image::Iop::requestedBox ( ) const

inline

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

inline

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

inline

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

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

virtual

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 ( )

inlinevirtual

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`
	)

virtual

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 )

virtual

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: set_texturemap

void Iop::unset_texturemap ( ViewerContext * ctx )

virtual

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
	)

virtual

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)) {
 geo.draw_solid(ctx);
 unset_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 )

virtual

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
	)

virtual

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
	)

virtual

Do the displacement...

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

float Iop::displacement_bound ( ) const

virtual

Return the maximum displacement bound

Referenced by DD::Image::Scene::add_render_primitive(), DD::Image::rTriangle::add_to_displacement_render(), and DD::Image::Scene::validate().

void Iop::blending_shader	(	const Pixel &	in,
		Pixel &	out
	)

virtual

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
	)

virtual

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
	)

virtual

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 )

inlinestatic

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 )

inlinestatic

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 )

inlinevirtual

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: gpuEngine_setupTextureTransform

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

inlinevirtual

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: gpuEngine_useTextureTransform

const char * Iop::gpuEngine_decl ( ) const

virtual

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

virtual

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 )

virtual

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

virtual

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 )

virtual

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 )

virtual

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

inlinevirtual

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 &
	)

friend

Not implemented in the library but you can define it

Classes

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation