CascadeJpegFile Class Reference

JPEG decoding. More...

#include <cascade/util/CascadeJpegFile.h>

List of all members.

Public Types
enum	ColorSpace { eRGB, eYUV, eYUYV }
Public Member Functions
	CascadeJpegFile ()
virtual	~CascadeJpegFile ()
	destructor
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
u32	GetImageWidth (void) const
u32	GetImageHeight (void) const
u32	GetImageBPP (void) const
u32	GetImageRotation (void) const
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)
Static Public Member Functions
static bool	GetScaledImageDims (u32 inDivisor, u32 inWidth, u32 inHeight, u32 &outWidth, u32 &outHeight)

---

Detailed Description

JPEG decoding.

The CascadeJpegFile class is used to decode JPEG image files. The decoding functions are designed to run in minimum memory, while allowing for rotation, scaling and clipping of the original image into the output data. All of these transformations are performed during the decoding process, which minimizes memory footprint.

Warning:

This class remains a work in progress. There are known performance issues with decoding and scaling, and known visual issues with the scaling.

CascadeJpegFile

---

Member Enumeration Documentation

enum CascadeJpegFile::ColorSpace

Enumeration values: eRGB  eYUV  eYUYV

---

Constructor & Destructor Documentation

CascadeJpegFile::CascadeJpegFile (   )

default constructor Lightweight. Init must be called to associate the object with a file.

virtual CascadeJpegFile::~CascadeJpegFile (   )  [virtual]

destructor

---

Member Function Documentation

void CascadeJpegFile::AbortDecode (  void   )

abort function Call (from another thread) to cause GetBitmapData to exit early and return false.

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

decode the image, optionally scaling, cropping and rotating Fills the supplied pointer with the decoded image, scaled, rotated and clipped if desired. You must call Init() before calling this function. Callers should call GetBitmapDataSize first, and allocate a pointer of the appropriate size. Note: The file has a particular set of dimensions, which can be returned with the GetImageInfo or individual accessors. These dimensions are for the data *AS IT IS WRITTEN* in the file, independent of any rotation (including the EXIF rotation returned by GetImageRotation!). Callers should be aware that any supplied rotation is performed after the scaling operation. If an image must be both rotated and scaled, the caller needs to figure out what pre-rotation scaling to apply in order to get the desired post-rotation image size (generally, this just involves swapping the width and height arguments when rotation is an odd multiple of 90 degrees). Lastly, callers may pass an optional clipping rectangle. The clipping operation is performed AFTER scaling, but BEFORE rotation. If, for example, the original image is 640x480, and the caller wants the 320x240 rectangle at the center of the image cut out, scaled back up to 640x480, and rotated 90 degrees (yielding an output bitmap that is 480x640), they would call GetBitmapData with: inScaledWidth = 1280 inScaledHeight = 960 inRotationDegrees = 90 inClipRect = CascadeRect(320, 240, 640, 480) Warning: The clipping rect MUST be equal to or smaller than the scaled size, and must fit entirely within the bounds of the scaled image. An invalid ClipRect (except the empty rectangle of 0,0,0,0) will cause the function to return false with no data. Parameters: outBitmapData  the buffer into which to write the decoded image inBitmapDataSize  the size of the supplied buffer (use GetBitmapDataSize if unsure). The function will return false if the buffer is of insufficient size. inClipRect  the rectangle to clip the returned image to inScaledWidth  (optional) the desired pre-clipping, pre-rotation width to which to scale the image. Pass zero for native size. inScaledHeight  (optional) the desired pre-clipping, pre-rotation height to which to scale the image. Pass zero for native size. inRotationDegrees  (optional) 0, 90, 180 and 270 degree rotations are supported Returns: true if the decode was successful, or false if not.

u32 CascadeJpegFile::GetBitmapDataSize (  u32  inScaledWidth = 0, u32  inScaledHeight = 0 )

get size of returned decoded data Call this function after calling Init() to get the size that the decoded bitmap data will be, including any desired scaling. (Call with no arguments or pass zeros to return the image's native size.) Parameters: inScaledWidth  desired scaled width, or zero for native size inScaledHeight  desired scaled height, or zero for native size Returns: the size that the decoded data will be, in bytes

const CascadeString& CascadeJpegFile::GetImageArtist (  void   )  const

artist accessor If the EXIF header is present and the Artist tag has been written, this will return a CascadeString which contains the contents of the tag. EXIF does not mandate a format. This is uncommon in digital camera images, but is used by some other systems. Returns: a reference to a CascadeString containing the contents of the Artist EXIF tag, or to an empty string if the information was not present in the file. Note that the reference becomes invalid when the CascadeJpegFile object is destroyed.

u32 CascadeJpegFile::GetImageBPP (  void   )  const

depth accessor Returns the native bit depth of the image

const CascadeString& CascadeJpegFile::GetImageCopyright (  void   )  const

copyright accessor If the EXIF header is present and the Copyright tag has been written, this will return a CascadeString which contains the contents of the tag. EXIF does not mandate a format. This is uncommon in digital camera images, but is used by some other systems. Returns: a reference to a CascadeString containing the contents of the Copyright EXIF tag, or to an empty string if the information was not present in the file. Note that the reference becomes invalid when the CascadeJpegFile object is destroyed.

const CascadeString& CascadeJpegFile::GetImageDate (  void   )  const

date accessor If the EXIF header is present and the DateTime tag has been written, this will return a CascadeString which contains that date information, in the EXIF-compliant string format. Returns: a reference to a CascadeString containing the date and time the image was created, or to an empty string if the information was not present in the file. The format is YYYY:MM:DD HH:MM:SS (19 characters)

u32 CascadeJpegFile::GetImageExposureDenominator (  void   )  const

exposure denominator accessor If the EXIF header is present and the ExposureTime tag has been written, this will return a u32 representing the denominator of the rational value in the tag. You should also call GetImageExposureNumerator(). Note: The ExposureTime tag in the EXIF header is of type RATIONAL, which is a ratio of two unsigned 32-bit numbers. For example, a typical value for a digital camera might be a shutter speed of 1/250th of a second. In such a case, this function will return 250, and GetImageExposureNumerator() will return 1. The functions are separate to facilitate easy display Returns: an unsigned 32-bit value representing the denominator of the rational number in the ExposureTime EXIF tag, or zero if the tag is not present.

u32 CascadeJpegFile::GetImageExposureNumerator (  void   )  const

exposure numerator accessor If the EXIF header is present and the ExposureTime tag has been written, this will return a u32 representing the numerator of the rational value in the tag. You should also call GetImageExposureDenominator(). Note: The ExposureTime tag in the EXIF header is of type RATIONAL, which is a ratio of two unsigned 32-bit numbers. For example, a typical value for a digital camera might be a shutter speed of 1/250th of a second. In such a case, this function will return 1, and GetImageExposureDenominator() will return 250. The functions are separate to facilitate easy display Returns: an unsigned 32-bit value representing the numerator of the rational number in the ExposureTime EXIF tag, or zero if the tag is not present.

bool CascadeJpegFile::GetImageFlashState (  bool &  outFlashState  )  const

flash state accessor If the EXIF header is present and the Flash tag has been written, this sets the supplied boolean to true if the flash fired, or false if not. The function returns a boolean specifying whether the flash information was present in the file. If no flash information is present, the outFlashState boolean is not modified. Parameters: outFlashState  set to true if the flash fired, or false if it did not. Not modified if the information is not present in the file. Returns: true if the information is present in the file, else false.

float CascadeJpegFile::GetImageFStop (  void   )  const

f-stop accessor If the EXIF header is present and the FNumber tag has been written, this will return a float representing the f-stop stored in that tag. Note: The FNumber tag in the EXIF header is of type RATIONAL, which is a ratio of two unsigned 32-bit numbers. However, the f-stop of a camera is typically expressed as a simple number -- like f2.5 or f4.0 -- so this function returns a simple float. You will want to limit the precision of the displayed result to one decimal place for most uses. Returns: a floating-point value representing the contents of the EXIF FNumber tag, or zero (0.0) if the tag is not present.

u32 CascadeJpegFile::GetImageHeight (  void   )  const

height accessor Returns the native height of the image

void CascadeJpegFile::GetImageInfo (  u32 &  outWidth, u32 &  outHeight, u32 &  outBPP )  const

get native image data Return the width, height and pixel depth of the main image. Sizes are the native sizes of the image Parameters: outWidth  filled with image width outHeight  filled with image height outBPP  filled with image bit depth

const CascadeString& CascadeJpegFile::GetImageMake (  void   )  const

make accessor If the EXIF header is present and the Make tag has been written, this will return a CascadeString which contains the contents of the tag. EXIF does not mandate a format. If the file originates from a digital camera, this will typically be "Canon" or "Olympus" or similar. Returns: a reference to a CascadeString containing the contents of the Make EXIF tag, or to an empty string if the information was not present in the file. Note that the reference becomes invalid when the CascadeJpegFile object is destroyed.

const CascadeString& CascadeJpegFile::GetImageModel (  void   )  const

model accessor If the EXIF header is present and the Model tag has been written, this will return a CascadeString which contains the contents of the tag. EXIF does not mandate a format. If the file originates from a digital camera, this will typically be "Canon PowerShot S230" or "Olympus C-5050Z" or similar. Returns: a reference to a CascadeString containing the contents of the Model EXIF tag, or to an empty string if the information was not present in the file. Note that the reference becomes invalid when the CascadeJpegFile object is destroyed.

u32 CascadeJpegFile::GetImageRotation (  void   )  const

rotation accessor If the EXIF header is present and the orientation tag has been written, this will return the rotation of the image as written into the file. To display the image upright, subtract this value from 360 and pass the result into GetBitmapData as the rotation parameter. Returns: the rotation of the image. 0, 90, 180 and 270 are possible return values. 0 is returned if no rotation data is present.

const CascadeString& CascadeJpegFile::GetImageTitle (  void   )  const

title accessor If the EXIF header is present and the ImageDescription tag has been written, this will return a CascadeString which contains the contents of the tag. EXIF does not mandate a format. This is uncommon in digital camera images, but is used for image titles by some systems. Returns: a reference to a CascadeString containing the contents of the ImageDescription EXIF tag, or to an empty string if the information was not present in the file. Note that the reference becomes invalid when the CascadeJpegFile object is destroyed.

u32 CascadeJpegFile::GetImageWidth (  void   )  const

width accessor Returns the native width of the image

const CascadeString& CascadeJpegFile::GetName (  void   )  const

name accessor Get the name of the image, as set in Init. Returns: a reference to a CascadeString containing the image name. The reference will become invalid when the file is deleted, so clients are encouraged to copy the reference if it needs to persist.

static bool CascadeJpegFile::GetScaledImageDims (  u32  inDivisor, u32  inWidth, u32  inHeight, u32 &  outWidth, u32 &  outHeight )  [static]

scaled dimension utility If you're trying to figure out what resolutions you can get from a JPEG image by scaling entirely in the DCT domain (which is high-performance), you may use this function to ensure that your dimensions agree with the JPEG implementation. Valid divisor are 1, 2, 4 and 8. The function is static, so you need not have a CascadeJpegFile instantiated. Parameters: inDivisor  the divisor inWidth  the starting width inHeight  the starting height outWidth  the scaled width is returned in this parameter outHeight  the scaled height is returned in this parameter Returns: true unless an invalid parameter is specified

bool CascadeJpegFile::GetThumbnailData (  u8 *  outThumbnailData, u32  inThumbnailDataSize, u32  inWidth, u32  inHeight, u32  inRotationDegrees = 0 )

fetch decoded image thumbnail, if present If the image file contains an EXIF-compliant thumbnail, this function decodes it and returns it, optionally scaling and rotating the thumbnail image. You must call Init before calling this function. Parameters: outThumbnailData  Calling function must provide a buffer of appropriate size inThumbnailDataSize  the size of the supplied buffer. The function returns false if the size is insufficient. inWidth  the pre-rotation width to which to scale the thumbnail inHeight  the pre-rotation height to which to scale the thumbnail inRotationDegrees  (optional) 0, 90, 180 and 270 degree rotation is supported. Returns: true if thumbnail was fetched. False if image had no thumbnail, if buffer was of insufficient size, or if an error was encountered.

bool CascadeJpegFile::HasThumbnail (  void   )

check for image thumbnail Returns true if the EXIF header is present and contains a thumbnail image.

bool CascadeJpegFile::Init (  const char *  inFilename, ColorSpace  inColorSpace = eRGB )

initialization For compatibility with older code, this function provides the old file-based initialization. It creates the stream internally and then calls the CascadeStream-based Init function. Parameters: inFilename  a path or file name to a JPEG file inColorSpace  (optional) the desired output color space. Supported spaces are RGB, YUV and YUYV (compressed chroma). Default is eRGB Returns: true if the header was read successfully.

bool CascadeJpegFile::Init (  CascadeStream *  inStream, const CascadeString &  inName, ColorSpace  inColorSpace = eRGB, bool  inDeleteStream = false )

initialization Initialization. From the supplied stream (which should be opened by the client before calling Init), reads the JPEG and EXIF header information. Returns false if the stream does not point to valid JPEG data, or if data cannot be read. Missing EXIF is not an error condition. If inDeleteStream is true, the stream object will be deleted when this CascadeJpegFile is deleted. Otherwise, the calling function is responsible for disposal of the stream. Parameters: inStream  any CascadeStream type containing JPEG data. inColorSpace  (optional) the desired output color space. Supported spaces are RGB, YUV and YUYV (compressed chroma). Default is eRGB inDeleteStream  (optional) if true, CascadeJpegFile takes ownership of the stream and will delete it when the CascadeJpegFile object is deleted. Default is false. Returns: true if the header was read successfully.

---

The documentation for this class was generated from the following file:

• CascadeJpegFile.h

---