The cl-soil Reference Manual

3.1.1 cl-soil/cl-soil.asd

Source

cl-soil.asd.

Parent Component

cl-soil (system).

ASDF Systems

cl-soil.

---

3.1.2 cl-soil/package.lisp

Source

cl-soil.asd.

Parent Component

cl-soil (system).

Packages

• cl-soil.
• stb-image.

---

3.1.3 cl-soil/backend.lisp

Dependency

package.lisp (file).

Source

cl-soil.asd.

Parent Component

cl-soil (system).

Internals

• soil-create-ogl-single-cubemap (function).
• soil-create-ogl-texture (function).
• soil-free-image-data (function).
• soil-last-result (function).
• soil-load-image (function).
• soil-load-image-from-memory (function).
• soil-load-ogl-cubemap (function).
• soil-load-ogl-cubemap-from-memory (function).
• soil-load-ogl-hdr-texture (function).
• soil-load-ogl-single-cubemap (function).
• soil-load-ogl-single-cubemap-from-memory (function).
• soil-load-ogl-texture (function).
• soil-load-ogl-texture-from-memory (function).
• soil-save-image (function).
• soil-save-screenshot (function).

---

3.1.4 cl-soil/cl-soil.lisp

Dependency

backend.lisp (file).

Source

cl-soil.asd.

Parent Component

cl-soil (system).

Public Interface

• create-ogl-single-cubemap (function).
• create-ogl-texture (function).
• free-image-data (function).
• last-result (function).
• load-image (function).
• load-image-from-memory (function).
• load-ogl-cubemap (function).
• load-ogl-cubemap-from-memory (function).
• load-ogl-hdr-texture (function).
• load-ogl-single-cubemap (function).
• load-ogl-single-cubemap-from-memory (function).
• load-ogl-texture (function).
• load-ogl-texture-from-memory (function).
• save-image (function).
• save-screenshot (function).

Internals

• handle-tex-flags (function).
• with-foreign-filepath (macro).
• with-foreign-filepaths (macro).
• with-zero-being-an-error (macro).

---

3.1.5 cl-soil/stbi.lisp

Dependency

cl-soil.lisp (file).

Source

cl-soil.asd.

Parent Component

cl-soil (system).

Public Interface

loadf (function).

Internals

%loadf (function).

---

3.1.6 cl-soil/docs.lisp

Dependency

stbi.lisp (file).

Source

cl-soil.asd.

Parent Component

cl-soil (system).

---

5.1.1 Ordinary functions

Function: create-ogl-single-cubemap (data-pointer width height channels face-order reuse-texture-id flags) ¶

Creates an OpenGL cubemap texture by splitting up 1 image into 6 parts. Returns the texture-id

data-pointer: pointer to the image data

width: width of the image in pixels

height: height of the image in pixels

channels: the number of channels:

Count Meaning
———————-
1 luminous
2 luminous/alpha
3 RGB
4 RGBA

face-order: the order of the faces in the file. Any combination of NSWEUD, for North, South, Up, etc as a keyword. For example :UDNSWE

reuse-texture-id: The gl texture id to reuse, or 0 to generate a new texture.

flags: One or a list of the following

Name Effect ——————————————–
:power-of-two force the image to be POT
:mipmaps generate mipmaps for the texture
:texture-repeats Sampling set to repeat (otherwise will clamp) :multiply-alpha for using (:one, :one_minus_src_alpha) blending :invert-y flip the image vertically
:compress-to-dxt if gpu support it, converts RGB to DXT1, RGBA to DXT5 :dds-load-direct will load DDS files directly without _ANY_ additional processing.

Package

cl-soil.

Source

cl-soil.lisp.

Function: create-ogl-texture (data-pointer width height &optional channels reuse-texture-id flags) ¶

Creates a 2D OpenGL texture from raw image data. Returns the texture-id

data-pointer: pointer to the image data

width: width of the image in pixels

height: height of the image in pixels

channels: the number of channels:

Count Meaning
———————-
1 luminous
2 luminous/alpha
3 RGB
4 RGBA

reuse-texture-id: The gl texture id to reuse, or 0 to generate a new texture.

flags: One or a list of the following

Name Effect ——————————————–
:power-of-two force the image to be POT
:mipmaps generate mipmaps for the texture
:texture-repeats Sampling set to repeat (otherwise will clamp) :multiply-alpha for using (:one, :one_minus_src_alpha) blending :invert-y flip the image vertically
:compress-to-dxt if gpu support it, converts RGB to DXT1, RGBA to DXT5 :dds-load-direct will load DDS files directly without _ANY_ additional processing.

Package

cl-soil.

Source

cl-soil.lisp.

Function: free-image-data (data-pointer) ¶

Frees the image data.

This is really just cffi:foreign-free but exists as a reminder to free your data.

Package

cl-soil.

Source

cl-soil.lisp.

Function: last-result () ¶

This function resturn a string describing the last thing that happened inside SOIL. It can be used to determine why an image failed to load.

Package

cl-soil.

Source

cl-soil.lisp.

Function: load-image (filepath &optional force-channels) ¶

Loads an image from disk. Returns the following:

- A pointer to the image data
- the width of the image
- the height of the image
- the component-count of the data as stored in the file
- the component-count of the returned image data

Where the component-count is one of the following:

Count Meaning
———————-
1 luminous
2 luminous/alpha
3 RGB
4 RGBA

filename: the name of the file to load

force-channels: One of the following:

Name Effect ——————————————-
:auto leaves the image in whatever format it was found :l forces the image to load as Luminous (greyscale) :la forces the image to load as Luminous with Alpha :rgb forces the image to load as Red Green Blue :rgba forces the image to load as Red Green Blue Alpha

Package

cl-soil.

Source

cl-soil.lisp.

Function: load-image-from-memory (data-pointer data-length &optional force-channels) ¶

Loads an image from memory. Returns the following:

- A pointer to the image data
- the width of the image in pixels
- the height of the image in pixels
- the component-count of the data as stored in the file
- the component-count of the returned image data

Where the component-count is one of the following:

Count Meaning
———————-
1 luminous
2 luminous/alpha
3 RGB
4 RGBA

data-pointer: pointer to the image data

data-length: length of the data in bytes

force-channels: One of the following:

Name Effect ——————————————-
:auto leaves the image in whatever format it was found :l forces the image to load as Luminous (greyscale) :la forces the image to load as Luminous with Alpha :rgb forces the image to load as Red Green Blue :rgba forces the image to load as Red Green Blue Alpha

Package

cl-soil.

Source

cl-soil.lisp.

Function: load-ogl-cubemap (x-pos-filepath x-neg-filepath y-pos-filepath y-neg-filepath z-pos-filepath z-neg-filepath &optional force-channels reuse-texture-id flags) ¶

Loads 6 images from disk into an OpenGL cubemap texture. Returns the texture-id

x-pos-filepath: the name of the file to upload as a texture face

x-neg-filepath: the name of the file to upload as a texture face

y-pos-filepath: the name of the file to upload as a texture face

y-neg-filepath: the name of the file to upload as a texture face

z-pos-filepath: the name of the file to upload as a texture face

z-neg-filepath: the name of the file to upload as a texture face

force-channels: One of the following:

Name Effect
——————————————-
:auto leaves the image in whatever format it was found
:l forces the image to load as Luminous (greyscale)
:la forces the image to load as Luminous with Alpha
:rgb forces the image to load as Red Green Blue
:rgba forces the image to load as Red Green Blue Alpha

reuse-texture-id: The gl texture id to reuse, or 0 to generate a new texture.

flags: One or a list of the following

Name Effect ——————————————–
:power-of-two force the image to be POT
:mipmaps generate mipmaps for the texture
:texture-repeats Sampling set to repeat (otherwise will clamp) :multiply-alpha for using (:one, :one_minus_src_alpha) blending :invert-y flip the image vertically
:compress-to-dxt if gpu support it, converts RGB to DXT1, RGBA to DXT5 :dds-load-direct will load DDS files directly without _ANY_ additional processing.

Package

cl-soil.

Source

cl-soil.lisp.

Function: load-ogl-cubemap-from-memory (x-pos-buffer-pointer x-pos-buffer-length x-neg-buffer-pointer x-neg-buffer-length y-pos-buffer-pointer y-pos-buffer-length y-neg-buffer-pointer y-neg-buffer-length z-pos-buffer-pointer z-pos-buffer-length z-neg-buffer-pointer z-neg-buffer-length &optional force-channels reuse-texture-id flags) ¶

Loads 6 images from memory into an OpenGL cubemap texture.
Returns the texture-id

x-pos-filepath: the name of the file to upload as a texture face

x-pos-length: length of the data in bytes

x-neg-filepath: the name of the file to upload as a texture face

x-neg-length: length of the data in bytes

y-pos-filepath: the name of the file to upload as a texture face

y-pos-length: length of the data in bytes

y-neg-filepath: the name of the file to upload as a texture face

y-neg-length: length of the data in bytes

z-pos-filepath: the name of the file to upload as a texture face

z-pos-length: length of the data in bytes

z-neg-filepath: the name of the file to upload as a texture face

z-neg-length: length of the data in bytes

force-channels: One of the following:

Name Effect
——————————————-
:auto leaves the image in whatever format it was found
:l forces the image to load as Luminous (greyscale)
:la forces the image to load as Luminous with Alpha
:rgb forces the image to load as Red Green Blue
:rgba forces the image to load as Red Green Blue Alpha

reuse-texture-id: The gl texture id to reuse, or 0 to generate a new texture.

flags: One or a list of the following

Name Effect ——————————————–
:power-of-two force the image to be POT
:mipmaps generate mipmaps for the texture
:texture-repeats Sampling set to repeat (otherwise will clamp) :multiply-alpha for using (:one, :one_minus_src_alpha) blending :invert-y flip the image vertically
:compress-to-dxt if gpu support it, converts RGB to DXT1, RGBA to DXT5 :dds-load-direct will load DDS files directly without _ANY_ additional processing.

Package

cl-soil.

Source

cl-soil.lisp.

Function: load-ogl-hdr-texture (filepath &optional fake-hdr-format rescale-to-max reuse-texture-id flags) ¶

Loads an HDR image from disk into an OpenGL texture. Returns the texture-id

filename: the name of the file to upload as a texture

fake-hdr-format: Which fake HDR representation to use:

Name Meaning
——————————————
:rgbe (* RGB (expt 2.0 (- A 128.0))
:rgb-div-a (/ RGB A)
:rgb-div-a2 (/ RGB (* A A))

reuse-texture-id: The gl texture id to reuse, or 0 to generate a new texture.

rescale-to-max: integer. <Not documented in original>

flags: One or a list of the following

Name Effect ——————————————–
:power-of-two force the image to be POT
:mipmaps generate mipmaps for the texture
:texture-repeats Sampling set to repeat (otherwise will clamp) :multiply-alpha for using (:one, :one_minus_src_alpha) blending :invert-y flip the image vertically
:compress-to-dxt if gpu support it, converts RGB to DXT1, RGBA to DXT5 :dds-load-direct will load DDS files directly without _ANY_ additional processing.

*Note:* If you want a true HDR texture try using ‘stb-image:loadf‘ to load an image as floating point data. The use GL to create an upload a float-texture.

Package

cl-soil.

Source

cl-soil.lisp.

Function: load-ogl-single-cubemap (filepath face-order &optional force-channels reuse-texture-id flags) ¶

Loads 1 image from disk and splits it into an OpenGL cubemap texture. Returns the texture-id

filename: the name of the file to upload as a texture

face-order: the order of the faces in the file. Any combination of NSWEUD, for North, South, Up, etc as a keyword. For example :UDNSWE

force-channels: One of the following:

Name Effect
——————————————-
:auto leaves the image in whatever format it was found
:l forces the image to load as Luminous (greyscale)
:la forces the image to load as Luminous with Alpha
:rgb forces the image to load as Red Green Blue
:rgba forces the image to load as Red Green Blue Alpha

reuse-texture-id: The gl texture id to reuse, or 0 to generate a new texture.

flags: One or a list of the following

Name Effect ——————————————–
:power-of-two force the image to be POT
:mipmaps generate mipmaps for the texture
:texture-repeats Sampling set to repeat (otherwise will clamp) :multiply-alpha for using (:one, :one_minus_src_alpha) blending :invert-y flip the image vertically
:compress-to-dxt if gpu support it, converts RGB to DXT1, RGBA to DXT5 :dds-load-direct will load DDS files directly without _ANY_ additional processing.

Package

cl-soil.

Source

cl-soil.lisp.

Function: load-ogl-single-cubemap-from-memory (data-pointer data-length face-order &optional force-channels reuse-texture-id flags) ¶

Loads 1 image from RAM and splits it into an OpenGL cubemap texture. Returns the texture-id

data-pointer: pointer to the image data

data-length: length of the data in bytes

face-order: the order of the faces in the file. Any combination of NSWEUD, for North, South, Up, etc as a keyword. For example :UDNSWE

force-channels: One of the following:

Name Effect
——————————————-
:auto leaves the image in whatever format it was found
:l forces the image to load as Luminous (greyscale)
:la forces the image to load as Luminous with Alpha
:rgb forces the image to load as Red Green Blue
:rgba forces the image to load as Red Green Blue Alpha

reuse-texture-id: The gl texture id to reuse, or 0 to generate a new texture.

flags: One or a list of the following

Name Effect ——————————————–
:power-of-two force the image to be POT
:mipmaps generate mipmaps for the texture
:texture-repeats Sampling set to repeat (otherwise will clamp) :multiply-alpha for using (:one, :one_minus_src_alpha) blending :invert-y flip the image vertically
:compress-to-dxt if gpu support it, converts RGB to DXT1, RGBA to DXT5 :dds-load-direct will load DDS files directly without _ANY_ additional processing.

Package

cl-soil.

Source

cl-soil.lisp.

Function: load-ogl-texture (filepath &optional force-channels reuse-texture-id flags) ¶

Loads an image from disk into an OpenGL texture. Returns the texture-id

filename: the name of the file to upload as a texture

force-channels: One of the following:

Name Effect
——————————————-
:auto leaves the image in whatever format it was found
:l forces the image to load as Luminous (greyscale)
:la forces the image to load as Luminous with Alpha
:rgb forces the image to load as Red Green Blue
:rgba forces the image to load as Red Green Blue Alpha

reuse-texture-id: The gl texture id to reuse, or 0 to generate a new texture.

flags: One or a list of the following

Name Effect ——————————————–
:power-of-two force the image to be POT
:mipmaps generate mipmaps for the texture
:texture-repeats Sampling set to repeat (otherwise will clamp) :multiply-alpha for using (:one, :one_minus_src_alpha) blending :invert-y flip the image vertically
:compress-to-dxt if gpu support it, converts RGB to DXT1, RGBA to DXT5 :dds-load-direct will load DDS files directly without _ANY_ additional processing.

Package

cl-soil.

Source

cl-soil.lisp.

Function: load-ogl-texture-from-memory (data-pointer data-length &optional force-channels reuse-texture-id flags) ¶

Loads an image from RAM into an OpenGL texture. Returns the texture-id

data-pointer: pointer to the image data

data-length: length of the data in bytes

force-channels: One of the following:

Name Effect
——————————————-
:auto leaves the image in whatever format it was found
:l forces the image to load as Luminous (greyscale)
:la forces the image to load as Luminous with Alpha
:rgb forces the image to load as Red Green Blue
:rgba forces the image to load as Red Green Blue Alpha

reuse-texture-id: The gl texture id to reuse, or 0 to generate a new texture.

flags: One or a list of the following

Name Effect ——————————————–
:power-of-two force the image to be POT
:mipmaps generate mipmaps for the texture
:texture-repeats Sampling set to repeat (otherwise will clamp) :multiply-alpha for using (:one, :one_minus_src_alpha) blending :invert-y flip the image vertically
:compress-to-dxt if gpu support it, converts RGB to DXT1, RGBA to DXT5 :dds-load-direct will load DDS files directly without _ANY_ additional processing.

Package

cl-soil.

Source

cl-soil.lisp.

Function: loadf (filepath) ¶

Package

stb-image.

Source

stbi.lisp.

Function: save-image (filepath image-type width height channels data) ¶

Saves an image from memory. Returns the filepath on success

filename: the name of the file to save to

image-type: One of the following formats

:tga
:bmp
:dds

width: the width of the image in pixels

height: the height of the image in pixels

channels: the number of channels. Where the integer is one of the following

Count Meaning
———————-
1 luminous
2 luminous/alpha
3 RGB
4 RGBA

data: cffi pointer to the image data

Package

cl-soil.

Source

cl-soil.lisp.

Function: save-screenshot (filepath image-type x y width height) ¶

Captures the OpenGL window (RGB) and saves it to disk. Returns the filepath on success

filename: the name of the file to save to

image-type: One of the following formats

:tga
:bmp
:dds

x: x component of origin in pixels

x: y component of origin in pixels

width: the width of the image in pixels

height: the height of the image in pixels

Package

cl-soil.

Source

cl-soil.lisp.

---

5.2.1 Macros

Macro: with-foreign-filepath ((c-str-var filepath &key directory-p) &body body) ¶

Package

cl-soil.

Source

cl-soil.lisp.

Macro: with-foreign-filepaths (var-path-dir-tripples &body body) ¶

Package

cl-soil.

Source

cl-soil.lisp.

Macro: with-zero-being-an-error (func-name &body body) ¶

Package

cl-soil.

Source

cl-soil.lisp.

---

5.2.2 Ordinary functions

Function: %loadf (filename x y comp req-comp) ¶

Package

stb-image.

Source

stbi.lisp.

Function: handle-tex-flags (flags) ¶

Package

cl-soil.

Source

cl-soil.lisp.

Function: soil-create-ogl-single-cubemap (data width height channels face-order reuse-texture-id flags) ¶

Package

cl-soil.

Source

backend.lisp.

Function: soil-create-ogl-texture (data width height channels reuse-texture-id flags) ¶

Package

cl-soil.

Source

backend.lisp.

Function: soil-free-image-data (img-data) ¶

Package

cl-soil.

Source

backend.lisp.

Function: soil-last-result () ¶

Package

cl-soil.

Source

backend.lisp.

Function: soil-load-image (filename width height channels force-channels) ¶

Package

cl-soil.

Source

backend.lisp.

Function: soil-load-image-from-memory (buffer buffer-length width height channels force-channels) ¶

Package

cl-soil.

Source

backend.lisp.

Function: soil-load-ogl-cubemap (x-pos-file x-neg-file y-pos-file y-neg-file z-pos-file z-neg-file force-channels reuse-texture-id flags) ¶

Package

cl-soil.

Source

backend.lisp.

Function: soil-load-ogl-cubemap-from-memory (x-pos-buffer x-pos-buffer-length x-neg-buffer x-neg-buffer-length y-pos-buffer y-pos-buffer-length y-neg-buffer y-neg-buffer-length z-pos-buffer z-pos-buffer-length z-neg-buffer z-neg-buffer-length force-channels reuse-texture-id flags) ¶

Package

cl-soil.

Source

backend.lisp.

Function: soil-load-ogl-hdr-texture (filename fake-hdr-format rescale-to-max reuse-texture-id flags) ¶

Package

cl-soil.

Source

backend.lisp.

Function: soil-load-ogl-single-cubemap (filename face-order force-channels reuse-texture-id flags) ¶

Package

cl-soil.

Source

backend.lisp.

Function: soil-load-ogl-single-cubemap-from-memory (buffer buffer-length face-order force-channels reuse-texture-id flags) ¶

Package

cl-soil.

Source

backend.lisp.

Function: soil-load-ogl-texture (filename force-channels reuse-texture-id flags) ¶

Package

cl-soil.

Source

backend.lisp.

Function: soil-load-ogl-texture-from-memory (buffer buffer-length force-channels reuse-texture-id flags) ¶

Package

cl-soil.

Source

backend.lisp.

Function: soil-save-image (filename image-type width height channels data) ¶

Package

cl-soil.

Source

backend.lisp.

Function: soil-save-screenshot (filename image-type x y width height) ¶

Package

cl-soil.

Source

backend.lisp.

---