tv.amwa.maj.enumeration (Media Authoring with Java API)
Date: 2016-02-05

# Package tv.amwa.maj.enumeration

Defines Java enumerations representing the enumerations specified in the AAF object specification and other enumerations used across the MAJ API.

See: Description

- Enum Summary
  Enum | Description
  --- | ---
  AlphaTransparencyType | Specifies whether the minimum alpha value or the maximum alpha value represents transparency.
  AppendOption | Specifies whether a file writing operation should append to or overwrite existing data.
  AuxBitsModeType | Represents the 3 bit auxiliary bits mode of audio essence stored in the AES/EBU audio file format and described by a AES3 PCM descriptor.
  AVCCodedContentKind | Picture type and coding type, as used in AVC sub descriptors.
  Boolean | Representation of Boolean values as an enumeration, as per the AAF-defined representation.
  ByteOrder | Specifies the byte order of a file, such as an AAF file.
  ChannelStatusModeType | Specifies how channel status data is encoded as part of a AES3 PCM descriptor.
  ColorSitingType | Specifies color siting that indicates where colored pixels are located with respect to their associated luminance value.
  ColorSpace | Specifies a kind of color space, such as "RGB" or "YCrCb".
  CompressEnable | Specifies whether compression or decompression should be enabled for an operation on essence.
  ContentScanningType | For MPEG coded content, specifies if the scanning type of underlying coded content is known and, if it is, what kind of scanning type it is.
  CriteriaType | A criteria can be used to select media by the kind of representation for that media.
  DefinitionKind | Specifies the kind of a definition, such as Class, Property, Operation etc..
  Depend | Specifies whether metadata dependencies should be followed or not as part of a cloning operation.
  EdgeType | Specifies the kind of film edge code.
  EditHintType | Specifies hints to be used when editing control points.
  ElectroSpatialFormulation | Specifies electro-spatial formulation, a property used to describe sound essence.
  EmphasisType | Specifies the encoded audio signal pre-emphasis for sound data.
  EssenceType | Specifies the kind of essence data in terms of its relationship with time.
  FadeType | Specifies the kind of an audio fade.
  FieldNumber | Specifies the first or second field of an interlaced image.
  FileRev | Specifies the revision of a file.
  FilmType | Specifies the format of a film.
  IncludedMedia | Specifies whether media is included or not by an operation, such as a clone.
  LayoutType | Specifies whether all the data for a complete sample is in one frame or is split into more than one field.
  MaterialType | Identifies the material type of content according the the SMPTE UMID specification SMPTE S330M.
  MediaOpenMode | Specifies whether media should be opened for reading only or whether it could be appended to.
  OperationChoice | TODO this comment or remove?
  PackageKind | Specifies the kind of a package.
  ProductReleaseType | Specifies the release type of a product, for example released, debug alpha etc..
  PulldownDirectionType | Specifies whether a pulldown operation is converting from tape to film speed or from film to tape speed.
  PulldownKindType | Specifies whether a pulldown operation is converting from nominally 30 Hz or 25 Hz video frame rate and whether frames are dropped or the video is played at another speed.
  ReferenceType | Specifies the type of a reference.
  RGBAComponentKind | Specifies the color or function of a component within a pixel, for example whether the component a red level, palette index etc..
  ScanningDirectionType | Describes the scanning direction of an image.
  SignalStandardType | Specifies an underlying signal standard used to define the raster.
  TapeCaseType | Describes the physical size of a tape.
  TapeFormatType | Describes the format of the tape.
  TCSource | Specifies the kind of a timecode stream.
  TypeCategory | Specifies a categorisation of an AAF data type.
  UserDataModeType | Represents the kind of the 4 bits of channel status that is used for user data related to audio essence stored in the AES/EBU audio file format and described by a AES3 PCM descriptor.
  VideoSignalType | Specifies the type of video signal on a videotape.

## Package tv.amwa.maj.enumeration Description

Defines Java enumerations representing the enumerations specified in the AAF object specification and other enumerations used across the MAJ API. The enumerations in this package have a fixed number of defined elements, unlike extendible enumerations that can be extended at runtime.

## Enumeration kinds

Section 21.2 of the AAF object specification v1.1 specifies a number of enumeration data types. Enumerations are made up of a fixed set of elements with each element represented by a name and an ordinal value. All of these enumerations are represented in this package by a Java enumeration.

As Java enumerations do not have to have an ordinal value associated with them, the AAF-specified ordinal value is provided through the `MediaEnumerationValue` interface that is implemented by all enumerations. The ordinal value of an element can be retrieved using the `value()` method. Some of the enumerations also provide a static `fromOrdinal(int)` method that can be used to return an enumeration element from its specified ordinal value.

Other enumerations are defined for implementation-specific reasons, such as `ByteOrder`. In general, these enumerations provide a convenient way to configure features the API or refer to property values in a user-friendly way.

## Extendible enumeration

Extendible enumeration data types do not have a fixed set of specified elements, although a currently known set of built-in elements is provided in section 23.1 of the AAF object specification v1.1. An extendible enumeration element consists of a name and AUID unique identifier pair, suitable for the representation of reference data sets. The built-in elements are defined in the constant package using the extendible enumeration annotation. Additional elements can be registered with a JVM using the registration methods of the warehouse.

## Heritage

The original versions of the enumerations of this package were derived from the `enum` type definitions in the existing C-based AAF reference implementation, from file "`AAFTypes.h`". A typical source enum definition looks like the code below:

        typedef aafInt32 aafContentScanningType_t;
        typedef enum _aafContentScanningType_e
        {
            kAAFContentScanning_NotKnown = 0,
            kAAFContentScanning_Progressive = 1,
            kAAFContentScanning_Interlace = 2,
            kAAFContentScanning_Mixed = 3
        } aafContentScanningType_e;

The following steps have been taken to convert the C-based enum type definitions into Java enumerations, taking advantage of Java's class-based representation of enumerations wherever possible:

- The name of the enumeration has had "`aaf`" removed from its start and "`_e`" removed from the end. Where the enumeration is specified in the AAF object specification then the name has been matched to that. In the example above, the enumeration name becomes "`ContentScanningType`".
- The characters "`kAAF`" have been removed from the start of each element name.
- As the name of elements of Java enumerations are scoped by the enumeration they belong to and so do not require a globally unique name, any enumeration-specific label used for each element name has been removed. This should make code written to use the MAJ API easier to read. In the example above, the characters "`ContentScanning_`" have been removed from the element names, for example "`Progressive`" instead of "`ContentScanning_Progressive`".
- The constant ordinal value associated with each enumeration element has become a value passed the the private constructor for each enumeration element. It is then stored within the enumeration element ready to be retrieved with a call to the `value()` method.

The resulting underlying Java code for the content scanning type is:

        public enum ContentScanningType
            implements AAFEnumerationValue {

            NotKnown(0),
            Progressive(1),
            Interlace(2),
            Mixed(3);

            private int value;

            private ContentScanningType(
                    int value) {

                this.value = value;
            }

            @Int64 public long value() {

                return (long) value;
            }
        }

See Also:
  `TypeDefinitionEnumeration`, `TypeDefinitionExtendibleEnumeration`

(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.