/*****************************************************************************/

// Copyright 2008 Adobe Systems Incorporated

// All Rights Reserved.

//

// NOTICE:  Adobe permits you to use, modify, and distribute this file in

// accordance with the terms of the Adobe license agreement accompanying it.

/*****************************************************************************/

/* $Id: //mondo/dng_sdk_1_4/dng_sdk/source/dng_opcodes.h#2 $ */ 

/* $DateTime: 2012/08/02 06:09:06 $ */

/* $Change: 841096 $ */

/* $Author: erichan $ */

/** \file

 * Base class and common data structures for opcodes (introduced in DNG 1.3).

 */

/*****************************************************************************/

#ifndef __dng_opcodes__

#define __dng_opcodes__

/*****************************************************************************/

#include "dng_auto_ptr.h"

#include "dng_classes.h"

#include "dng_rect.h"

#include "dng_types.h"

/*****************************************************************************/

/// \brief List of supported opcodes (by ID).

enum dng_opcode_id

  {

  // Internal use only opcode.  Never written to DNGs.

  dngOpcode_Private       = 0,

  // Warp image to correct distortion and lateral chromatic aberration for

  // rectilinear lenses.

  dngOpcode_WarpRectilinear     = 1,

  // Warp image to correction distortion for fisheye lenses (i.e., map the

  // fisheye projection to a perspective projection).

  dngOpcode_WarpFisheye     = 2,

  // Radial vignette correction.

  dngOpcode_FixVignetteRadial   = 3,

  // Patch bad Bayer pixels which are marked with a special value in the image.

  dngOpcode_FixBadPixelsConstant  = 4,

  // Patch bad Bayer pixels/rectangles at a list of specified coordinates.

  dngOpcode_FixBadPixelsList    = 5,

  // Trim image to specified bounds.

  dngOpcode_TrimBounds      = 6,

  // Map an area through a 16-bit LUT.

  dngOpcode_MapTable        = 7,

  // Map an area using a polynomial function.

  dngOpcode_MapPolynomial     = 8,

  // Apply a gain map to an area.

  dngOpcode_GainMap       = 9,

  // Apply a per-row delta to an area.

  dngOpcode_DeltaPerRow     = 10,

  // Apply a per-column delta to an area.

  dngOpcode_DeltaPerColumn    = 11,

  // Apply a per-row scale to an area.

  dngOpcode_ScalePerRow     = 12,

  // Apply a per-column scale to an area.

  dngOpcode_ScalePerColumn    = 13

  };

/*****************************************************************************/

/// \brief Virtual base class for opcode.

class dng_opcode

  {

  public:

    /// Opcode flags.

    enum

      {

      kFlag_None      = 0,  //!< No flag.

      kFlag_Optional      = 1,  //!< This opcode is optional.

      kFlag_SkipIfPreview = 2   //!< May skip opcode for preview images.

      };

  private:

    uint32 fOpcodeID;

    uint32 fMinVersion;

    uint32 fFlags;

    bool fWasReadFromStream;

    uint32 fStage;

  protected:

    dng_opcode (uint32 opcodeID,

          uint32 minVersion,

          uint32 flags);

    dng_opcode (uint32 opcodeID,

          dng_stream &stream,

          const char *name);

  public:

    virtual ~dng_opcode ();

    /// The ID of this opcode.

    uint32 OpcodeID () const

      {

      return fOpcodeID;

      }

    /// The first DNG version that supports this opcode.

    uint32 MinVersion () const

      {

      return fMinVersion;

      }

    /// The flags for this opcode.

    uint32 Flags () const

      {

      return fFlags;

      }

    /// Is this opcode optional?

    bool Optional () const

      {

      return (Flags () & kFlag_Optional) != 0;

      }

    /// Should the opcode be skipped when rendering preview images?

    bool SkipIfPreview () const

      {

      return (Flags () & kFlag_SkipIfPreview) != 0;

      }

    /// Was this opcode read from a data stream?

    bool WasReadFromStream () const

      {

      return fWasReadFromStream;

      }

    /// Which image processing stage (1, 2, 3) is associated with this

    /// opcode?

    uint32 Stage () const

      {

      return fStage;

      }

    /// Set the image processing stage (1, 2, 3) for this opcode. Stage 1 is

    /// the original image data, including masked areas. Stage 2 is

    /// linearized image data and trimmed to the active area. Stage 3 is

    /// demosaiced and trimmed to the active area.

    void SetStage (uint32 stage)

      {

      fStage = stage;

      }

    /// Is the opcode a NOP (i.e., does nothing)? An opcode could be a NOP

    /// for some specific parameters. 

    virtual bool IsNOP () const

      {

      return false;

      }

    /// Is this opcode valid for the specified negative?

    virtual bool IsValidForNegative (const dng_negative & /* negative */) const

      {

      return true;

      }

    /// Write opcode to a stream.

    /// \param stream The stream to which to write the opcode data.

    virtual void PutData (dng_stream &stream) const;

    /// Perform error checking prior to applying this opcode to the

    /// specified negative. Returns true if this opcode should be applied to

    /// the negative, false otherwise.

    bool AboutToApply (dng_host &host,

               dng_negative &negative);

    /// Apply this opcode to the specified image with associated negative.

    virtual void Apply (dng_host &host,

              dng_negative &negative,

              AutoPtr<dng_image> &image) = 0;

  };

/*****************************************************************************/

/// \brief Class to represent unknown opcodes (e.g, opcodes defined in future

/// DNG versions).

class dng_opcode_Unknown: public dng_opcode

  {

  private:

    AutoPtr<dng_memory_block> fData;

  public:

    dng_opcode_Unknown (dng_host &host,

              uint32 opcodeID,

              dng_stream &stream);

    virtual void PutData (dng_stream &stream) const;

    virtual void Apply (dng_host &host,

              dng_negative &negative,

              AutoPtr<dng_image> &image);

  };

/*****************************************************************************/

/// \brief Class to represent a filter opcode, such as a convolution.

class dng_filter_opcode: public dng_opcode

  {

  protected:

    dng_filter_opcode (uint32 opcodeID,

               uint32 minVersion,

               uint32 flags);

    dng_filter_opcode (uint32 opcodeID,

               dng_stream &stream,

               const char *name);

  public:

    /// The pixel data type of this opcode.

    virtual uint32 BufferPixelType (uint32 imagePixelType)

      {

      return imagePixelType;

      }

    /// The adjusted bounds (processing area) of this opcode. It is limited to

    /// the intersection of the specified image area and the GainMap area.

    virtual dng_rect ModifiedBounds (const dng_rect &imageBounds)

      {

      return imageBounds;

      }

    /// Returns the width and height (in pixels) of the repeating mosaic pattern.

    virtual dng_point SrcRepeat ()

      {

      return dng_point (1, 1);

      }

    /// Returns the source pixel area needed to process a destination pixel area

    /// that lies within the specified bounds.

    /// \param dstArea The destination pixel area to be computed.

    /// \param imageBounds The overall image area (dstArea will lie within these

    /// bounds).

    /// \retval The source pixel area needed to process the specified dstArea.

    virtual dng_rect SrcArea (const dng_rect &dstArea,

                  const dng_rect & /* imageBounds */)

      {

      return dstArea;

      }

    /// Given a destination tile size, calculate input tile size. Simlar to

    /// SrcArea, and should seldom be overridden.

    ///

    /// \param dstTileSize The destination tile size that is targeted for output.

    ///

    /// \param imageBounds The image bounds (the destination tile will

    /// always lie within these bounds).

    ///

    /// \retval The source tile size needed to compute a tile of the destination

    /// size.

    virtual dng_point SrcTileSize (const dng_point &dstTileSize,

                     const dng_rect &imageBounds)

      {

      return SrcArea (dng_rect (dstTileSize),

              imageBounds).Size ();

      }

    /// Startup method called before any processing is performed on pixel areas.

    /// It can be used to allocate (per-thread) memory and setup tasks.

    ///

    /// \param negative The negative object to be processed.

    ///

    /// \param threadCount The number of threads to be used to perform the

    /// processing.

    ///

    /// \param threadCount Total number of threads that will be used for

    /// processing. Less than or equal to MaxThreads.

    ///

    /// \param tileSize Size of source tiles which will be processed. (Not all

    /// tiles will be this size due to edge conditions.)

    ///

    /// \param imageBounds Total size of image to be processed.

    ///

    /// \param imagePlanes Number of planes in the image. Less than or equal to

    /// kMaxColorPlanes.

    ///

    /// \param bufferPixelType Pixel type of image buffer (see dng_tag_types.h).

    ///

    /// \param allocator dng_memory_allocator to use for allocating temporary

    /// buffers, etc.

    virtual void Prepare (dng_negative & /* negative */,

                uint32 /* threadCount */,

                const dng_point & /* tileSize */,

                const dng_rect & /* imageBounds */,

                uint32 /* imagePlanes */,

                uint32 /* bufferPixelType */,

                dng_memory_allocator & /* allocator */)

      {

      }

    /// Implements filtering operation from one buffer to another. Source

    /// and destination pixels are set up in member fields of this class.

    /// Ideally, no allocation should be done in this routine.

    ///

    /// \param negative The negative associated with the pixels to be

    /// processed.

    ///

    /// \param threadIndex The thread on which this routine is being called,

    /// between 0 and threadCount - 1 for the threadCount passed to Prepare

    /// method.

    ///

    /// \param srcBuffer Input area and source pixels.

    ///

    /// \param dstBuffer Destination pixels.

    ///

    /// \param dstArea Destination pixel processing area.

    ///

    /// \param imageBounds Total image area to be processed; dstArea will

    /// always lie within these bounds.

    virtual void ProcessArea (dng_negative &negative,

                  uint32 threadIndex,

                  dng_pixel_buffer &srcBuffer,

                  dng_pixel_buffer &dstBuffer,

                  const dng_rect &dstArea,

                  const dng_rect &imageBounds) = 0;

    virtual void Apply (dng_host &host,

              dng_negative &negative,

              AutoPtr<dng_image> &image);

  };

/*****************************************************************************/

/// \brief Class to represent an in-place (i.e., pointwise, per-pixel) opcode,

/// such as a global tone curve.

class dng_inplace_opcode: public dng_opcode

  {

  protected:

    dng_inplace_opcode (uint32 opcodeID,

                uint32 minVersion,

                uint32 flags);

    dng_inplace_opcode (uint32 opcodeID,

                dng_stream &stream,

                const char *name);

  public:

    /// The pixel data type of this opcode.

    virtual uint32 BufferPixelType (uint32 imagePixelType)

      {

      return imagePixelType;

      }

    /// The adjusted bounds (processing area) of this opcode. It is limited to

    /// the intersection of the specified image area and the GainMap area.

    virtual dng_rect ModifiedBounds (const dng_rect &imageBounds)

      {

      return imageBounds;

      }

    /// Startup method called before any processing is performed on pixel areas.

    /// It can be used to allocate (per-thread) memory and setup tasks.

    ///

    /// \param negative The negative object to be processed.

    ///

    /// \param threadCount The number of threads to be used to perform the

    /// processing.

    ///

    /// \param threadCount Total number of threads that will be used for

    /// processing. Less than or equal to MaxThreads.

    ///

    /// \param tileSize Size of source tiles which will be processed. (Not all

    /// tiles will be this size due to edge conditions.)

    ///

    /// \param imageBounds Total size of image to be processed.

    ///

    /// \param imagePlanes Number of planes in the image. Less than or equal to

    /// kMaxColorPlanes.

    ///

    /// \param bufferPixelType Pixel type of image buffer (see dng_tag_types.h).

    ///

    /// \param allocator dng_memory_allocator to use for allocating temporary

    /// buffers, etc.

    virtual void Prepare (dng_negative & /* negative */,

                uint32 /* threadCount */,

                const dng_point & /* tileSize */,

                const dng_rect & /* imageBounds */,

                uint32 /* imagePlanes */,

                uint32 /* bufferPixelType */,

                dng_memory_allocator & /* allocator */)

      {

      }

    /// Implements image processing operation in a single buffer. The source

    /// pixels are provided as input to the buffer, and this routine

    /// calculates and writes the destination pixels to the same buffer.

    /// Ideally, no allocation should be done in this routine.

    ///

    /// \param negative The negative associated with the pixels to be

    /// processed.

    ///

    /// \param threadIndex The thread on which this routine is being called,

    /// between 0 and threadCount - 1 for the threadCount passed to Prepare

    /// method.

    ///

    /// \param srcBuffer Input area and source pixels.

    ///

    /// \param dstBuffer Destination pixels.

    ///

    /// \param dstArea Destination pixel processing area.

    ///

    /// \param imageBounds Total image area to be processed; dstArea will

    /// always lie within these bounds.

    virtual void ProcessArea (dng_negative &negative,

                  uint32 threadIndex,

                  dng_pixel_buffer &buffer,

                  const dng_rect &dstArea,

                  const dng_rect &imageBounds) = 0;

    virtual void Apply (dng_host &host,

              dng_negative &negative,

              AutoPtr<dng_image> &image);

  };

/*****************************************************************************/

#endif

/*****************************************************************************/