libsswf: sswf::TagImage Class Reference

# sswf::TagImage Class Reference

The image class in SWF. More...

`#include <libsswf.h>`

Inheritance diagram for sswf::TagImage:

List of all members.

## Public Types
enum | image_format_t { IMAGE_FORMAT_UNKNOWN = 0, IMAGE_FORMAT_LOSSLESS_BEST, IMAGE_FORMAT_LOSSLESS_8, IMAGE_FORMAT_LOSSLESS_16, IMAGE_FORMAT_LOSSLESS_32, IMAGE_FORMAT_JPEG, IMAGE_FORMAT_max }
| The list of formats available for the TagImage. More...
## Public Member Functions
void | GetImageData (image_t &image_data)
| Retrieve the current image information.
ErrorManager::error_code_t | LoadJPEG (const char *filename, image_t &im)
| Load a JPEG image.
ErrorManager::error_code_t | LoadTGA (const char *filename, image_t &im)
| Load a Targa image.
virtual ErrorManager::error_code_t | Save (Data &data)
| Save the image in the specified Data buffer.
ErrorManager::error_code_t | SaveJPEG (Data &encoding, Data &image)
| Save a JPEG in a set of Data buffers.
ErrorManager::error_code_t | SetAlpha (image_t &im, const image_t &mask)
| Set the alpha channel of an image.
void | SetDeblock (int deblock)
| Defines the deblock filter parameter for a JPEG.
ErrorManager::error_code_t | SetFilename (const char *image, const char *mask)
| Load an image in the specified TagImage.
void | SetFormat (image_format_t format)
| Set the required format for when the image is to be saved.
void | SetImage (long width, long height, unsigned char *data, bool alpha=false, long count=0, unsigned char *colormap=0)
| Set an image in the TagImage object.
void | SetQuality (int quality)
| Defines the quality level for a JPEG.
| TagImage (TagBase *parent)
| Initializes the TagImage object.
virtual swf_type_t | TypeFlags (void) const
| Returns the flags defined for a TagImage.
## Private Member Functions
virtual ErrorManager::error_code_t | ParseTag (swf_tag_t tag, const Data &data)
virtual ErrorManager::error_code_t | PreSave (void)
| Check that the image can be saved.
## Private Attributes
unsigned char * | f_colormap
long | f_count
int | f_deblock
image_format_t | f_format
image_t | f_image
int | f_quality
## Classes
struct | image_t
| Defines a bitmap. More...

## Detailed Description

This class is used to include an image in an SWF animation. Images become fills in a style which is then rendered by a shape object.

SWF supports only two image formats: JPEG and Lossless (which is similar to PNG: a compressed bitmap using zlib.)

Older movies were constrained to one set of JPEG Tables and any number of DefineBitsJPEG. Newer movies can incorporate the JPEG Tables in the DefineBitsJPEG2. Also, since version 3, SWF supports DefineBitsJPEG3 that includes an alpha channel (compressed with zlib) for JPEG images.

Lossless images can also include an alpha channel. It supports different formats such as grey scales and paletted images. The library will automatically try to use a palette if possible (i.e. if your image is small or only uses a very limited number of colors.)

See also:
  SWF Alexis' Reference—DefineJPEGTables

  SWF Alexis' Reference—DefineBitsJPEG

  SWF Alexis' Reference—DefineBitsJPEG2

  SWF Alexis' Reference—DefineBitsJPEG3

  SWF Alexis' Reference—DefineBitsLossless

  SWF Alexis' Reference—DefineBitsLossless2

  SWF Alexis' Reference—swf_tag

## Member Enumeration Documentation

enum sswf::TagImage::image_format_t

This enumeration lists all the possible formats supported by the SWF format. Note that does not define the image formats supported by the SSWF library.

Enumerator:

  IMAGE_FORMAT_UNKNOWN | By default the format of an image is set to Unknown. This is the default format until you specifically call the sswf::TagImage::SetFormat() function. The TagImage does not try to guess the output format for you (at least, not yet.)
  IMAGE_FORMAT_LOSSLESS_BEST | Used to let the library select between the different lossless formats. This format is a special internal format one can use to let the library choose between the different available lossless formats. This means the library will try all the different modes and choose the one which generates the smallest result. See also: sswf::TagImage::IMAGE_FORMAT_LOSSLESS_8 sswf::TagImage::IMAGE_FORMAT_LOSSLESS_16 sswf::TagImage::IMAGE_FORMAT_LOSSLESS_32
  IMAGE_FORMAT_LOSSLESS_8 | Save a paletted image. This format is not currently supported because we do not have a working quantization function. The sswf::TagImage::IMAGE_FORMAT_LOSSLESS_BEST may make use of that format if it can transform the entire image to a paletted image. See also: sswf::TagImage::IMAGE_FORMAT_LOSSLESS_BEST sswf::TagImage::IMAGE_FORMAT_LOSSLESS_16 sswf::TagImage::IMAGE_FORMAT_LOSSLESS_32
  IMAGE_FORMAT_LOSSLESS_16 | Save a lossless image in 16 bits. Save the image in a lossless 16 bits image. When the sswf::TagImage::IMAGE_FORMAT_LOSSLESS_BEST is used, it switches to the 16 bits format only if all the colors use only the 5 top bits (i.e. bits 0, 1 and 2 are all zeroes.) The 16 bits image is really only 15 bits, 5 bits per component (xrrrrrgggggbbbbb). See also: sswf::TagImage::IMAGE_FORMAT_LOSSLESS_BEST sswf::TagImage::IMAGE_FORMAT_LOSSLESS_8 sswf::TagImage::IMAGE_FORMAT_LOSSLESS_32
  IMAGE_FORMAT_LOSSLESS_32 | Saves the Lossless image in 32 bits. This format saves an RGB image in XRGB format and an ARGB image in ARGB format. When no alpha is saved it puts 0 everywhere. See also: sswf::TagImage::IMAGE_FORMAT_LOSSLESS_BEST sswf::TagImage::IMAGE_FORMAT_LOSSLESS_8 sswf::TagImage::IMAGE_FORMAT_LOSSLESS_16
  IMAGE_FORMAT_JPEG | Saves the image compressed with JPEG. This format requests that the TagImage be compressed using the JPEG format.
  IMAGE_FORMAT_max | Maximum format number. This definition is only to define the largest possible format.

## Constructor & Destructor Documentation

TagImage::TagImage | ( | TagBase * | parent | ) |

This function initializes the image to all defaults.

This means no image, no alpha channel, default quality.

Parameters:

  `[in]` | parent | The TagHeader in which this TagImage is to be inserted

References sswf::TagImage::image_t::f_alpha, f_colormap, f_count, sswf::TagImage::image_t::f_data, f_deblock, f_format, sswf::TagImage::image_t::f_height, f_image, f_quality, sswf::TagImage::image_t::f_width, and IMAGE_FORMAT_UNKNOWN.

## Member Function Documentation

sswf::TagImage::GetImageData | ( | image_t & | image_data | ) | `[inline]`

This function retrieves the image information. This is a direct copy of the image structure with the internal data pointer. Do not modify the pointer or free it.

Parameters:

  `[out]` | image_data | An image structure

Returns:
  A copy of the internal image structure

References f_image.

ErrorManager::error_code_t TagImage::LoadJPEG | ( | const char * | filename,
|  | image_t & | im |
| ) |  |  |

This function loads and decompresses a JPEG image.

If you want to set an image in the TagImage, use SetFilename() instead.

Note:
  This function does not call OnError(). It is expected that you will use SetFilename() which generates errors as required. Note that the function specifically returns ErrorManager::ERROR_CODE_UNKNOWN_FORMAT if the image does not look like a JPEG. Other errors means that either there was an I/O error or the JPEG is corrupted.

Parameters:

  `[in]` | filename | The name of the file to be loaded
  `[in]` | im | The bitmap structure where the image is loaded

Returns:
  An error code or ErrorManager::ERROR_CODE_NONE

See also:
  sswf::TagImage::LoadTGA(const char *filename, image_t& im)

References sswf::ErrorManager::ERROR_CODE_INVALID_IMAGE, sswf::ErrorManager::ERROR_CODE_IO, sswf::ErrorManager::ERROR_CODE_NONE, sswf::ErrorManager::ERROR_CODE_UNKNOWN_FORMAT, sswf::TagImage::image_t::f_alpha, sswf::TagImage::image_t::f_data, sswf::TagImage::image_t::f_height, sswf::TagImage::image_t::f_width, sswf::MemoryManager::MemAlloc(), SSWF_JPG_ERROR::pub, SSWF_JPG_ERROR::setjmp_buffer, sswfFillInputBuffer(), sswfInitSource(), sswfJPEGError(), sswfResyncToRestart(), sswfSkipInputData(), and sswfTermSource().

Referenced by SetFilename().

ErrorManager::error_code_t TagImage::LoadTGA | ( | const char * | filename,
|  | image_t & | im |
| ) |  |  |

This function loads and decompresses a Targa image.

If you want to set an image in the TagImage, use SetFilename() instead.

Parameters:

  `[in]` | filename | The name of the file to be loaded
  `[in]` | im | The bitmap structure where the image is loaded

Returns:
  An error code or ErrorManager::ERROR_CODE_NONE

See also:
  sswf::TagImage::LoadJPEG(const char *filename, image_t& im)

References sswf::ErrorManager::ERROR_CODE_IO, sswf::ErrorManager::ERROR_CODE_NONE, sswf::ErrorManager::ERROR_CODE_UNKNOWN_FORMAT, sswf::TagImage::image_t::f_alpha, sswf::TagImage::image_t::f_data, sswf::TagImage::image_t::f_height, sswf::TagImage::image_t::f_width, sswf::MemoryManager::MemAlloc(), sswf::swap(), TGA_HEADER_SIZE, TGA_OFFSET_BITS_PER_PIXEL, TGA_OFFSET_COLORMAP_TYPE, TGA_OFFSET_FLAGS, TGA_OFFSET_HEIGHT_HI, TGA_OFFSET_HEIGHT_LO, TGA_OFFSET_IDENTIFIER_LENGTH, TGA_OFFSET_IMAGE_TYPE, TGA_OFFSET_WIDTH_HI, and TGA_OFFSET_WIDTH_LO.

Referenced by SetFilename().

virtual ErrorManager::error_code_t sswf::TagImage::ParseTag | ( | swf_tag_t | tag,
|  | const Data & | data |
| ) |  |  | `[private, virtual]`

Implements sswf::TagBase.

ErrorManager::error_code_t TagImage::PreSave | ( | void |  | ) | `[private, virtual]`

This function makes sure that the image format was defined and depending on the format and whether it uses an alpha channel, decides whether the minimum version is 2 or 3.

Returns:
  An error code or ErrorManager::ERROR_CODE_NONE

Reimplemented from sswf::TagBase.

References sswf::ErrorManager::ERROR_CODE_NONE, sswf::ErrorManager::ERROR_CODE_UNSUPPORTED_IMAGE_FORMAT, sswf::TagImage::image_t::f_alpha, f_deblock, f_format, f_image, IMAGE_FORMAT_JPEG, IMAGE_FORMAT_LOSSLESS_16, IMAGE_FORMAT_LOSSLESS_32, IMAGE_FORMAT_LOSSLESS_BEST, sswf::TagBase::MinimumVersion(), and sswf::TagBase::OnError().

ErrorManager::error_code_t TagImage::Save | ( | Data & | data | ) | `[virtual]`

This function saves the image in the specified Data buffer. Whenever saving the image in one of the Lossless formats, the function tries to transform it to a paletted image since in general a paletted image can be saved in a smaller image.

Bug:
  At this time, the function does not support LOSSLESS8.

Returns:
  An error code or ErrorManager::ERROR_CODE_NONE

Implements sswf::TagBase.

References sswf::Data::Append(), sswf::assert(), sswf::Data::ByteSize(), sswf::ErrorManager::ERROR_CODE_NONE, sswf::ErrorManager::ERROR_CODE_UNSUPPORTED_IMAGE_FORMAT, sswf::TagImage::image_t::f_alpha, sswf::TagImage::image_t::f_data, f_deblock, f_format, sswf::TagImage::image_t::f_height, f_image, sswf::TagImage::image_t::f_width, IMAGE_FORMAT_JPEG, IMAGE_FORMAT_LOSSLESS_16, IMAGE_FORMAT_LOSSLESS_32, IMAGE_FORMAT_LOSSLESS_8, IMAGE_FORMAT_LOSSLESS_BEST, sswf::MemoryManager::MemAlloc(), sswf::MemoryManager::MemFree(), sswf::TagBase::OnError(), sswf::Data::PutByte(), sswf::Data::PutLong(), sswf::Data::PutShort(), sswf::TagBaseID::SaveID(), SaveJPEG(), sswf::TagBase::SaveTag(), sswf::TagBase::SWF_TAG_DEFINE_BITS_JPEG2, sswf::TagBase::SWF_TAG_DEFINE_BITS_JPEG3, sswf::TagBase::SWF_TAG_DEFINE_BITS_JPEG4, sswf::TagBase::SWF_TAG_DEFINE_BITS_LOSSLESS, sswf::TagBase::SWF_TAG_DEFINE_BITS_LOSSLESS2, and sswf::Data::Write().

ErrorManager::error_code_t TagImage::SaveJPEG | ( | Data & | encoding,
|  | Data & | image |
| ) |  |  |

This function saves a JPEG image table encodings and compressed bits in two Data buffers.

Parameters:

  `[in]` | encoding | Save the JPEG tables in this Data buffer
  `[in]` | image | Save the JPEG compressed bits in this Data buffer

Returns:
  An error or ErrorManager::ERROR_CODE_NONE

References sswf::ErrorManager::ERROR_CODE_JPEG, sswf::ErrorManager::ERROR_CODE_NONE, sswf::TagImage::image_t::f_data, sswf::TagImage::image_t::f_height, f_image, f_quality, sswf::TagImage::image_t::f_width, sswf::MemoryManager::MemAlloc(), sswf::MemoryManager::MemFree(), sswf::TagBase::OnError(), SSWF_JPG_ERROR::pub, SSWF_JPG_ERROR::setjmp_buffer, sswfEmptyOutputBuffer(), sswfInitDestination(), sswfJPEGError(), and sswfTermDestination().

Referenced by Save().

ErrorManager::error_code_t TagImage::SetAlpha | ( | image_t & | im,
|  | const image_t & | mask |
| ) |  |  |

This function takes an image and a mask as input and copy the mask in the alpha channel of the image.

The function works only if both images are exactly of the same size (i.e. same width and height.)

Parameters:

  `[in]` | im | The image receiving the mask as its alpha channel
  `[in]` | mask | The image used as the alpha channel

Returns:
  An error code or ErrorManager::ERROR_CODE_NONE

References sswf::ErrorManager::ERROR_CODE_NONE, sswf::ErrorManager::ERROR_CODE_SIZE_MISMATCH, sswf::TagImage::image_t::f_alpha, sswf::TagImage::image_t::f_data, sswf::TagImage::image_t::f_height, sswf::TagImage::image_t::f_width, and sswf::TagBase::OnError().

Referenced by SetFilename().

sswf::TagImage::SetDeblock | ( | int | deblock | ) | `[inline]`

When displaying an image using the JPEG format, one can choose the deblock filter parameter. This is done with this function.

The deblocking is a number from 0 to 256. (An 8.8 fixed value of 0.0 to 1.0)

Parameters:

  `[in]` | deblock | The deblocking filter parameter used to display the JPEG image.

References f_deblock.

ErrorManager::error_code_t TagImage::SetFilename | ( | const char * | image,
|  | const char * | mask |
| ) |  |  |

read one or two JPEG or targa files when filenames are specified

Returns:
  An error code or ErrorManager::ERROR_CODE_NONE

References sswf::ErrorManager::ERROR_CODE_NONE, sswf::ErrorManager::ERROR_CODE_UNKNOWN_FORMAT, sswf::TagImage::image_t::f_alpha, f_colormap, f_count, sswf::TagImage::image_t::f_data, f_image, LoadJPEG(), LoadTGA(), sswf::MemoryManager::MemClean(), sswf::MemoryManager::MemFree(), and SetAlpha().

sswf::TagImage::SetFormat | ( | image_format_t | format | ) | `[inline]`

This function setst the format that the TagImage will use when saving the image.

The possible formats are:

            IMAGE_FORMAT_LOSSLESS_BEST
            IMAGE_FORMAT_LOSSLESS_8
            IMAGE_FORMAT_LOSSLESS_16
            IMAGE_FORMAT_LOSSLESS_32
            IMAGE_FORMAT_JPEG

The IMAGE_FORMAT_LOSSLESS_BEST format is used to let the system choose between the different LOSSLESS formats. It is lossless meaning that the best to ensure the smallest possible image is used without losing even one pixel (which often means using LOSSLESS 32.)

Parameters:

  `[in]` | format | One of the IMAGE_FORMAT_...

References f_format.

void TagImage::SetImage | ( | long | width,
|  | long | height,
|  | unsigned char * | data,
|  | bool | alpha = `false`,
|  | long | count = `0`,
|  | unsigned char * | colormap = `0` |
| ) |  |  |

This function saves the specified image in the TagImage object.

The image is specified by all of its characteristics: width, height, buffer (data), whether it includes an alpha channel and whether it has a colormap.

The data pointer is saved as is in the image structure. This means the TagImage becomes the owner of that pointer. It will automatically free it with a call to MemFree().

It is expected that you use your image memory allocator to allocate this buffer:

            TagImage my_image;

            ...
            data = my_image->MemAlloc(width * height * 4, "My Image");
            ...
            my_image->SetImage(...);
            ...
            // MemFree(data) -- done by the TagImage destructor when necessary
            ...

Todo:
  The colormap parameter is currently ignored.

Parameters:

  `[in]` | width | The width of the image
  `[in]` | height | The height of the image
  `[in]` | data | The pointer to the data buffer (ARGB)
  `[in]` | alpha | Whether the alpha channel is valid
  `[in]` | count | The size of the colormap
  `[in]` | colormap | The colors in the colormap (RGBA)

References sswf::TagImage::image_t::f_alpha, f_colormap, f_count, sswf::TagImage::image_t::f_data, sswf::TagImage::image_t::f_height, f_image, sswf::TagImage::image_t::f_width, and sswf::MemoryManager::MemClean().

sswf::TagImage::SetQuality | ( | int | quality | ) | `[inline]`

When saving an image using the JPEG format, one can choose the quality of the image. This is done with this function.

The quality is a number from 0 to 100.

Parameters:

  `[in]` | quality | The quality used to compress the image to a JPEG

References f_quality.

TagBase::swf_type_t TagImage::TypeFlags | ( | void |  | ) | const`[virtual]`

This function defines the type flags for a tag image.

It is a definition and it has an identifier.

Returns:
  SWF_TYPE_DEFINE and SWF_TYPE_HAS_ID

Implements sswf::TagBase.

References SWF_TYPE_DEFINE, and SWF_TYPE_HAS_ID.

## Member Data Documentation

unsigned char* sswf::TagImage::f_colormap`[private]`

Referenced by SetFilename(), SetImage(), and TagImage().

long sswf::TagImage::f_count`[private]`

Referenced by SetFilename(), SetImage(), and TagImage().

int sswf::TagImage::f_deblock`[private]`

Referenced by PreSave(), Save(), SetDeblock(), and TagImage().

image_format_t sswf::TagImage::f_format`[private]`

Referenced by PreSave(), Save(), SetFormat(), and TagImage().

image_t sswf::TagImage::f_image`[private]`

Referenced by GetImageData(), PreSave(), Save(), SaveJPEG(), SetFilename(), SetImage(), and TagImage().

int sswf::TagImage::f_quality`[private]`

Referenced by SaveJPEG(), SetQuality(), and TagImage().

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

- libsswf.h
- libsswf_tag_image.c++