PDG_AttributeTypes.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.
 *
 * COMMENTS:
 */

#ifndef __PDG_ATTRIBUTE_TYPES_H__
#define __PDG_ATTRIBUTE_TYPES_H__

#include <SYS/SYS_Types.h>

/// Enumeration of possible attribute types
enum class PDG_AttributeType : int8
{
    /// Undefined or uninitialized attribute type
    eUndefined      = -1,

    /// An array of `int` values
    eIntegerArray   = 0,

    /// An array of `fpreal` values
    eFloatArray     = 1,

    /// An array of `UT_StringHolder` values
    eStringArray    = 2,

    /// An array of `PDG_File` values, e.g. File info structs
    eFileArray      = 3,

    /// A single, opaque PyObject
    ePythonObject   = 4,

    /// A single PDG_ApplicationShim::Geometry instance
    eGeometry       = 5,

    /// An array of `UT_OptionsHolder` values
    eDictArray      = 6,
};

/// Enumeration of extra attribute flags. Flags can be ORed together.
enum class PDG_AttributeFlag : uint16
{
    /// Covenience value, all flags off
    eNoFlags            = 0x0000,

    /// The attribute should not be copied onto downstream work items
    eNoCopyFlag         = 0x0001,

    /// The attribute's value should be exported to the job environment
    eEnvExportFlag      = 0x0002,

    /// The attribute is read-only and cannot be modified on this work item
    eReadOnlyFlag       = 0x0004,

    /// The attribute is for internal use, and will be accessed with other
    /// API methods. It should not be displayed in the UI
    eInternalFlag       = 0x0008,

    /// The attribute contains a operator path
    eOperatorFlag       = 0x0010,

    /// The attribute contains a path that should be transfered to
    /// remote machines when the work item cooks.
    eTransferFlag       = 0x0020,

    /// The attribute should be copied to internal dependent(s) within
    /// the node, before the dependent(s) cooks
    eDependentFlag      = 0x0040,

    /// The attribute should not cause the owner to be dirtied if it
    /// changes between cooks, e.g due to work item regeneration
    eNoDirtyFlag        = 0x0080,

    /// The attribute is not saved when the owner is serialized
    eTransientFlag      = 0x0100,

    /// The attribute is bound to a particular work item. This flag is
    /// only relevant for global/graph attributes
    eBoundFlag          = 0x0200,

    /// The attribute should be treated as an extra input. If the file
    /// changes on disk between cooks, the cache of the work items using
    /// the file is invalided.
    eInputFileFlag      = 0x0400,

    /// The attribute is a numeric value, but should be treated as a time
    /// stamp instead of a plain number when being displayed
    eTimestampFlag      = 0x0800,

    /// The attribute is a numeric value, but should be treated as a memory
    /// size instead of a plain number when being displayed
    eMemoryValueFlag    = 0x1000,

    //// Covenience value, the bitwise OR of all other  flags
    eAllFlags           = 0xFFFF
};

/// Enumeration of attribute cast results
enum class PDG_AttributeCast
{
    /// No cast error occured (success)
    eSuccess,

    /// Cast failed due to a missing/undefined attribute
    eErrorMissing,

    /// Cast failed due to a type mismatch (string vs. int)
    eErrorType,

    /// Cast failed due to an index being out of bounds
    eErrorBounds,

    /// Cast failed due to an invalid tag (applies to files only)
    eErrorTag,
};

/// Enumeration of possible errors that could occur when attempting to
/// to construct an attribute reference
enum class PDG_AttributeError
{
    /// No error was specified, i.e. the ref is valid
    eNone,

    /// An unspecified error occured - the ref is invalid
    eUnspecified,

    /// The requested attribute was not found - the ref is invalid
    eNotFound,

    /// The requested attribute was a readonly when attempting to create 
    /// a RW ref - the ref is invalid
    eReadOnly,

    /// The requested attribute is internal, and therefore cannot be
    /// removed by user code
    eInternal,

    /// The entire attribute map is read only
    eAttributesReadOnly,

    /// The requested attribute type did not match the attribute - the
    /// ref is invalid
    eTypeConflict,

    /// The requested attribute is static and was not upgraded to dynamic
    eTypeUpgrade,

    /// The requested attribute already exists, but the API call was 
    /// instruct to not overwrite existing values
    eOverwrite,

    /// The ref is uninitialized and needs to be created at a later point
    eUninitialized,

    /// The attribute doesn't support a flag that was passed to a SetFlag
    /// call
    eInvalidFlag,

    /// The attribute isn't an array type, but needs to be in order to 
    /// perform the specified operation
    eTypeArray,
};

/// Enumeration of different ways that attributes can be combined
enum class PDG_AttributeMergeOp
{
    /// The attribute should be excluded as it does not match any of
    /// the patterns in the map
    eIgnore,

    /// The attribute is flattened, i.e. the first value for the attrib
    /// is used an no other values are selected.
    eFirstValue,

    /// The attribute overwrites existing values, unless the destination
    /// has its own modications
    eLastValue,

    /// The unique values for the attribute are kept,
    eUniqueValues,

    /// The attribute values are concatenated together into an array
    eAppendArray,

    /// The minimum value is kept
    eMinimum,

    /// The maximum value is kept
    eMaximum,

    /// The sum of the values is kept
    eSum,

    /// The attribute values are averaged
    eAverage,

    /// The most common value is kept
    eMode,

    /// The middle value is kept
    eMedian,

    /// The values are kept in sorted order
    eSorted,

    /// The values are kept in sorted order, and made unique
    eSortedUnique,
};

/// Enumerations of errors that can occur when merging attributes
enum class PDG_AttributeMergeError
{
    /// No error occured
    eNone,

    /// Mismatch between types
    eType,

    /// Invalid merge operation for the attribute type
    eInvalidOp,

    /// Mismatch between stride lengths
    eStride,
};

/// Enumeration of types of attribute that can be queried from work items
enum class PDG_AttributeIntrinsic
{
    /// Index [numeric, string]
    eIndexAttrib,
    /// Frame [numeric, string]
    eFrameAttrib,
    /// Loop depth [numeric, string]
    eLoopDepthAttrib,
    /// Work item unique id [numeric, string]
    eIdAttrib,
    /// Input result list size [numeric, string]
    eInputSizeAttrib,
    // Output result list size [numeric, string]
    eOutputSizeAttrib,

    /// Name [string]
    eNameAttrib,
    /// Label [string]
    eLabelAttrib,
    /// Log path [string]
    eLogAttrib,

    /// Input result list [string]
    eInputAttrib,
    /// Input tag [string]
    eInputTagAttrib,

    /// Output result list [string]
    eOutputAttrib,
    /// Output tag [string]
    eOutputTagAttrib,

    /// Scheduler name [string]
    eSchedulerName,
    /// Node name [string]
    eNodeName,

    /// Custom attribute name [numeric, string]
    eCustomAttrib
};

/// Detrmines when to overwrite an attribute when requesting a writeable
/// reference to it.
enum class PDG_AttributeOverwrite
{
    /// Never overwrite the attribute
    eNever,

    /// Only overwrite the attribute if the type matches
    eMatch,

    /// Always overwrite the attribute. If the attribute exists with 
    /// different type, it will be removed and replaced with a new
    /// attribute of the requested type.
    eAlways
};

/// Enumeration of the different ways that attributes can be saved
enum class PDG_AttributeSaveType
{
    /// Flatten attributes, saving both dynamic and static as a mix
    eFlatten,

    /// Save only static
    eStatic,

    /// Save only dynamic
    eDynamic,

    /// Save all attributes, including ones from the parent map that
    /// are not directly owned by this map
    eAll,
};

/// Enumeration of merge strategies for handling collisions when
/// deserializing attributes into a map with existing attributes
enum class PDG_AttributeCollision
{
    /// The existing attribute is kept and the deserialized attribute is
    /// discarded
    eKeep,

    /// The existing attribute is replaced with the deserialized attribute
    eReplace,

    /// Deserialization fails when an existing attribute is found with the
    /// same name as the one being deserialized
    eError
};

/// Enumeration of attribute copy operations
enum class PDG_AttributeCopyOp
{
    /// Only copy if the existing attribute does not exist
    eNew,

    /// Overwrites the attribute even if the type is different, destroying
    /// the original data in the process
    eOverwriteType,

    /// Overwrite the existing attribute if the type matches
    eOverwrite,

    /// Append to the existing attribute if it exists and matches
    eAppend,

    /// Prepend to the existing attribute if it exists and matches
    ePrepend,

    /// Update the values in place, and leave any extra array values beyond
    /// the incoming range as-is
    eUpdate,
};

/// Enumeration of error levels when interacting with the attribute API. This
/// exists a convenience for custom nodes, the Python API, etc and is not used
/// internally by any of the attribute code.
///
/// Specifies how an error should be reported to users when interacting with
/// an attribute API method.
enum class PDG_AttributeErrorLevel
{
    /// Nothing is reported to the user
    eQuiet,

    /// A warning is reported to the user
    eWarning,

    /// An error is reported to the user
    eError
};

#endif /* __PDG_ATTRIBUTE_TYPES_H__ */