chickadee » soil

soil

SOIL bindings for Chicken.

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:

Thanks to:

Reference

Flags and Enumerations

Image Loading

The format of images that may be loaded.

force-channels/auto constant

Leaves the image in whatever format it was found.

force-channels/luminous constant

Forces the image to load as Luminous (greyscale).

force-channels/luminous-alpha constant

Forces the image to load as Luminous with Alpha.

force-channels/rgb constant

Forces the image to load as Red Green Blue.

force-channels/rgba constant

Forces the image to load as Red Green Blue Alpha.

Texture Creation

texture-id/create-new-id constant

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 constant

Force the image to be power-of-two.

texture/mipmaps constant

Generate mipmaps for the texture.

texture/repeats constant

Sets the image to repeating, otherwise it will be clamped.

texture/multiply-alpha constant

For when using (GL_ONE, GL_ONE_MINUS_SRC_ALPHA) blending.

texture/invert-y constant

Flip the image vertically.

texture/compress constant

If the card supports it this will convert RGB to DXT1, and RGBA to DXT5.

texture/dds-direct constant

Will load DDS files directly without any additional processing.

texture/ntsc-safe-rgb constant

Clamps RGB components to the NTSC GL safe range.

texture/cogo-y constant

RGB becomes CoYCg and RGBA becomes CoCgAY.

texture/rectangle constant

Uses ARB_texture_rectangle; generates pixedl indexed with no repeat, mip maps or cube maps.

Saving File Formats

save-type/tga constant

TGA format in uncompressed RGBA or RGB.

save-type/bmp constant

BMP format in uncompressed RGB

save-type/dds constant

DDS format in DXT1 or DXT5

Cube Maps

dds-cubemap-face-order constant

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 constant

RGB * pow( 2.0, A - 128.0)

fake-hdr/rgb-div-alpha constant

RGB / A

fake-hdr/rgb-div-alpha-squared constant

RGB / (A * A)

Functions

(load-ogl-texture filename force-channels texture-id texture-flags) procedure

Loads an image from disk into an OpenGL texture.

filename parameter
force-channels parameter
texture-id parameter
texture-flags parameter

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) procedure

Loads a cubemap texture from disc.

xpos-file parameter
xneg-file parameter
ypos-file parameter
yneg-file parameter
zpos-file parameter
zneg-file parameter
force-channels parameter
texture-id parameter
texture-flags parameter

Returns an OpenGL texture-id.

(load-ogl-single-cubemap filename face-order force-channels texture-id texture-flags) procedure

Loads a single image from disc and splits it into an OpenGL cubemap texture.

filename parameter
face-order parameter
force-channels parameter
texture-id parameter
texture-flags parameter

Returns an OpenGL texture-id.

(load-ogl-hdr-texture filename hdr-format rescale-to-max texture-id texture-flags) procedure

Loads an HDR image from disk into an OpenGL texture.

filename parameter
hdr-format parameter
rescale-to-max parameter
texture-id parameter
texture-flags parameter

Returns an OpenGL texture-id.

(load-ogl-texture-from-memory buffer length force-channels texture-id texture-flags) procedure

Loads an image from memory into an OpenGL texture.

buffer parameter
length parameter
force-channels parameter
texture-id parameter
texture-flags parameter

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) procedure

Loads a cubemap texture from memory.

xpos-buffer parameter
xpos-length parameter
xneg-buffer parameter
xneg-length parameter
ypos-buffer parameter
ypos-length parameter
yneg-buffer parameter
yneg-length parameter
zpos-buffer parameter
zpos-length parameter
zneg-buffer parameter
zneg-length parameter
force-channels parameter
texture-id parameter
texture-flags parameter

Returns an OpenGL texture-id.

(load-ogl-single-cubemap-from-memory buffer length order force-channels texture-id texture-flags) procedure

Loads a single image from memory and splits it into an OpenGL cubemap texture.

buffer parameter
length parameter
face-order parameter
force-channels parameter
texture-id parameter
texture-flags parameter

Returns an OpenGL texture-id.

(create-ogl-texture data width height force-channels texture-id texture-flags) procedure

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 parameter
width parameter
height parameter
force-channels parameter
texture-id parameter
texture-flags parameter

Returns an OpenGL texture-id.

(create-ogl-single-cubemap data width height force-channels order texture-id texture-flags) procedure
data parameter
width parameter
height parameter
face-order parameter
force-channels parameter
texture-id parameter
texture-flags parameter

Returns an OpenGL texture-id.

(save-screenshot filename save-type x y width height) procedure

Captures the OpenGL window (RGB) and saves it to disk.

filename parameter
save-type parameter
x parameter
y parameter
width parameter
height parameter

Returns #t if succesful.

(last-result) procedure

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.

Contents »