Changeset 25815 in project


Ignore:
Timestamp:
01/17/12 06:39:42 (9 years ago)
Author:
svnwiki
Message:

Anonymous wiki edit for IP [70.71.179.201]: First pass soil documentation

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/soil

    r25471 r25815  
    1 == SOIL
    2 
    3 Simple OpenGL Image Library
    4 
    5 Coming soon
    6 
    7 For now, it's available on Github: https://github.com/dleslie/soil-egg
     1[[tags: egg soil image opengl gl bmp tga dds png jpg game]]
     2
     3== soil
     4
     5SOIL bindings for Chicken.
     6
     7[[toc:]]
     8
     9== Disclaimer
     10
     11For now, the egg is available at:
     12https://github.com/dleslie/soil-egg
     13
     14The interface adheres closely to the stock SOIL interface.
     15
     16Much thanks to Jonathan Dummer for writing the original SOIL library.
     17
     18== SOIL Overview
     19
     20SOIL is a tiny c library for uploading images as textures into OpenGL.  Also saving and loading of images is supported.
     21
     22It uses Sean's Tool Box image loader as a base:
     23http://www.nothings.org/
     24
     25SOIL upgrades stb_image to load TGA and DDS files, and adds a direct path for loading DDS files straight into OpenGL textures, when applicable.
     26
     27Image Formats:
     28; BMP : load and save
     29; TGA : load and save
     30; DDS : load and save
     31; PNG : load
     32; JPG : load
     33
     34OpenGL Texture Features:
     35* resample to power-of-two sizes
     36* MIPmap generation
     37* compressed texture S3TC formats (if supported)
     38* can pre-multiply alpha for you, for better compositing
     39* can flip image about the y-axis (except pre-compressed DDS files)
     40
     41Thanks to:
     42* Sean Barret - for the awesome stb_image
     43* Dan Venkitachalam - for finding some non-compliant DDS files, and patching some explicit casts
     44* everybody at gamedev.net
     45* Jonathan Dummer for writing SOIL
     46
     47== Reference
     48
     49=== Flags and Enumerations
     50
     51==== Image Loading
     52
     53The format of images that may be loaded.
     54
     55<constant>force-channels/auto</constant>
     56
     57Leaves the image in whatever format it was found.
     58
     59<constant>force-channels/luminous</constant>
     60
     61Forces the image to load as Luminous (greyscale).
     62
     63<constant>force-channels/luminous-alpha</constant>
     64
     65Forces the image to load as Luminous with Alpha.
     66
     67<constant>force-channels/rgb</constant>
     68
     69Forces the image to load as Red Green Blue.
     70
     71<constant>force-channels/rgba</constant>
     72
     73Forces the image to load as Red Green Blue Alpha.
     74
     75==== Texture Creation
     76
     77<constant>texture-id/create-new-id</constant>
     78
     79Passed 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).
     80
     81==== OpenGL Texture Format
     82
     83<constant>texture/power-of-two</constant>
     84
     85Force the image to be power-of-two.
     86
     87<constant>texture/mipmaps</constant>
     88
     89Generate mipmaps for the texture.
     90
     91<constant>texture/repeats</constant>
     92
     93Sets the image to repeating, otherwise it will be clamped.
     94
     95<constant>texture/multiply-alpha</constant>
     96
     97For when using (GL_ONE, GL_ONE_MINUS_SRC_ALPHA) blending.
     98
     99<constant>texture/invert-y</constant>
     100
     101Flip the image vertically.
     102
     103<constant>texture/compress</constant>
     104
     105If the card supports it this will convert RGB to DXT1, and RGBA to DXT5.
     106
     107<constant>texture/dds-direct</constant>
     108
     109Will load DDS files directly without any additional processing.
     110
     111<constant>texture/ntsc-safe-rgb</constant>
     112
     113Clamps RGB components to the NTSC GL safe range.
     114
     115<constant>texture/cogo-y</constant>
     116
     117RGB becomes CoYCg and RGBA becomes CoCgAY.
     118
     119<constant>texture/rectangle</constant>
     120
     121Uses ARB_texture_rectangle; generates pixedl indexed with no repeat, mip maps or cube maps.
     122
     123==== Saving File Formats
     124
     125<constant>save-type/tga</constant>
     126
     127TGA format in uncompressed RGBA or RGB.
     128
     129<constant>save-type/bmp</constant>
     130
     131BMP format in uncompressed RGB
     132
     133<constant>save-type/dds</constant>
     134
     135DDS format in DXT1 or DXT5
     136
     137==== Cube Maps
     138
     139<constant>dds-cubemap-face-order</constant>
     140
     141The 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.
     142
     143==== Internal HDR Representations
     144
     145<constant>fake-hdr/rgbe</constant>
     146
     147RGB * pow( 2.0, A - 128.0)
     148
     149<constant>fake-hdr/rgb-div-alpha</constant>
     150
     151RGB / A
     152
     153<constant>fake-hdr/rgb-div-alpha-squared</constant>
     154
     155RGB / (A * A)
     156
     157=== Functions
     158
     159<procedure>(load-ogl-texture filename force-channels texture-id texture-flags)</procedure>
     160
     161Loads an image from disk into an OpenGL texture.
     162
     163<parameter>filename</parameter> Name of the file to load
     164<parameter>force-channels</parameter> Format of image channels to force, see above definitions for appropriate values
     165<parameter>texture-id</parameter> Use either texture-id/create-new-id or use an existing texture id to overwrite an existing texture
     166<parameter>texture-flags</parameter> See above for appropriate texture/* to use, ie, texture/repeats or texture/mipmaps. Flags are bitwise, and can be combined with bitwise-ior
     167
     168Returns an OpenGL texture-id.
     169
     170<procedure>(load-ogl-cubemap xpos-file xneg-file ypos-file yneg-file zpos-file zneg-file force-channels texture-id texture-flags)</procedure>
     171
     172Loads a cubemap texture from disc.
     173
     174<parameter>xpos-file</parameter> File to load for the +x cube face
     175<parameter>xneg-file</parameter> File to load for the -x cube face
     176<parameter>ypos-file</parameter> File to load for the +y cube face
     177<parameter>yneg-file</parameter> File to load for the -y cube face
     178<parameter>zpos-file</parameter> File to load for the +z cube face
     179<parameter>zneg-file</parameter> File to load for the -z cube face
     180<parameter>force-channels</parameter> Format of image channels to force, see above definitions for appropriate values
     181<parameter>texture-id</parameter> Use either texture-id/create-new-id or use an existing texture id to overwrite an existing texture
     182<parameter>texture-flags</parameter> See above for appropriate texture/* to use, ie, texture/repeats or texture/mipmaps. Flags are bitwise, and can be combined with bitwise-ior
     183
     184Returns an OpenGL texture-id.
     185
     186<procedure>(load-ogl-single-cubemap filename face-order force-channels texture-id texture-flags)</procedure>
     187
     188Loads a single image from disc and splits it into an OpenGL cubemap texture.
     189
     190<parameter>filename</parameter> File to load and split into the texture
     191<parameter>face-order</parameter> The order of the faces in the file, any combination of NSWEUD
     192<parameter>force-channels</parameter> Format of image channels to force, see above definitions for appropriate values
     193<parameter>texture-id</parameter> Use either texture-id/create-new-id or use an existing texture id to overwrite an existing texture
     194<parameter>texture-flags</parameter> See above for appropriate texture/* to use, ie, texture/repeats or texture/mipmaps. Flags are bitwise, and can be combined with bitwise-ior
     195
     196Returns an OpenGL texture-id.
     197
     198<procedure>(load-ogl-hdr-texture filename hdr-format rescale-to-max texture-id texture-flags)</procedure>
     199
     200Loads an HDR image from disk into an OpenGL texture.
     201
     202<parameter>filename</parameter> File to load and split into the texture
     203<parameter>hdr-format</parameter> One of the fake-hdr/* flags, IE, fake-hdr/rgbe
     204<parameter>rescale-to-max</parameter> If true, rescales the image to max
     205<parameter>texture-id</parameter> Use either texture-id/create-new-id or use an existing texture id to overwrite an existing texture
     206<parameter>texture-flags</parameter> See above for appropriate texture/* to use, ie, texture/repeats or texture/mipmaps. Flags are bitwise, and can be combined with bitwise-ior
     207
     208Returns an OpenGL texture-id.
     209
     210<procedure>(load-ogl-texture-from-memory buffer length force-channels texture-id texture-flags)</procedure>
     211
     212Loads an image from memory into an OpenGL texture.
     213
     214<parameter>buffer</parameter> The blob from which the image should be loaded
     215<parameter>length</parameter> The length, in bytes, to read from the blob
     216<parameter>force-channels</parameter> Format of image channels to force, see above definitions for appropriate values
     217<parameter>texture-id</parameter> Use either texture-id/create-new-id or use an existing texture id to overwrite an existing texture
     218<parameter>texture-flags</parameter> See above for appropriate texture/* to use, ie, texture/repeats or texture/mipmaps. Flags are bitwise, and can be combined with bitwise-ior
     219
     220Returns an OpenGL texture-id.
     221
     222<procedure>(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)</procedure>
     223
     224Loads a cubemap texture from memory.
     225
     226<parameter>xpos-buffer</parameter> Buffer to load for the +x cube face
     227<parameter>xpos-length</parameter> Size, in bytes, to read from xpos-buffer
     228<parameter>xneg-buffer</parameter> Buffer to load for the -x cube face
     229<parameter>xneg-length</parameter> Size, in bytes, to read from xneg-buffer
     230<parameter>ypos-buffer</parameter> Buffer to load for the +y cube face
     231<parameter>ypos-length</parameter> Size, in bytes, to read from ypos-buffer
     232<parameter>yneg-buffer</parameter> Buffer to load for the -y cube face
     233<parameter>yneg-length</parameter> Size, in bytes, to read from yneg-buffer
     234<parameter>zpos-buffer</parameter> Buffer to load for the +z cube face
     235<parameter>zpos-length</parameter> Size, in bytes, to read from zpos-buffer
     236<parameter>zneg-buffer</parameter> Buffer to load for the -z cube face
     237<parameter>zneg-length</parameter> Size, in bytes, to read from zneg-buffer
     238<parameter>force-channels</parameter> Format of image channels to force, see above definitions for appropriate values
     239<parameter>texture-id</parameter> Use either texture-id/create-new-id or use an existing texture id to overwrite an existing texture
     240<parameter>texture-flags</parameter> See above for appropriate texture/* to use, ie, texture/repeats or texture/mipmaps. Flags are bitwise, and can be combined with bitwise-ior
     241
     242Returns an OpenGL texture-id.
     243
     244<procedure>(load-ogl-single-cubemap-from-memory buffer length order force-channels texture-id texture-flags)</procedure>
     245
     246Loads a single image from memory and splits it into an OpenGL cubemap texture.
     247
     248<parameter>buffer</parameter> Blob to load and split into the texture
     249<parameter>length</parameter> Size, in bytes, to read from the blob
     250<parameter>face-order</parameter> The order of the faces in the file, any combination of NSWEUD
     251<parameter>force-channels</parameter> Format of image channels to force, see above definitions for appropriate values
     252<parameter>texture-id</parameter> Use either texture-id/create-new-id or use an existing texture id to overwrite an existing texture
     253<parameter>texture-flags</parameter> See above for appropriate texture/* to use, ie, texture/repeats or texture/mipmaps. Flags are bitwise, and can be combined with bitwise-ior
     254
     255Returns an OpenGL texture-id.
     256
     257<procedure>(create-ogl-texture data width height force-channels texture-id texture-flags)</procedure>
     258
     259Creates 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).
     260
     261<parameter>data</parameter> Blob to upload as an OpenGL texture
     262<parameter>width</parameter> The width of the image in pixels
     263<parameter>height</parameter> The height of the image in pixels
     264<parameter>force-channels</parameter> Format of image channels to force, see above definitions for appropriate values
     265<parameter>texture-id</parameter> Use either texture-id/create-new-id or use an existing texture id to overwrite an existing texture
     266<parameter>texture-flags</parameter> See above for appropriate texture/* to use, ie, texture/repeats or texture/mipmaps. Flags are bitwise, and can be combined with bitwise-ior
     267
     268Returns an OpenGL texture-id.
     269
     270<procedure>(create-ogl-single-cubemap data width height force-channels order texture-id texture-flags)</procedure>
     271
     272<parameter>data</parameter> Blob to upload as an OpenGL texture
     273<parameter>width</parameter> The width of the image in pixels
     274<parameter>height</parameter> The height of the image in pixels
     275<parameter>face-order</parameter> The order of the faces in the file, any combination of NSWEUD
     276<parameter>force-channels</parameter> Format of image channels to force, see above definitions for appropriate values
     277<parameter>texture-id</parameter> Use either texture-id/create-new-id or use an existing texture id to overwrite an existing texture
     278<parameter>texture-flags</parameter> See above for appropriate texture/* to use, ie, texture/repeats or texture/mipmaps. Flags are bitwise, and can be combined with bitwise-ior
     279
     280Returns an OpenGL texture-id.
     281
     282<procedure>(save-screenshot filename save-type x y width height)</procedure>
     283
     284Captures the OpenGL window (RGB) and saves it to disk.
     285
     286<parameter>filename</parameter> The file to save the image to
     287<parameter>save-type</parameter> The format to save the image in, one of save-type/*
     288<parameter>x</parameter> Start x position
     289<parameter>y</parameter> Start y position
     290<parameter>width</parameter> Width of image
     291<parameter>height</parameter> Height of image
     292
     293Returns #t if succesful.
     294
     295<procedure>(last-result)</procedure>
     296
     297Returns the last error message as a string.
     298
     299== Known Issues
     300
     301
     302== Author
     303
     304Dan Leslie (dan@ironoxide.ca)
     305
     306== Version history
     307
     308; 1.0 : First release
     309
     310== License
     311
     312Copyright 2012 Daniel J. Leslie. All rights reserved.
     313
     314Redistribution and use in source and binary forms, with or without modification, are
     315permitted provided that the following conditions are met:
     316
     317   1. Redistributions of source code must retain the above copyright notice, this list of
     318      conditions and the following disclaimer.
     319
     320   2. Redistributions in binary form must reproduce the above copyright notice, this list
     321      of conditions and the following disclaimer in the documentation and/or other materials
     322      provided with the distribution.
     323
     324THIS SOFTWARE IS PROVIDED BY DANIEL J. LESLIE ''AS IS'' AND ANY EXPRESS OR IMPLIED
     325WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
     326FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL DANIEL J. LESLIE OR
     327CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
     328CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
     329SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
     330ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
     331NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
     332ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     333
     334The views and conclusions contained in the software and documentation are those of the
     335authors and should not be interpreted as representing official policies, either expressed
     336or implied, of Daniel J. Leslie.
Note: See TracChangeset for help on using the changeset viewer.