COP_Signature.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 */

#pragma once

#include "COP_API.h"

#include <OP/OP_DataTypes.h>
#include <UT/UT_Array.h>
#include <UT/UT_StringHolder.h>

/// Types of basic data that are passed around a COP network.
typedef enum {
    COP_TYPE_UNDEF      = 0,
    COP_TYPE_METADATA,
    COP_TYPE_INT,
    COP_TYPE_FLOAT,
    COP_TYPE_VECTOR2,
    COP_TYPE_VECTOR,
    COP_TYPE_VECTOR4,
    COP_TYPE_GEO,
    COP_TYPE_VDB_METADATA,
    COP_TYPE_VDB_INT,
    COP_TYPE_VDB_FLOAT,
    COP_TYPE_VDB_VECTOR,
    COP_TYPE_ATTRIB_METADATA,
    COP_TYPE_ATTRIB_INT,
    COP_TYPE_ATTRIB_FLOAT,
    COP_TYPE_ATTRIB_VECTOR2,
    COP_TYPE_ATTRIB_VECTOR,
    COP_TYPE_ATTRIB_VECTOR4,

    // This is not a true type of data, but represents a collection of plain
    // types from above.
    COP_TYPE_CABLE
} COP_Type;

/// Returns true if src is implicitly convertible to dst.
COP_API bool COPtypeIsConvertible(COP_Type src, COP_Type dst);
/// Returns true if src is implicitly convertible to dst in Apex,
/// where layers and vdbs are indistinguishable for callbacks..
COP_API bool COPtypeIsApexConvertible(COP_Type src, COP_Type dst);
/// Returns the English label for a type.
COP_API const char *COPtypeLabel(COP_Type t);
/// Returns a type corresponding to the given English label.
COP_API COP_Type COPtypeFromLabel(const char* label);
/// Returns the number of channels for a type.
COP_API inline int COPtypeChannels(const COP_Type t)
{
    switch (t)
    {
        case COP_TYPE_INT:
        case COP_TYPE_FLOAT:
        case COP_TYPE_VDB_FLOAT:
        case COP_TYPE_VDB_INT:
        case COP_TYPE_ATTRIB_FLOAT:
        case COP_TYPE_ATTRIB_INT:
           return 1;
        case COP_TYPE_VECTOR2:
        case COP_TYPE_ATTRIB_VECTOR2:
            return 2;
        case COP_TYPE_VDB_VECTOR:
        case COP_TYPE_VECTOR: 
        case COP_TYPE_ATTRIB_VECTOR: 
            return 3;
        case COP_TYPE_VECTOR4:
        case COP_TYPE_ATTRIB_VECTOR4:
            return 4;
        case COP_TYPE_METADATA:
        case COP_TYPE_ATTRIB_METADATA:
        case COP_TYPE_VDB_METADATA:
        case COP_TYPE_UNDEF:
        case COP_TYPE_GEO:
           return 1;
        case COP_TYPE_CABLE:
           return 0;
    }
    UT_ASSERT(!"Unhandled cop type");
    return 1;
}
/// Returns true if this is a layer type
COP_API bool COPtypeIsLayer(COP_Type t);
COP_API bool COPtypeIsLayerOrUndef(COP_Type t);
COP_API bool COPtypeIsGeo(COP_Type t);
COP_API bool COPtypeIsVDB(COP_Type t);
COP_API bool COPtypeIsAttribute(COP_Type t);

class COP_CableStructure;
class COP_PortData;
class IMX_Layer;
class IMX_VDB;
class IMX_Attribute;

/// Type of data that was output by a COP_Verb
COP_API COP_Type COPtype(const COP_PortData&, int index = 0);
/// Type of data for the given layer
COP_API COP_Type COPtype(const IMX_Layer&);
/// Type of data for the given vdb
COP_API COP_Type COPtype(const IMX_VDB&);
/// Type of data for the given attrib
COP_API COP_Type COPtype(const IMX_Attribute&);

/// Signature for a node.
/// Signature consists of a name (internal and label), and lists of types for
/// the inputs and outputs.
class COP_API COP_Signature
{
public:
    /// same as COP_Signature("default", "Default")
    COP_Signature() : COP_Signature("default", "Default") {}
    /// Constructs a new signature with the given name and label.
    COP_Signature(const UT_StringHolder &name, const UT_StringHolder &label);
    /// Constructs a new signature with the given name, label, and number of
    /// inputs and outputs.
    COP_Signature(const UT_StringHolder &name, const UT_StringHolder &label,
                  int inputs, int outputs);
    /// Constructs a new signature with the given name, label, and lists of
    /// inputs and outputs. A character in a list corresponds to an input or
    /// output. Its type can be one of the following:
    ///     i:      COP_TYPE_INT
    ///     m:      COP_TYPE_METADATA
    ///     f:      COP_TYPE_FLOAT
    ///     u:      COP_TYPE_VECTOR2
    ///     v:      COP_TYPE_VECTOR
    ///     p:      COP_TYPE_VECTOR4
    ///     g:      COP_TYPE_GEO
    ///     I:      COP_TYPE_VDB_INT
    ///     F:      COP_TYPE_VDB_FLOAT
    ///     V:      COP_TYPE_VDB_VECTOR
    ///     C:      COP_TYPE_CABLE
    /// If a type is succeeded by the ! symbol, then it's marked as null (or not
    /// connected).
    /// If a type is preceeded by 1,2,3 it specifies the dimension,
    ///     1: IMX_Attribute: COP_TYPE_ATTRIB_
    ///     2: IMX_Layer: COP_TYPE_
    ///     3: IMX_VDB: COP_TYPE_VDB_
    /// The next symbol should be ifuvp to specify the type.
    COP_Signature(const UT_StringHolder &name, const UT_StringHolder &label,
                  const UT_StringRef &input_list,
                  const UT_StringRef &output_list);
    /// Constructs a signature given lists of types and null states for inputs
    /// and outputs.
    COP_Signature(const UT_StringHolder &name, const UT_StringHolder &label,
                  const UT_Array<COP_Type> &input_types,
                  const UT_Array<bool> &input_null_states,
                  const UT_Array<COP_Type> &output_types,
                  const UT_Array<bool> &output_null_states);

    /// Returns the cost of converting all inputs of this signature into types
    /// from the array.
    /// If abort_on_impossible is true, returns -1 if one of the inputs is not
    /// convertible.
    int getInputConversionCost(const UT_Array<COP_Type> &inputs,
                               bool abort_on_impossible = false) const;

    /// Sets the number of inputs for this signature. If the current size
    /// is not zero, the last entry is duplicated to fill array.
    void setNumberOfInputs(int inputs);
    /// Sets the number of outputs for this signature. If the current size
    /// is not zero, the last entry is duplicated to fill array.
    void setNumberOfOutputs(int outputs);
    /// Sets the type of an input. If null state of the input is not provided,
    /// it will stay unchanged from the previous setting.
    void setInput(OP_InputIdx input, COP_Type type);
    void setInput(OP_InputIdx input, COP_Type type, bool is_null);
    /// Sets the type of an output. If null state of the output is not provided,
    /// it will stay unchanged from the previous setting.
    void setOutput(OP_OutputIdx output, COP_Type type);
    void setOutput(OP_OutputIdx output, COP_Type type, bool is_null);
    /// Sets the connected state of an input.
    void setInputIsNull(OP_InputIdx input, bool is_null);
    /// Sets the connected state of an output.
    void setOutputIsNull(OP_OutputIdx output, bool is_null);

    /// Returns the number of inputs.
    int getNumberOfInputs() const;
    /// Returns the number of outputs.
    int getNumberOfOutputs() const;
    /// Get type of the input at the specified index.
    COP_Type getInputType(OP_InputIdx index) const;
    /// Get type of the output at the specified index.
    COP_Type getOutputType(OP_OutputIdx index) const;
    /// Get whether the input at the specified index is connected.
    bool isInputNull(OP_InputIdx index) const;
    /// Get whether the output at the specified index is connected.
    bool isOutputNull(OP_OutputIdx index) const;

    /// Returns true if inputs of this signature (starting at i_start) are
    /// convertible from its outputs (starting at o_start).
    bool inputsMatchOutputs(OP_InputIdx i_start = 0, OP_OutputIdx o_start = 0)
        const;
    /// Returns true if inputs of this signature (starting at i_start) are
    /// convertible from outputs of the other signature (starting at o_start).
    /// That is, false is returned if other.outputType(k) is not convertible
    /// into inputType(k-o_start+i_start) for some k. Only checks valid input
    /// and output indices.
    bool inputsMatchOutputs(const COP_Signature& other, OP_InputIdx i_start = 0,
                            OP_OutputIdx o_start = 0) const;

    /// Returns true if this signature has an input that is of cable type.
    bool hasCableInput() const;
    /// Returns true if this signature has an output that is of cable type.
    bool hasCableOutput() const;

    /// Makes a list of cable structures for the inputs. Each cable stucture
    /// has a single field that's the same type as the corresponding input on
    /// this signature.
    UT_Array<COP_CableStructure> makeInputCableStructures() const;

    /// Returns the internal name of this signature.
    const UT_StringHolder &getName() const { return myName; }
    /// Returns the English label for this signature.
    const UT_StringHolder &getLabel() const { return myLabel; }
    /// Changes name of this signature.
    void setName(const UT_StringHolder& name) { myName = name; }
    /// Changes label for this signature.
    void setLabel(const UT_StringHolder& label) { myLabel = label; }

    /// Removes the input at the given index.
    void removeInput(OP_InputIdx index);
    /// Removes the output at the given index.
    void removeOutput(OP_OutputIdx index);

    UT_StringHolder format() const;
    /// Returns the format string for encoding all inputs (including their null
    /// states).
    UT_StringHolder getInputFormat() const;
    /// Returns the format string for encoding all outputs (including their null
    /// states).
    UT_StringHolder getOutputFormat() const;

    /// Two signatures are equivalent if all input and output states match
    /// exactly.
    bool operator==(const COP_Signature& other) const;
    
    /// Returns the array of input null states.
    const UT_Array<bool>& getInputNullStates() const
    {
        return myInputIsNull;
    }
    /// Returns the array of output null states.
    const UT_Array<bool>& getOutputNullStates() const
    {
        return myOutputIsNull;
    }
    /// Returns the array of this signature's input types.
    const UT_Array<COP_Type>& getInputTypes() const
    {
        return myInputTypes;
    }
    /// Returns the array of this signature's output types.
    const UT_Array<COP_Type>& getOutputTypes() const
    {
        return myOutputTypes;
    }

protected:
    /// List of input types for this signature.
    UT_Array<COP_Type>          myInputTypes;
    /// List of output types for this signature.
    UT_Array<COP_Type>          myOutputTypes;
    /// Flag for each input indicating whether it's null (unconnected).
    UT_Array<bool>              myInputIsNull;
    /// Flag for each output indicating whether it's null (unconnected).
    UT_Array<bool>              myOutputIsNull;
    /// The signature's internal name.
    UT_StringHolder             myName;
    /// The signature's label.
    UT_StringHolder             myLabel;

    friend class                COP_OperatorInfo;
};

COP_API size_t
UTformatBuffer(char *buffer, size_t buffer_size,
               const UT_Array<COP_Signature> &v);
COP_API size_t
UTformatBuffer(char *buffer, size_t buffer_size, const COP_Signature &v);
COP_API size_t
UTformatBuffer(char *buffer, size_t buffer_size, const COP_Type &v);