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

tv.amwa.maj.model

## Interface RGBADescriptor

- All Superinterfaces:
    AAFFileDescriptor, EssenceDescriptor, InterchangeObject, MediaEntity, MetadataObject, PictureDescriptor
  All Known Implementing Classes:
    RGBADescriptorImpl

      public interface RGBADescriptor
      extends PictureDescriptor

  Specifies the description of a file of video essence formatted with three color components or with three color components and an alpha component.

  In addition to the parameters inherited from digital image descriptor, this interface adds pixel layout (order of R, B, G, alpha), pixel structure (sizes of the various components), palette, palette layout, and palette structure.

  See Also:
    `SourcePackage.getEssenceDescriptor()`, `CodecConstant.RGBA`, `RGBALayout`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `ALPHAMAXREF_DEFAULT` Default value for the alpha maximum reference level property, which is 255.
    `static int` | `ALPHAMINREF_DEFAULT` Default value for the alpha minimum reference level property, which is 0.
    `static int` | `COMPONENTMAXREF_DEFAULT` Default value for the component maximum reference level property, which is 255.
    `static int` | `COMPONENTMINREF_DEFAULT` Default value for the component minimum reference level property, which is 0.
    `static ScanningDirectionType` | `SCANNINGDIRECTION_DEFAULT` Default value for the scanning direction property, which is `ScanningDirectionType.LeftToRightTopToBottom`.

    - ### 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
    --- | ---
    `RGBADescriptor` | `clone()` Create a cloned copy of this RGBA descriptor.
    `int` | `countPaletteLayoutElements()` Returns the number of components per pixel in the palette of this RGBA descriptor.
    `int` | `countPixelLayoutElements()` Returns the number of components per pixel in data represented by this RGBA descriptor.
    `int` | `getAlphaMaxRef()` Returns the maximum alpha value of this RGBA descriptor, for example 239 or 959 (8 or 10 bits).
    `int` | `getAlphaMinRef()` Returns the minimum alpha value of the RGBA descriptor, for example 16 or 64 (8 or 10 bits).
    `int` | `getComponentMaxRef()` Returns the maximum value for RGB components of this RGBA descriptor, for example 239 or 959 (8 or 10 bits).
    `int` | `getComponentMinRef()` Returns the minimum value for RGB components of the RGBA descriptor, for example 16 or 64 (8 or 10 bits).
    `byte[]` | `getPalette()` Returns the palette property of the RGBA descriptor, which is an array of color values that are used to specify an image.
    `RGBAComponent[]` | `getPaletteLayout()` Returns the layout and structure of the components of a single entry for the palette of the RGBA descriptor.
    `RGBAComponent[]` | `getPixelLayout()` Returns the layout and structure of the components in a single pixel of data represented by the RGBA descriptor.
    `ScanningDirectionType` | `getScanningDirection()` Returns the scanning direction of this RGBA descriptor, which specifies the scanning direction of the image.
    `void` | `setAlphaMaxRef(Integer alphaMaxRef)` Sets the maximum alpha value of the RGBA descriptor, for example 239 or 959 (8 or 10 bits).
    `void` | `setAlphaMinRef(Integer alphaMinRef)` Sets the minimum alpha value of this RGBA descriptor, for example 16 or 64 (8 or 10 bits).
    `void` | `setComponentMaxRef(Integer componentMaxRef)` Sets the maximum value for RGB components of this RGBA descriptor, for example 239 or 959 (8 or 10 bits).
    `void` | `setComponentMinRef(Integer componentMinRef)` Sets the minimum value for RGB components of the RGBA descriptor, for example 16 or 64 (8 or 10 bits).
    `void` | `setPalette(byte[] palette)` Sets the palette property of the RGBA descriptor, which is an array of color values that are used to specify an image.
    `void` | `setPaletteLayout(RGBAComponent[] paletteLayoutArray)` Sets the layout and structure of the components of a single entry for the palette of the RGBA descriptor.
    `void` | `setPixelLayout(RGBAComponent[] pixelLayoutArray)` Sets the layout and structure of the components in a single pixel of data represented by the RGBA descriptor.
    `void` | `setScanningDirection(ScanningDirectionType scanningDirection)` Sets the scanning direction of this RGBA descriptor, which specifies the scanning direction of the image.

    - ### 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

    - #### COMPONENTMINREF_DEFAULT

          static final int COMPONENTMINREF_DEFAULT

      Default value for the component minimum reference level property, which is 0.

      See Also:
        `getComponentMinRef()`, `setComponentMinRef(Integer)`, Constant Field Values

    - #### COMPONENTMAXREF_DEFAULT

          static final int COMPONENTMAXREF_DEFAULT

      Default value for the component maximum reference level property, which is 255.

      See Also:
        `getComponentMaxRef()`, `setComponentMaxRef(Integer)`, Constant Field Values

    - #### ALPHAMINREF_DEFAULT

          static final int ALPHAMINREF_DEFAULT

      Default value for the alpha minimum reference level property, which is 0.

      See Also:
        `getAlphaMinRef()`, `setAlphaMinRef(Integer)`, Constant Field Values

    - #### ALPHAMAXREF_DEFAULT

          static final int ALPHAMAXREF_DEFAULT

      Default value for the alpha maximum reference level property, which is 255.

      See Also:
        `getAlphaMaxRef()`, `setAlphaMaxRef(Integer)`, Constant Field Values

    - #### SCANNINGDIRECTION_DEFAULT

          static final ScanningDirectionType SCANNINGDIRECTION_DEFAULT

      Default value for the scanning direction property, which is `ScanningDirectionType.LeftToRightTopToBottom`.

      See Also:
        `getScanningDirection()`, `setScanningDirection(ScanningDirectionType)`

  - ### Method Detail

    - #### setPixelLayout

          void setPixelLayout(@RGBALayout
                              RGBAComponent[] pixelLayoutArray)
                       throws NullPointerException

      Sets the layout and structure of the components in a single pixel of data represented by the RGBA descriptor. The layout array contains RGBAComponent items. Each item defines a size in bits for a component and the kind of component (red, green etc.).

      If you set less than 8 entries, the remaining entries will be padded with `RGBAComponentKind.None` and a size of zero.

      Parameters:
        `pixelLayoutArray` - Array of RGBA components, indicating the order and size of components in the data represented by the RGBA descriptor.
      Throws:
        `NullPointerException` - The given array of RGBA components is `null` or one or more of the elements of the array are `null`.
      See Also:
        `RGBAComponent`, `RGBAComponentKind`

    - #### countPixelLayoutElements

          @UInt32
          int countPixelLayoutElements()

      Returns the number of components per pixel in data represented by this RGBA descriptor.

      Returns:
        Number of components per pixel in data represented by this RGBA descriptor.

    - #### getPixelLayout

          @RGBALayout
          RGBAComponent[] getPixelLayout()

      Returns the layout and structure of the components in a single pixel of data represented by the RGBA descriptor. The layout array contains RGBAComponent items. Each item defines a size in bits for a component and the kind of component (red, green etc.).

      Returns:
        Array of RGBA components, indicating the order and size of components in the data represented by the RGBA descriptor.

    - #### setPalette

          void setPalette(byte[] palette)
                   throws IllegalArgumentException

      Sets the palette property of the RGBA descriptor, which is an array of color values that are used to specify an image. The palette must be in the form specified by the palette layout.

      To omit this optional property, set this value to `null`. If the layout of this RGBA descriptor requires a palette, an `IllegalArgumentException` will be thrown if an attempt is made to omit the palette property.

      Parameters:
        `palette` - Palette of the RGBA descriptor.
      Throws:
        `IllegalArgumentException` - Cannot omit the palette for an RGBA descriptor that requires a palette.
      See Also:
        `getPixelLayout()`, `getPaletteLayout()`, `RGBAComponentKind.Palette`

    - #### getPalette

          byte[] getPalette()
                     throws PropertyNotPresentException

      Returns the palette property of the RGBA descriptor, which is an array of color values that are used to specify an image. The palette is in the form specified by the palette layout. This property is optional.

      Returns:
        Palette of the RGBA descriptor.
      Throws:
        `PropertyNotPresentException` - The optional palette property is not present in this RGBA descriptor.
      See Also:
        `getPixelLayout()`, `getPaletteLayout()`, `RGBAComponentKind.Palette`

    - #### countPaletteLayoutElements

          @UInt32
          int countPaletteLayoutElements()
                                          throws PropertyNotPresentException

      Returns the number of components per pixel in the palette of this RGBA descriptor.

      Returns:
        Number of component per pixel in the palette of this RGBA descriptor.
      Throws:
        `PropertyNotPresentException` - The optional palette layout property is not present in this RGBA descriptor.
      See Also:
        `getPaletteLayout()`

    - #### setPaletteLayout

          void setPaletteLayout(@RGBALayout
                                RGBAComponent[] paletteLayoutArray)
                         throws IllegalArgumentException

      Sets the layout and structure of the components of a single entry for the palette of the RGBA descriptor. The layout array contains RGBAComponent items. Each item defines a size in bits for a component and the kind of component (red, green etc.).

      If you set less than 8 entries, the remaining entries will be padded with `RGBAComponentKind.None` and a size of zero.

      To omit this optional property, call this method with `null`. If the RGBA descriptor requires a palette and an attempt is made to omit the property, an `IllegalArgumentException` will be thrown.

      Parameters:
        `paletteLayoutArray` - Array of RGBA components, indicating the order and size of components in the palette of the RGBA descriptor.
      Throws:
        `IllegalArgumentException` - Cannot omit the palette layout for an RGBA descriptor that requires a palette, or the given layout refers to a palette.
      See Also:
        `getPalette()`, `RGBAComponent`, `RGBAComponentKind.Palette`

    - #### getPaletteLayout

          @RGBALayout
          RGBAComponent[] getPaletteLayout()
                                                throws PropertyNotPresentException

      Returns the layout and structure of the components of a single entry for the palette of the RGBA descriptor. The layout array contains RGBAComponent items. Each item defines a size in bits for a component and the kind of component (red, green etc.).

      Returns:
        Array of RGBA components, indicating the order and size of components in the palette of the RGBA descriptor.
      Throws:
        `PropertyNotPresentException` - The optional palette layout property is not present for this RGBA descriptor.
      See Also:
        `getPalette()`, `RGBAComponent`, `RGBAComponentKind.Palette`

    - #### setComponentMaxRef

          void setComponentMaxRef(@UInt32
                                  Integer componentMaxRef)
                           throws IllegalArgumentException

      Sets the maximum value for RGB components of this RGBA descriptor, for example 239 or 959 (8 or 10 bits).

      The default value for this optional property is 255. To omit this optional property, call this method with `null`.

      Parameters:
        `componentMaxRef` - Maximum value for RGB components of this RGBA descriptor.
      Throws:
        `IllegalArgumentException` - The given component maximum reference level is negative.
      See Also:
        `COMPONENTMAXREF_DEFAULT`, `setComponentMinRef(Integer)`, `RGBAComponentKind.Red`, `RGBAComponentKind.Green`, `RGBAComponentKind.Blue`

    - #### getComponentMaxRef

          @UInt32
          int getComponentMaxRef()

      Returns the maximum value for RGB components of this RGBA descriptor, for example 239 or 959 (8 or 10 bits).

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

      Returns:
        Maximum value for RGB components of this RGBA descriptor.
      See Also:
        `COMPONENTMAXREF_DEFAULT`, `getComponentMinRef()`, `RGBAComponentKind.Red`, `RGBAComponentKind.Green`, `RGBAComponentKind.Blue`

    - #### setComponentMinRef

          void setComponentMinRef(@UInt32
                                  Integer componentMinRef)
                           throws IllegalArgumentException

      Sets the minimum value for RGB components of the RGBA descriptor, for example 16 or 64 (8 or 10 bits).

      The default value for this optional property is 0. To omit this optional property, call this method with `null`.

      Parameters:
        `componentMinRef` - Minimum value for RGB components of the RGBA descriptor.
      Throws:
        `IllegalArgumentException` - The given component minimum reference level is negative.
      See Also:
        `COMPONENTMINREF_DEFAULT`, `setComponentMaxRef(Integer)`, `RGBAComponentKind.Red`, `RGBAComponentKind.Green`, `RGBAComponentKind.Blue`

    - #### getComponentMinRef

          @UInt32
          int getComponentMinRef()

      Returns the minimum value for RGB components of the RGBA descriptor, for example 16 or 64 (8 or 10 bits).

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

      Returns:
        Minimum value for RGB components.
      See Also:
        `COMPONENTMINREF_DEFAULT`, `getComponentMaxRef()`, `RGBAComponentKind.Red`, `RGBAComponentKind.Green`, `RGBAComponentKind.Blue`

    - #### setAlphaMaxRef

          void setAlphaMaxRef(@UInt32
                              Integer alphaMaxRef)
                       throws IllegalArgumentException

      Sets the maximum alpha value of the RGBA descriptor, for example 239 or 959 (8 or 10 bits).

      The default value for this optional property is 255. To omit this optional property, call this method with `null`.

      Parameters:
        `alphaMaxRef` - Maximum alpha value of this RGBA descriptor.
      Throws:
        `IllegalArgumentException` - The given maximum alpha reference level is negative.
      See Also:
        `ALPHAMAXREF_DEFAULT`, `setAlphaMinRef(Integer)`, `PictureDescriptor.getAlphaTransparency()`, `RGBAComponentKind.Alpha`

    - #### getAlphaMaxRef

          @UInt32
          int getAlphaMaxRef()

      Returns the maximum alpha value of this RGBA descriptor, for example 239 or 959 (8 or 10 bits).

      If this optional property is not present, the default value of 255 is returned.

      Returns:
        Maximum alpha value of this RGBA descriptor.
      See Also:
        `ALPHAMAXREF_DEFAULT`, `getAlphaMinRef()`, `PictureDescriptor.getAlphaTransparency()`, `RGBAComponentKind.Alpha`

    - #### setAlphaMinRef

          void setAlphaMinRef(@UInt32
                              Integer alphaMinRef)

      Sets the minimum alpha value of this RGBA descriptor, for example 16 or 64 (8 or 10 bits).

      The default value for this property is 0. To omit this optional property, call this method with `null`.

      Parameters:
        `alphaMinRef` - Minimum alpha value of this RGBA descriptor.
      See Also:
        `ALPHAMINREF_DEFAULT`, `setAlphaMaxRef(Integer)`, `PictureDescriptor.getAlphaTransparency()`, `RGBAComponentKind.Alpha`

    - #### getAlphaMinRef

          @UInt32
          int getAlphaMinRef()

      Returns the minimum alpha value of the RGBA descriptor, for example 16 or 64 (8 or 10 bits).

      If this optional property is not present, the default value of 0 is returned.

      Returns:
        Minimum alpha value of this RGBA descriptor.
      See Also:
        `ALPHAMINREF_DEFAULT`, `getAlphaMaxRef()`, `PictureDescriptor.getAlphaTransparency()`, `RGBAComponentKind.Alpha`

    - #### setScanningDirection

          void setScanningDirection(ScanningDirectionType scanningDirection)

      Sets the scanning direction of this RGBA descriptor, which specifies the scanning direction of the image. The value exactly matches the equivalent property in SMPTE 268M.

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

      Parameters:
        `scanningDirection` - Scanning direction of this RGBA descriptor.
      See Also:
        `SCANNINGDIRECTION_DEFAULT`, `ScanningDirectionType`

    - #### getScanningDirection

          ScanningDirectionType getScanningDirection()

      Returns the scanning direction of this RGBA descriptor, which specifies the scanning direction of the image. The value exactly matches the equivalent property in SMPTE 268M.

      This property is optional and has a default value of `ScanningDirectionType.LeftToRightTopToBottom`. If the optional property is not present, the default value is returned.

      Returns:
        Scanning direction of this RGBA descriptor.
      See Also:
        `SCANNINGDIRECTION_DEFAULT`, `ScanningDirectionType`

    - #### clone

          RGBADescriptor clone()

      Create a cloned copy of this RGBA 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 RGBA descriptor.

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