[[tags: egg soil image opengl gl bmp tga dds png jpg game]] == soil SOIL bindings for Chicken. [[toc:]] == Disclaimer For now, the egg is available at: https://github.com/dleslie/soil-egg The interface adheres closely to the stock SOIL interface. Much thanks to Jonathan Dummer for writing the original SOIL library. == SOIL Overview SOIL is a tiny c library for uploading images as textures into OpenGL. Also saving and loading of images is supported. It uses Sean's Tool Box image loader as a base: http://www.nothings.org/ SOIL upgrades stb_image to load TGA and DDS files, and adds a direct path for loading DDS files straight into OpenGL textures, when applicable. Image Formats: ; BMP : load and save ; TGA : load and save ; DDS : load and save ; PNG : load ; JPG : load OpenGL Texture Features: * resample to power-of-two sizes * MIPmap generation * compressed texture S3TC formats (if supported) * can pre-multiply alpha for you, for better compositing * can flip image about the y-axis (except pre-compressed DDS files) Thanks to: * Sean Barret - for the awesome stb_image * Dan Venkitachalam - for finding some non-compliant DDS files, and patching some explicit casts * everybody at gamedev.net * Jonathan Dummer for writing SOIL == Reference === Flags and Enumerations ==== Image Loading The format of images that may be loaded. force-channels/auto Leaves the image in whatever format it was found. force-channels/luminous Forces the image to load as Luminous (greyscale). force-channels/luminous-alpha Forces the image to load as Luminous with Alpha. force-channels/rgb Forces the image to load as Red Green Blue. force-channels/rgba Forces the image to load as Red Green Blue Alpha. ==== Texture Creation texture-id/create-new-id Passed in as reuse-texture-id, and will cause SOIL to register a new texture ID using glGenTextures(). If the value passed into reuse-texture-id > 0 then SOIL will just reuse that texture ID (great for reloading image assets in-game). ==== OpenGL Texture Format texture/power-of-two Force the image to be power-of-two. texture/mipmaps Generate mipmaps for the texture. texture/repeats Sets the image to repeating, otherwise it will be clamped. texture/multiply-alpha For when using (GL_ONE, GL_ONE_MINUS_SRC_ALPHA) blending. texture/invert-y Flip the image vertically. texture/compress If the card supports it this will convert RGB to DXT1, and RGBA to DXT5. texture/dds-direct Will load DDS files directly without any additional processing. texture/ntsc-safe-rgb Clamps RGB components to the NTSC GL safe range. texture/cogo-y RGB becomes CoYCg and RGBA becomes CoCgAY. texture/rectangle Uses ARB_texture_rectangle; generates pixedl indexed with no repeat, mip maps or cube maps. ==== Saving File Formats save-type/tga TGA format in uncompressed RGBA or RGB. save-type/bmp BMP format in uncompressed RGB save-type/dds DDS format in DXT1 or DXT5 ==== Cube Maps dds-cubemap-face-order The current face order as defined in the C preprocessor. Defaults to EWUDNS. In order to reorder this you will need to define SOIL_DDS_CUBEMAP_FACE_ORDER in the C preprocessor, likely in the #> <# header block of the appropriate scheme source file. ==== Internal HDR Representations fake-hdr/rgbe RGB * pow( 2.0, A - 128.0) fake-hdr/rgb-div-alpha RGB / A fake-hdr/rgb-div-alpha-squared RGB / (A * A) === Functions (load-ogl-texture filename force-channels texture-id texture-flags) Loads an image from disk into an OpenGL texture. filename Name of the file to load force-channels Format of image channels to force, see above definitions for appropriate values texture-id Use either texture-id/create-new-id or use an existing texture id to overwrite an existing texture texture-flags See above for appropriate texture/* to use, ie, texture/repeats or texture/mipmaps. Flags are bitwise, and can be combined with bitwise-ior Returns an OpenGL texture-id. (load-ogl-cubemap xpos-file xneg-file ypos-file yneg-file zpos-file zneg-file force-channels texture-id texture-flags) Loads a cubemap texture from disc. xpos-file File to load for the +x cube face xneg-file File to load for the -x cube face ypos-file File to load for the +y cube face yneg-file File to load for the -y cube face zpos-file File to load for the +z cube face zneg-file File to load for the -z cube face force-channels Format of image channels to force, see above definitions for appropriate values texture-id Use either texture-id/create-new-id or use an existing texture id to overwrite an existing texture texture-flags See above for appropriate texture/* to use, ie, texture/repeats or texture/mipmaps. Flags are bitwise, and can be combined with bitwise-ior Returns an OpenGL texture-id. (load-ogl-single-cubemap filename face-order force-channels texture-id texture-flags) Loads a single image from disc and splits it into an OpenGL cubemap texture. filename File to load and split into the texture face-order The order of the faces in the file, any combination of NSWEUD force-channels Format of image channels to force, see above definitions for appropriate values texture-id Use either texture-id/create-new-id or use an existing texture id to overwrite an existing texture texture-flags See above for appropriate texture/* to use, ie, texture/repeats or texture/mipmaps. Flags are bitwise, and can be combined with bitwise-ior Returns an OpenGL texture-id. (load-ogl-hdr-texture filename hdr-format rescale-to-max texture-id texture-flags) Loads an HDR image from disk into an OpenGL texture. filename File to load and split into the texture hdr-format One of the fake-hdr/* flags, IE, fake-hdr/rgbe rescale-to-max If true, rescales the image to max texture-id Use either texture-id/create-new-id or use an existing texture id to overwrite an existing texture texture-flags See above for appropriate texture/* to use, ie, texture/repeats or texture/mipmaps. Flags are bitwise, and can be combined with bitwise-ior Returns an OpenGL texture-id. (load-ogl-texture-from-memory buffer length force-channels texture-id texture-flags) Loads an image from memory into an OpenGL texture. buffer The blob from which the image should be loaded length The length, in bytes, to read from the blob force-channels Format of image channels to force, see above definitions for appropriate values texture-id Use either texture-id/create-new-id or use an existing texture id to overwrite an existing texture texture-flags See above for appropriate texture/* to use, ie, texture/repeats or texture/mipmaps. Flags are bitwise, and can be combined with bitwise-ior Returns an OpenGL texture-id. (load-ogl-cubemap-from-memory xpos-buffer xpos-length xneg-buffer xneg-length ypos-buffer ypos-length yneg-buffer yneg-length zpos-buffer zpos-length zneg-buffer zneg-length force-channels texture-id texture-flags) Loads a cubemap texture from memory. xpos-buffer Buffer to load for the +x cube face xpos-length Size, in bytes, to read from xpos-buffer xneg-buffer Buffer to load for the -x cube face xneg-length Size, in bytes, to read from xneg-buffer ypos-buffer Buffer to load for the +y cube face ypos-length Size, in bytes, to read from ypos-buffer yneg-buffer Buffer to load for the -y cube face yneg-length Size, in bytes, to read from yneg-buffer zpos-buffer Buffer to load for the +z cube face zpos-length Size, in bytes, to read from zpos-buffer zneg-buffer Buffer to load for the -z cube face zneg-length Size, in bytes, to read from zneg-buffer force-channels Format of image channels to force, see above definitions for appropriate values texture-id Use either texture-id/create-new-id or use an existing texture id to overwrite an existing texture texture-flags See above for appropriate texture/* to use, ie, texture/repeats or texture/mipmaps. Flags are bitwise, and can be combined with bitwise-ior Returns an OpenGL texture-id. (load-ogl-single-cubemap-from-memory buffer length order force-channels texture-id texture-flags) Loads a single image from memory and splits it into an OpenGL cubemap texture. buffer Blob to load and split into the texture length Size, in bytes, to read from the blob face-order The order of the faces in the file, any combination of NSWEUD force-channels Format of image channels to force, see above definitions for appropriate values texture-id Use either texture-id/create-new-id or use an existing texture id to overwrite an existing texture texture-flags See above for appropriate texture/* to use, ie, texture/repeats or texture/mipmaps. Flags are bitwise, and can be combined with bitwise-ior Returns an OpenGL texture-id. (create-ogl-texture data width height force-channels texture-id texture-flags) Creates a 2D OpenGL texture from raw image data. The raw data is not freed after being uploaded. (And it is thus safe to use a blob). data Blob to upload as an OpenGL texture width The width of the image in pixels height The height of the image in pixels force-channels Format of image channels to force, see above definitions for appropriate values texture-id Use either texture-id/create-new-id or use an existing texture id to overwrite an existing texture texture-flags See above for appropriate texture/* to use, ie, texture/repeats or texture/mipmaps. Flags are bitwise, and can be combined with bitwise-ior Returns an OpenGL texture-id. (create-ogl-single-cubemap data width height force-channels order texture-id texture-flags) data Blob to upload as an OpenGL texture width The width of the image in pixels height The height of the image in pixels face-order The order of the faces in the file, any combination of NSWEUD force-channels Format of image channels to force, see above definitions for appropriate values texture-id Use either texture-id/create-new-id or use an existing texture id to overwrite an existing texture texture-flags See above for appropriate texture/* to use, ie, texture/repeats or texture/mipmaps. Flags are bitwise, and can be combined with bitwise-ior Returns an OpenGL texture-id. (save-screenshot filename save-type x y width height) Captures the OpenGL window (RGB) and saves it to disk. filename The file to save the image to save-type The format to save the image in, one of save-type/* x Start x position y Start y position width Width of image height Height of image Returns #t if succesful. (last-result) Returns the last error message as a string. == Known Issues == Author Dan Leslie (dan@ironoxide.ca) == Version history ; 1.0 : First release == License Copyright 2012 Daniel J. Leslie. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY DANIEL J. LESLIE ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL DANIEL J. LESLIE OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of Daniel J. Leslie.