COST (GBP)

4.00

Computing › Graphics › Formats ›

GIF

Implements the GIF file format

Controller: CodeCogs

Contents

Interface
Class GIF
Page Comments

Dependents

Interface

C++

#include <codecogs/computing/graphics/formats/gif.h>

using namespace Graphics::Formats;

class

GIF

Implements methods to manipulate GIF images.

[constructor]	GIF () Implicit constructor
[constructor]	GIF (unsigned char *buffer) Constructor that reads GIF data from the given buffer.
std::vector<RGBValue>	colorTable the color table array
void	createCanvas () Creates the canvas for the given dimensions.
void	setPixel (int x, int y, unsigned char colorIndex) Sets the pixel at the given coordinates to the specified color.
unsigned char	getPixel (int x, int y) Returns the color of the pixel at the given coordinates.
void	readFromBuffer (unsigned char *buffer) Reads GIF data from the given buffer
int	writeToBuffer (unsigned char* &buffer) Writes GIF data to the given buffer
std::string	getVersion () Returns the version of the currently loaded GIF.
unsigned short	getWidth () Returns the width of the current canvas.
void	setWidth (unsigned short width) Sets the width of the current canvas.
unsigned short	getImageWidth () Returns the width of the image inside the GIF canvas.
void	setImageWidth (unsigned short imageWidth) Sets the width of the image inside the GIF's canvas.
unsigned short	getHeight () Returns the height of the current canvas.
void	setHeight (unsigned short height) Sets the height of the current canvas.
unsigned short	getImageHeight () Returns the height of the image inside the GIF canvas.
void	setImageHeight (unsigned short imageHeight) Sets the height of the image inside the GIF's canvas.
unsigned char	getBitsPerPixel () Returns the color depth for the currently loaded GIF.
bool	isTransparent () Specifies whether the GIF has transparency enabled.
void	setTransparency (bool transparent) Enables or disables transparency for the current GIF.
unsigned char	getTransparentColor () Returns the transparent color.
void	setTransparentColor (unsigned char transparentColorIndex) Sets the transparent color.
unsigned char	getBackgroundColor () Returns the current background color.
void	setBackgroundColor (unsigned char bkColor) Sets the index of the background color to the specified value.
unsigned short	getImageLeftOffset () Returns the left offset of the image inside the canvas.
void	setImageLeftOffset (unsigned short imageLeftOffset) Sets the left offset of the image inside the canvas.
unsigned short	getImageTopOffset () Returns the left offset of the image inside the canvas.
void	setImageTopOffset (unsigned short imageTopOffset) Sets the top offset of the image inside the canvas.
unsigned char	m_initialCodeSize the initial code size used when encoding and decoding image data
IO::Compression::VariableLZW	m_coder the variable compression size LZW coder used when encoding and decoding GIF image data
std::string	m_imageData the uncompressed image data, stored as a string
std::string	m_ver GIF version
unsigned short	m_width width and height of the GIF image
unsigned char	m_bpp bits per pixel
unsigned char	m_pixelAspectRatio pixel aspect ratio if this value is nonzero, the pixel width and height are not equal (m_pixelRatio + 15)/64 is the pixel width divided by the pixel height
bool	m_transparent specifies whether the GIF is transparent
unsigned char	m_transparentColorIndex the index of the transparent color in the color table
unsigned char	m_bkColor the index of the background color in the color table
bool	m_GCTFlag specifies whether a global color table exists
unsigned short	m_GCTSize global color table size
bool	m_GCTSortFlag specifies whether the colors in the global color table are sorted in order of importance
unsigned short	m_imageLeftOffset left offset of the image within the logical screen
unsigned short	m_imageTopOffset top offset of the image within the logical screen
unsigned short	m_imageWidth GIF image width
unsigned short	m_imageHeight GIF image height
bool	m_LCTFlag specifies whether the image uses a local color table
unsigned short	m_LCTSize local color table size
bool	m_LCTSortFlag specifies whether the colors in the local color table are sorted in order of importance
void	readHeader (unsigned char* &buffer)
void	writeHeader (std::string &buffer)
void	readImageHeader (unsigned char* &buffer)
void	writeImageHeader (std::string &buffer)

Overview

This module implements a class that allows you to load, save and manipulate non-animated GIF content. It also allows you to set various parameters of the image, like transparency, color table, and others.

The GIF format uses a lossless data compression algorithm to store its image data. The algorithm is a modification of the classic Lempel-Ziv-Welch (LZW) dictionary method, using variable code sizes during the compression process. The modified LZW algorithm is available as IO/Compression/VariableLZW.

The GIF class can be used in a variety of circumstances, from extracting information about a GIF file, modifying a GIF and saving it, to creating a GIF image from scratch and saving it to disk.

Expand the following example to see how you can display information about a GIF.

#include <codecogs/graphics/formats/gif.h>
#include <iostream>
#include <fstream>
 
int main()
{
  // name of the file to open (without the .gif extension)
  std::string fileName = "hat.gif";
 
  // size of the file to open
  int fileSize = 606;
 
  // create a temporary buffer into which the whole file is loaded
  unsigned char *buffer = new unsigned char[fileSize];
 
  // open the file for reading
  std::ifstream inf(fileName.c_str(), std::ios_base::in | std::ios_base::binary);
 
  // read all its contents into the buffer
  inf.read((char *)buffer, fileSize);
 
  // close the file
  inf.close();
 
  // decode the data in the buffer and store it in a GIF object
  Graphics::Formats::GIF image(buffer);
 
  // the buffer can now be removed from memory
  delete [] buffer;
 
  // display some information about the GIF image
  std::cout << "          Version: " << image.getVersion() << std::endl;
  std::cout << "            Width: " << image.getWidth() << std::endl;
  std::cout << "           Height: " << image.getHeight() << std::endl;
 
  std::cout << std::endl;
 
  std::cout << "   Bits per pixel: " << (int) image.getBitsPerPixel() << std::endl;
  std::cout << "     Transparency: " << (image.isTransparent() ? "On" : "Off") << std::endl;
 
  std::cout << std::endl;
 
  std::cout << " Color table size: " << image.colorTable.size() << std::endl;
  std::cout << " Background color: " << (int) image.getBackgroundColor() << std::endl;
  if (image.isTransparent())
  {
    std::cout << "Transparent color: " << (int) image.getTransparentColor() << std::endl;
  }
 
  std::cout << std::endl;
 
  return 0;
}

Input file:

MISSING IMAGE!

378/hat.gif cannot be found in /users/378/hat.gif. Please contact the submission author.

Output:

Version: GIF89a
            Width: 29
           Height: 28
 
   Bits per pixel: 8
     Transparency: On
 
 Color table size: 64
 Background color: 42
Transparent color: 42

The main input-output methods provided by this class are readFromBuffer and writeToBuffer, while the actual GIF manipulation is achived by changing the colorTable public variable, or by calling the setPixel method. The next example reads a GIF file from the disk, adds a border to it using the setPixel method and then writes the new GIF file to disk.

#include <codecogs/graphics/formats/gif.h>
#include <iostream>
#include <fstream>
 
int main()
{
  // name of the file to open (without the .gif extension)
  std::string fileName = "hat";
 
  // size of the file to open
  int fileSize = 606;
 
  // create a temporary buffer into which the whole file is loaded
  unsigned char *buffer = new unsigned char[fileSize];
 
  // open the file for reading
  std::ifstream inf((fileName + ".gif").c_str(), std::ios_base::in | std::ios_base::binary);
 
  // read all its contents into the buffer
  inf.read((char *)buffer, fileSize);
 
  // close the file
  inf.close();
 
  // decode the data in the buffer and store it in a GIF object
  Graphics::Formats::GIF image(buffer);
 
  // the buffer can now be removed from memory
  delete [] buffer;
 
  // draw a border around the image using the setPixel() method
 
  // store the width and height of the image
  int xmax = image.getWidth(), ymax = image.getHeight();
 
  // index of the color to draw the border with
  unsigned char color = 0;
 
  // draw the horizontal lines
  for (int x = 0; x < xmax; ++x)
  {
    image.setPixel(x, 0, color);
    image.setPixel(x, ymax - 1, color);
  }
 
  // draw the vertical lines
  for (int y = 0; y < ymax; ++y)
  {
    image.setPixel(0, y, color);
    image.setPixel(xmax - 1, y, color);
  }
 
  // encode the GIF image data into the buffer (previously declared)
  // "size" stores the size of the resulting encoded data
  int size = image.writeToBuffer(buffer);
 
  // open the file for writing
  std::ofstream outf((fileName + "_border.gif").c_str(), std::ios_base::out |
std::ios_base::binary);
 
  // write all the data in the buffer into the file
  outf.write((char *)buffer, size);
 
  // close the file
  outf.close();
 
  // the buffer can now be removed from memory
  delete [] buffer;
 
  return 0;
}

Input file:

MISSING IMAGE!

378/hat.gif cannot be found in /users/378/hat.gif. Please contact the submission author.

Output file:

MISSING IMAGE!

378/hat_border.gif cannot be found in /users/378/hat_border.gif. Please contact the submission author.

If you would like to create the whole GIF image from scratch, then you first need to make sure the canvas is set up properly, i.e. you need to set the dimensions of the GIF and call the createCanvas method to create the GIF's canvas on which you can draw. The next example draws a cross on a 50x50 canvas and saves it to disk.

#include <codecogs/graphics/formats/gif.h>
#include <iostream>
#include <fstream>
 
int main()
{
  // create a GIF object
  Graphics::Formats::GIF image;
 
  // add the colors we need to the color table
 
  // enable transparency
  image.setTransparency(true);
 
  // add the background transparent color
  image.colorTable.push_back(Graphics::Formats::RGBValue(0, 0, 0));
 
  // set the transparent color's index (0 in this case)
  image.setTransparentColor(0);
 
  // set the background color to the transparent color
  image.setBackgroundColor(0);
 
  // add the red color to draw with
  image.colorTable.push_back(Graphics::Formats::RGBValue(255, 0, 0));
 
  // set the image dimensions
  image.setWidth(50);
  image.setImageWidth(50);
  image.setHeight(50);
  image.setImageHeight(50);
 
  // create the canvas with the given dimensions
  image.createCanvas();
 
  // draw the cross
  unsigned short xmax = image.getWidth();
  for (unsigned short i = 0; i < xmax; ++i)
  {
    image.setPixel(i, i, 1);
    image.setPixel(xmax - i - 1, i, 1);
  }
 
  // name of the file to write to
  std::string fileName = "cross.gif";
 
  // create a temporary buffer into which
  // the entire image data is temporarily stored
  unsigned char *buffer;
 
  // encode the GIF image data into the buffer
  // "size" stores the size of the resulting encoded data
  int size = image.writeToBuffer(buffer);
 
  // open the file for writing
  std::ofstream outf(fileName.c_str(), std::ios_base::out | std::ios_base::binary);
 
  // write all the data in the buffer into the file
  outf.write((char *)buffer, size);
 
  // close the file
  outf.close();
 
  // the buffer can now be removed from memory
  delete [] buffer;
 
  return 0;
}

Output file:

MISSING IMAGE!

378/cross.gif cannot be found in /users/378/cross.gif. Please contact the submission author.

Authors

Lucian Bentea, August 2009

References

LZW and GIF explained by Steve Blackstock, http://www.cis.udel.edu/~amer/CISC651/lzw.and.gif.explained.html
"Compressed image file formats: JPEG, PNG, GIF, XBM, BMP" by John Miano, Chapter 12, http://books.google.com/books?id=_nJLvY757dQC&dq=Compressed+image+file+formats&printsec=frontcover&source=bn&hl=ro&ei=ImaPSuGxIsiK_Abyh5SvAg&sa=X&oi=book_result&ct=result&resnum=4#v=onepage&q=&f=false
The Wikipedia page on the GIF format, http://en.wikipedia.org/wiki/Graphics_Interchange_Format

Class GIF

Members of GIF

GIF

GIF(

)

This is the implicit constructor for the GIF class, setting the GIF's parameters to default values.

GIF

GIF( unsigned char* buffer )[constructor]

This version of the constructor allows you to load GIF data as soon as you create an instance of the GIF class.

The data is loaded from the given buffer parameter, as if it were a GIF file on the disk. To load the data, this constructor makes a call to the readFromBuffer method.

buffer

the buffer containing the GIF data

CreateCanvas

voidcreateCanvas(

)

You may call this function after setting up the image's width and height. It will create the canvas with the given dimensions, on which you can draw using the setPixel method.

SetPixel

voidsetPixel(	int	`x`
	int	`y`
	unsigned char	`colorIndex`	)

Call this method to set the pixel at the x and y coordinates to have the color with index colorIndex in the color table.

Make sure you first call the createCanvas method before setting any pixel on the canvas.

x	the abscissa of the pixel
y	the ordinate of the pixel
colorIndex	the index of the color you want the pixel to have

GetPixel

unsigned chargetPixel(	int	`x`
	int	`y`	)

Call this method to obtain the color of the pixel at the x and y coordinates, as an index in the color table.

Make sure you first call the createCanvas method before calling this method to return the color at the specified coordinates.

x	the abscissa of the pixel
y	the ordinate of the pixel

Returns

the color at the given coordinates, as an index in the color table

ReadFromBuffer

voidreadFromBuffer( unsigned char* buffer )

This method reads the data in the given buffer parameter, as if it were the contents of a GIF file on the disk. The data is decoded and stored in the GIF object.

buffer

the buffer containing the GIF data

WriteToBuffer

intwriteToBuffer( unsignedchar*& buffer )

This method writes the data from the GIF object into the given buffer parameter, as if it were a GIF file on the disk. The data is encoded and stored in the specified buffer.

GetVersion

std::stringgetVersion(

)

Call this method to obtain the version of the currently loaded GIF. This can be either GIF87a or GIF89a.

Returns

the version of the currently loaded GIF

GetWidth

unsigned shortgetWidth(

)

This method returns the width of the currently active canvas. If a GIF image is loaded into the GIF object, then this method returns the width of the loaded GIF.

Returns

the width of the current canvas

SetWidth

voidsetWidth( unsigned short width )

Call this method to set the width of the GIF's canvas to the specified value.

width

the desired width for the GIF's canvas

GetImageWidth

unsigned shortgetImageWidth(

)

If a GIF image is loaded into the GIF object, this method returns the width of the image inside the GIF's canvas.

Returns

the width of the image on the GIF's canvas

SetImageWidth

voidsetImageWidth( unsigned short imageWidth )

Call this method to set the width of the GIF's canvas to the specified value.

imageWidth

the desired width for the image inside the GIF's canvas

GetHeight

unsigned shortgetHeight(

)

This method returns the height of the currently active canvas. If a GIF image is loaded into the GIF object, then this method returns the height of the loaded GIF.

Returns

the height of the current canvas

SetHeight

voidsetHeight( unsigned short height )

Call this method to set the height of the GIF's canvas to the specified value.

height

the desired height for the GIF's canvas

GetImageHeight

unsigned shortgetImageHeight(

)

If a GIF image is loaded into the GIF object, this method returns the height of the image inside the GIF's canvas.

Returns

the height of the image on the GIF's canvas

SetImageHeight

voidsetImageHeight( unsigned short imageHeight )

Call this method to set the height of the GIF's canvas to the specified value.

imageHeight

the desired height for the image inside the GIF's canvas

GetBitsPerPixel

unsigned chargetBitsPerPixel(

)

This method returns the color depth for the currently loaded GIF.

Returns

the GIF's color depth

IsTransparent

boolisTransparent(

)

This method returns a boolean value indicating whether the GIF is transparent. The index of the transparent color in the color table can be obtained or set using the getTransparentColor and setTransparentColor methods, respectively.

Returns

true if the current GIF is transparent, false otherwise

SetTransparency

voidsetTransparency( bool transparent )

Call this method to enable or disable transparency for the current GIF.

transparent

true if you want to enable transparency, false if not

GetTransparentColor

unsigned chargetTransparentColor(

)

Call this method to obtain the index of the transparent color in the color table, in case transparency is enabled for the GIF.

Returns

the index of the transparent color in the color table

SetTransparentColor

voidsetTransparentColor( unsigned char transparentColorIndex )

Call this method to set the index of the current transparent color in the color table to the one specified through the transparentColorIndex parameter.

transparentColorIndex

the desired index in the color table for the transparent color

GetBackgroundColor

unsigned chargetBackgroundColor(

)

This method returns the index of the currently selected color for the canvas' background.

Returns

the index of the current background color

SetBackgroundColor

voidsetBackgroundColor( unsigned char bkColor )

Call this method to set the index of the background color in the color table to the value specified through the bkColor parameter.

bkColor

the desired index of the background color in the color table

GetImageLeftOffset

unsigned shortgetImageLeftOffset(

)

This method returns the offset from the left of the canvas, to the image inside the GIF's canvas.

Returns

the left offset of the image inside the GIF's canvas

SetImageLeftOffset

voidsetImageLeftOffset( unsigned short imageLeftOffset )

Call this method to set the offset from the left of the canvas, to the image inside the GIF's canvas, to the value specified through the imageLeftOffset parameter.

imageLeftOffset

the desired left offset for the image inside the GIF's canvas

GetImageTopOffset

unsigned shortgetImageTopOffset(

)

This method returns the offset from the top of the canvas, to the image inside the GIF's canvas.

Returns

the top offset of the image inside the GIF's canvas

SetImageTopOffset

voidsetImageTopOffset( unsigned short imageTopOffset )

Call this method to set the offset from the left of the canvas, to the image inside the GIF's canvas, to the value specified through the imageLeftOffset parameter.

imageTopOffset

the desired top offset for the image inside the GIF's canvas