Fetching latest commit…
Cannot retrieve the latest commit at this time
|Failed to load latest commit information.|
[NOTE: Please see additional notes at the bottom] [ COPYRIGHT NOTICES ] OpenGL Image library v1.0 GLi and the GLi specification are (C) Frank L. Morales II (altf2o) Source code for libGLi (C) Frank L. Morales II (altf2o) TGA, TARGA, and the TGA specification are (C) Truevision. Source code for libTGA (C) Frank L. Morales II (altf2o) This code makes use of the zlib lossless compression library. Information on the zlib library and it's author's can be found at: http://www.gzip.org/zlib/ The OpenGL name and API is copyright it's respective owners. Please visit: http://www.opengl.org/ for more information. This library targets the OpenGL API but is in no way associated with OpenGL or the OpenGL ARB (Architecture Review Board). This is a 100% 3rd party and independantly developed image file format and library. I make no claims that myself, the name GLi, the GLi specification and libGLi are in any way associated with OpenGL or the OpenGL ARB. [ GOALS OF THIS LIBRARY ] The goal was to create an image format that could easily be used in OpenGL texture mapping. I wanted a library that could compress using lossless compression techniques (by the well established zlib library) as well as have a VERY easy to understand and parse structure. All while keeping the sections that were important to a modern day image file format. We also needed a file format where no section was optional. This would reduce the robustness of the file format in comparison to some others. However it would greatly reduce the complexity of parsing the image, which would lead to improved performance and smaller library code. The result is the GLi specification. The goals and how i feel i accomplished them are as follows: 1) We needed to be able to quickly and easily determine if the current file is a valid GLi image. Therefor i took a note from the 'ELF' executable file format and used a similar 4 byte field. The first variable in our image header is: mBytes (4 bytes). Our images (if they're valid) start w/ the first 4 bytes being: 0x7F, 'G', 'L', 'i' . This allows us to quickly determine if the file is valid or not and act accordingly. To make it easier we declare an array (in GLi.h) which contains these 4 bytes called, MAGIC_BYTES. Using any type of memory compare function we can quickly and easily determine if the current file is valid. 2) We needed a way to quickly and most importantly RELIABLY establish the EXACT version of the image format used to write the image we're trying to work with. We introduce the next variable in our header: version (1 byte). This will contain the version used to write the GLi image. To make it easier, this value can be set with, and compared against the #define from GLi.h: GLI_CURRENT_VERSION As of this writing the ONLY possible value is 1. 3) Next we needed a way to specify a meaningful value to tell OpenGL which format our pixel data is in. We introduce the next variable in our header: format (4 bytes). To keep things simple we addressed the problem of reversed pixel data, i.e. BGR form as apposed to the standard RGB. To make it easier our format ONLY supports storing pixel data in the RGB format. As of version 1.0 we support 8\24\32 bits per pixel. We offer 2 macros in GLi.h the first being: CONVERTBGRtoRGB which expects a pointer to a valid 'gli_image' structure. And: CONVERTBGRAtoRGBA which also expects a pointer to a valid 'gli_image' structure. Both of which simply reverse the image data's pixel order. 4) The next 3 fields are the images "width": width (4 bytes) "height": height (4 bytes) and "pixel depth": pxlDepth (1 bytes). Those are obviously a must for many things. One issue i had was other formats storing the pixel depth in 'bits per pixel' i.e. for a 24bpp image pxlDepth would be 24. In the GLi format we store the pixel depth in bytes. So for a 24bpp image, pxlDepth will be 3 (8bits per pixel). 5) I wanted a way to quickly get the size of the raw uncompressed image data. width * height * pxlDepth make up this value. However instead of having to compute that on load, we have a variable: imgSize (4 bytes) which holds the size of our raw uncompressed pixel data in bytes. 6) The next 2 fields weren't really problems in other formats, this is just how i decided they would work best. It's easier IMHO to have 2 valid C-strings of known size to give the author of the image their due credit, as well as a time stamp for when the image was created. This gives us our next two fields: author (24 bytes) and: stamp (28 bytes) Both can hold 1 less than the given value, that is to save 1 byte for the terminating null character. 7) We wanted to be able to compress the pixel data as much as possible. However since the target was texture mapping and such in OpenGL the last thing we want is lossy compression. Therefor we acknowledge the fact that we won't get as good of compression ratios, but we can still greatly reduce the size of our images raw pixel data, and keep the same excellent quality. To do that we compress JUST the pixel data with the zlib lossless compression library. (NOTE: Upon loading an image the pixel data is ALWAYS uncompressed. When the function 'gli_load' returns a valid structure the image data has already been uncompressed for you, assuming the image was compressed.) To signal we have compressed data our header structures variable: comp (comp[ressed]) (1 byte) will be set to: GLI_IMAGE_COMPRESSED. Otherwise it should hold the value: GLI_IMAGE_NOTCOMPRESSED. NOTE: Any other values (besides GLI_IMAGE_COMPRESSED) are assumed to mean the image is NOT compressed. If we do have GLI_IMAGE_COMPRESSED then our next headers variable: compSize (comp[ressed]Size) (4 bytes) will hold the size of our compressed pixel data (in bytes). NOTE: We also specify 2 #define's named: GLI_IMAGE_COMPRESS and it's counterpart: GLI_IMAGE_DONTCOMPRESS They should be used when telling a function who's preparing an image structure, to compress the data, or not to compress the data. That function should then set the structures 'comp' variable to: GLI_IMAGE_COMPRESSED, or GLI_IMAGE_NOTCOMPRESSED respectively. ---------- Up until now this is what we consider our gli_image structures "header" it is a total of 79 bytes. After this there's only 1 more 4 byte variable. When reading in the entire header do NOT include that 4 byte variable. To make that easier to remember ALWAYS use the supplied #define: GLI_HEADER_SIZE . 8) Lastly we wanted our pixel data to ALWAYS be in a known place. We therefor didn't include any optional sections like some other formats do. So the last thing our structure has is a variable named: image (4 bytes). Which is a pointer to some area of memory we'll allocate and store the (raw) pixel data into. NOTE: This format was an experiment i happened to find useful. It was not meant to be a replace all, widely used image format. I could have used a stripped targa loader, or bitmap loader etc... but where's the fun in that? :-) If it does become popular great, i'd be glad to see other's benefit from my work in any way shape or form. However let it be known my intentions were to create a very strait forward, simple, easy to use and understand, image file format for my texture mapping needs. I feel this has accomplished that goal quite well. You may modify and or use this library in any way you see fit so long as the following is met: [ USING AND MODIFYING THE LIBRARY ] The libraries presented here (libGLi and libTGA), and all other accompanying "tools" (in the tools_src/ directory) are subject to the LGPL license. A copy of that has been shipped w/ this library, and is in the file: LGPL.license Please refer to it for rules about modifying this code, and using any of these libraries in your free, or proprietary applications. Constructive critisism is always welcome. Please send comments and or questions to: firstname.lastname@example.org , please remember to use: GLi Comment\Question in the "Subject" line of the email. Makes my life easier. That aside, i hope someone finds this useful, i currently use it for all my texture mapping needs. FMorales... [UPDATE 7/20/2010] I have updated my system to Ubuntu 10.04 x86_64. As of this writing this suite of utilities and libraries works flawlessly on both 32 and 64bit platforms. One thing i did have to do is add a couple packages so my system was ready to build: sudo apt-get install zlib1g-dev libglut3-dev Also once built, we need to add our ./lib/ path to our searchable library path so our applications can find it. For testing, during my current session, I simply use the following while using my Bash shell: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/full/path/to/libGLi/lib/ If you had any issues running 'make' or running any applications, retry now, it should work just fine.