Kicking it Olde Sküül! Burgerlib on Github Follow Olde Sküül on Twitter Burgerbecky on LinkedIn Burgerbecky on LinkedIn
Loading...
Searching...
No Matches
Burger::FileGIF Class Reference

Reads and writes GIF files. More...

Collaboration diagram for Burger::FileGIF:

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_tGetPalette (void) const
 Get the file image's palette.
 
RGBAWord8_tGetPalette (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 FileGIFNew (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
pOutputPointer 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
pOutputPointer to the output stream to store the file image
pImagePointer to a valid Image structure containing the image data
uDelayTime 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
pOutputPointer to the output stream to store the file image
pImagePointer to a valid Image structure containing the image data
uLoopCountValue 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
pOutputPointer to an Image record to store the new image into
pInputPointer 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
pOutputPointer to an Image record to store the new image into
pInputPointer 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
pInputPointer 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
pInputPointer 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
pOutputPointer to an Image record to store the new image into
pInputPointer 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
pOutputPointer to the output stream to store the file image
pImagePointer 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
bAspectRatioNew 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
bBackGroundColorIndexNew 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
uFrameDelayTime 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
uLoopCountNew 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
pInputPointer to the palette to copy
uStartIndexColor index of the 256 color internal palette to start modification
uPaletteSizeNumber 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
pInputPointer to the palette to copy
uStartIndexColor index of the 256 color internal palette to start modification
uPaletteSizeNumber 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
bTransparentColorEnableFALSE 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
bTransparentColorNew 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
pOutputPointer 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
pOutputPointer 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
pOutputPointer 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
pOutputPointer to the output stream
pInputPointer 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
pOutputPointer 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.