GD Library FAQ

Please Read Before Inquiring

What does "gd" stand for?

In gd 1.0, it stood for "gif draw." After the Unisys patent on the LZW compression used in GIF came to light and GIF support was dropped, it did not officially stand for anything, but let's just say "graphics draw" and leave it at that. (GIF support is back, thanks to the expiration of the patent, but gd can draw much more than GIFs.)

Does gd support GIF images?

Yes. Support for GIF was restored in gd 2.0.28 on July 21st, 2004. Support for creating GIF animations is also available. Note that gdlib-config --features can be used to list the image formats supported by gd. Versions of gdlib-config prior to recent updates do not support the --features option, which can be understood to mean that GIF is not available.

How do I install gd on Linux?

Well, what do you really want?

If you want gd for a PHP application, just do (for Fedora):

yum install php-gd

Or, for Red Hat Enterprise Linux or CentOS:

up2date php-gd

Then do:

service httpd restart

Other Linux distributions may have gd already compiled into PHP, or they may have a similar php-gd package that brings in PHP's gd module. PHP includes its own distribution of gd, you do not need mine.

If you really want gd for C programming or some other language that has an extension built on top of my distribution of gd, do:

yum install gd-devel

Or the equivalent for your Linux distribution.

Note: this might not install the latest, most-cutting edge version of gd, depending on the Linux distribution you are running and how current their gd packages are at the moment.

How do I get gd to work with PHP?

Update: please note that PHP may or may not have been updated yet to include support for the GIF and animated GIF features that have been added to gd. See www.php.net for the official word on what is and isn't standard in PHP's internal version of gd at this time.

php 4.3.x is available, and it includes a version of gd as "standard equipment." php_gd2.dll is included in a standard PHP installation for Windows, it's just not enabled by default. To turn it on, the user may simply uncomment the line "extension=php_gd2.dll" in php.ini and restart the PHP extension. Change:

#extension=php_gd2.dll

To:

extension=php_gd2.dll

You may also have to correct the extension directory setting from:

extension_dir = "./"

Or:

extension_dir = "./extensions"

To (FOR WINDOWS):

extension_dir = "c:/php/extensions" NOTE: SUBSTITUTE THE ACTUAL PHP INSTALLATION DIRECTORY ON *YOUR* COMPUTER.

Thanks to Benoit Blais for this last point. Thanks also to Alan MacDougall and Perculator.

The PHP 4.3.x version of gd offers features similar to and sometimes in addition to those included in the latest version of gd found here. If you are working with PHP, using the built-in gd of PHP 4.3.0 or better is recommended. However, if you wish to continue using php 4.2.3 but need gd support for it, see the patching PHP for gd 2.0.8 and up page for important information. Please understand that patching PHP is probably not easier than upgrading PHP unless you have a very good reason to believe upgrading will not work for you.

The php-gd maintainers included a statement saying that their improvements would be contributed back to the "mainstream" gd, so I look forward to seeing them merged in the near future, and I wish to thank the PHP authors for the considerable work already done in this area.

If you want gd for PHP on Linux, you can rebuild PHP from source with the --enable-gd option, or you can make your life much, much easier by using packages already available as part of your Linux distribution. See how do I install gd on Linux?

Where can I get a compiled DLL of gd for Windows?

CURRENTLY NOT INTENDED FOR PHP, SEE ABOVE. A compiled DLL of gd with all features enabled is now available from the gd home page. To avoid conflicts the DLL is named bgd.dll. This is of course intended for programmers, but opens up the field to those who found compiling gd from scratch under Windows to be very challenging. bgd.dll includes png, jpeg, and freetype support as "standard equipment." A similar precompiled library for Linux is planned for the immediate future.

Where can I find an example of PHP programming with gd?

Try this amazing presentation by Jeff Knight of New York PHP. In addition to explaining the use of GD from PHP, Mr. Knight provides fascinating, live examples. Recommended.

Why do my JPEG thumbnails have missing colors with gd 2.0.x?

When creating truecolor images, you need to call gdImageCreateTrueColor, not gdImageCreate. This used to "work" in gd 1.x, but only in the sense that gd 1.x had no support for real truecolor at all, so it faked it by dithering your image. gd 2.x supports real truecolor, and also has a better way of reducing to palette color when you really want to do that; see the gdImageTrueColorToPalette function -- but you don't need it for this job. PHP and Perl programmers: the function names for you are similar, just leave off the gd prefix.

How come MRTG (or product XYZ) doesn't work right?

I wrote gd; I can help you with that. I can't help you with someone else's product, even if it happens to use gd. First install gd according to the documentation, then read the documentation for the product that requires it, and contact its authors if need be.

Where do I get gd?

See the gd home page for links to current versions of gd, as well as the manual.

I have added a cool feature. How do I submit the code for inclusion in gd?

I'd be very interested to see your patch, provided that you are willing to allow it to be released under the existing license terms; see the manual for more information. Please contact us.

Are you available to customize gd on a paid consulting basis?

Certainly. Please contact us for more information. For a fast response be sure to specify that you are interested in paid support.

gd keeps saying it can't find png or jpeg support. I did install libpng and libjpeg. What am I missing?

Be sure to do "make install-headers" for libpng and "make install-lib" for libjpeg, in addition to "make install." You may also need to use a command line like this one when configuring gd: ./configure '--with-jpeg=/usr/local' '--with-png=/usr/local'
'--with-zlib-dir=/usr/local'
Often, users have installed these things in /usr/local/include and /usr/local/lib, but do not actually have those directories in their default include and library paths when configuring gd. Thanks to Santanu Misra and Alastair Battrick.

Why does bgd.dll crash with my C program?

You are trying to use gd's stdio library functions with a different C runtime library. Read on for notes on individual compilers.

Microsoft Visual C++: If you want to use gdImageCreateFromPng, gdImagePng, and other functions that take a FILE *, you MUST use Visual C++ 6.0 or earlier and you MUST link with the "multithreaded DLL" runtime library option. If you wish to use the .NET compiler, read the "Borland C++" section for an alternative method.

If you do not take the time to understand this, your program simply will not work! Note: the "multithreaded debug DLL" option is NOT the same thing and will NOT work. If you don't want to use the "multithreaded DLL" runtime library option (see "code generation" under "settings"), then read the "Borland C++" section for an alternative method.

GNU mingw32: you should have no problems. The mingw32 compiler is designed to link your application with msvcrt.dll, the same C runtime library that bgd.dll was linked with. (We build it with mingw32, as it happens.)

GNU cygwin: if you are compiling with -mno-cygwin, see the GNU mingw32 entry, above. If you are linking with the full cygwin runtime library, you might be better off installing gd from source. "configure" and "make install" should work for you as they do on full Unix systems. If you have solved the problem of using a win32 DLL from cygwin, however, you can certainly use bgd.dll using the same techniques described below for Borland C++.

Borland C++: this product apparently provides its own C runtime library, incompatible with Microsoft's msvcrt.dll. You cannot use the FILE * functions in gd.h. However, there is an alternative. The gdImagePngPtr and gdImageCreateFromPngPtr functions provide a way to write image file data to a memory buffer, or load an image from a buffer of image file data. See the next two questions for code samples.

How do I load an image file from a buffer in memory?

The following C code shows how to load an entire image file into a buffer in memory, then ask gd to read the image from that buffer. Please note that since you are responsible for allocating the buffer, You are also responsible for freeing the buffer with your normal memory management functions.

Note to Borland C++ programmers: this code will allow you to load an image using the bgd.dll library, because no FILE * objects are passed across the DLL boundary.

Of course, there is a gdImageCreateFromJpegPtr function available as well. This particular example loads a PNG image.

#include <sys/types.h>
#include <sys/stat.h>
#include <stdlib.h>

gdImagePtr myLoadPng(char *filename)
{
  FILE *in;
  struct stat stat_buf;
  gdImagePtr im;
  in = fopen("myimage.png", "rb");
  if (!in) {
    /* Error */
  }
  if (fstat(fileno(in), &stat_buf) != 0) {
    /* Error */
  }
  /* Read the entire thing into a buffer 
    that we allocate */
  char *buffer = malloc(stat_buf.st_size);
  if (!buffer) {
    /* Error */
  }
  if (fread(buffer, 1, stat_buf.st_size, in) 
    != stat_buf.st_size) 
  {
    /* Error */
  }
  im = gdImageCreateFromPngPtr(
    stat_buf.st_size, buffer);
  /* WE allocated the memory, WE free 
    it with our normal free function */
  free(buffer);
  fclose(in);
  return im;
} 

Why don't I have lib.exe?

The makemsvcimport.bat batch file will fail to produce bgd.dll if you are using the Microsoft Visual C++ Free Toolkit. Fortunately, a solution to this problem is available; an acceptable substitute can be created as a simple batch file that uses tools that are included in that package. See this highly useful page of the MaxDB wiki.

How do I save an image to a buffer in memory?

The following C code shows how to save a gd image to a memory buffer, and then write that buffer to a file on disk. You could also write it directly to stdout, preceded by a Content-type: image/png header and two CR/LF sequences, to directly return an image from a CGI program.

Note to Borland C++ programmers: this code will allow you to save an image using the bgd.dll library, because no FILE * objects are passed across the DLL boundary.

For your convenience, gd allocates the buffer for you; when you are done with it, you must call gdFree to release it.

Of course, there is a gdImageJpegPtr function available as well. This particular example saves a PNG image.

#include <sys/types.h>
#include <sys/stat.h>
#include <stdlib.h>

void mySavePng(char *filename, 
  gdImagePtr im)
{
  FILE *out;
  int size;
  char *data;
  out = fopen("filename, "wb");
  if (!out) {
    /* Error */
  }
  data = (char *) gdImagePngPtr(im, &size);
  if (!data) {
    /* Error */
  }
  if (fwrite(data, 1, size, out) != size) {
    /* Error */
  }
  if (fclose(out) != 0) {
    /* Error */
  }
  gdFree(data);  
}

Why doesn't my gd 1.x program work well with gd 2.x?

There are two common reasons:
  • You were using an ancient version of gd 1.x with GIF support, and now you are using a not-quite-new-enough version of gd 2.x without GIF support. Solution: get the latest gd 2.x which again supports GIF.
  • You are trying to make thumbnails, or otherwise copy photographic-quality images like JPEG files. But you are creating the new image with gdImageCreate, which makes a palette-color image not suitable for photographs. Solution: use gdImageCreateTrueColor (new in gd 2.x), which creates a true-color image. This sort of "worked" in gd 1.x because gd 1.x did a quick and nasty job of converting JPEGs to palette color when reading them. But you will get much better results doing it the right way in gd 2.x. If you really want to, you can reduce to palette color after the copy using gdImageTrueColorToPalette.

Why does gd cause my PHP script to run out of memory?

Most often, the problem is that the memory_limit parameter in php.ini is set to something very conservative, like 8M (eight megabytes). Increase that setting and restart the web server.

Of course, opening truly huge images can cause real memory problems, if several are open at once. 8,000 pixels times 8,000 pixels times four bytes for truecolor equals a walloping 256 megabytes.

How can I determine the image dimensions without loading the entire image into memory (and possibly running out)?

Very large images can cause gd to run out of memory (see the previous question). And sometimes the image file itself isn't terribly large— consider a JPEG of a completely blank field, 8,000 pixels on a side: the file compresses well but representing it in memory as a bitmap is impractical.

If you are coding in PHP, you can check for this situation with the getimagesize function, which determines the image dimensions without using gd. This is possible because the popular image formats all store the image dimensions near the beginning of the file where they are easily accessible. Perl programmers can use the similar Image::Size CPAN module. If you are not using PHP or Perl and your language of choice does not offer a similar feature, you can implement the technique yourself. See the GIF specification, the JPEG specification, and the PNG specification.


Follow us on Twitter | Contact Us

Copyright 1994-2014 Boutell.Com, Inc. All Rights Reserved.