OpenGLUT Documentation
Introduction | Documentation | Examples | Proposals | Authors | Copying | Todo | Bugs | Links

OpenGLUT Image Loading API Proposal

This is a proposal for the purpose of discussion and discussion. This API is not currently implemented in OpenGLUT.


Applications often wish to load textures from images. Historically, one has been left to either implement one's own reader from scratch, or hunt down an image-format reader such as libpng for the PNG format and implement an interface to read the private format used to communicate to the library. While these are certainly viable options, they are nuisances.

This proposal would add an image-loading facility directly to OpenGLUT so that one can manage images more readily.

One concern that OpenGLUT has is to minimize the number of libraries that are forced onto client applications. The recent thread seemed to settle on making one or more formats available at compile-time, and at least one ``native'' format that does not require an external library.

The goal is to allow an application to read an image with essentially a single OpenGLUT function call.

The proposed usage to get the image into a texture is to call:

    GLvoid *glutReadImageBuf(
      const    GLvoid *buffer,
      GLint    bufferSize,
      GLint   *internalFormat
      GLsizei *width,
      GLsizei *height,
      GLenum  *format,
      GLenum  *type

...and store the result in a GLvoid * variable, say, pixels. Then to call:

    free( pixels );

(Note that OpenGLUT does not guarantee that a valid image is returned, nor does it guarantee that the image has power-of-2 width and height. In practice, then, you should check at least those three values between the call to glutReadImageBuf() and glTexImage2D().)

An alternate method to read from a file, rather than a memory buffer, is also proposed. That form involves a const char *fileName parameter in place of the first two parameters for the data source. This alternate is purely a convenience and would replace about 2 lines of code (one of which would be the call to glutReadImageBuf(). The file-based form would look like so:

    GLvoid *glutReadImageFile(
        const char *fileName,
        GLint      *internalFormat,
        GLsizei    *width,
        GLsizei    *height,
        GLenum     *format

This mechanism provides a simple way to read images: Read the data into a buffer and then pass the buffer to glutReadImage(). OpenGLUT will try to interpret the data using the file formats that it knows about. The image formats being considered can all be distinguished from one another, without ambiguity.

The meaning of fileName is extremely system-dependant.

JPEG and PNG are seen as the most practical formats. But because source package systems can suffer from extensive shared library use, a third format that can be directly supported (no external libraries required) will be provided. PNM is the proposed third format: It is simple, flexible, and reasonably neutral. It has the additional merit of having many pipelinable tools available so that you may use popen() (or _popen() on WIN32) to read a PNM produced by such a tool from almost any other type of file, and can be scaled to power-of-2 dimensions by other programs. (See the netpbm project.)

You must always check the results of glutReadImage*(). The data may be garbled or may be using unrecognized extensions to the formats. It may not be in a supported format. OpenGLUT may not be able to allocate the resources for the image. The ice weasels may be invading. Whatever.


Feedback, comments or suggestions can be directed either to the mail list or discussion forum.

OpenGLUT Development @ Sourceforge
Homepage | Summary | Files | CVS | Forums | Lists | Bugs | RFE

Generated on Sat Feb 5 01:47:28 2005 for OpenGLUT by doxygen
The OpenGLUT project is hosted by