CascadeJpegFile.h

Go to the documentation of this file.

//---------------------------------------------------------------------
// CascadeJpegFile.h
//
// The CascadeJpegFile class represents a single JPEG file.  It is able
// to parse the EXIF header when present to extract the thumbnail
// and image information.  It also uses jpeglib to decode the
// image and return an uncompressed pixmap.
//
// If a maximum size is specified during decompression, an
// appropriate scale factor will be given to jpeglib to limit
// the maximum size of the returned pixmap.  Pass zero in this
// argument for no limit to the output buffer size.
//
// Author: Mike Kobb (mjkobb)
//
// Includes some adaptation of a work in the public domain, from the 
// book "Graphics Gems III", article "General Filtered Image Rescaling"
// by Dale Schumacher.
//
// (c) 2002-2003 Roku, LLC
//---------------------------------------------------------------------

#ifndef CASCADEJPEGFILE_H
#define CASCADEJPEGFILE_H

#include <cascade/CascadeTypedefs.h>

class CascadeJpegFile
{
public:
    typedef enum
    {
        eRGB,
        eYUV,
        eYUYV
    } ColorSpace;

public:
    CascadeJpegFile();

    virtual ~CascadeJpegFile();

#if 0
    static bool Validate( const char *inFilename );
#endif

    bool Init( CascadeStream *inStream,
               const CascadeString &inName,
               ColorSpace inColorSpace = eRGB,
               bool inDeleteStream = false );
    
    bool Init( const char *inFilename, ColorSpace inColorSpace=eRGB );

    u32 GetBitmapDataSize( u32 inScaledWidth = 0, u32 inScaledHeight = 0 );

    bool GetBitmapData( u8  *outBitmapData,
                        u32 inBitmapDataSize,
                        CascadeRect &inClipRect,
                        u32 inScaledWidth = 0,
                        u32 inScaledHeight = 0,
                        u32 inRotationDegrees = 0 );

    void AbortDecode( void );
        
    bool GetThumbnailData( u8 *outThumbnailData,
                           u32 inThumbnailDataSize,
                           u32 inWidth,
                           u32 inHeight,
                           u32 inRotationDegrees = 0 );
        
    void GetImageInfo( u32 &outWidth, u32 &outHeight, u32 &outBPP ) const;
  
    // NOTE: These three functions return the same data returned in the
    // function above, but may be more convenient when passing the data
    // as arguments to another function.

    u32 GetImageWidth( void ) const;

    u32 GetImageHeight( void ) const;

    u32 GetImageBPP( void ) const;

    u32 GetImageRotation( void ) const;

    static bool GetScaledImageDims( u32 inDivisor, 
                                    u32 inWidth,
                                    u32 inHeight,
                                    u32 &outWidth, 
                                    u32 &outHeight );

    const CascadeString & GetName( void ) const;

    const CascadeString & GetImageDate( void ) const;

    const CascadeString & GetImageMake( void ) const;
    
    const CascadeString & GetImageModel( void ) const;
    
    const CascadeString & GetImageTitle( void ) const;

    const CascadeString & GetImageArtist( void ) const;
    
    const CascadeString & GetImageCopyright( void ) const;
    
    u32 GetImageExposureNumerator( void ) const;
    
    u32 GetImageExposureDenominator( void ) const;
    float GetImageFStop( void ) const;
        
    bool GetImageFlashState( bool &outFlashState ) const;

    bool HasThumbnail( void );
    
#if 0
    // Return the width, height and pixel depth of the thumbnail image.
    // You should clal hasThumbnail first.  Will return all zeroes if no
    // thumbnail is present.
    // THIS FUNCTION DOES NOT WORK -- IT ALWAYS RETURNS ZEROS
    void GetThumbnailInfo( u32 &outWidth, u32 &outHeight, u32 &outBPP )
    { 
        outWidth = mThumbnailWidth; 
        outHeight = mThumbnailHeight; 
        outBPP = mThumbnailBPP; 
    };
    
    // Accessors. Same data returned as above, but maybe more convenient
    // to pass to other functions.
    // You should clal hasThumbnail first.  Will return all zeroes if no
    // thumbnail is present.
    // THESE FUNCTIONS DO NOT WORK -- THEY ALWAYS RETURNS ZEROS
    u32 GetThumbnailWidth( void ) { return mThumbnailWidth; };
    u32 GetThumbnailHeight( void ) { return mThumbnailHeight; };
    u32 GetThumbnailBPP( void ) { return mThumbnailBPP; };
#endif

private:
    class   PrivateMembers;
    PrivateMembers  *m_private;
};

// ---------------------------------------------------------------------------
// Class PixelWriter
//
// Object to handle writing image data into a destination buffer, taking
// rotation into account.  Performs one more conditional operation (a test of
// mCurRasterIndex against mRasterWidth) and one more addition (increment
// mCurRasterIndex) per pixel than a straight copy to an upright buffer.
//
// Note the absence of any indexes in the writing function.  The assumption
// here is that the object is constructed, and then the pixels are written
// sequentially from the top-left of the source image to the bottom right, 
// proceeding horizontally across each row and then on to the next row.
//
// We do support writing more than one pixel per call, for cases where we
// have a buffer of data to write.
// ---------------------------------------------------------------------------
class PixelWriter
{
public:
    PixelWriter( u8 *inBuffer, u32 inWidth, u32 inHeight, 
                 u32 inRotationDegees, u32 inColorComponents );
    virtual ~PixelWriter();

    // Copy mColorComponents 8-bit pixel components from this pointer to
    // the destination.
    void WritePixels( u8* inPixelData, u32 inNumPixels );

    // Reset the internal state so we start writing from the
    // beginning of the destination buffer again.
    void Reset( void );

private:
    // First pixel (corresponds to top-left pixel in non-rotated image)
    u8* mRasterStart;

    // Last pixel in the array
    u8* mRasterEnd;

    // First pixel of current scan line (keeping in mind that we scan
    // pixels into the image in source order, so a line may be a column, etc)
    u8* mCurRowStart;

    // Next pixel to write
    u8* mCurPixel;

    // Width of one *source* image scan line, in pixels
    u32 mRasterWidth;

    // Current index into the current scan line
    u32 mCurRasterIndex;

    // Number of bytes to increment for next pixel.
    // 1 pixel for upright
    // -1 pixel for 180
    // mRasterWidth pixels for 90 degree rotation
    // -mRasterWidth pixels for 270 degree rotation
    s32 mPixelByteOffset;

    // Number of bytes to add to mCurRowStart when mCurRasterIndex ==
    // mRasterWidth (i.e. we've written mRasterWidth pixels to this row) 
    // in order to get the next row
    // mRasterWidth pixels for upright
    // -mRasterWidth pixels for 180
    // -1 pixel for 90
    // 1 pixel for 270
    s32 mRasterOffset;

    // FIXME: Could have source and destination components, and use this
    // function to pad out alpha as well.
    // Number of 8-bit components that make up a pixel
    u32 mColorComponents;
};


#endif //CASCADEJPEGFILE_H

// CHANGE HISTORY
// ==============
// 01/28/2003   mjkobb  Post-CES cleanup, rename CascadeJpegFile, convert
//                      to Cascade typedefs
// 02/21/2003   mjkobb  Oops, havent' updated these comments in awhile. This
//                      checkin includes a reasonably-stable image scaling 
//                      enhancement to GetBitmapData.  Scales X and Y axes
//                      independently and rotates during the decoding process
//                      to minimize memory required.  Uses a "Mitchell" filter
//                      (a cubic function).
// 03/17/2003   mjkobb  Added rudimentary support for aborting a decode
//                      operation.  Strictly speaking, this should have
//                      some nice thread-safety associated, but right now
//                      the simple-minded approach works.
// 05/23/2003   mjkobb  Major re-structuring.  Moved the threaded slideshow
//                      functionality into CImageWindow, so that 
//                      it and CThumbnailWindow could have independent 
//                      key and command processing.
// 06/05/2003   mjkobb  Add setjmp/longjmp-based error recovery to the
//                      class so that clients don't suddenly exit
//                      when a problem is encountered.
// 07/02/2003   mjkobb  Added support for RGB or YUV color space selection
// 07/24/2003   mjkobb  Added accessors for EXIF data and modified return
//                      types of EXIF Rational functions
// 07/28/2003   mjkobb  Make CascadeJpegFile a derivative of CascadeFile for
//                      easier access to the file name
// 12/09/2003   mjkobb  Add YUYV support
// 05/16/2005   mjkobb  Cleaned up API to make a proper Cascade class.  No
//                      longer derives from CascadeFile.  Accepts a
//                      CascadeStream in its initialization (with a backward-
//                      compatible path initializer).

---