source: project/wiki/eggref/5/soil @ 37442

Last change on this file since 37442 was 37442, checked in by Kooda, 17 months ago

Document soil for CHICKEN 5

File size: 13.7 KB
Line 
1[[tags: egg soil image opengl gl bmp tga dds png jpg game]]
2
3
4== soil
5[[toc:]]
6[[toc:]]
7
8[[http://www.lonesock.net/soil.html|SOIL]] bindings for Chicken.
9
10The source is available on [[https://www.upyum.com/cgit.cgi/soil-egg/|a git repository]].
11
12The interface adheres closely to the stock SOIL interface.
13
14soil is known to work on Linux, Mac OS X, Windows, and with OpenGL ES.
15
16Much thanks to Jonathan Dummer for writing the original SOIL library.
17
18
19=== SOIL Overview
20[[http://www.lonesock.net/soil.html|SOIL]] is a tiny C library for uploading images as textures into OpenGL. Also, saving and loading of images is supported.
21
22SOIL uses [[http://www.nothings.org/|Sean's Tool Box]] image loader as a base, upgrading it to load TGA and DDS files, and adds a direct path for loading DDS files straight into OpenGL textures, when applicable.
23
24The following image formats are supported:
25
26* BMP: load and save
27* TGA: load and save
28* DDS: load and save
29* PNG: load
30* JPG: load
31
32OpenGL Texture Features:
33
34* resample to power-of-two sizes
35* MIPmap generation
36* compressed texture S3TC formats (if supported)
37* can pre-multiply alpha for you, for better compositing
38* can flip image about the y-axis (except pre-compressed DDS files)
39
40
41=== Reference
42
43==== Functions
44<procedure> (load-ogl-texture filename force-channels texture-id texture-flags)</procedure>
45
46Loads an image from disk into an OpenGL texture.
47
48* {{filename}}: Name of the file to load
49* {{force-channels}}: Format of image channels to force, see below definitions for appropriate values
50* {{texture-id}}: Use either {{texture-id/create-new-id}} or use an existing texture id to overwrite an existing texture
51* {{texture-flags}}: See below for appropriate {{texture/***}} flags to use, i.e., {{texture/repeats}} or {{texture/mipmaps}}. Flags are bitwise, and can be combined with {{bitwise-ior}}
52
53Returns an OpenGL texture ID.
54
55<procedure> (load-ogl-cubemap xpos-file xneg-file ypos-file yneg-file zpos-file zneg-file force-channels texture-id texture-flags)</procedure>
56
57Loads a cubemap texture from disc.
58
59* {{xpos-file}}: File to load for the +x cube face
60* {{xneg-file}}: File to load for the -x cube face
61* {{ypos-file}}: File to load for the +y cube face
62* {{yneg-file}}: File to load for the -y cube face
63* {{zpos-file}}: File to load for the +z cube face
64* {{zneg-file}}: File to load for the -z cube face
65* {{force-channels}}: Format of image channels to force, see below definitions for appropriate values
66* {{texture-id}}: Use either {{texture-id/create-new-id}} or use an existing texture id to overwrite an existing texture
67* {{texture-flags}}: See below for appropriate {{texture/***}} flags to use, i.e., {{texture/repeats}} or {{texture/mipmaps}}. Flags are bitwise, and can be combined with {{bitwise-ior}}
68
69Returns an OpenGL texture ID.
70
71<procedure> (load-ogl-single-cubemap filename face-order force-channels texture-id texture-flags)</procedure>
72
73Loads a single image from disc and splits it into an OpenGL cubemap texture.
74
75* {{filename}}: File to load and split into the texture
76* {{face-order}}: The order of the faces in the file, any permutation of {{"NSWEUD"}} representing North, South, West, East, Up, Down
77* {{force-channels}}: Format of image channels to force, see below definitions for appropriate values
78* {{texture-id}}: Use either {{texture-id/create-new-id}} or use an existing texture id to overwrite an existing texture
79* {{texture-flags}}: See below for appropriate {{texture/***}} flags to use, i.e., {{texture/repeats}} or {{texture/mipmaps}}. Flags are bitwise, and can be combined with {{bitwise-ior}}
80
81Returns an OpenGL texture ID.
82
83<procedure> (load-ogl-hdr-texture filename hdr-format rescale-to-max texture-id texture-flags)</procedure>
84
85Loads an HDR image from disk into an OpenGL texture.
86
87* {{filename}}: File to load and split into the texture
88* {{hdr-format}}: One of the {{fake-hdr/***}} flags, i.e., {{fake-hdr/rgbe}}
89* {{rescale-to-max}}: If true, rescales the image to max
90* {{texture-id}}: Use either {{texture-id/create-new-id}} or use an existing texture id to overwrite an existing texture
91* {{texture-flags}}: See below for appropriate {{texture/***}} flags to use, i.e., {{texture/repeats}} or {{texture/mipmaps}}. Flags are bitwise, and can be combined with {{bitwise-ior}}
92
93Returns an OpenGL texture ID.
94
95<procedure> (load-ogl-texture-from-memory buffer length force-channels texture-id texture-flags)</procedure>
96
97Loads an image from memory into an OpenGL texture.
98
99* {{buffer}}: The blob from which the image should be loaded
100* {{length}}: The length, in bytes, to read from the blob
101* {{force-channels}}: Format of image channels to force, see below definitions for appropriate values
102* {{texture-id}}: Use either {{texture-id/create-new-id}} or use an existing texture id to overwrite an existing texture
103* {{texture-flags}}: See below for appropriate {{texture/***}} flags to use, i.e., {{texture/repeats}} or {{texture/mipmaps}}. Flags are bitwise, and can be combined with {{bitwise-ior}}
104
105Returns an OpenGL texture ID.
106
107<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>
108
109Loads a cubemap texture from memory.
110
111* {{xpos-buffer}}: Buffer to load for the +x cube face
112* {{xpos-length}}: Size, in bytes, to read from xpos-buffer
113* {{xneg-buffer}}: Buffer to load for the -x cube face
114* {{xneg-length}}: Size, in bytes, to read from xneg-buffer
115* {{ypos-buffer}}: Buffer to load for the +y cube face
116* {{ypos-length}}: Size, in bytes, to read from ypos-buffer
117* {{yneg-buffer}}: Buffer to load for the -y cube face
118* {{yneg-length}}: Size, in bytes, to read from yneg-buffer
119* {{zpos-buffer}}: Buffer to load for the +z cube face
120* {{zpos-length}}: Size, in bytes, to read from zpos-buffer
121* {{zneg-buffer}}: Buffer to load for the -z cube face
122* {{zneg-length}}: Size, in bytes, to read from zneg-buffer
123* {{force-channels}}: Format of image channels to force, see below definitions for appropriate values
124* {{texture-id}}: Use either {{texture-id/create-new-id}} or use an existing texture id to overwrite an existing texture
125* {{texture-flags}}: See below for appropriate {{texture/***}} flags to use, i.e., {{texture/repeats}} or {{texture/mipmaps}}. Flags are bitwise, and can be combined with {{bitwise-ior}}
126
127Returns an OpenGL texture ID.
128
129<procedure> (load-ogl-single-cubemap-from-memory buffer length order force-channels texture-id texture-flags)</procedure>
130
131Loads a single image from memory and splits it into an OpenGL cubemap texture.
132
133* {{buffer}}: Blob to load and split into the texture
134* {{length}}: Size, in bytes, to read from the blob
135* {{face-order}}: The order of the faces in the file, any permutation of {{"NSWEUD"}} representing North, South, West, East, Up, Down
136* {{force-channels}}: Format of image channels to force, see below definitions for appropriate values
137* {{texture-id}}: Use either {{texture-id/create-new-id}} or use an existing texture id to overwrite an existing texture
138* {{texture-flags}}: See below for appropriate {{texture/***}} flags to use, i.e., {{texture/repeats}} or {{texture/mipmaps}}. Flags are bitwise, and can be combined with {{bitwise-ior}}
139
140Returns an OpenGL texture ID.
141
142<procedure> (create-ogl-texture data width height force-channels texture-id texture-flags)</procedure>
143
144Creates 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).
145
146* {{data}}: Blob to upload as an OpenGL texture
147* {{width}}: The width of the image in pixels
148* {{height}}: The height of the image in pixels
149* {{force-channels}}: Format of image channels to force, see below definitions for appropriate values
150* {{texture-id}}: Use either {{texture-id/create-new-id}} or use an existing texture id to overwrite an existing texture
151* {{texture-flags}}: See below for appropriate {{texture/***}} flags to use, i.e., {{texture/repeats}} or {{texture/mipmaps}}. Flags are bitwise, and can be combined with {{bitwise-ior}}
152
153Returns an OpenGL texture ID.
154
155<procedure> (create-ogl-single-cubemap data width height force-channels order texture-id texture-flags)</procedure>
156
157* {{data}}: Blob to upload as an OpenGL texture
158* {{width}}: The width of the image in pixels
159* {{height}}: The height of the image in pixels
160* {{face-order}}: The order of the faces in the file, any permutation of {{"NSWEUD"}} representing North, South, West, East, Up, Down
161* {{force-channels}}: Format of image channels to force, see below definitions for appropriate values
162* {{texture-id}}: Use either {{texture-id/create-new-id}} or use an existing texture id to overwrite an existing texture
163* {{texture-flags}}: See below for appropriate {{texture/***}} flags to use, i.e., {{texture/repeats}} or {{texture/mipmaps}}. Flags are bitwise, and can be combined with {{bitwise-ior}}
164
165Returns an OpenGL texture ID.
166
167<procedure> (save-screenshot filename save-type x y width height)</procedure>
168
169Captures the OpenGL window (RGB) and saves it to disk.
170
171* {{filename}}: The file to save the image to
172* {{save-type}}: The format to save the image in, one of save-type/*
173* {{x}}: Start x position
174* {{y}}: Start y position
175* {{width}}: Width of image
176* {{height}}: Height of image
177
178Returns {{#t}} if successful.
179
180<procedure> (last-result)</procedure>
181
182Returns the last error message as a string.
183
184<procedure> (ogl-texture-width texture)</procedure>
185<procedure> (ogl-texture-height texture)</procedure>
186
187Returns the width and height of the given OpenGL texture.
188
189
190==== Flags
191
192===== Image Loading
193These flags affect the format of images that are loaded.
194
195<constant> force-channels/auto</constant>
196
197Leaves the image in whatever format it was found.
198
199<constant> force-channels/luminous</constant>
200
201Forces the image to load as Luminous (greyscale).
202
203<constant> force-channels/luminous-alpha</constant>
204
205Forces the image to load as Luminous with Alpha.
206
207<constant> force-channels/rgb</constant>
208
209Forces the image to load as Red Green Blue.
210
211<constant> force-channels/rgba</constant>
212
213Forces the image to load as Red Green Blue Alpha.
214
215
216===== Texture Creation
217<constant> texture-id/create-new-id</constant>
218
219Passed in as the {{texture-id}} argument, this will cause soil to register a new texture ID using {{gl:gen-textures}}. If the value passed as a {{texture-id}} argument is greater than zero, then soil will just reuse that texture ID (great for reloading image assets in-game).
220
221
222===== OpenGL Texture Format
223If multiple {{texture/***}} flags are to be passed to the {{texture}} argument, they must be OR’d (i.e. with {{bitwise-ior}}) together.
224
225<constant> texture/power-of-two</constant>
226
227Force the image to be power-of-two.
228
229<constant> texture/mipmaps</constant>
230
231Generate mipmaps for the texture.
232
233<constant> texture/repeats</constant>
234
235Sets the image to repeating, otherwise it will be clamped.
236
237<constant> texture/multiply-alpha</constant>
238
239For when using ({{gl:+one+}}, {{gl:+one-minus-src-alpha+}}) blending.
240
241<constant> texture/invert-y</constant>
242
243Flip the image vertically.
244
245<constant> texture/compress</constant>
246
247If the card supports it this will convert RGB to DXT1, and RGBA to DXT5.
248
249<constant> texture/dds-direct</constant>
250
251Will load DDS files directly without any additional processing.
252
253<constant> texture/ntsc-safe-rgb</constant>
254
255Clamps RGB components to the NTSC GL safe range.
256
257<constant> texture/cogo-y</constant>
258
259RGB becomes CoYCg and RGBA becomes CoCgAY.
260
261<constant> texture/rectangle</constant>
262
263Uses {{ARB_texture_rectangle}}; generates pixedl indexed with no repeat, mip maps or cube maps.
264
265
266===== Saving File Formats
267<constant> save-type/tga</constant>
268
269TGA format in uncompressed RGBA or RGB.
270
271<constant> save-type/bmp</constant>
272
273BMP format in uncompressed RGB
274
275<constant> save-type/dds</constant>
276
277DDS format in DXT1 or DXT5
278
279
280===== Internal HDR Representations
281<constant> fake-hdr/rgbe</constant>
282
283RGB * pow( 2.0, A - 128.0)
284
285<constant> fake-hdr/rgb-div-alpha</constant>
286
287RGB / A
288
289<constant> fake-hdr/rgb-div-alpha-squared</constant>
290
291RGB / (A * A)
292
293
294=== Authors
295Dan Leslie (dan@ironoxide.ca)
296
297Alex Charlton (alex.n.charlton@gmail.com)
298
299Adrien (Kooda) Ramos (kooda@upyum.com)
300
301
302=== Version history
303* 1.6: Ported to CHICKEN 5 and libepoxy
304* 1.3: Remove {{dds-cubemap-face-order}}, fix texture creation function return values, support OpenGL ES
305* 1.2: SOIL source built into egg
306* 1.1: Added procedures to retrieve texture size
307* 1.0: First release
308
309
310=== License
311Copyright 2012 Daniel J. Leslie. All rights reserved.
312
313Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
314
315# Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
316
317
318# 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.
319
320
321
322THIS 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.
323
324The 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.
325
Note: See TracBrowser for help on using the repository browser.