Reads and writes GIF files. More...

Collaboration diagram for Burger::FileGIF:

[legend]

Public Member Functions
const char *	ParseHeader (InputMemoryStream *pInput)
	Parse the GIF header.

const char *	ParseExtension (InputMemoryStream *pInput)
	Process a GIF extension block.

const char *	ParseImage (Image pOutput, InputMemoryStream pInput)
	Parse a GIF image block.

uint_t	WriteHeader (OutputMemoryStream *pOutput)
	Write a GIF header.

uint_t	WriteImage (OutputMemoryStream pOutput, const Image pInput)
	Write a frame using GIF compression.

uint_t	WriteExtensionNetScape20 (OutputMemoryStream *pOutput)
	Write out the loop count.

uint_t	WriteExtensionGraphicControl (OutputMemoryStream *pOutput)
	Write out a GIF Graphic Control Extension.

uint_t	WriteTerminator (OutputMemoryStream *pOutput)
	Write out the terminator descriptor.

	FileGIF ()
	Default constructor.

uint_t	Load (Image pOutput, InputMemoryStream pInput)
	Parses a GIF file.

uint_t	LoadNextFrame (Image pOutput, InputMemoryStream pInput)
	Parses a GIF file.

uint_t	Save (OutputMemoryStream pOutput, const Image pImage)
	Write an Image structure out as a GIF file image.

uint_t	AnimationSaveStart (OutputMemoryStream pOutput, const Image pImage, uint_t uLoopCount=0)
	Start writing a GIF animation file.

uint_t	AnimationSaveFrame (OutputMemoryStream pOutput, const Image pImage, uint_t uDelay=0)
	Write out an image frame to a GIF animation file.

uint_t	AnimationSaveFinish (OutputMemoryStream *pOutput)
	Wrap up writing a GIF animation file.

uint_t	GetAspectRatio (void) const
	Get the file image's pixel aspect ratio.

void	SetAspectRatio (uint_t bAspectRatio)
	Set the file image's aspect ratio.

uint_t	GetBackgroundColorIndex (void) const
	Get the file image's background color index.

void	SetBackgroundColorIndex (uint_t bBackGroundColorIndex)
	Set the file image's background color index.

uint_t	GetTransparentColorIndex (void) const
	Get the file image's transparent color index.

void	SetTransparentColorIndex (uint_t bTransparentColor)
	Set the file image's transparent color index.

uint_t	GetTransparentColorEnable (void) const
	Return TRUE if the frame has a transparent color index.

void	SetTransparentColorEnable (uint_t bTransparentColorEnable)
	Enable/disable the file image's transparent color index.

uint_t	GetLoopCount (void) const
	Get the file image's animation loop count.

void	SetLoopCount (uint_t uLoopCount)
	Set the file image's loop count.

uint_t	GetFrameDelay (void) const
	Get the current animation frame delay.

void	SetFrameDelay (uint_t uFrameDelay)
	Set the animation frame delay.

const RGBAWord8_t *	GetPalette (void) const
	Get the file image's palette.

RGBAWord8_t *	GetPalette (void)
	Get the file image's palette.

void	SetPalette (const RGBWord8_t *pInput, uint_t uStartIndex=0, uint_t uPaletteSize=256)
	Set the file image's palette (RGB)

void	SetPalette (const RGBAWord8_t *pInput, uint_t uStartIndex=0, uint_t uPaletteSize=256)
	Set the file image's palette (RGBA)

Static Public Member Functions
static FileGIF *	New (void)
	Allocate and initialize a FileGIF.

Static Public Attributes
static const uint32_t	FILETYPE = 0x47494666
	'GIFf' Mac File type for GIF files (Byte swapped on little endian machines)

static const uint32_t	AUXTYPE = 0x6F676C65
	'ogle' Mac creator code for GIF files (Byte swapped on little endian machines)

Private Attributes
RGBAWord8_t	m_Palette [256]
	Palette found in the image.

RGBAWord8_t	m_GlobalPalette [256]
	Global GIF palette.

uint_t	m_uLogicalWidth
	Parsed width of the image.

uint_t	m_uLogicalHeight
	Parsed height of the image.

uint_t	m_uColorShift
	Shift value for palette resolution.

uint16_t	m_uLoopCount
	GIF animation loop count.

uint16_t	m_uFrameDelay
	GIF animation time delay for current frame.

uint8_t	m_bTransparentColor
	GIF transparent color index.

uint8_t	m_bTransparentColorEnable
	TRUE if this frame uses a transparent color index

uint8_t	m_bAspectRatio
	GIF aspect ratio.

uint8_t	m_bBackgroundColorIndex
	GIF background color.

uint8_t	m_bGIF89
	GIF file read is 89 format, not 87.

Detailed Description

Reads and writes GIF files.

This class will read and write out GIF files and use Image class instances as data transporters

It follows the specification found in spec-gif89a.txt

See also: GIFEncoder or GIFDecoder

Constructor & Destructor Documentation

◆ FileGIF()

Burger::FileGIF::FileGIF ( )

Default constructor.

Initializes all extra file data to defaults

Member Function Documentation

◆ AnimationSaveFinish()

uint_t Burger::FileGIF::AnimationSaveFinish ( OutputMemoryStream * pOutput )

Wrap up writing a GIF animation file.

Finish writing out an in-progress animation stream. After issuing this call, the OutputMemoryStream has a valid GIF file image.

Parameters

pOutput Pointer to the output stream to store the file image

Returns: Zero if successful

See also: AnimationSaveStart(OutputMemoryStream *,const Image *,uint_t) or AnimationSaveFrame(OutputMemoryStream *,const Image *,uint_t)

◆ AnimationSaveFrame()

uint_t Burger::FileGIF::AnimationSaveFrame	(	OutputMemoryStream *	pOutput,
		const Image *	pImage,
		uint_t	uDelay = 0 )

Write out an image frame to a GIF animation file.

Append a new frame of animation data to the GIF file being created.

Parameters

pOutput	Pointer to the output stream to store the file image
pImage	Pointer to a valid Image structure containing the image data
uDelay	Time delay between frames in 1/100ths of a second (0 = no delay)

Returns: Zero if successful

See also: AnimationSaveStart(OutputMemoryStream *,const Image *,uint_t) or AnimationSaveFinish(OutputMemoryStream *)

◆ AnimationSaveStart()

uint_t Burger::FileGIF::AnimationSaveStart	(	OutputMemoryStream *	pOutput,
		const Image *	pImage,
		uint_t	uLoopCount = 0 )

Start writing a GIF animation file.

Given an image in 8 bit format, obtain the size of the image and write out the image size and initial palette it out to the GIF file.

Note: NO IMAGE DATA is written with this call. Call AnimationSaveFrame() to output the image data; Before calling this function, make sure the color palette for the pixel data is already set with a call to SetPalette(const RGBWord8_t *,uint_t,uint_t). This palette is used for the global palette that's included in the GIF file header.

Parameters

pOutput	Pointer to the output stream to store the file image
pImage	Pointer to a valid Image structure containing the image data
uLoopCount	Value to store in the GIF file loop count record. 0 = infinite loop

Returns: Zero if successful

See also: AnimationSaveFrame(OutputMemoryStream *,const Image *,uint_t) or AnimationSaveFinish(OutputMemoryStream *)

◆ GetAspectRatio()

uint_t Burger::FileGIF::GetAspectRatio ( void ) const

inline

Get the file image's pixel aspect ratio.

Factor used to compute an approximation of the aspect ratio of the pixel in the original image. If the value of the field is not 0, this approximation of the aspect ratio is computed based on the formula:

Aspect Ratio = (GetAspectRatio() + 15) / 64 (15 is for rounding up)

The Pixel Aspect Ratio is defined to be the quotient of the pixel's width over its height. The value range in this field allows specification of the widest pixel of 4:1 to the tallest pixel of 1:4 in increments of 1/64th.

Returns: The GIF formatted aspect ratio value

See also: SetAspectRatio(uint_t), GetBackgroundColorIndex(void) const or GetLoopCount(void) const

◆ GetBackgroundColorIndex()

uint_t Burger::FileGIF::GetBackgroundColorIndex ( void ) const

inline

Get the file image's background color index.

Return the GIF file header's background color index. This value is usually set to zero.

Returns: The color index to use as the background color

See also: SetBackgroundColorIndex(uint_t), GetAspectRatio(void) const or GetLoopCount(void) const

◆ GetFrameDelay()

uint_t Burger::FileGIF::GetFrameDelay ( void ) const

inline

Get the current animation frame delay.

Animated GIF files have a delay time in 1/100ths of a second. This function, when called after parsing a frame, will have the time delay the player should wait before displaying the next frame in the sequence. Zero means no delay.

Returns: The time delay before showing the next frame in 1/100ths of a second

See also: SetFrameDelay(uint_t)

◆ GetLoopCount()

uint_t Burger::FileGIF::GetLoopCount ( void ) const

inline

Get the file image's animation loop count.

GIF files have a special record to contain the number of times the animation should loop. If a file is written as an animation, this record should be set to a count, or leave as zero meaning this animation should loop forever.

Returns: The GIF animation loop count (Zero means forever)

See also: SetLoopCount(uint_t), GetAspectRatio(void) const or GetBackgroundColorIndex(void) const

◆ GetPalette() [1/2]

RGBAWord8_t * Burger::FileGIF::GetPalette ( void )

inline

Get the file image's palette.

Obtain a pointer to the 256 entry RGBA color palette found in the GIF file

Returns: Pointer to the 256 entry RGBAWord8_t palette

See also: Burger::FileGIF::GetPalette(void) const

◆ GetPalette() [2/2]

const RGBAWord8_t * Burger::FileGIF::GetPalette ( void ) const

inline

Get the file image's palette.

Obtain a constant pointer to the 256 entry RGBA color palette found in the GIF file

Returns: Constant pointer to the 256 entry RGBAWord8_t palette

See also: Burger::FileGIF::GetPalette(void)

◆ GetTransparentColorEnable()

uint_t Burger::FileGIF::GetTransparentColorEnable ( void ) const

inline

Return TRUE if the frame has a transparent color index.

Return the GIF file frame's transparent color index enable flat. This value is usually set to FALSE, meaning there is no transparent color index and can change from frame to frame.

Returns: FALSE if there is no transparent color index, TRUE if transparency is enabled

See also: SetTransparentColorEnable(uint_t)

◆ GetTransparentColorIndex()

uint_t Burger::FileGIF::GetTransparentColorIndex ( void ) const

inline

Get the file image's transparent color index.

Return the GIF file frame's transparent color index. This value is usually set to zero and can change from frame to frame.

Returns: The color index to use as the transparent color

See also: SetTransparentColorIndex(uint_t)

◆ Load()

uint_t Burger::FileGIF::Load	(	Image *	pOutput,
		InputMemoryStream *	pInput )

Parses a GIF file.

Read in a GIF file and set the extra variables

Will parse an 8 bit compressed and uncompressed GIF files.

Note: A descriptive error message is passed to Debug::Warning()

Parameters

pOutput	Pointer to an Image record to store the new image into
pInput	Pointer to a memory stream that has a GIF file image

Returns: Zero for success or non-zero on failure

◆ LoadNextFrame()

uint_t Burger::FileGIF::LoadNextFrame	(	Image *	pOutput,
		InputMemoryStream *	pInput )

Parses a GIF file.

Read in a GIF file and set the extra variables

Will parse an 8 bit compressed and uncompressed GIF files.

Note: A descriptive error message is passed to Debug::Warning()

Parameters

pOutput	Pointer to an Image record to store the new image into
pInput	Pointer to a memory stream that has a GIF file image

Returns: Zero for success or non-zero on failure

◆ New()

Burger::FileGIF *BURGER_API Burger::FileGIF::New ( void )

static

Allocate and initialize a FileGIF.

Returns: A pointer to a default FileGIF class or NULL if out of memory

See also: Delete(const T *)

◆ ParseExtension()

const char * Burger::FileGIF::ParseExtension ( InputMemoryStream * pInput )

Process a GIF extension block.

For all GIF blocks that are identified with a '!', process them

Parameters

pInput Pointer to the input stream

Returns: NULL if the header was read successfully, or a pointer to an English error message with the reason for failure.

◆ ParseHeader()

const char * Burger::FileGIF::ParseHeader ( InputMemoryStream * pInput )

Parse the GIF header.

Parameters

pInput Pointer to the input stream

As per section 17 of the GIF specification, read in the 13 byte header and set up the file global information

Returns: NULL if the header was read successfully, or a pointer to an English error message with the reason for failure.

◆ ParseImage()

const char * Burger::FileGIF::ParseImage	(	Image *	pOutput,
		InputMemoryStream *	pInput )

Parse a GIF image block.

Parameters

pOutput	Pointer to an Image record to store the new image into
pInput	Pointer to the input stream

◆ Save()

uint_t Burger::FileGIF::Save	(	OutputMemoryStream *	pOutput,
		const Image *	pImage )

Write an Image structure out as a GIF file image.

Given an image in 8 bit format, write it out as a GIF file. No other image data formats are supported, this is a limitation to the GIF file format.

Note: Before calling this function, make sure the color palette for the pixel data is already set with a call to SetPalette(const RGBWord8_t *,uint_t,uint_t)

Parameters

pOutput	Pointer to the output stream to store the file image
pImage	Pointer to a valid Image structure containing the image data

Returns: Zero if successful

◆ SetAspectRatio()

void Burger::FileGIF::SetAspectRatio ( uint_t bAspectRatio )

inline

Set the file image's aspect ratio.

Sets the GIF file header's aspect ratio. Use zero for default.

Parameters

bAspectRatio New GIF formatted aspect ratio token

See also: GetAspectRatio(void) const, SetBackgroundColorIndex(uint_t) or SetLoopCount(uint_t)

◆ SetBackgroundColorIndex()

void Burger::FileGIF::SetBackgroundColorIndex ( uint_t bBackGroundColorIndex )

inline

Set the file image's background color index.

Sets the GIF file header's background color index

Parameters

bBackGroundColorIndex New GIF background color index

See also: GetBackgroundColorIndex(void) const, SetAspectRatio(uint_t) or SetLoopCount(uint_t)

◆ SetFrameDelay()

void Burger::FileGIF::SetFrameDelay ( uint_t uFrameDelay )

inline

Set the animation frame delay.

Before appending a new frame to an animation, set this value to the desired frame delay to pause before showing the next frame in 1/100ths of a second.

Parameters

uFrameDelay Time delay before the next frame

See also: GetFrameDelay(void) const

◆ SetLoopCount()

void Burger::FileGIF::SetLoopCount ( uint_t uLoopCount )

inline

Set the file image's loop count.

Set the GIF animation's loop count. Only used when writing animated gifs

Note: This value is written as a uint16_t. Any values larger than 65535 will be truncated.

Parameters

uLoopCount New animation loop count

See also: GetLoopCount(void) const, SetAspectRatio(uint_t) or SetBackgroundColorIndex(uint_t)

◆ SetPalette() [1/2]

void Burger::FileGIF::SetPalette	(	const RGBAWord8_t *	pInput,
		uint_t	uStartIndex = 0,
		uint_t	uPaletteSize = 256 )

inline

Set the file image's palette (RGBA)

Given a pointer to a palette, copy the colors into this class for writing to an 8 bit GIF file.

If the starting index is greater than 255, this function does nothing. If the color entry count exceeds 256 colors, the remaining colors are ignored to prevent buffer overruns

Parameters

pInput	Pointer to the palette to copy
uStartIndex	Color index of the 256 color internal palette to start modification
uPaletteSize	Number of color entries in the palette (Maximum 256)

See also: SetPalette(const RGBWord8_t *,uint_t,uint_t)

◆ SetPalette() [2/2]

void Burger::FileGIF::SetPalette	(	const RGBWord8_t *	pInput,
		uint_t	uStartIndex = 0,
		uint_t	uPaletteSize = 256 )

inline

Set the file image's palette (RGB)

Given a pointer to a palette, copy the colors into this class for writing to an 8 bit GIF file. Since the Alpha is missing from the input, each entry set will have the alpha set to zero.

If the starting index is greater than 255, this function does nothing. If the color entry count exceeds 256 colors, the remaining colors are ignored to prevent buffer overruns

Parameters

pInput	Pointer to the palette to copy
uStartIndex	Color index of the 256 color internal palette to start modification
uPaletteSize	Number of color entries in the palette (Maximum 256)

See also: SetPalette(const RGBAWord8_t *,uint_t,uint_t)

◆ SetTransparentColorEnable()

void Burger::FileGIF::SetTransparentColorEnable ( uint_t bTransparentColorEnable )

inline

Enable/disable the file image's transparent color index.

Enables or disables the GIF file frame's transparent color index. It must be set before a frame is converted into GIF format. Pass zero to disable transparency, non-zero to enable it.

Parameters

bTransparentColorEnable FALSE to disable transparency, TRUE to enable it

See also: GetTransparentColorIndex(void) const

◆ SetTransparentColorIndex()

void Burger::FileGIF::SetTransparentColorIndex ( uint_t bTransparentColor )

inline

Set the file image's transparent color index.

Sets the GIF file frame's transparent color index. It must be set before a frame is converted into GIF format.

Parameters

bTransparentColor New GIF frame transparent color index

See also: GetTransparentColorIndex(void) const

◆ WriteExtensionGraphicControl()

uint_t Burger::FileGIF::WriteExtensionGraphicControl ( OutputMemoryStream * pOutput )

Write out a GIF Graphic Control Extension.

Insert the GIF extension for Graphic Control as per section 23 of the gif98a specification. This record contains the transparent color and the frame delay for a gif animation

Parameters

pOutput Pointer to the output stream

Returns: 0 for no error, non zero on error

◆ WriteExtensionNetScape20()

uint_t Burger::FileGIF::WriteExtensionNetScape20 ( OutputMemoryStream * pOutput )

Write out the loop count.

Insert the GIF extension of "NETSCAPE2.0" that contains the loop count for a GIF animation file.

Parameters

pOutput Pointer to the output stream

Returns: 0 for no error, non zero on error

See also: SetLoopCount(uint_t) or GetLoopCount(void) const

◆ WriteHeader()

uint_t Burger::FileGIF::WriteHeader ( OutputMemoryStream * pOutput )

Write a GIF header.

As per section 17 of the GIF specification, write out a the 13 byte header from the file global information

Parameters

pOutput Pointer to the output stream

Returns: 0 for no error, non zero on error

◆ WriteImage()

uint_t Burger::FileGIF::WriteImage	(	OutputMemoryStream *	pOutput,
		const Image *	pInput )

Write a frame using GIF compression.

Compress the image using GIF LZW and write out the data into the stream. If the palette was changed, write out a new local palette.

Parameters

pOutput	Pointer to the output stream
pInput	Pointer to the pixel data

Returns: 0 for no error, non zero on error

◆ WriteTerminator()

uint_t Burger::FileGIF::WriteTerminator ( OutputMemoryStream * pOutput )

Write out the terminator descriptor.

Insert a ';' at the end of the GIF file being written to terminate the file

Parameters

pOutput Pointer to the output stream

Returns: 0 for no error, non zero on error

Member Data Documentation

◆ AUXTYPE

const uint32_t Burger::FileGIF::AUXTYPE = 0x6F676C65

static

'ogle' Mac creator code for GIF files (Byte swapped on little endian machines)

◆ FILETYPE

const uint32_t Burger::FileGIF::FILETYPE = 0x47494666

static

'GIFf' Mac File type for GIF files (Byte swapped on little endian machines)

◆ m_bAspectRatio

uint8_t Burger::FileGIF::m_bAspectRatio

private

GIF aspect ratio.

◆ m_bBackgroundColorIndex

uint8_t Burger::FileGIF::m_bBackgroundColorIndex

private

GIF background color.

◆ m_bGIF89

uint8_t Burger::FileGIF::m_bGIF89

private

GIF file read is 89 format, not 87.

◆ m_bTransparentColor

uint8_t Burger::FileGIF::m_bTransparentColor

private

GIF transparent color index.

◆ m_bTransparentColorEnable

uint8_t Burger::FileGIF::m_bTransparentColorEnable

private

TRUE if this frame uses a transparent color index

◆ m_GlobalPalette

RGBAWord8_t Burger::FileGIF::m_GlobalPalette[256]

private

Global GIF palette.

◆ m_Palette

RGBAWord8_t Burger::FileGIF::m_Palette[256]

private

Palette found in the image.

◆ m_uColorShift

uint_t Burger::FileGIF::m_uColorShift

private

Shift value for palette resolution.

◆ m_uFrameDelay

uint16_t Burger::FileGIF::m_uFrameDelay

private

GIF animation time delay for current frame.

◆ m_uLogicalHeight

uint_t Burger::FileGIF::m_uLogicalHeight

private

Parsed height of the image.

◆ m_uLogicalWidth

uint_t Burger::FileGIF::m_uLogicalWidth

private

Parsed width of the image.

◆ m_uLoopCount

uint16_t Burger::FileGIF::m_uLoopCount

private

GIF animation loop count.

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ FileGIF()

Member Function Documentation

◆ AnimationSaveFinish()

◆ AnimationSaveFrame()

◆ AnimationSaveStart()

◆ GetAspectRatio()

◆ GetBackgroundColorIndex()

◆ GetFrameDelay()

◆ GetLoopCount()

◆ GetPalette() [1/2]

◆ GetPalette() [2/2]

◆ GetTransparentColorEnable()

◆ GetTransparentColorIndex()

◆ Load()

◆ LoadNextFrame()

◆ New()

◆ ParseExtension()

◆ ParseHeader()

◆ ParseImage()

◆ Save()

◆ SetAspectRatio()

◆ SetBackgroundColorIndex()

◆ SetFrameDelay()

◆ SetLoopCount()

◆ SetPalette() [1/2]

◆ SetPalette() [2/2]

◆ SetTransparentColorEnable()

◆ SetTransparentColorIndex()

◆ WriteExtensionGraphicControl()

◆ WriteExtensionNetScape20()

◆ WriteHeader()

◆ WriteImage()

◆ WriteTerminator()

Member Data Documentation

◆ AUXTYPE

◆ FILETYPE

◆ m_bAspectRatio

◆ m_bBackgroundColorIndex

◆ m_bGIF89

◆ m_bTransparentColor

◆ m_bTransparentColorEnable

◆ m_GlobalPalette

◆ m_Palette

◆ m_uColorShift

◆ m_uFrameDelay

◆ m_uLogicalHeight

◆ m_uLogicalWidth

◆ m_uLoopCount