IMG/IMG_DeepShadow.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.
 *
 * Produced by:
 *      Andrew Clinton
 *      Side Effects Software Inc
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        IMG_DeepShadow.h ( IMG Library, C++)
 *
 * COMMENTS:    Deep shadow API
 */

#ifndef __IMG_DeepShadow__
#define __IMG_DeepShadow__

#include "IMG_API.h"
#include <UT/UT_PtrArray.h>

class img_DeepShadow;
class img_DeepShadowPixel;
class IMG_DeepShadow;
class IMG_DeepShadowChannel;
class UT_WorkBuffer;
class UT_Options;

typedef enum
{
    IMG_DEPTH_NEAREST = 0,
    IMG_DEPTH_FARTHEST = 1,
    IMG_DEPTH_MIDPOINT = 2
} IMG_DepthMode;

typedef enum
{
    IMG_COMPRESS_DISCRETE = 0,
    IMG_COMPRESS_LINEAR = 1
} IMG_DepthInterp;

/// @brief Thread-safe convenience class to make reading DSM pixels easy
///
/// This is a thread-safe convenience class to wrap around reading pixels
/// which ensures that the pixel is closed properly.
///
/// @warning Beware when declaring an IMG_DeepPixelReader in the same scope
/// as an IMG_DeepShadow.  Since the pixel reader keeps a reference to the
/// file, the destruction order is important -- though calling close()
/// should avoid any problems.
///
/// The class should be used as follows: @code
///
///             IMG_DeepPixelReader     pixel(dsm);
///             for (x, y) in raster {
///                 if (pixel.open(x, y)) {
///                     for (i = 0; i < pixel.getDepth(); i++)
///                          data = pixel.getData(chp, i);
///                 }
///             }
/// @endcode
///
class IMG_API IMG_DeepPixelReader {
public:
     IMG_DeepPixelReader(IMG_DeepShadow &dsm);
    ~IMG_DeepPixelReader();

    /// Open a pixel for reading
    bool                open(int x, int y);
    /// Close the pixel.  This is called automatically on destruction.
    /// However, if an IMG_DeepPixelReader and IMG_DeepShadow are created in
    /// the same scope, the IMG_DeepPixelReader may hold onto references (and
    /// cause crashing errors).  Calling close() manually is a safe thing to
    /// do.
    void                close();
    /// Returns the number of z-records
    int                 getDepth() const;
    /// Return the data for the channel at the given depth index.
    const fpreal        *getData(const IMG_DeepShadowChannel &chp,
                                    int depth_index);

    /// After opening, you can call either of these methods to ensure that the
    /// data is in the correct form for your application.  "composited" pixels
    /// will have the data accumulated over from front to back.  "uncomposited"
    /// pixels will have the raw data for each z-record.
    ///
    /// If the force flag is false, then the state of the file will be used
    /// to determine whether the deep records need to be processed or not.
    ///
    /// These methods should be called after the pixel has been opened.
    void                composite(const IMG_DeepShadowChannel &pz,
                                  const IMG_DeepShadowChannel &of,
                                  bool force = false);
    void                uncomposite(const IMG_DeepShadowChannel &pz,
                                    const IMG_DeepShadowChannel &of,
                                    bool force = false);

    /// @private Internal constructor - please do not call this
    IMG_DeepPixelReader(img_DeepShadow *dsm);
private:
    img_DeepShadowPixel *myHandle;
};

/// @brief Single channel of a Houdini DSM image
///
/// A Houdini deep shadow/camera file can have any number of image channels
/// (planes).  A DSM image contains a single channel for opacity.  A deep
/// camera image has the opacity channel along with any number of extra image
/// channels.
class IMG_API IMG_DeepShadowChannel {
public:
    /// @param name             The unique name of the DSM channel
    /// @param float_offset
    ///         When data is read or written in deep shadow files, the pixel
    ///         data is interleaved.  That is, the data for a single pixel can
    ///         be represented as an array of floats.  Each channel has a
    ///         unique offset into the array.  The user should @b not assume
    ///         that the offsets are contiguous.  For example, the pixel data
    ///         might look like: @code
    ///                 [ Of.r,         // Opacity red
    ///                   Of.g,         // Opacity green
    ///                   Of.b,         // Opacity blue
    ///                   Cf.r,         // Color (red)
    ///                   Cf.g,         // Color (green)
    ///                   Cf.b,         // Color (blue)
    ///                   s,            // s coordinate
    ///                   t,            // t coordinate
    ///                   N.x,          // Normal x
    ///                   N.y,          // Normal y
    ///                   N.z,          // Normal z
    ///                 ]
    ///         @endcode
    ///         Where the channels would be defined by: @code
    ///                 IMG_DeepShadowChannel("Of", 0, 3);
    ///                 IMG_DeepShadowChannel("Cf", 3, 3);
    ///                 IMG_DeepShadowChannel("s", 6, 1);
    ///                 IMG_DeepShadowChannel("t", 7, 1);
    ///                 IMG_DeepShadowChannel("N", 8, 3);
    ///         @endcode
    /// @param tuple_size       Number of floats
    /// @param storage
    ///         Storage type.  This may be one of { "real16", "real32",
    ///         "real64" }.  This value represents the storage of the channel
    ///         in the file.
    /// @see IMG_DeepShadow::addExtraChannel()
     IMG_DeepShadowChannel(const char *name,
                            int float_offset,
                            int tuple_size,
                            const char *storage="real32");
    /// Copy constructor
     IMG_DeepShadowChannel(const IMG_DeepShadowChannel &src);
    ~IMG_DeepShadowChannel();

    IMG_DeepShadowChannel &operator=(const IMG_DeepShadowChannel &s);
    bool                   operator==(const IMG_DeepShadowChannel &s) const;

    /// @{
    /// Data acceess function
    const char          *getName() const        { return myName; }
    const char          *getStorage() const     { return myStorage; }
    int                  getOffset() const      { return myOffset; }
    int                  getTupleSize() const   { return myTupleSize; }
    /// @}

private:
    char        *myName;
    char        *myStorage;
    int          myOffset;
    int          myTupleSize;
};

/// @brief Class to read or write deep shadow/camera images
///
/// This class provides a creation interface for deep shadow maps.
/// The class can be used as follows: @code
///     setOption(...);
///     setOption(...);
///     ...
///     open(fname, xres, yres);
///     foreach pixel loop
///             pixelStart(pixel);
///             foreach record
///                     pixelWrite(record);
///             end loop
///             pixelClose()
///     end loop
///     close();
/// @endcode
///
/// To read from an existing deep shadow map, the class can be used as
/// follows: @code
///     IMG_DeepShadow          dsm;
///     IMG_DeepPixelReader     pixel;
///     dsm.open(fname);
///     foreach (x,y) in raster:
///             pixel.open(x, y)
///             for (i = 0; i < pixel.getDepth(); i++)
///                     pixel.getData(chp, i);
///     close();
/// @endcode
///
/// @see
///     - TIL_TextureMap - for filtered evaluation of DSM/DCM's)
///     - IMG_DeepPixelReader - For thread-safe reading of DSM pixels
///     - IMG_DeepShadowChannel
class IMG_API IMG_DeepShadow {
public:
             IMG_DeepShadow();
    virtual ~IMG_DeepShadow();

    /// Set a file creation option.  Options must be set before the 
    /// file is opened with open() below.
    ///
    /// Currently (and this list may be out of date), the options are:
    /// -  "ofstorage"   = one of {     "int8", "int16", "int32", "int64",
    ///                                 "uint8", "uint16", "uint32", "uint64",
    ///                                 "real16", "real32", "real64" }
    /// -  "pzstorage"   = one of { "int8" ... "real64" }
    /// -  "ofsize"      = one of { "1", "3" }
    /// -  "compression  = a value between "0" and "9" (lossyness)
    /// -  "zbias"       = minimum delta between z-values (float value)
    /// -  "depth_mode"  = one of { "nearest", "midpoint", "farthest" }
    /// -  "depth_interp" = one of { "discrete", "continuous" }
    /// -  "compositing"  = "0" will turn off pre-compositing of the z-records
    ///    This is recommended when dealing with deep camera maps (i.e. if
    ///    there are extra channels)
    void                 setOption(const char *option, const char *value);

    /// Set options based on the "texture:*" options defined in the UT_Options.
    /// The UT_Options will be checked for options:
    ///  - @c texture:ofstorage
    ///  - @c texture:pzstorage
    ///  - @c texture:ofsize
    ///  - @c etc.
    void                 setOptions(const UT_Options &options);

    /// Print the current values of the file options into the work buffer
    void                 printArgs(UT_WorkBuffer &wbuf);

    /// Get a description of the available options that can be provided in
    /// setOption()
    const char          *getDescription();

    /// Add an extra channel to be stored along with Of and Pz.  Any number of
    /// channels may be added (though the file size will increase accordingly).
    /// - The name must be unique among (and not Of or Pz)
    /// - The float_offset is the offset into the "data" in the
    ///   pixelWrite() method.  Note that the opacity must occupy the first 3
    ///   floats of the data array.  So, the float_offset @b must be at least 3.
    /// - The tuple_size is the number of elements in the channel
    ///   Currently, this must be 1, 3 or 4.
    /// - The storage specifies the storage type (and uses the same
    ///   tokens as the "ofstorage" option (i.e. int8, int16, int32, int64,
    ///   uint8, uint16, uint32, uint64, real16, real32 or real64.
    /// The extra channels must be added @b before open() is called.
    bool                 addExtraChannel(const IMG_DeepShadowChannel &def,
                                         const UT_Options *options=0);

    /// Open a deep shadow map for writing.  This method will return false
    /// if there were errors opening the texture.
    bool                 open(const char *name, int xres, int yres);

    /// Start writing data to a pixel.  This method must be called exactly
    /// once for each pixel.  Starting pixels in a regular order will 
    /// be more efficient than writing them in a random order, but is not
    /// required.
    bool                 pixelStart(int x, int y);

    /// Write data to the currently open pixel.  This method inserts an 
    /// unordered data record with the given z-value and data into the 
    /// current pixel.  vsize is the number of floats that are contained
    /// in the data array.
    ///
    /// The first 3 floats of the data array must be the opacity (RGB).  Any
    /// extra channel data follows this according to the float_offset
    /// associated with the channel.  This data may be quantized to a single
    /// float depending on the options.
    ///
    /// If @c vsize doesn't contain a full record, then this method will fail.
    /// vsize must be greater or equal to 3 (depending on extra channels)
    ///
    /// Currently, mantra will always interpret the data as a rgb opacity
    /// triple.
    bool                 pixelWrite(float z, const float *data, int vsize);

    /// Perform the same operation as pixelWrite() except assume that data
    /// is pre-sorted by increasing z-value.  This method will perform
    /// slightly better than pixelWrite() as data does not need to be sorted.
    bool                 pixelWriteOrdered(float z, const float *data,
                                            int vsize);

    /// Close a pixel and flush the pixel's data to file.
    bool                 pixelClose();

    /// Close the deep shadow map and write it to disk.
    bool                 close();

    /// Get UT_Option structure from TBF.  These options are stored with the
    /// file and may be queried in VEX using teximport().
    UT_Options          *getTBFOptions();


public:
    /// Open a deep shadow map for reading.
    bool                 open(const char *name);

    /// Get the resolution of the deep shadow map.
    void                 resolution(int &xres, int &yres);

    /// Get the number of channels in the DSM
    int                  getChannelCount() const;

    /// Get a channel definition
    const IMG_DeepShadowChannel *getChannel(int i) const;

    /// Get the raw data values for a pixel, in the order that they appear
    /// in the file.  This method should be called repeatedly for each pixel
    /// until a 0 is returned, indicating that all records have been read
    /// for that pixel.  Reading pixels in a regular order will be more
    /// efficient than reading them in a random order.
    ///
    /// @warning You should copy the data out of the returned pointer before
    /// proceeding.  Do NOT refer to this pointer after reading more data
    /// from the shadow map.  Because of this, this method is @b not
    /// thread-safe.
    ///
    /// @deprecated In favour of  IMG_DeepPixelReader
    float SYS_DEPRECATED        *pixelRead(int x, int y, float &z, int &vsize);

private:
    friend class        IMG_DeepPixelReader;

    bool                openPixelRead(IMG_DeepPixelReader &h, int x, int y);
    void                closePixelRead(IMG_DeepPixelReader &h);

    // Get the pixel's depth complexity (the number of records in Z)
    int                 getPixelDepth(IMG_DeepPixelReader &h);

    // Get the data for the pixel being read:
    // You should copy the data out of the returned pointer before proceeding.
    // Do NOT refer to this pointer after reading more data from the shadow map.
    // The index is must be between 0 and (getPixelDepth()-1)
    const fpreal        *getPixelData(IMG_DeepPixelReader &h,
                                const IMG_DeepShadowChannel &chp,
                                int index);

private:
    friend class         img_DeepShadow;
    virtual void         printError(const char *, ...) const;
    virtual void         printWarning(const char *, ...) const;

private:
    img_DeepShadow                              *myFile;

public:
    IMG_DepthInterp      depthInterp();
};

#endif

---