Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the clinch Reference Manual, version 0.5, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 04:14:09 2022 GMT+0.
Next: Systems, Previous: The clinch Reference Manual, Up: The clinch Reference Manual [Contents][Index]
Clinch is a simple, yet powerful 3d game engine for Lisp.
Clinch is a usable but still under development. It will become a stable and fast workhorse tool for developing games, visualizations and productivity software. I have plans for a graphical shell which incorporates the strengths of Lisp, 3D, shaders, 2d vector graphics, richtext support, 3d physics and much more.
Modern OpenGL features such as shaders and GPU buffers. [Done]
Commercial grade windowing, controller, force-feedback, sound, music and more thorough SDL2. [Done]
Create and inspect OpenGL objects on the fly. [Done]
Live code in a multithreaded environment. [Done]
Load plug-ins for more functionality. [Done]
3d physics with joints and motors using the ODE physics engine. [Done]
Texture loading and saving with FreeImage. [Done]
Integration with 2D vector graphics with Cairo. [Done]
Integration with fonts and text positioning with Pango. [Done]
3D asset importing using ClassImp. [Current Development]
Animate textures. [Done]
Animate 3D objects. [Current Development]
2D physics [Experimental]
3D GUI [Current Development]
Clinch should be as fast or faster than most script-based graphics engines and require less development time. While it may never rival professional libraries and engines, the ability to modify the 3D engine and environment from the REPL allows skilled developers to create applications in a fast, intuitive and flexible way.
Clinch should be as simple as possible for someone familiar with 3D graphics programming to understand. I still remember how easy it was to write a single pixel to the screen in DOS and while I can't simplify to that degree (without losing modern power and flexibility), I can remove many of the most common difficulties. These include texture and vertex buffers, shader compiling and linking, shader variable passing, drawing text and 2D graphics, 3D transformations, etc.
Time spent looking for solutions is spent time, period. It ruins developer flow and can stop a project (especially a small one) indefinitely. Clinch should have few basic primitives which solve the general cases well and allow for easy replacements when necessary. It should be well documented and have a consistent interface. I will strive to keep abstraction leaks at a minimum.
Clinch does not try to wrap other libraries inside the Clinch namespace. This keeps developers from "relearning" the same functionality.
Clinch does not inflict any particular design onto its client applications. It can be easily modified to create a specific engine. It uses plugins to minimize it's own overhead.
Although Clinch can be used as a complete engine, most parts of Clinch are independent. You can use objects by themselves as best suits your application. For example, you can use a buffer object by itself. This also helps with testing by isolating the various parts of Clinch. The following is in hierarchical order based on the default configuration. This is to explain it as clearly as possible, not to indicate a necessary design.
A transform is a 4x4 matrix which is used to hold and apply a C array of 16 floating values. CL-game-math is used as the default linear algebra library and its arrays may be passed to the shader. There are funcions for creating various projection matrices. Math functions are supplied through the rtg-math package.
Nodes are usually the topmost objects in the hierarchy. Nodes abstract 3D transform "chains" and hierarchy. Nodes encapulate transforms and can be scaled, rotated, and translated. They also may have children. Nodes are multiplied together in a hierarchy to create the current transforms which is passes to its children. A node can be used in multiple places within a hierarchy (or tree) or even in several different ones. This is done by passing a list of parents to the update function. It will then append itself and call update on its children. In this way, the transform are only calculated when they or their parent(s) have changed.
Buffers abstract the shared data on the graphics card. They can carry almost any data to the graphics card in bulk, including vertexes, normals, and texture coordinates. Buffers are usually sent to a shader through the entity object. A buffer's data can be accessed directly by using the map/unmap or pullg/pushg functions.
Textures abstract the 2D textures and allow easy access to their raw data. Textures can be loaded from files, drawn on with vector graphics or used as render targets. A texture's data can be accessed directly by using the map/unmap or pullg/pushg functions.
They use Pixel Buffer Object to make texture reading and writing faster. It's a separate buffer object which can send and/or receive data from a texture. It's a separate buffer so it can be used for several similar textures.
Shaders are the compiled output from text-based source code. Clinch supports vertex, fragment and geometry shaders.
Shader programs are complete, usable GPU programs. They take input and output to a texture (by default the screen). Shader-programs require a vertex and fragment shader and may also include a geometry shader. They require a list of uniform and attribute arguments.
Entities are the rendered meshes. They bring together the shader-program, buffers, textures, attributes, uniforms and transforms together into something which can be rendered on the screen. A shader and an index buffer are required although they would be useless without at least one vertex buffer.
An application can have several viewports. As Clinch does not force any particular windowing implementation, it can not have a window class. Once your window is set up, however, you can use the viewport handle for drawing an area on screen.
Frame buffer objects allows OpenGL to render to a texture or textures instead of a screen. The my also have a depth and/or stencle buffer.
Clinch creates the window for you to make things easier. By default it's launched in a separate thread.
Next: Files, Previous: Introduction, Up: The clinch Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
An OpenGL Game Engine.
Brad Beer (WarWeasle)
MIT
0.5
Next: Packages, Previous: Systems, Up: The clinch Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: clinch/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
clinch (system).
Next: clinch/threads.lisp, Previous: clinch/clinch.asd, Up: Lisp [Contents][Index]
clinch (system).
Next: clinch/clinch.lisp, Previous: clinch/package.lisp, Up: Lisp [Contents][Index]
package.lisp (file).
clinch (system).
Next: clinch/transform.lisp, Previous: clinch/threads.lisp, Up: Lisp [Contents][Index]
threads.lisp (file).
clinch (system).
Next: clinch/node.lisp, Previous: clinch/clinch.lisp, Up: Lisp [Contents][Index]
clinch.lisp (file).
clinch (system).
Next: clinch/shaders.lisp, Previous: clinch/transform.lisp, Up: Lisp [Contents][Index]
transform.lisp (file).
clinch (system).
Next: clinch/shader-program.lisp, Previous: clinch/node.lisp, Up: Lisp [Contents][Index]
node.lisp (file).
clinch (system).
Next: clinch/default-shaders.lisp, Previous: clinch/shaders.lisp, Up: Lisp [Contents][Index]
shaders.lisp (file).
clinch (system).
Next: clinch/buffer.lisp, Previous: clinch/shader-program.lisp, Up: Lisp [Contents][Index]
shader-program.lisp (file).
clinch (system).
Next: clinch/index-buffer.lisp, Previous: clinch/default-shaders.lisp, Up: Lisp [Contents][Index]
default-shaders.lisp (file).
clinch (system).
Next: clinch/pixel-buffer.lisp, Previous: clinch/buffer.lisp, Up: Lisp [Contents][Index]
buffer.lisp (file).
clinch (system).
Next: clinch/texture.lisp, Previous: clinch/index-buffer.lisp, Up: Lisp [Contents][Index]
index-buffer.lisp (file).
clinch (system).
pixel-buffer (class).
Next: clinch/2d-node.lisp, Previous: clinch/pixel-buffer.lisp, Up: Lisp [Contents][Index]
pixel-buffer.lisp (file).
clinch (system).
Next: clinch/entity.lisp, Previous: clinch/texture.lisp, Up: Lisp [Contents][Index]
texture.lisp (file).
clinch (system).
Next: clinch/viewport.lisp, Previous: clinch/2d-node.lisp, Up: Lisp [Contents][Index]
2d-node.lisp (file).
clinch (system).
Next: clinch/framebuffer.lisp, Previous: clinch/entity.lisp, Up: Lisp [Contents][Index]
entity.lisp (file).
clinch (system).
with-viewport (macro).
Next: clinch/animation.lisp, Previous: clinch/viewport.lisp, Up: Lisp [Contents][Index]
viewport.lisp (file).
clinch (system).
Next: clinch/window.lisp, Previous: clinch/framebuffer.lisp, Up: Lisp [Contents][Index]
framebuffer.lisp (file).
clinch (system).
Next: clinch/shapes.lisp, Previous: clinch/animation.lisp, Up: Lisp [Contents][Index]
animation.lisp (file).
clinch (system).
Previous: clinch/window.lisp, Up: Lisp [Contents][Index]
window.lisp (file).
clinch (system).
Next: Definitions, Previous: Files, Up: The clinch Reference Manual [Contents][Index]
Packages are listed by definition order.
common-lisp.
Next: Indexes, Previous: Packages, Up: The clinch Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Special variables, Previous: Public Interface, Up: Public Interface [Contents][Index]
A single-float version of pi.
Next: Macros, Previous: Constants, Up: Public Interface [Contents][Index]
Global Opengl Contex object.
An alist of discovered controllers. Format: (controller-id . sdl-controller-handle)
The default on-idle handler. Mapped as both a function and a variable.
Change in time (delta time, dt) since the last on-idle call.
The current entity
Current Frame Buffer Object.
An alist of discovered haptic feedback devices. Format: (controller-id . sdl-haptic-device-handle)
Runs before the next on-idle call. No arguments.
Current default node.
Called when a new controller is discovered. Arguments: (controller-id axis-id value timestamp)
Called when a controller’s axis moves. Arguments (controller-id axis-id position timestamp)
Called when a controller’s button is pressed. Arguments: (controller-id axis-id value timestamp)
Called when a controller’s button is released. Arguments: (controller-id axis-id value timestamp)
Called when a controller is remapped. Arguments: (window data1 data2 timestamp)
Called when a controller is removed. Arguments: (window data1 data2 timestamp)
Called when there are no pending events. Take no arguments. Default can be overridden.
Called when a key is pressed. Arguments (win keysym state ts)
Called when a key is released. Arguments (win keysym state ts)
Called when mouse button is released. Arguments: (win mouse x y button state clicks ts)
Called when mouse button is pressed. Arguments: (win mouse x y button state clicks ts)
Called when mouse is moved. Arguments (win mouse state x y xrel yrel ts)
Called when mouse button is released. Arguments: (win mouse x y button state clicks ts)
Called when the mouse wheel is moved. Arguments: (win mouse x y ts)
Called when clinch is about to exit. Take no arguments.
Called when editing text.
Call when text input happens.
Called when window is closing. Arguments (window timestamp)
Called when window gains mouse focus. Arguments (window timestamp)
Called when window is exposed and need redrawn. Arguments (window timestamp)
Called when window gains focus. Arguments (window timestamp)
Called when window loses focus. Arguments (window timestamp)
Called when window is hidden. Arguments (window timestamp)
Called when window is loses mouse focus. Arguments (window timestamp)
Called when window is maximized. Arguments (window timestamp)
Called when window is minimized. Arguments (window timestamp)
Called when the window has been moved. Arguments (window x y timestamp)
Always called when window size changes. Arguments (window width height timestamp)
Called when window is restored to normal position and size. Arguments (window timestamp)
Always called when window size changes. Arguments (window width height timestamp)
An automatically generated orthogonal projection for the window. Pixel to pixel.
Current default projection.
The current texture. Defaults to the window’s overlay.
Time elapsed since (init) in milliseconds.
Weak hash of loaded OpenGL objects.
Current viewport object.
Global window object.
Next: Ordinary functions, Previous: Special variables, Up: Public Interface [Contents][Index]
Runs body in main thread for safe OpenGL calls. Waits for return value.
Runs body in main thread for safe OpenGL calls. Returns immediately.
Converts degrees to radians.
Creates and updates an event handler. Use this for all your *on-* events. It’s just a nice wrapper around (setf event (lambda ...
Converts degrees to radians.
Coerce a number to a single-float.
Converts radians to degrees.
Converts radians to degrees.
Convenience macro for useing and resetting an FBO.
Convenience macro for mapping and unmapping the buffer data. Name is the symbol name to use for the buffer pointer.
A wrapper which creates a new node and set it as current.
A wrapper which sets and unsets the current *node* object.
Creates a temporary pixel buffer for a texture.
Next: Generic functions, Previous: Macros, Up: Public Interface [Contents][Index]
Decomposes a matrix into it’s position vector3, rotation quaterion and scaling vector3. Useful for creating/updating the node object.
Creates/returns a shader-program which blits a texture to an entity.
Uniforms:
P: projection matrix
M: model-view matrix
t1: texture
Attributes:
v: Vertexes
tc1: texture coordinates
Creates/returns a shader-program which uses simple phong shading with a single color.
Uniforms:
P: projection matrix
M: model-view matrix
ambientLight: Ambient Light Color
lightDirection: Direction of light
lightIntensity: Color of light
color: color of object
Attributes:
v: Vertexes
Creates/returns a 1x1 texture with the values (1.0, 1.0, 1.0, 1.0). This is a nice placeholder when you don’t want a custom shader.
Gets the direction from the middle of the screen.
Creates Clinch’s window in it’s own thread.
Use ! (wait and return a value from main thread) or
Use !! (return immediately with a nil.
Create a raw CFFI frustum matrix.
Create a raw CFFI orthogonal matrix.
Create a raw CFFI perspective matrix.
Creates a quad entity of width and height.
Given an origin, direction and a triangle returns if and where they intersect. Presently does not cull backfacing triangles.
Graph is an association list whose keys are objects and whose values are lists of objects on which the corresponding key depends. Test is used to compare elements, and should be a suitable test for hash-tables. Topological-sort returns two values. The first is a list of objects sorted toplogically. The second is a boolean indicating whether all of the objects in the input graph are present in the topological ordering (i.e., the first value).
Unloads all loaded OpenGL objects.
Unproject from the screen to transform space.
Next: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
Resets a node to default. Position 0, rotation 0 and scale of 1. Shortcut is !0.
Resets a node’s rotation to 1,0,0,0. Shortcut is !r0
Resets a node’s scaling to 1,1,1. Shortcut is !s0
Resets a node’s translation to 0,0,0. Shortcut is !t0
Shaders pass information by using named values called Uniforms and Attributes. This sets a uniform to the matrix of a node.
Shaders pass information by using named values called Uniforms and Attributes. This sets a uniform to a matrix value.
Shaders pass information by using named values called Uniforms and Attributes. This sets a uniform to value.
Binds the frame buffer for use.
Wrapper around glBindFrameBuffer. Puts the Framebuffer into play.
Wrapper around glBindBuffer. Puts the texture into play.
Bind buffer to a shader attribute.
It is possible to bind static information to an attribute. That’s what this does.
Returns a color-attachment by number.
Sets an attachment’s number
automatically generated reader method
Binds the depth buffer for use.
Use this buffer as an index array and draw somthing.
Use this buffer as an index array and draw somthing within start and end bounds.
Shaders pass information by using named values called Uniforms and Attributes. This gets the gl id of a attribute name.
Shaders pass information by using named values called Uniforms and Attributes. If we are using the raw id, this returns it.
Shaders pass information by using named values called Uniforms and Attributes. This gets the gl id of a uniform name.
Shaders pass information by using named values called Uniforms and Attributes. If we are using the raw id, this returns it.
automatically generated reader method
id.
automatically generated reader method
id.
Creates and adds a color buffer for the frame buffer.
Creates a depth texture for a framebuffer.
Multiplies nodes and matrix transforms.
Multiplies a node? I’m not sure if this works.
Multiplies a node? I’m not sure if this works.
automatically generated reader method
name.
automatically generated reader method
name.
automatically generated reader method
Returns shader-program’s available information such as shader source, uniforms and attributes.
Sets the texture data from a pixel buffer.
automatically generated reader method
type.
automatically generated reader method
type.
automatically generated writer method
type.
automatically generated writer method
type.
Rotate node. Shortcut is !r.
Scale node. Shortcut is !s.
automatically generated reader method
automatically generated reader method
automatically generated reader method
automatically generated reader method
automatically generated writer method
get the entire transform.
Translate node. Shortcut is !t.
Wrapper around glBindFrameBuffer. Puts the Framebuffer into play.
Unloads an opengl object. Does nothing for non-opengl objects.
Unloads and releases all frame-buffer resources, also any renderbuffers
Release entity resources. If :all t, then the index buffer and all uniforms and attributes are unloaded.
Unloads and releases all shader-program resources.
automatically generated reader method
automatically generated writer method
Start using the shader-program.
automatically generated reader method
Next: Classes, Previous: Generic functions, Up: Public Interface [Contents][Index]
Create the shader program. Currently there is no way to change the shader. You must make a new one.
Sets up a texture instance with gc finalizer. Do not depend on finalizers, release resources manually if you can.
type: cffi type NOTE: use :unsigned-int if you are creating an index buffer.
id: OpenGL buffer id
stride: The number of values in each pixel.
usage: Tells OpenGL how often you wish to access the buffer.
loaded: Has data been put into the buffer. Buffers without data is just future storage, just be sure to set it before you use it.
format: The OpenGL Format of the Color Data. blue-green-red-alpha is default and prefered for simplicity.
wrap-s & wrap-t: Wrap texture vertical or horizontal.
mag-filter & min-filter: Magnification an minimization method.
Creates a node with optional translation (vector3), rotation (quaterion) and scaling (vector3). Can also use another node or matrix to set its value. If a node and another value is give, the other value is used starting with the matrix.
Creates an entity.
:parent adds itself to the given parent. The entity doesn’t keep track of its parent. (t means the root node)
:indexes sets the index buffer. Required.
:mode sets what kind of object (triangle, square, etc) will be drawn. Only triangles are tested.
:uniforms sets the uniform values as an alist.
:attributes sets the attribute values as an alist.
:shader-program sets the shader program.
:enabled sets if this entity will render.
Creates an FBO with optional color attachments, depth-attachements and stencil attachments.
Sets up a buffer instance.
type: cffi type NOTE: Use the index buffer for indices.
id: OpenGL buffer id
vcount: vertex count (or number of tuples if not using vertexes)
stride: The number of items in each vertex (or each tuple.) NOTE: use 1 if you are creating an index buffer.
target: OpenGL buffer target. If you use this, think about subclassing. For more info lookup glBindBuffer().
NOTE: use :element-array-buffer if you are creating an index buffer.
usage: Tells OpenGL how often you wish to access the buffer.
loaded: Has data been put into the buffer. Buffers without data is just future storage, just be sure to set it before you use it.
data: The data with which to fill the buffer. If data has a size, vcount does not need to be set.
Previous: Standalone methods, Up: Public Interface [Contents][Index]
:animation
0
:start
t
:paused
t
:repeat
1
:run-speed
:run-length
Creates and keeps track of GPU buffer object (shared memory with gpu).
common-lisp.
:float
:qtype
:static-draw
:usage
:count
This slot is read-only.
:array-buffer
:target
This slot is read-only.
Renders a mesh with a shader-program with attributes and uniforms.
:shader-program
This slot is read-only.
:attributes
This slot is read-only.
:bones
t
:enabled
The Frame Buffer Object or FBO. Use this to render to textures.
:draw-framebuffer
:target
This slot is read-only.
:depth-buffer
This slot is read-only.
This slot is read-only.
Creates and keeps track of GPU index buffer object (shared memory with gpu).
common-lisp.
:unsigned-int
:qtype
:static-draw
clinch:usage
:count
This slot is read-only.
:element-array-buffer
:target
This slot is read-only.
A node class for creating hierarchies of objects. It caches calculations for speed. Not enough in itself, and is not required by Clinch.
clinch::v0
:translation
This slot is read-only.
(rtg-math.quaternions:identity)
:rotation
This slot is read-only.
This slot is read-only.
t
:enabled
:children
Creates and keeps track of the shader-program objects. Requires an UNLOAD call when you are done. Bind Buffer functions are in Buffer.l
This slot is read-only.
This slot is read-only.
Creates and keeps track of a texture object. Can be used with a pixelbuffer to speed things up.
:tex-id
common-lisp.
:unsigned-char
:qtype
:rgba
:internal-format
:bgra
:format
Creates a viewport.
Previous: Public Interface, Up: Definitions [Contents][Index]
Next: Special variables, Previous: Internals, Up: Internals [Contents][Index]
Weak hash of OpenGL objects waiting to be unloaded by another.
Next: Ordinary functions, Previous: Special variables, Up: Internals [Contents][Index]
Helper macro that we can use to allow us to continue from an
error. Remember to hit C in slime or pick the restart so errors don’t kill the app.
Enables REPL access via UPDATE-SWANK in the main loop using SDL2. Wrap this around the sdl2:with-init code.
A wrapper which sets and unsets a viewport.
Next: Generic functions, Previous: Macros, Up: Internals [Contents][Index]
Adds item to list of loaded OpenGL objects.
Returns the buffer type as a cffi type.
Removes item from list of loaded OpenGL objects. Does NOT call unload.
I think this is a tree walker which applies a function to a clinch node tree.
Called from within the main loop, this keep the lisp repl working while cepl runs
Next: Classes, Previous: Ordinary functions, Up: Internals [Contents][Index]
Add a color buffer at position index.
automatically generated reader method
automatically generated reader method
key.
automatically generated reader method
key.
automatically generated reader method
key.
automatically generated reader method
key.
automatically generated reader method
key.
List the shader-program’s attribute arguments.
List the shader-program’s attribute arguments.
List the shader-program’s uniform arguments.
automatically generated reader method
automatically generated writer method
Creates a geometry shader.
Creates a fragment shader.
Creates a vertex shader.
Removes a shader-program attribute
Removes a shader-program uniform
Resets a node to default. Position 0, rotation 0 and scale of 1. Shortcut is !0.
Resets a node’s rotation to 1,0,0,0. Shortcut is !r0
Resets a node’s scaling to 1,1,1. Shortcut is !s0
Resets a node’s translation to 0,0,0. Shortcut is !t0
Get the rotation matrix.
Get the scale matrix.
Gets a shader-program attribute
Sets a shader-program attribute.
automatically generated reader method
Gets a shader-program uniform
Sets a shader-program uniform.
automatically generated reader method
automatically generated reader method
Get the translation matrix.
Bind buffer to a shader-program attribute.
Stop using the normal array
Stop using the vertex array
Previous: Generic functions, Up: Internals [Contents][Index]
Fragment Shader Class.
:fragment-shader
Geometry Shader Class.
:geometry-shader
Creates a buffer for quickly reading and writing to textures. This is separate from the texture’s data.
:pixel-unpack-buffer
Base class for all individual shaders.
Vertex Shader Class.
:vertex-shader
Previous: Definitions, Up: The clinch Reference Manual [Contents][Index]
Jump to: | !
$
(
*
_
A B C D E F G H I K L M N P Q R S T U V W X Y |
---|
Jump to: | !
$
(
*
_
A B C D E F G H I K L M N P Q R S T U V W X Y |
---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
Jump to: | *
+
A B C D E F H I K L M N P R S T U V W X Y |
---|
Jump to: | *
+
A B C D E F H I K L M N P R S T U V W X Y |
---|
Jump to: | 2
A B C D E F G I N P S T V W |
---|
Jump to: | 2
A B C D E F G I N P S T V W |
---|