The cl-soil Reference Manual

This is the cl-soil Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 15:43:39 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 cl-soil

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

Author

Chris Bagley (Baggers) <>

License

BSD 2 Clause

Dependencies
  • cffi (system).
  • documentation-utils (system).
  • cl-opengl (system).
Source

cl-soil.asd.

Child Components

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/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

3.1.3 cl-soil/backend.lisp

Dependency

package.lisp (file).

Source

cl-soil.asd.

Parent Component

cl-soil (system).

Internals

3.1.4 cl-soil/cl-soil.lisp

Dependency

backend.lisp (file).

Source

cl-soil.asd.

Parent Component

cl-soil (system).

Public Interface
Internals

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


4 Packages

Packages are listed by definition order.


4.1 cl-soil

Source

package.lisp.

Use List
  • cffi.
  • common-lisp.
Public Interface
Internals

4.2 stb-image

Source

package.lisp.

Nickname

stbi

Use List
  • cffi.
  • common-lisp.
Public Interface

loadf (function).

Internals

%loadf (function).


5 Definitions

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


5.1 Public Interface


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 Internals


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.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %  
C   F   H   L   M   S   W  
Index Entry  Section

%
%loadf: Private ordinary functions

C
create-ogl-single-cubemap: Public ordinary functions
create-ogl-texture: Public ordinary functions

F
free-image-data: Public ordinary functions
Function, %loadf: Private ordinary functions
Function, create-ogl-single-cubemap: Public ordinary functions
Function, create-ogl-texture: Public ordinary functions
Function, free-image-data: Public ordinary functions
Function, handle-tex-flags: Private ordinary functions
Function, last-result: Public ordinary functions
Function, load-image: Public ordinary functions
Function, load-image-from-memory: Public ordinary functions
Function, load-ogl-cubemap: Public ordinary functions
Function, load-ogl-cubemap-from-memory: Public ordinary functions
Function, load-ogl-hdr-texture: Public ordinary functions
Function, load-ogl-single-cubemap: Public ordinary functions
Function, load-ogl-single-cubemap-from-memory: Public ordinary functions
Function, load-ogl-texture: Public ordinary functions
Function, load-ogl-texture-from-memory: Public ordinary functions
Function, loadf: Public ordinary functions
Function, save-image: Public ordinary functions
Function, save-screenshot: Public ordinary functions
Function, soil-create-ogl-single-cubemap: Private ordinary functions
Function, soil-create-ogl-texture: Private ordinary functions
Function, soil-free-image-data: Private ordinary functions
Function, soil-last-result: Private ordinary functions
Function, soil-load-image: Private ordinary functions
Function, soil-load-image-from-memory: Private ordinary functions
Function, soil-load-ogl-cubemap: Private ordinary functions
Function, soil-load-ogl-cubemap-from-memory: Private ordinary functions
Function, soil-load-ogl-hdr-texture: Private ordinary functions
Function, soil-load-ogl-single-cubemap: Private ordinary functions
Function, soil-load-ogl-single-cubemap-from-memory: Private ordinary functions
Function, soil-load-ogl-texture: Private ordinary functions
Function, soil-load-ogl-texture-from-memory: Private ordinary functions
Function, soil-save-image: Private ordinary functions
Function, soil-save-screenshot: Private ordinary functions

H
handle-tex-flags: Private ordinary functions

L
last-result: Public ordinary functions
load-image: Public ordinary functions
load-image-from-memory: Public ordinary functions
load-ogl-cubemap: Public ordinary functions
load-ogl-cubemap-from-memory: Public ordinary functions
load-ogl-hdr-texture: Public ordinary functions
load-ogl-single-cubemap: Public ordinary functions
load-ogl-single-cubemap-from-memory: Public ordinary functions
load-ogl-texture: Public ordinary functions
load-ogl-texture-from-memory: Public ordinary functions
loadf: Public ordinary functions

M
Macro, with-foreign-filepath: Private macros
Macro, with-foreign-filepaths: Private macros
Macro, with-zero-being-an-error: Private macros

S
save-image: Public ordinary functions
save-screenshot: Public ordinary functions
soil-create-ogl-single-cubemap: Private ordinary functions
soil-create-ogl-texture: Private ordinary functions
soil-free-image-data: Private ordinary functions
soil-last-result: Private ordinary functions
soil-load-image: Private ordinary functions
soil-load-image-from-memory: Private ordinary functions
soil-load-ogl-cubemap: Private ordinary functions
soil-load-ogl-cubemap-from-memory: Private ordinary functions
soil-load-ogl-hdr-texture: Private ordinary functions
soil-load-ogl-single-cubemap: Private ordinary functions
soil-load-ogl-single-cubemap-from-memory: Private ordinary functions
soil-load-ogl-texture: Private ordinary functions
soil-load-ogl-texture-from-memory: Private ordinary functions
soil-save-image: Private ordinary functions
soil-save-screenshot: Private ordinary functions

W
with-foreign-filepath: Private macros
with-foreign-filepaths: Private macros
with-zero-being-an-error: Private macros


A.3 Variables