CDCIDescriptor (Media Authoring with Java API)
Date: 2016-02-05

tv.amwa.maj.model

## Interface CDCIDescriptor

- All Superinterfaces:
    AAFFileDescriptor, EssenceDescriptor, InterchangeObject, MediaEntity, MetadataObject, PictureDescriptor
  All Known Subinterfaces:
    CDCIDescriptor, MPEGVideoDescriptor
  All Known Implementing Classes:
    CDCIDescriptorImpl, MPEGVideoDescriptorImpl

      public interface CDCIDescriptor
      extends PictureDescriptor

  Specifies the description of a file of video essence formatted with one luminance component and two color-difference components, as specified according to the AAF object specification v1.1. This format is also known as "YCbCr".

  Note that the default values for the optional white reference level and color range properties depend on the required component width property. Therefore, the default values of these properties should be computed at runtime.

  See Also:
    `CodecConstant.CDCI`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `ALPHASAMPLEDEPTH_DEFAULT` Default value for the alpha sample depth property, which is 0.
    `static int` | `BLACKREFLEVEL_DEFAULT` Default value for the black reference level property which is 0.
    `static ColorSitingType` | `COLORSITING_DEFAULT` Default value for the color siting property, which is `ColorSitingType.CoSiting`.
    `static short` | `PADDINGBITS_DEFAULT` Default value for the padding bits property, which is 0.
    `static boolean` | `REVERSEDBYTEORDER_DEFAULT` Default value for the reversed byte order property, which is `false`.
    `static int` | `VERTICALSUBSAMPLING_DEFAULT` Default value for the vertical subsampling property, which is 1.

    - ### Fields inherited from interface tv.amwa.maj.model.PictureDescriptor

      `ALPHATRANSPARENCY_DEFAULT, DISPLAYF2OFFSET_DEFAULT, IMAGEALIGNMENTFACTOR_DEFAULT, IMAGEENDOFFSET_DEFAULT, IMAGESTARTOFFSET_DEFAULT, STOREDF2OFFSET_DEFAULT, Uncompressed`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `CDCIDescriptor` | `clone()` Create a cloned copy of this CDCI descriptor.
    `int` | `getAlphaSampleDepth()` Returns the alpha sample depth property of the CDCI descriptor, which specifies the number of bits used to store the alpha component.
    `int` | `getBlackRefLevel()` Returns the black reference level property for this CDCI descriptor, which specifies the digital luminance component value associated with black.
    `int` | `getColorRange()` Returns the color range property for this CDCI descriptor, which specifies the range of allowable digital chrominance component values.
    `ColorSitingType` | `getColorSiting()` Returns the color siting property of the CDCI descriptor, which specifies how to compute subsampled chrominance values.
    `int` | `getComponentDepth()` Returns the component width property of this CDCI descriptor, which specifies the number of bits used to store each component.
    `int` | `getHorizontalSubsampling()` Returns the horizontal subsampling property for this CDCI descriptor, which specifies the ratio of luminance sampling to chrominance sampling in the horizontal direction.
    `short` | `getPaddingBits()` Returns the padding bits property of the CDCI descriptor, which specifies the number of bits padded to each pixel.
    `boolean` | `getReversedByteOrder()` Sets the reversed byte order property of the CDCI descriptor, which specifies whether the luma and chroma sample order is reversed relative to the order defined by ITU-R BT.601.
    `int` | `getVerticalSubsampling()` Returns the vertical subsampling property of the CDCI descriptor, which specifies the ratio of luminance sampling to chrominance sampling in the vertical direction.
    `int` | `getWhiteRefLevel()` Sets the white reference level property of this CDCI descriptor, which specifies the digital luminance component component value associated with white.
    `void` | `setAlphaSampleDepth(Integer alphaSampleDepth)` Sets the alpha sample depth property of the CDCI descriptor, which specifies the number of bits used to store the alpha component.
    `void` | `setBlackRefLevel(Integer blackRefLevel)` Sets the black reference level property for this CDCI descriptor, which specifies the digital luminance component value associated with black.
    `void` | `setColorRange(Integer colorRange)` Sets the color range property for this CDCI descriptor, which specifies the range of allowable digital chrominance component values.
    `void` | `setColorSiting(ColorSitingType colorSiting)` Sets the color siting property of the CDCI descriptor, which specifies how to compute subsampled chrominance values.
    `void` | `setComponentDepth(int componentDepth)` Sets the component depth property of this CDCI descriptor, which specifies the number of bits used to store each component.
    `void` | `setHorizontalSubsampling(int horizontalSubsampling)` Sets the horizontal subsampling property for this CDCI descriptor, which specifies the ratio of luminance sampling to chrominance sampling in the horizontal direction.
    `void` | `setPaddingBits(Short paddingBits)` Sets the padding bits property of this CDCI descriptor, which specifies the number of bits padded to each pixel.
    `void` | `setReversedByteOrder(Boolean reversedByteOrder)` Sets the reversed byte order property of the CDCI descriptor, which specifies whether the luma and chroma sample order is reversed relative to the order defined by ITU-R BT.601.
    `void` | `setVerticalSubsampling(Integer verticalSubsampling)` Sets the vertical subsampling property of the CDCI descriptor, which specifies the ratio of luminance sampling to chrominance sampling in the vertical direction.
    `void` | `setWhiteRefLevel(Integer whiteRefLevel)` Sets the white reference level property of this CDCI descriptor, which specifies the digital luminance component component value associated with white.

    - ### Methods inherited from interface tv.amwa.maj.model.PictureDescriptor

      `areDisplayValuesPresent, areSampledValuesPresent, getActiveFormatDescriptor, getAlphaTransparency, getCodingEquations, getColorPrimaries, getDisplayF2Offset, getDisplayHeight, getDisplayView, getDisplayWidth, getDisplayXOffset, getDisplayYOffset, getFieldDominance, getFrameLayout, getImageAlignmentFactor, getImageAspectRatio, getImageEndOffset, getImageStartOffset, getPictureCompression, getSampledHeight, getSampledView, getSampledWidth, getSampledXOffset, getSampledYOffset, getSignalStandard, getStoredF2Offset, getStoredHeight, getStoredView, getStoredWidth, getTransferCharacteristic, getVideoLineMap, getVideoLineMapSize, setActiveFormatDescriptor, setAlphaTransparency, setCodingEquations, setColorPrimaries, setDisplayF2Offset, setDisplayView, setFieldDominance, setFrameLayout, setImageAlignmentFactor, setImageAspectRatio, setImageEndOffset, setImageStartOffset, setPictureCompression, setSampledView, setSignalStandard, setStoredF2Offset, setStoredView, setTransferCharacteristic, setVideoLineMap`

    - ### Methods inherited from interface tv.amwa.maj.model.AAFFileDescriptor

      `getCodec, getContainerFormat, getEssenceLength, getLinkedTrackID, getSampleRate, setCodec, setContainerFormat, setEssenceLength, setLinkedTrackID, setSampleRate`

    - ### Methods inherited from interface tv.amwa.maj.model.EssenceDescriptor

      `appendLocator, appendSubDescriptor, clearLocators, countLocators, countSubDescriptors, getLocatorAt, getLocators, getSubDescriptorAt, getSubDescriptors, insertLocatorAt, insertSubDescriptorAt, prependLocator, prependSubDescriptor, removeLocatorAt, removeSubDescriptorAt`

    - ### Methods inherited from interface tv.amwa.maj.model.InterchangeObject

      `addApplicationPlugin, clearApplicationPlugins, containsApplicationPlugin, containsApplicationPlugin, countApplicationPlugins, deepEquals, disableGenerationTracking, enableGenerationTracking, equals, getApplicationPlugins, getGeneration, getLinkedGenerationID, getObjectClass, isGenerationTracked, removeApplicationPlugin, removeApplicationPlugin, setLinkedGenerationID, setObjectClass, toString`

    - ### Methods inherited from interface tv.amwa.maj.industry.MediaEntity

      `getPersistentID, setPersistentIndex`

- - ### Field Detail

    - #### VERTICALSUBSAMPLING_DEFAULT

          static final int VERTICALSUBSAMPLING_DEFAULT

      Default value for the vertical subsampling property, which is 1.

      See Also:
        `getVerticalSubsampling()`, `setVerticalSubsampling(Integer)`, Constant Field Values

    - #### ALPHASAMPLEDEPTH_DEFAULT

          static final int ALPHASAMPLEDEPTH_DEFAULT

      Default value for the alpha sample depth property, which is 0.

      See Also:
        `getAlphaSampleDepth()`, `setAlphaSampleDepth(Integer)`, Constant Field Values

    - #### PADDINGBITS_DEFAULT

          static final short PADDINGBITS_DEFAULT

      Default value for the padding bits property, which is 0.

      See Also:
        `getPaddingBits()`, `setPaddingBits(Short)`, Constant Field Values

    - #### COLORSITING_DEFAULT

          static final ColorSitingType COLORSITING_DEFAULT

      Default value for the color siting property, which is `ColorSitingType.CoSiting`.

      See Also:
        `getColorSiting()`, `setColorSiting(ColorSitingType)`

    - #### BLACKREFLEVEL_DEFAULT

          static final int BLACKREFLEVEL_DEFAULT

      Default value for the black reference level property which is 0.

      See Also:
        `getBlackRefLevel()`, `setBlackRefLevel(Integer)`, Constant Field Values

    - #### REVERSEDBYTEORDER_DEFAULT

          static final boolean REVERSEDBYTEORDER_DEFAULT

      Default value for the reversed byte order property, which is `false`.

      See Also:
        `getReversedByteOrder()`, `setReversedByteOrder(Boolean)`, Constant Field Values

  - ### Method Detail

    - #### setComponentDepth

          void setComponentDepth(@UInt32
                                 int componentDepth)
                          throws IllegalArgumentException

      Sets the component depth property of this CDCI descriptor, which specifies the number of bits used to store each component. Typical values can be 8, 10, 12, 14, or 16, but others are permitted by the MAJ API implementation. Each component in a sample is packed contiguously; the sample is filled with the number of bits specified by the optional padding bits property. If the padding bits property is omitted, samples are packed contiguously.

      Parameters:
        `componentDepth` - Component width for the CDCI descriptor.
      Throws:
        `IllegalArgumentException` - The given component width is negative.
      See Also:
        `getPaddingBits()`

    - #### getComponentDepth

          @UInt32
          int getComponentDepth()

      Returns the component width property of this CDCI descriptor, which specifies the number of bits used to store each component. Typical values can be 8, 10, 12, 14, or 16, but others are permitted by the MAJ API implementation. Each component in a sample is packed contiguously; the sample is filled with the number of bits specified by the optional padding bits property. If the padding bits property is omitted, samples are packed contiguously.

      Returns:
        Component width for the CDCI descriptor.
      See Also:
        `getPaddingBits()`

    - #### setHorizontalSubsampling

          void setHorizontalSubsampling(@UInt32
                                        int horizontalSubsampling)

      Sets the horizontal subsampling property for this CDCI descriptor, which specifies the ratio of luminance sampling to chrominance sampling in the horizontal direction.

      For 4:2:2 video, the value is 2, which means that there are twice as many luminance values as there are color-difference values. Another typical value is 1; however other values are permitted by the MAJ API implementation.

      Parameters:
        `horizontalSubsampling` - Horizontal subsampling of the CDCI descriptor.

    - #### getHorizontalSubsampling

          @UInt32
          int getHorizontalSubsampling()

      Returns the horizontal subsampling property for this CDCI descriptor, which specifies the ratio of luminance sampling to chrominance sampling in the horizontal direction.

      For 4:2:2 video, the value is 2, which means that there are twice as many luminance values as there are color-difference values. Another typical value is 1; however other values are permitted by the MAJ API implementation.

      Returns:
        Horizontal subsampling of the CDCI descriptor.

    - #### setVerticalSubsampling

          void setVerticalSubsampling(@UInt32
                                      Integer verticalSubsampling)
                               throws IllegalArgumentException

      Sets the vertical subsampling property of the CDCI descriptor, which specifies the ratio of luminance sampling to chrominance sampling in the vertical direction.

      For 4:2:2 video, the value is 2, which means that there are twice as many luminance values as there are color-difference values. Another typical value is 1; however other values are permitted by the MAJ API implementation.

      To omit this optional property, call ths method with `null`.

      Parameters:
        `verticalSubsampling` - Vertical subsampling of the CDCI descriptor.
      Throws:
        `IllegalArgumentException` - The given vertical subsampling property is negative.
      See Also:
        `VERTICALSUBSAMPLING_DEFAULT`

    - #### getVerticalSubsampling

          @UInt32
          int getVerticalSubsampling()

      Returns the vertical subsampling property of the CDCI descriptor, which specifies the ratio of luminance sampling to chrominance sampling in the vertical direction.

      For 4:2:2 video, the value is 2, which means that there are twice as many luminance values as there are color-difference values. Another typical value is 1; however other values are permitted by the MAJ API implementation.

      The default value of this optional property will be returned if it is not present.

      Returns:
        Vertical subsampling of the CDCI descriptor.
      See Also:
        `VERTICALSUBSAMPLING_DEFAULT`

    - #### setColorSiting

          void setColorSiting(ColorSitingType colorSiting)

      Sets the color siting property of the CDCI descriptor, which specifies how to compute subsampled chrominance values.

      Valid values are:

      - `ColorSitingType.CoSiting` - To calculate subsampled pixels, take the preceding's pixels color value, discard the other color values and cosite the color with the first luminance value.
      - `ColorSitingType.Averaging` - To calculate subsampled pixels, take the average of the two adjacent pixels' color values and site the color in the center of the luminance pixels.
      - `ColorSitingType.ThreeTap` - To calculate subsampled pixels, take 25 percent of the the previous pixel's color value, 50 percent of the first value and 25 percent of the second value. For the first value in a row, use 75 percent of that value since there is no previous value. The `ThreeTap` value is only meaningful when the horizontal subsampling property has a value of 2.

      The color siting property is optional and has a default value of `ColorSitingType.CoSiting`. Calling this method with `null` to omit this property.

      Parameters:
        `colorSiting` - Color siting for the CDCI descriptor.
      See Also:
        `COLORSITING_DEFAULT`

    - #### getColorSiting

          ColorSitingType getColorSiting()

      Returns the color siting property of the CDCI descriptor, which specifies how to compute subsampled chrominance values.

      Valid values are:

      - `ColorSitingType.CoSiting` - To calculate subsampled pixels, take the preceding's pixels color value, discard the other color values and cosite the color with the first luminance value.
      - `ColorSitingType.Averaging` - To calculate subsampled pixels, take the average of the two adjacent pixels' color values and site the color in the center of the luminance pixels.
      - `ColorSitingType.ThreeTap` - To calculate subsampled pixels, take 25 percent of the the previous pixel's color value, 50 percent of the first value and 25 percent of the second value. For the first value in a row, use 75 percent of that value since there is no previous value. The `ThreeTap` value is only meaningful when the horizontal subsampling property has a value of 2.

      The color siting property is optional and has a default value of `ColorSitingType.CoSiting`. The default value will be returned if the property is not present.

      Returns:
        Color siting for the CDCI descriptor.
      See Also:
        `COLORSITING_DEFAULT`

    - #### setBlackRefLevel

          void setBlackRefLevel(@UInt32
                                Integer blackRefLevel)
                         throws IllegalArgumentException

      Sets the black reference level property for this CDCI descriptor, which specifies the digital luminance component value associated with black.

      For CCIR-601/2, the value is 16 for 8-bit video and 64 for 10-bit video. For YUV, the value is 0. These are typical values; other values will not be disallowed by the MAJ API implementation.

      The same value is used in CDCI and RGBA when standard colorspace conversion is used.

      This property is optional and has a default value of 0. To omit the property, call this method with `null`.

      Parameters:
        `blackRefLevel` - Black reference level of the CDCI descriptor.
      Throws:
        `IllegalArgumentException` - The given black reference level is negative.
      See Also:
        `BLACKREFLEVEL_DEFAULT`

    - #### getBlackRefLevel

          @UInt32
          int getBlackRefLevel()

      Returns the black reference level property for this CDCI descriptor, which specifies the digital luminance component value associated with black.

      For CCIR-601/2, the value is 16 for 8-bit video and 64 for 10-bit video. For YUV, the value is 0. These are typical values; other values will not be disallowed by the MAJ API implementation.

      The same value is used in CDCI and RGBA when standard colorspace conversion is used.

      If the property is omitted, its default value will be returned.

      Returns:
        Black reference level of the CDCI descriptor.
      See Also:
        `BLACKREFLEVEL_DEFAULT`

    - #### setWhiteRefLevel

          void setWhiteRefLevel(@UInt32
                                Integer whiteRefLevel)
                         throws IllegalArgumentException

      Sets the white reference level property of this CDCI descriptor, which specifies the digital luminance component component value associated with white.

      For CCIR-601/2, the value is 235 for 8-bit video and 940 for 10-bit video. For YUV, the value is 255 for 8-bit video and 1023 for 10-bit video. These are typical values; other values will not be disallowed by the MAJ API implementation.

      This property is optional. The default value is the maximum unsigned integer value for the component size. To omit this optional property, call this method with `null`.

      Parameters:
        `whiteRefLevel` - White reference level for the CDCI descriptor.
      Throws:
        `IllegalArgumentException` - Cannot set the white reference level of this CDCI descriptor to a negative value.
      See Also:
        `getComponentDepth()`

    - #### getWhiteRefLevel

          @UInt32
          int getWhiteRefLevel()

      Sets the white reference level property of this CDCI descriptor, which specifies the digital luminance component component value associated with white.

      For CCIR-601/2, the value is 235 for 8-bit video and 940 for 10-bit video. For YUV, the value is 255 for 8-bit video and 1023 for 10-bit video. These are typical values; other values will not be disallowed by the MAJ API implementation.

      If the property is not present, its default value will be returned. The default value is the maximum unsigned integer value for the component size.

      Returns:
        White reference level for the CDCI descriptor.
      See Also:
        `getComponentDepth()`

    - #### setColorRange

          void setColorRange(@UInt32
                             Integer colorRange)

      Sets the color range property for this CDCI descriptor, which specifies the range of allowable digital chrominance component values. Chrominance values are unsigned and the range is centered on 128 for 8-bit video and 512 for 10-bit video. This value is used for both chrominance components.

      For CCIR-601/2, the range is 225 for 8-bit video and 897 for 10-bit video. For YUV, the range is 255 for 8-bit video and 1023 for 10-bit video. hese are typical values; other values will not be disallowed by the MAJ API implementation.

      This property is optional. The default value is the maximum unsigned integer value for the component size. To omit this optional property, call this method with `null`.

      Parameters:
        `colorRange` - Color range for the CDCI descriptor.
      Throws:
        `IllegalArgumentException` - Cannot set the color range property of this CDCI descriptor to a negative value.
      See Also:
        `getComponentDepth()`

    - #### getColorRange

          @UInt32
          int getColorRange()

      Returns the color range property for this CDCI descriptor, which specifies the range of allowable digital chrominance component values. Chrominance values are unsigned and the range is centered on 128 for 8-bit video and 512 for 10-bit video. This value is used for both chrominance components.

      For CCIR-601/2, the range is 225 for 8-bit video and 897 for 10-bit video. For YUV, the range is 255 for 8-bit video and 1023 for 10-bit video. These are typical values; other values will not be disallowed by the MAJ API implementation.

      If this optional property is not present, the default value is returned. The default value is the maximum unsigned integer value for the component size.

      Returns:
        Color range for the CDCI descriptor.
      See Also:
        `getComponentDepth()`

    - #### setPaddingBits

          void setPaddingBits(@Int16
                              Short paddingBits)

      Sets the padding bits property of this CDCI descriptor, which specifies the number of bits padded to each pixel.

      This is an optional property with a default value of 0. To omit this optional property, call this method with `null`.

      Parameters:
        `paddingBits` - Padding bits of the CDCI descriptor.
      See Also:
        `PADDINGBITS_DEFAULT`

    - #### getPaddingBits

          @Int16
          short getPaddingBits()

      Returns the padding bits property of the CDCI descriptor, which specifies the number of bits padded to each pixel.

      If this optional property is not present, its default value is returned.

      Returns:
        Padding bits property of the CDCI descriptor.
      See Also:
        `PADDINGBITS_DEFAULT`

    - #### setAlphaSampleDepth

          void setAlphaSampleDepth(@UInt32
                                   Integer alphaSampleDepth)
                            throws IllegalArgumentException

      Sets the alpha sample depth property of the CDCI descriptor, which specifies the number of bits used to store the alpha component.

      This property is optional and has a default value of 0. To omit this optional property, call this method with `null`.

      Parameters:
        `alphaSampleDepth` - Alpha sample depth property of the CDCI descriptor.
      Throws:
        `IllegalArgumentException` - The giv en alpha sampling width value is negative.
      See Also:
        `ALPHASAMPLEDEPTH_DEFAULT`

    - #### getAlphaSampleDepth

          @UInt32
          int getAlphaSampleDepth()

      Returns the alpha sample depth property of the CDCI descriptor, which specifies the number of bits used to store the alpha component.

      If this optional property is not present, its default value is returned.

      Returns:
        Alpha sample depth property of the CDCI descriptor.
      See Also:
        `ALPHASAMPLEDEPTH_DEFAULT`

    - #### setReversedByteOrder

          void setReversedByteOrder(@Bool
                                    Boolean reversedByteOrder)

      Sets the reversed byte order property of the CDCI descriptor, which specifies whether the luma and chroma sample order is reversed relative to the order defined by ITU-R BT.601. The value is `false` if the sample order conforms conforms to ITU-R BT.601, or `true` if the order is reversed (i.e. the luma sample precedes the chroma).

      This property is optional and has a default value of `false`. To omit this optional property, call this method with `null`.

      Parameters:
        `reversedByteOrder` - Is the byte order reversed?
      See Also:
        `REVERSEDBYTEORDER_DEFAULT`, `ColorSitingType.Rec601`

    - #### getReversedByteOrder

          @Bool
          boolean getReversedByteOrder()

      Sets the reversed byte order property of the CDCI descriptor, which specifies whether the luma and chroma sample order is reversed relative to the order defined by ITU-R BT.601. The value is `false` if the sample order conforms conforms to ITU-R BT.601, or `true` if the order is reversed (i.e. the luma sample precedes the chroma).

      If this optional property is not present, its default value is returned.

      Returns:
        Is the byte order reversed?
      See Also:
        `REVERSEDBYTEORDER_DEFAULT`, `ColorSitingType.Rec601`

    - #### clone

          CDCIDescriptor clone()

      Create a cloned copy of this CDCI descriptor.

      Specified by:
        `clone` in interface `AAFFileDescriptor`
      Specified by:
        `clone` in interface `EssenceDescriptor`
      Specified by:
        `clone` in interface `InterchangeObject`
      Specified by:
        `clone` in interface `MediaEntity`
      Specified by:
        `clone` in interface `PictureDescriptor`
      Returns:
        Cloned copy of this CDCI descriptor.

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