source: project/wiki/eggref/4/soil @ 32144

Last change on this file since 32144 was 32144, checked in by acharlton, 6 years ago

wiki/soil: Update to 1.3.0

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