glpng.htm

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content=
   5 "text/html; charset=us-ascii">
   6 <title>glpng</title>
   7 </head>
   8 <body bgcolor="#FFFFFF">
   9 <h2 align="center">PNG loader library for OpenGL v1.45
  10 (10/7/2000)</h2>
  11 <p align="center">Ben Wyatt <a href=
  12 "mailto:ben@wyatt100.freeserve.co.uk">ben@wyatt100.freeserve.co.uk</a></p>
  13 <h3>Introduction</h3>
  14 <p>This is a library for OpenGL to load PNG graphics files as an
  15 OpenGL texture as easily as possible. It also has a number of
  16 options for generating the alpha channel and mipmaps. It is
  17 implemented using modified versions of the LibPNG 1.0.2 and ZLib
  18 1.1.3 libraries.</p>
  19 <p>This software is provided 'as-is', without any express or
  20 implied warranty. In no event will the author be held liable for
  21 any damages arising from the use of this software.</p>
  22 <p>Permission is hereby granted to use, copy, modify, and
  23 distribute this source code, or portions hereof, for any purpose,
  24 without fee, subject to the following restrictions:</p>
  25 <ol>
  26 <li>The origin of this source code must not be misrepresented. You
  27 must not claim that you wrote the original software. If you use
  28 this software in a product, an acknowledgment in the product
  29 documentation would be appreciated but is not required.</li>
  30 <li>Altered versions must be plainly marked as such and must not be
  31 misrepresented as being the original source.</li>
  32 <li>This notice must not be removed or altered from any source
  33 distribution.</li>
  34 </ol>
  35 <h3>Installation for MSDEV</h3>
  36 <p>Copy glpng.h to your include/GL folder and copy glpng.lib and
  37 glpngd.lib to your lib folder. Then just do #include
  38 &lt;GL/glpng.h&gt; and with a bit of luck, MSDEV will automatically
  39 link with glpng.lib (release lib) or glpngd.lib (debug lib).</p>
  40 <h3>Installation for Any Other Compiler</h3>
  41 <p>Copy glpng.h to your include/GL folder. Then you'll have to
  42 build the library yourself with the included source code. Included
  43 are makefiles for Linux and SGI. If you need to modify the source
  44 code to make it work on your system, please get in contact so I can
  45 make future versions compatible.</p>
  46 <h3>Compiling with LibPNG or ZLib</h3>
  47 <p>If you are using LibPNG or ZLib in your project there may be
  48 problems if you link with the glpng library. To solve this, include
  49 glpng.c in your project and, if you're using MSDEV, modify glpng.h
  50 to not automatically link with glpng.lib or glpngd.lib.</p>
  51 <h3>OpenGL DLL Dynamic Loading using glsetup</h3>
  52 <p>To use glpng with glsetup, include glpng.c, LibPNG and ZLib in
  53 your project. In glpng.c, change #include &lt;GL/gl.h&gt; to
  54 include the glsetup include and modify glpng.h to not automatically
  55 link with glpng.lib or glpngd.lib.</p>
  56 <h3>Functions</h3>
  57 <ul>
  58 <li><a href="#pngLoad">pngLoad</a></li>
  59 <li><a href="#pngLoadF">pngLoadF</a></li>
  60 <li><a href="#pngBind">pngBind</a></li>
  61 <li><a href="#pngBindF">pngBindF</a></li>
  62 <li><a href="#pngLoadRaw">pngLoadRaw</a></li>
  63 <li><a href="#pngLoadRawF">pngLoadRawF</a></li>
  64 <li><a href="#SetStencil">pngSetStencil</a></li>
  65 <li><a href="#pngSetAlphaCallback">pngSetAlphaCallback</a></li>
  66 <li><a href="#pngSetViewingGamma">pngSetViewingGamma</a></li>
  67 <li><a href=
  68 "#pngSetStandardOrientation">pngSetStandardOrientation</a></li>
  69 </ul>
  70 <pre>
  71 <a name=
  72 "pngLoad"><strong>success = pngLoad(filename, mipmap, trans, info)</strong></a>
  73 </pre>
  74 <blockquote>
  75 <table border="1">
  76 <tr>
  77 <td valign="top">filename</td>
  78 <td>Filename of PNG file, including ".png"</td>
  79 </tr>
  80 <tr>
  81 <td valign="top">mipmap</td>
  82 <td>Mipmapping parameter:
  83 <ul>
  84 <li>0 or PNG_NOMIPMAP if no mipmap or for the base mipmap
  85 level</li>
  86 <li>1,2,3... for mipmap detail level</li>
  87 <li>PNG_BUILDMIPMAPS to call a clone of gluBuild2DMipmaps (box
  88 filter)</li>
  89 <li>PNG_SIMPLEMIPMAPS to generate mipmaps without filtering (uses
  90 upper-left of each 2x2 box)</li>
  91 </ul>
  92 </td>
  93 </tr>
  94 <tr>
  95 <td valign="top">trans</td>
  96 <td>Transparency setting:
  97 <ul>
  98 <li>PNG_ALPHA to use alpha channel in PNG file, if there is
  99 one</li>
 100 <li>PNG_SOLID for no transparency</li>
 101 <li><a name="PNG_STENCIL">PNG_STENCIL</a> to set pixels of a
 102 certain value to alpha 0, otherwise 1 (see <a href=
 103 "#SetStencil">pngSetStencil</a>)</li>
 104 <li>PNG_BLEND1 to set alpha to r+g+b</li>
 105 <li>PNG_BLEND2 to set alpha to (r+g+b)/2</li>
 106 <li>PNG_BLEND3 to set alpha to (r+g+b)/3</li>
 107 <li>PNG_BLEND4 to set alpha to
 108 r<sup>2</sup>+g<sup>2</sup>+b<sup>2</sup></li>
 109 <li>PNG_BLEND5 to set alpha to
 110 (r<sup>2</sup>+g<sup>2</sup>+b<sup>2</sup>)/2</li>
 111 <li>PNG_BLEND6 to set alpha to
 112 (r<sup>2</sup>+g<sup>2</sup>+b<sup>2</sup>)/3</li>
 113 <li>PNG_BLEND7 to set alpha to
 114 (r<sup>2</sup>+g<sup>2</sup>+b<sup>2</sup>)/4</li>
 115 <li>PNG_BLEND8 to set alpha to
 116 sqrt(r<sup>2</sup>+g<sup>2</sup>+b<sup>2</sup>)</li>
 117 <li><a name="PNG_CALLBACK">PNG_CALLBACK</a> to use the callback
 118 function defined by <a href=
 119 "#pngSetAlphaCallback">pngSetAlphaCallback</a>.</li>
 120 </ul>
 121 </td>
 122 </tr>
 123 <tr>
 124 <td valign="top">info</td>
 125 <td>Pointer to a pngInfo structure to store texture info or NULL if
 126 you don't care. The pngInfo fields are:
 127 <ul>
 128 <li>Width - width of the original image in pixels</li>
 129 <li>Height - height of the original image in pixels</li>
 130 <li>Depth - depth of the original image, where colours =
 131 2<sup>Depth</sup></li>
 132 <li>Alpha - the number of bits used for the alpha channel (0 if no
 133 alpha channel)</li>
 134 </ul>
 135 </td>
 136 </tr>
 137 </table>
 138 <p>Loads a PNG file and calls glTexImage2D with appropriate
 139 parameters. The texture will be resized if the dimensions are not
 140 powers of 2 or over the maximum texture size. Should be able to
 141 load all colour depths (except 64-bit) and alpha channels if
 142 available. It converts them to an appropriate format and gives them
 143 to glTexImage2D. The OpenGL paletted texture extension is used if
 144 available.</p>
 145 <p>Returns 1 on success or 0 if file could not be loaded.</p>
 146 </blockquote>
 147 <pre>
 148 <a name=
 149 "pngLoadF"><strong>success = pngLoadF(file, mipmap, trans, info)</strong></a>
 150 </pre>
 151 <blockquote>
 152 <table border="1">
 153 <tr>
 154 <td valign="top">file</td>
 155 <td>FILE opened with fopen("something.png", "rb")</td>
 156 </tr>
 157 </table>
 158 <p>This is used to load a PNG from an already opened file. Handy if
 159 you want to batch all your data and textures into one big data
 160 file.</p>
 161 </blockquote>
 162 <pre>
 163 <a name=
 164 "pngBind"><strong>id = pngBind(filename, mipmap, trans, info, wrapst, minfilter, magfilter)</strong></a><strong>
 165 </strong><a name=
 166 "pngBindF"><strong>id = pngBindF(file, mipmap, trans, info, wrapst, minfilter, magfilter)</strong></a>
 167 </pre>
 168 <blockquote>
 169 <table border="1">
 170 <tr>
 171 <td valign="top">wrapst</td>
 172 <td>GL_CLAMP or GL_REPEAT (look up glTexParameter)</td>
 173 </tr>
 174 <tr>
 175 <td valign="top">minfilter</td>
 176 <td>Minification function for filtering (look up
 177 glTexParameter)</td>
 178 </tr>
 179 <tr>
 180 <td valign="top">magfilter</td>
 181 <td>Magnification function for filtering (look up
 182 glTexParamter)</td>
 183 </tr>
 184 </table>
 185 <p>Automates the process further - loads a PNG file, sets the
 186 OpenGL parameters, binds it to an OpenGL texture and returns it's
 187 ID, or 0 if the file couldn't be loaded.</p>
 188 </blockquote>
 189 <pre>
 190 <a name=
 191 "pngLoadRaw"><strong>success = pngLoadRaw(filename, rawinfo)</strong></a><strong>
 192 </strong><a name=
 193 "pngLoadRawF"><strong>success = pngLoadRawF(file, rawinfo)</strong></a>
 194 </pre>
 195 <blockquote>
 196 <table border="1">
 197 <tr>
 198 <td valign="top">rawinfo</td>
 199 <td>Pointer to a pngRawInfo structure in which to store the PNG
 200 data. The pngRawInfo has these fields:
 201 <ul>
 202 <li>Width, Height, Depth, Alpha - as in pngInfo</li>
 203 <li>Components - number of colour components (1, 2, 3 or 4)</li>
 204 <li>Data - pointer to image data stored as RGBRGB... or RGBARGBA...
 205 or indices to the palette table. Must be freed manually using
 206 free()</li>
 207 <li>Palette - pointer to palette table stored as RGBRGB... or
 208 RGBARGBA... Will be NULL if there is no palette table. Must be
 209 freed manually using free()</li>
 210 </ul>
 211 </td>
 212 </tr>
 213 </table>
 214 </blockquote>
 215 <pre>
 216 <a name=
 217 "SetStencil"><strong>pngSetStencil(red, green, blue)</strong></a>
 218 </pre>
 219 <blockquote>
 220 <table border="1">
 221 <tr>
 222 <td valign="top">red,green,blue</td>
 223 <td>The colour to stencil out when using the <a href=
 224 "#PNG_STENCIL">PNG_STENCIL</a> option</td>
 225 </tr>
 226 </table>
 227 </blockquote>
 228 <blockquote>
 229 <p>This selects the colour to stencil out when using <a href=
 230 "#PNG_STENCIL">PNG_STENCIL</a>. The parameters are 0 to 255. By
 231 default the colour is 0,0,0 (pure black).</p>
 232 </blockquote>
 233 <pre>
 234 <a name=
 235 "pngSetAlphaCallback"><strong>pngSetAlphaCallback(function)</strong></a>
 236 </pre>
 237 <blockquote>
 238 <table border="1">
 239 <tr>
 240 <td valign="top">function</td>
 241 <td>Pointer to a function taking three unsigned char parameters
 242 (red, green, blue) and returning an unsigned char (alpha)</td>
 243 </tr>
 244 </table>
 245 </blockquote>
 246 <blockquote>
 247 <p>This sets the function to be called when using <a href=
 248 "#PNG_CALLBACK">PNG_CALLBACK</a>. During the alpha channel
 249 generation process, this function will be called for every pixel,
 250 with the appropriate RGB values, and will use the result for the
 251 alpha value. The RGB and alpha values all range from 0 to 255. The
 252 default callback function simply returns 255.</p>
 253 </blockquote>
 254 <pre>
 255 <a name=
 256 "pngSetViewingGamma"><strong>pngSetViewingGamma(gamma)</strong></a>
 257 </pre>
 258 <blockquote>
 259 <table border="1">
 260 <tr>
 261 <td valign="top">gamma</td>
 262 <td>New gamma correction value</td>
 263 </tr>
 264 </table>
 265 <p>By default, gamma correction is set to 1.0 for Windows, 1.7 for
 266 SGI and 1.45 for Macs. If the VIEWING_GAMMA environmental variable
 267 is set, that is used instead. You can override both of these values
 268 using pngSetViewingGamma().</p>
 269 </blockquote>
 270 <pre>
 271 <a name=
 272 "pngSetStandardOrientation"><strong>pngSetStandardOrientation(standardorientation)</strong></a>
 273 </pre>
 274 <blockquote>
 275 <table border="1">
 276 <tr>
 277 <td>standardorientation</td>
 278 <td>If to use the standard orientation (0 is default)</td>
 279 </tr>
 280 </table>
 281 <p>By default, the image is loaded so that texture coordinates 0,0
 282 represent the top-left - a result of me not knowing the OpenGL spec
 283 :-). If you wish to use the standard OpenGL representation where
 284 0,0 is the bottom-left, set this to 1.</p>
 285 </blockquote>
 286 <h3>Examples</h3>
 287 <p>Here's an example of pngLoad(), to load "Texture.png" with
 288 nearest filter, clamping on and no mipmaps or alpha channels...</p>
 289 <blockquote>
 290 <pre>
 291 pngInfo info;
 292 GLuint id;
 293 </pre>
 294 <pre>
 295 glGenTextures(1, &amp;id);
 296 glBindTexture(GL_TEXTURE_2D, id);
 297 </pre>
 298 <pre>
 299 glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST);
 300 glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST);
 301 glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP);
 302 glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP);
 303 </pre>
 304 <pre>
 305 if (pngLoad("Texture.png", PNG_NOMIPMAP, PNG_SOLID, &amp;info)) {
 306    puts("Loaded Texture.png with resounding success");
 307    printf("Size=%i,%i Depth=%i Alpha=%i\n", info.Width, info.Height, info.Depth, info.Alpha);
 308 }
 309 else {
 310    puts("Can't load Texture.png");
 311    exit(1);
 312 }
 313 </pre></blockquote>
 314 <p>And here's an example to load the same texture with the same
 315 options using pngBind()...</p>
 316 <blockquote>
 317 <pre>
 318 pngInfo info;
 319 GLuint id = pngBind("Texture.png", PNG_NOMIPMAP, PNG_SOLID, &amp;info, GL_CLAMP, GL_NEAREST, GL_NEAREST);
 320 </pre>
 321 <pre>
 322 if (id != 0) {
 323    puts("Loaded Texture.png with resounding success");
 324    printf("Size=%i,%i Depth=%i Alpha=%i\n", info.Width, info.Height, info.Depth, info.Alpha);
 325 }
 326 else {
 327    puts("Can't load Texture.png");
 328    exit(1);
 329 }
 330 </pre></blockquote>
 331 <p>If those two examples don't make sense, try the included full
 332 source example (which needs <a href=
 333 "http://reality.sgi.com/opengl/glut3/glut3.html">GLUT</a>).</p>
 334 <h3>Bugs</h3>
 335 <ul>
 336 <li>64-bit PNGs can't be loaded (missing LibPNG feature as far as I
 337 can tell).</li>
 338 </ul>
 339 <h3>Possible Future Developments</h3>
 340 <ul>
 341 <li>Better attempts could be made to find the optimal texture
 342 format for OpenGL. At the moment, it converts everything to 24 or
 343 32 bit, or uses the paletted texture extension in certain (easy to
 344 handle) cases.</li>
 345 <li>Other mipmap generating algorithms could be implemented
 346 (wavelet stuff?). Source donations are welcome.</li>
 347 <li>Saving the frame buffer to a PNG file.</li>
 348 <li>Support for GL_INTENSITY, GL_LUMINANCE_ALPHA and others.</li>
 349 </ul>
 350 <h3>History</h3>
 351 <table border="0">
 352 <tr>
 353 <td valign="top" nowrap>1.33 (20/5/99)</td>
 354 <td valign="top">First public release.</td>
 355 </tr>
 356 <tr>
 357 <td valign="top" nowrap>1.34 (27/5/99)</td>
 358 <td valign="top">Optimised alpha channel generating, added Alpha
 359 property to the pngInfo structure, illegal texture sizes are
 360 resized.</td>
 361 </tr>
 362 <tr>
 363 <td valign="top" nowrap>1.35 (4/6/99)</td>
 364 <td valign="top">Added pngLoadRaw and pngLoadRawF functions.</td>
 365 </tr>
 366 <tr>
 367 <td valign="top" nowrap>1.36 (9/6/99)</td>
 368 <td valign="top">Fixed problem causing linking warnings/errors (I
 369 think) and reduced the size of the library considerably.</td>
 370 </tr>
 371 <tr>
 372 <td valign="top" nowrap>1.37 (13/6/99)</td>
 373 <td valign="top">Added alpha channel generation callback
 374 function.</td>
 375 </tr>
 376 <tr>
 377 <td valign="top" nowrap>1.38 (22/6/99)</td>
 378 <td valign="top">Stopped it from disabling texturing on calls to
 379 pngBind and pngBindF.</td>
 380 </tr>
 381 <tr>
 382 <td valign="top" nowrap>1.39 (8/7/99)</td>
 383 <td valign="top">Fixed a bug in the extensions reading code, which
 384 caused some machines to crash.</td>
 385 </tr>
 386 <tr>
 387 <td valign="top" nowrap>1.40 (27/9/99)</td>
 388 <td valign="top">Added support for SGI, Linux, and gamma correction
 389 (thanks to Mark B. Allan!). Fixed bug in raw reading of gray
 390 textures (thanks to Johann Scholtz!). Removed all use of GLU
 391 functions to make it easier to dynamically load opengl32.dll or
 392 3dfxvgl.dll or whatever. Added simple mipmap generator.</td>
 393 </tr>
 394 <tr>
 395 <td valign="top" nowrap>1.41 (20/10/99)</td>
 396 <td valign="top">Made a small optimisation and improved
 397 documentation. Remembered to include the makefiles for Linux and
 398 SGI in the zip (!).</td>
 399 </tr>
 400 <tr>
 401 <td valign="top" nowrap>1.42 (01/03/00)</td>
 402 <td valign="top">Fixed problems with compiling on SGI (thanks to
 403 Thomas Sondergaard!). Added pngSetStandardOrientation (thanks to
 404 Scott Franke!).</td>
 405 </tr>
 406 <tr>
 407 <td valign="top" nowrap>1.43 (11/05/00)</td>
 408 <td valign="top">Added debug library and fixed the crash when there
 409 wasn't a terminating png info structure (thanks to Dan
 410 Hawkins!).</td>
 411 </tr>
 412 <tr>
 413 <td valign="top" nowrap>1.44 (01/07/00)</td>
 414 <td valign="top">Fixed release and debug libraries so they stop
 415 producing warnings and errors in MSDEV.</td>
 416 </tr>
 417 <tr>
 418 <td valign="top" nowrap>1.45 (10/07/00)</td>
 419 <td valign="top">Fixed bug where the standard orientation flag was
 420 being ignored in pngLoadRawF (thanks to Mark B. Allan!).</td>
 421 </tr>
 422 </table>
 423 <p>Get the latest version from <a href=
 424 "http://www.wyatt100.freeserve.co.uk/download.htm">http://www.wyatt100.freeserve.co.uk/download.htm</a></p>
 425 </body>
 426 </html>