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