glpng.htm

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