Input Handling
==============

Constant Number of Inputs
-------------------------

Setting a constant number of inputs for your Op is pretty simple: just call **inputs(int i)** where i is the number of inputs you want your Op to have in its constructor. 
For example, Checkerboard2.cpp defines a zero input (that is, generator) behavior using:

.. code-block:: c

  CheckerBoard2(Node* node) : Iop(node)
  {
    inputs(0);
    //...
  }

Likewise, Keymix.cpp defines its 3 inputs using:

.. code-block:: c

  Keymix(Node* node) : Iop(node)
  {
    inputs(3);
    //...
  }

Depending on the client NUKE configuration, the first four inputs display as a splay across the top of the node, labeled according to their short names (see below). 
The remainder stack on the left hand side of the node. Clients can pull them out in turn incrementally, with their labels appearing as the respective inputs are 
picked up. Due to this, it's generally advisable to put commonly connected inputs on low indexes, and less frequently used inputs on incrementally greater indexes.

.. note::

  Bear in mind that different Op sub-classes define different default numbers of inputs (for example, Black defines 0, whilst Iop is 1). Some, such as the source type classes,
  may not expect any inputs to be defined at all, so if you're looking to have node inputs in such circumstances it's likely that you're picking the wrong base type
  for your operator.

Dynamic Number of Inputs
------------------------

Setting up optional, or dynamic, inputs requires a little more work, namely defining **minimum_inputs()** & **maximum_inputs()** on your Op to return the required numbers
respectively. Additionally, if there's circumstances under which the Op does not require one or more of the inputs, you need to define **uses_input(int i)** so that NUKE can optimize
the tree and draw the Node Graph (DAG) correctly.

Check out the AppendClip.cpp source included in the NDK as an example, the relevant parts of which are reproduced below:

.. code-block:: c

  class AppendClip : public Iop
  //...
  public:
  //...
    int minimum_inputs() const { return 1; }
    int maximum_inputs() const { return 10000; }
  //...
  };

  float AppendClip::uses_input(int i) const
  {
    if (i == input0 && weight0 > .01f)
      return weight0;
    if (i == input1 && weight1 > .01f)
      return weight1;
    return .01f;
  }

Check out the AppendClip Op inside of NUKE as well. As you can see, by default the node appears with a single input. Connecting that input results in additional inputs appearing
in the stack on the left hand side of the node. If you're a little masochistic, you can keep adding inputs to satisfy yourself that it does indeed top out at 10000, or you
can simply take our word for it.

The **uses_input** definition is interesting since it returns a float as opposed to the more to be expected bool. The float is used to govern the weight with which
the input highlighting is drawn when the Node Graph (DAG) is processing. Additionally, if the weight returned is zero, NUKE may optimize the Op hooked up to that input
out of the Node Graph, meaning the pointer to it may be null (or invalid). Treat with care!

.. note::

  As before, sensible ordering (and naming - see below) of inputs is very important. Common usage with low indexes, infrequent usage with high indexes.

Optional (Right Hand Side Mask) Inputs
--------------------------------------

In most circumstances, simply numbering the most commonly used inputs with a low index and increasing the index as frequency of use decreases is enough to imply which 
inputs are optional. It is also possible to create a stack of inputs on the right hand side of the node through the use of the **optional_input()** call. In nearly 
all circumstances, this right hand stack is a single input used as a mask, as provided by the mask functionality of the NukeWrapper. However, you can define this as you
desire should an alternative behavior be more appropriate. **optional_input** returns an index, and inputs between this returned index and the maximum number of inputs 
are drawn on the right hand side of the node.

.. note::

  The naming 'optional' can be a little misleading in this circumstance. If you want to define an input as 'required' then it may be sensible to report a warning error
  if the user has not connected sufficient inputs for the Op to do its thing.

Naming/Labelling Inputs
-----------------------

Inputs can be labeled by overriding **input_label(int i)** and returning a char* containing the label for the input indexed by i. The default implementation has a few tricks
up its sleeve - single inputs aren't labeled, two inputs are B for 0 and A for 1 (to match standard NUKE merge conventions) and numbers for beyond that. It's generally worth
following the merge B/A standard for Ops that bring in a range of channels in one way, shape, or form. If it allows more of an arbitrary 'mix', then the Shuffle/ShuffleCopy convention
of numbering is generally wise. In general, keeping the label to 1 to 3 characters is wise, particularly in the example of a large number of Op inputs, 
as the Node Graph can become very difficult to read otherwise. With a small number of inputs, you can generally get away with longer names without compromising readability. The below
snippet, taken from the UVProject.cpp example, shows an example of such longer naming:

.. code-block:: c

  const char* input_label(int input, char* buffer) const
  {
    switch (input) {
      case 0:
        return 0;
      case 1:
        return "axis/cam";
      default:
        return 0;
    }
  }


NUKE does provide an **input_longlabel** method. This is currently unused (in terms of being presented in the UI), but it is recommended that you implement this if you do **input_label**
for future compatibility.

Input Class Testing
-------------------

NUKE Ops can inherit from a variety of classes, and in many circumstances you only want certain types of Ops to be plugged into certain inputs. For example, a convolve would
have little use for a piece of 3D geometry on one of its inputs. By default, most base classes you inherit from set up what sort of operators can be plugged into them for you. 
For example, an image operator expects another image operator on its input for the most part, and a source geometry expects a texture map, rather than another geometry Op.

You can override this behavior by reimplementing **test_input(int input, Op* op)**, returning either true or false depending on whether such a connection should be allowed. An
excellent example of this included in the NDK is the UVProject.cpp source whose test_input is reproduced below:

.. code-block:: c

  bool test_input(int input, Op* op) const
  {
    if (input == 1)
      return dynamic_cast<AxisOp*>(op) != 0;
    return GeoOp::test_input(input, op);
  }

This basically checks the second input to see if it's got an Axis node somewhere in its inheritance tree, and if not, disallows connection. All other connections revert to using the 
default **GeoOp** provided **test_input**, which allows connection to 3D geometry as you might expect.

.. note::

  If you override **test_input**, you probably want to additionally override **default_input** as discussed below.

Default Inputs
--------------

Related to the concept of input class testing, setting the default input returned by the Op allows you to override what class is passed to a function when no operator is connected
on that input. This allows you to avoid the joy of testing for NULL's all over the place in your code, but can lead to confusion if you're expecting this behavior! If you're overriding
the **test_input** function to allow connection from other Op types, it's likely you want to override the **default_input** to return a lowest common denominator type Op of the type
you're expecting (or indeed NULL for that input if you're happy testing for this elsewhere in your Op). If you're looking to test for connection, you can also override this to return
NULL, but be aware you then have to test for NULL in all places you're expecting to access the input operator.

For example, the Phong.cpp sample overrides default_input in the following manner, to allow for NULL testing elsewhere in the operator:

.. code-block:: c

  Op* default_input(int input) const
  {
    if (input == 0)
      return Material::default_input(input);
    return 0;
  }

Subsequently, it uses tests similar to the following to figure out whether there's a connection. If the **default_input** hadn't been overriden, then testing for connection would have been a whole
lot more convoluted:

.. code-block:: c

  if (input(1) != 0 && input(0) == default_input(0))
    input1().shade_GL(ctx, geo);

In another example, the UVProject.cpp sample overrides **default_input** because the **test_input** has been overriden:

.. code-block:: c

  Op* default_input(int input) const
  {
    if (input == 1)
      return 0;
    return GeoOp::default_input(input);
  }

If it didn't, then the second input would appear under the hood to be connected to an operator type it theoretically shouldn't be connected to. Note that in this example, it does return 
NULL despite it not being strictly a case of the Op wanting to check for connection subsequently. If you check the rest of the sample, you'll see that in the **_validate** for example, it
tests for connection to a variety of Axis-derived connections to allow for different behaviors depending on this connection type. 
In most other circumstances, you want to return, for example, a **DD::Image::Op::Iop::default_input(input)** type instead (depending on whatever Op type you're allowing connection to).
