The cl-soil Reference Manual

Table of Contents

The cl-soil Reference Manual

This is the cl-soil Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 15:20:45 2021 GMT+0.

1 Introduction

cl-soil

Common lisp wrapper around the SOIL library (http://www.lonesock.net/soil.html)

All public symbols have docstrings.

API docs can also be found here

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 cl-soil

Author

Chris Bagley (Baggers) <techsnuffle@gmail.com>

License

BSD 2 Clause

Description

A thin binding over libSOIL.so which allows easy loading of images

Dependencies

• cffi
• documentation-utils
• cl-opengl

Source

cl-soil.asd (file)

Components

• package.lisp (file)
• backend.lisp (file)
• cl-soil.lisp (file)
• stbi.lisp (file)
• docs.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 cl-soil.asd

Location

cl-soil.asd

Systems

cl-soil (system)

3.1.2 cl-soil/package.lisp

Parent

cl-soil (system)

Location

package.lisp

Packages

• cl-soil
• stb-image

3.1.3 cl-soil/backend.lisp

Dependency

package.lisp (file)

Parent

cl-soil (system)

Location

backend.lisp

Internal Definitions

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

Parent

cl-soil (system)

Location

cl-soil.lisp

Exported Definitions

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

Internal Definitions

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

Parent

cl-soil (system)

Location

stbi.lisp

Exported Definitions

loadf (function)

Internal Definitions

%loadf (function)

3.1.6 cl-soil/docs.lisp

Dependency

stbi.lisp (file)

Parent

cl-soil (system)

Location

docs.lisp

4 Packages

Packages are listed by definition order.

4.1 cl-soil

Source

package.lisp (file)

Use List

• cffi
• common-lisp

Exported Definitions

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

Internal Definitions

• handle-tex-flags (function)
• 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)
• with-foreign-filepath (macro)
• with-foreign-filepaths (macro)
• with-zero-being-an-error (macro)

4.2 stb-image

Source

package.lisp (file)

Nickname

stbi

Use List

• cffi
• common-lisp

Exported Definitions

loadf (function)

Internal Definitions

%loadf (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

Function: loadf FILEPATH

Package

stb-image

Source

stbi.lisp (file)

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 (file)

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 (file)

5.2 Internal definitions

5.2.1 Macros

Macro: with-foreign-filepath (C-STR-VAR FILEPATH &key DIRECTORY-P) &body BODY

Package

cl-soil

Source

cl-soil.lisp (file)

Macro: with-foreign-filepaths VAR-PATH-DIR-TRIPPLES &body BODY

Package

cl-soil

Source

cl-soil.lisp (file)

Macro: with-zero-being-an-error FUNC-NAME &body BODY

Package

cl-soil

Source

cl-soil.lisp (file)

5.2.2 Functions

Function: %loadf FILENAME X Y COMP REQ-COMP

Package

stb-image

Source

stbi.lisp (file)

Function: handle-tex-flags FLAGS

Package

cl-soil

Source

cl-soil.lisp (file)

Function: soil-create-ogl-single-cubemap DATA WIDTH HEIGHT CHANNELS FACE-ORDER REUSE-TEXTURE-ID FLAGS

Package

cl-soil

Source

backend.lisp (file)

Function: soil-create-ogl-texture DATA WIDTH HEIGHT CHANNELS REUSE-TEXTURE-ID FLAGS

Package

cl-soil

Source

backend.lisp (file)

Function: soil-free-image-data IMG-DATA

Package

cl-soil

Source

backend.lisp (file)

Function: soil-last-result ()

Package

cl-soil

Source

backend.lisp (file)

Function: soil-load-image FILENAME WIDTH HEIGHT CHANNELS FORCE-CHANNELS

Package

cl-soil

Source

backend.lisp (file)

Function: soil-load-image-from-memory BUFFER BUFFER-LENGTH WIDTH HEIGHT CHANNELS FORCE-CHANNELS

Package

cl-soil

Source

backend.lisp (file)

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 (file)

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 (file)

Function: soil-load-ogl-hdr-texture FILENAME FAKE-HDR-FORMAT RESCALE-TO-MAX REUSE-TEXTURE-ID FLAGS

Package

cl-soil

Source

backend.lisp (file)

Function: soil-load-ogl-single-cubemap FILENAME FACE-ORDER FORCE-CHANNELS REUSE-TEXTURE-ID FLAGS

Package

cl-soil

Source

backend.lisp (file)

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 (file)

Function: soil-load-ogl-texture FILENAME FORCE-CHANNELS REUSE-TEXTURE-ID FLAGS

Package

cl-soil

Source

backend.lisp (file)

Function: soil-load-ogl-texture-from-memory BUFFER BUFFER-LENGTH FORCE-CHANNELS REUSE-TEXTURE-ID FLAGS

Package

cl-soil

Source

backend.lisp (file)

Function: soil-save-image FILENAME IMAGE-TYPE WIDTH HEIGHT CHANNELS DATA

Package

cl-soil

Source

backend.lisp (file)

Function: soil-save-screenshot FILENAME IMAGE-TYPE X Y WIDTH HEIGHT

Package

cl-soil

Source

backend.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types