The glkit Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The glkit Reference Manual

This is the glkit Reference Manual, version 0.0, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:53:04 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

glkit

This is a utility kit for functionality related to OpenGL. Right now, it provides the following:

Shaders

kit.gl.shader provides a thin, extensible, program-oriented model for GL shaders. This closely mimics how GL works:

(defdict shaders-3.3 (:shader-path #P"...")
   (shader basic-vertex :vertex-shader (:file "vertex.glsl"))
   (program :solid (:color)
     (:vertex-shader basic-vertex)
     (:fragment-shader "..."))
   (program (:sprite
              :uniforms ((:texture "texture_id"))
              :attrs ((:vertex 0)
                      (:uv 1)
                      ...))
     (:vertex-shader basic-vertex)
     (:fragment-shader (:file "..."))))

This defines a series of shader programs grouped into a "dictionary". Once in a GL context, one or more dictionaries may be compiled, programs activated, and uniforms set, all symbolically.

You may specify any legal combination of shaders in the shaders section. Reusing text between shaders is easy by defining named shaders with the SHADER directive. Text may also be loaded from a file using (:file PATHNAME) as above. Additional handling may be defined; see below.

To actually compile and use a dictionary, call the following; it will attempt to compile and link all the specified programs, reporting any errors along the way to *error-output*:

(compile-shader-dictionary (dict shaders-3.3))
  ;; => DICTIONARY

This requires a valid GL context, will only work when it is otherwise legal to make GL calls. As well, the returned SHADER-DICTIONARY object is only valid in the GL context in which it was compiled. It will not work in others. If desired, more than one dictionary may be compiled in a context; nothing besides convenience groups programs in a dictionary.

Once you have this object, you may do interesting things with it:

(kit.gl.shader:use-program DICTIONARY :name)

;; Note these apply only to the *current program*,
;; different programs have different sets of uniforms
(kit.gl.shader:uniformi DICTIONARY :v1 0)
(kit.gl.shader:uniformf DICTIONARY :v2 x y)

;; etc

Note these are different functions than the cl-opengl variety; they take the dictionary object, as well as symbolic names, rather than IDs.

Customizing

It's also possible to define other ways to produce shader strings, by specializing either of the following generic functions:

(parse-shader-source SOURCE SHADER-TYPE SHADER-LIST)
(parse-shader-source-complex KEY PARAMS SHADER-TYPE SHADER-LIST)

The first specializes on a few SOURCE types by default; do not alter these:

The SHADER-TYPE parameter is any valid shader type, e.g. :vertex-shader; SHADER-LIST is the current list of "named" shaders, in the form (NAME . (TYPE VALUE)). Notably, VALUE is not processed, and should be passed recursively to PARSE-SHADER-SOURCE if used.

To process forms like (:file PATHNAME), PARSE-SHADER-SOURCE-COMPLEX takes the CAR and CDR or that list, as well other parameters similar to PARSE-SHADER-SOURCE.

These are mostly useful for projects which desire to add extended shader capability, such as a shader DSL, or loading in some other manner.

VAOs

kit.gl.vao provides an easy way to define VAO layouts, as well as instantiate, bind, and draw them. It aims to provide complete VAO functionality.

To use, first one defines a VAO:

(defvao NAME ()
  (LAYOUT-TYPE (OPTS)
    (ATTR :type COUNT)
    ...)
  (LAYOUT-TYPE
    ...))

For example:

(defvao vertex-color ()
  (:separate ()
    (vertex :float 3)
    (color :float 3)))

This defines a VAO with VERTEX and COLOR attributes, which are each 3 :float values. This uses a separate VBO for each. (The LAYOUT-TYPE will be covered below.)

Using a VAO is just as easy:

(let ((vao (make-instance 'vao :type 'vertex-color)))
  (vao-buffer-data vao 0 (* 4 VERTEX-FLOAT-COUNT) POINTER-TO-VERTEX-FLOATS)
  (vao-buffer-data vao 1 (* 4 COLOR-FLOAT-COUNT) POINTER-TO-COLOR-FLOATS)

  ;; Establish more stuff here.. active shaders, uniforms, etc, then:
  (vao-draw vao :count VERTEX-COUNT))

This requires a valid, active GL context, just like other GL functions. DEFVAO does not, but everything else, including the make-instance, does.

Alternatively, you can use VAO-BUFFER-VECTOR (and VAO-BUFFER-SUB-VECTOR), and supply a vector of :element-type 'single-float or :element-type 'double-float instead of a pointer. This is only available if your implementation supports static-vectors (most do). This is for convenience; managing the data yourself can reduce copying and consing considerably.

Note the numbers above require you fill in a few specific things:

The pointer data you must supply pre-formatted. However, for separate VBOs, this is reasonably easy to accomplish with something like static-vectors, or you can use the less-efficient -vector variants which do this for you.

Dictionary

Layouts

There are three layout types:

You may specify one or more groups to a VAO definition:

(defvao NAME
  (:separate () ...)
  (:separate () ...)
  (:interleave () ...)
  ...)

You must be aware of the underlying VBO layout to the extent that you must specify the correct index to vao-buffer-data. In the future, you will be able to specify a valid symbolic name, though this may not be as efficient.

You may also specify a :divisor option to the group, which corresponds to the DIVISOR parameter to glVertexAttribDivisor, allowing one attribute for multiple vertices. Note that because this is per-group, if you wish to have separate divisors per attribute, they must be in separate groups.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 glkit

Author

rpav

License

MIT

Description

Various utilities for OpenGL

Version

0.0

Dependencies
Source

glkit.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

Modules are listed depth-first from the system components tree.


Next: , Previous: , Up: Modules   [Contents][Index]

3.1 glkit/shader-dict

Dependency

protocol.lisp (file)

Parent

glkit (system)

Location

shader-dict/

Components

Next: , Previous: , Up: Modules   [Contents][Index]

3.2 glkit/vao

Dependency

shader-dict (module)

Parent

glkit (system)

Location

vao/

Component

vao.lisp (file)


Previous: , Up: Modules   [Contents][Index]

3.3 glkit/tex

Dependency

vao (module)

Parent

glkit (system)

Location

tex/

Components

Next: , Previous: , Up: Top   [Contents][Index]

4 Files

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


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 glkit.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/glkit-20171227-git/glkit.asd

Systems

glkit (system)

Packages

glkit.asdf


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.2 glkit/package.lisp

Parent

glkit (system)

Location

package.lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.3 glkit/protocol.lisp

Dependency

package.lisp (file)

Parent

glkit (system)

Location

protocol.lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.4 glkit/shader-dict/shaders.lisp

Parent

shader-dict (module)

Location

shader-dict/shaders.lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.5 glkit/shader-dict/uniforms.lisp

Dependency

shaders.lisp (file)

Parent

shader-dict (module)

Location

shader-dict/uniforms.lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.6 glkit/shader-dict/macros.lisp

Dependency

uniforms.lisp (file)

Parent

shader-dict (module)

Location

shader-dict/macros.lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.7 glkit/vao/vao.lisp

Parent

vao (module)

Location

vao/vao.lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.8 glkit/tex/util.lisp

Parent

tex (module)

Location

tex/util.lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.9 glkit/tex/texture.lisp

Dependency

util.lisp (file)

Parent

tex (module)

Location

tex/texture.lisp


Previous: , Up: Lisp files   [Contents][Index]

4.1.10 glkit/tex/fbo.lisp

Dependency

texture.lisp (file)

Parent

tex (module)

Location

tex/fbo.lisp


Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

5.1 glkit.asdf

Source

/home/quickref/quicklisp/dists/quicklisp/software/glkit-20171227-git/glkit.asd

Use List

Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   G   L   M  
Index Entry  Section

F
File, Lisp, glkit.asd: The glkit<dot>asd file
File, Lisp, glkit/package.lisp: The glkit/package<dot>lisp file
File, Lisp, glkit/protocol.lisp: The glkit/protocol<dot>lisp file
File, Lisp, glkit/shader-dict/macros.lisp: The glkit/shader-dict/macros<dot>lisp file
File, Lisp, glkit/shader-dict/shaders.lisp: The glkit/shader-dict/shaders<dot>lisp file
File, Lisp, glkit/shader-dict/uniforms.lisp: The glkit/shader-dict/uniforms<dot>lisp file
File, Lisp, glkit/tex/fbo.lisp: The glkit/tex/fbo<dot>lisp file
File, Lisp, glkit/tex/texture.lisp: The glkit/tex/texture<dot>lisp file
File, Lisp, glkit/tex/util.lisp: The glkit/tex/util<dot>lisp file
File, Lisp, glkit/vao/vao.lisp: The glkit/vao/vao<dot>lisp file

G
glkit.asd: The glkit<dot>asd file
glkit/package.lisp: The glkit/package<dot>lisp file
glkit/protocol.lisp: The glkit/protocol<dot>lisp file
glkit/shader-dict: The glkit/shader-dict module
glkit/shader-dict/macros.lisp: The glkit/shader-dict/macros<dot>lisp file
glkit/shader-dict/shaders.lisp: The glkit/shader-dict/shaders<dot>lisp file
glkit/shader-dict/uniforms.lisp: The glkit/shader-dict/uniforms<dot>lisp file
glkit/tex: The glkit/tex module
glkit/tex/fbo.lisp: The glkit/tex/fbo<dot>lisp file
glkit/tex/texture.lisp: The glkit/tex/texture<dot>lisp file
glkit/tex/util.lisp: The glkit/tex/util<dot>lisp file
glkit/vao: The glkit/vao module
glkit/vao/vao.lisp: The glkit/vao/vao<dot>lisp file

L
Lisp File, glkit.asd: The glkit<dot>asd file
Lisp File, glkit/package.lisp: The glkit/package<dot>lisp file
Lisp File, glkit/protocol.lisp: The glkit/protocol<dot>lisp file
Lisp File, glkit/shader-dict/macros.lisp: The glkit/shader-dict/macros<dot>lisp file
Lisp File, glkit/shader-dict/shaders.lisp: The glkit/shader-dict/shaders<dot>lisp file
Lisp File, glkit/shader-dict/uniforms.lisp: The glkit/shader-dict/uniforms<dot>lisp file
Lisp File, glkit/tex/fbo.lisp: The glkit/tex/fbo<dot>lisp file
Lisp File, glkit/tex/texture.lisp: The glkit/tex/texture<dot>lisp file
Lisp File, glkit/tex/util.lisp: The glkit/tex/util<dot>lisp file
Lisp File, glkit/vao/vao.lisp: The glkit/vao/vao<dot>lisp file

M
Module, glkit/shader-dict: The glkit/shader-dict module
Module, glkit/tex: The glkit/tex module
Module, glkit/vao: The glkit/vao module

Jump to:   F   G   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions


Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables


Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   G   P   S  
Index Entry  Section

G
glkit: The glkit system
glkit.asdf: The glkit<dot>asdf package

P
Package, glkit.asdf: The glkit<dot>asdf package

S
System, glkit: The glkit system

Jump to:   G   P   S