TIL_Stitch.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.
 *
 * NAME:        TIL_Stitch.h (TIL Library, C++)
 *
 * COMMENTS:
 */

#ifndef __TIL_Stitch__
#define __TIL_Stitch__

#include "TIL_API.h"
#include <UT/UT_Rect.h>
#include <UT/UT_Span.h>
#include <UT/UT_Array.h>
#include <UT/UT_NonCopyable.h>
#include <IMG/IMG_File.h>

/// @brief Combine a number of separate tiles into a single image.
///
/// The stitcher takes a list of readers (one for each tile) and a single image
/// writer.  The readers and writers need to have the same AOV definitions.
namespace TIL_Stitch
{
    /// Class to store scanline data.
    class TIL_API Scanline
        : public UT_NonCopyable
    {
    public:
        Scanline();
        virtual ~Scanline();
    };

    /// Class to represent an input "tile" which is stitched into the final
    /// image
    class TIL_API TileReader
        : public UT_NonCopyable
    {
    public:
        TileReader();
        virtual ~TileReader();

        /// Return the data window of the tile in pixels
        virtual const UT_DimRect        &dataWindow() const = 0;

        virtual bool    canRead(const Scanline *scanline) const = 0;

        /// Open tile for reading
        virtual bool    open() = 0;

        /// Read an AOV from the tile
        virtual bool    readScanline(int plane, int xoff, int scanline,
                                    Scanline *buffer) = 0;

        /// Close tile when finished reading
        virtual bool    close() = 0;
    };

    /// Class to read the tile data and write it to an output sink.
    class TIL_API StitchWriter
        : public UT_NonCopyable
    {
    public:
        StitchWriter();
        virtual ~StitchWriter();

        // Return the dimensions of the data window
        virtual const UT_DimRect        &dataWindow() const = 0;

        // Start a new row of tiles (i.e. this tile has a different y value
        // than the previous tile).  By default this does nothing.  Return @c
        // false if there's an error.
        virtual bool    startRow(const TileReader &first);

        // Called when the last tile has been written
        virtual bool    finishImage();

        // Process a tile reader
        virtual bool    process(TileReader &tile) = 0;
    };

    TIL_API UT_DimRect  unionDataWindow(const UT_Span<const TileReader *> &tiles);

    TIL_API bool stitch(StitchWriter &w, const UT_Span<TileReader *> &tiles,
                        bool top_down);

    /// Convenience class to represent a raster scanline
    class TIL_API IMGScanline : public Scanline
    {
    public:
        struct ScanData
        {
            const uint8 *data(exint xoff) const { return myData.get() + myBPP*xoff; }
            uint8       *data(exint xoff) { return myData.get() + myBPP*xoff; }

            UT_UniquePtr<uint8[]>        myData;
            const IMG_Plane             *myPlane = nullptr;
            exint                        myBPP = 0;
        };
        IMGScanline();
        ~IMGScanline() override;

        void             allocate(int width,
                                const UT_Array<const IMG_Plane *> &planes);
        const uint8     *data(int plane, int xoff) const
                         {
                             return myPlanes[plane].data(xoff);
                         }
        uint8           *data(int plane, int xoff)
                         {
                             return myPlanes[plane].data(xoff);
                         }

        int             numPlanes() const { return myNumPlanes; }
        const IMG_Plane *plane(int i) const { return myPlanes[i].myPlane; }

    private:
        UT_UniquePtr<ScanData[]>        myPlanes;
        int                             myNumPlanes = 0;
        int                             myWidth = 0;
    };

    /// Convenience class to read a tile from a file
    /// @note this class expects the scanlines to be interleaved (rgbrgb...)
    class TIL_API IMGTileReader : public TileReader
    {
    public:
        IMGTileReader();
        ~IMGTileReader() override;

        struct OpenStyle
        {
            bool        isValid() const { return myFilename != nullptr; }
            IMG_FilePtr open();

            const char                          *myFilename = nullptr;
            const IMG_FileParms                 *myOptions = nullptr;
            const IMG_Format                    *myFormat = nullptr;
            UT_Array<const IMG_Format *>         myFormatList;
        };

        bool    setFile(const char *filename,
                            const IMG_FileParms *options = nullptr,
                            const IMG_Format *fmt = nullptr)
        {
            myOpen.myFilename = filename;
            myOpen.myOptions = options;
            myOpen.myFormat = fmt;
            myOpen.myFormatList.clear();
            return initStat();
        }
        bool    setFile(const char *filename,
                            const UT_Array<const IMG_Format *> &formats,
                            const IMG_FileParms *options = nullptr)
        {
            myOpen.myFilename = filename;
            myOpen.myOptions = options;
            myOpen.myFormat = nullptr;
            myOpen.myFormatList = formats;
            return initStat();
        }

        const UT_DimRect        &dataWindow() const override;
        bool    open() override;
        bool    canRead(const Scanline *scanline) const override;
        bool    readScanline(int plane, int xoff, int scanline,
                                Scanline *buffer) override;
        bool    close() override;

        bool    isValid() const { return myFile.get() != nullptr; }

        IMG_FilePtr     stealStream() { return std::move(myFile); }
        const char      *getFilename() const { return myOpen.myFilename; }
    protected:
        bool            init(IMG_FilePtr fp);
        bool            initStat();
        virtual void    error(const char *msg) const;

        UT_DimRect      myDataWindow;
        IMG_FilePtr     myFile;
        OpenStyle       myOpen;
    };

    /// Convenience class to write to an image file
    /// @note this class expects the scanlines to be interleaved (rgbrgb...)
    class TIL_API IMGWriter : public StitchWriter
    {
    public:
        // Takes ownership of the file
        IMGWriter(IMG_FilePtr fp);
        ~IMGWriter() override;

        const UT_DimRect        &dataWindow() const override;
        bool                     startRow(const TileReader &row) override;
        bool                     finishImage() override;
        bool                     process(TileReader &tile) override;

        int                      tilesRead() const { return myTilesRead; }

    protected:
        virtual bool    flushScanlines();
        virtual void    error(const char *msg) const;
        virtual void    warning(const char *msg) const;

        IMG_FilePtr                     myFile;
        UT_DimRect                      myDataWindow;
        UT_Array<const IMG_Plane *>     myPlanes;
        UT_Array<IMGScanline>           myScanBuffer;
        exint                           myBytesPerPixel; // Total bytes per pixel
        int                             myY0, myY1; // Span of scanlines of current row
        int                             myTilesRead;
    };
};

#endif