This is the cepl.spaces Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 14:52:23 2024 GMT+0.
cepl.spaces/cepl.spaces.asdcepl.spaces/package.lispcepl.spaces/constants.lispcepl.spaces/nht-routes.lispcepl.spaces/space.lispcepl.spaces/predefined-spaces.lispcepl.spaces/pos.lispcepl.spaces/space-errors.lispcepl.spaces/space-walking.lispcepl.spaces/space-transforms.lispcepl.spaces/pos-funcs.lispcepl.spaces/vector-space.lispcepl.spaces/spatial-vector.lispcepl.spaces/gpu.lispcepl.spaces/docs.lispThe main system appears first, followed by any subsystem dependency.
cepl.spacesAdds abstractions over vector spaces to CEPL
Chris Bagley (Baggers) <techsnuffle@gmail.com>
BSD 2 Clause
fn (system).
rtg-math (system).
rtg-math.vari (system).
varjo (system).
cepl (system).
documentation-utils (system).
package.lisp (file).
constants.lisp (file).
nht-routes.lisp (file).
space.lisp (file).
predefined-spaces.lisp (file).
pos.lisp (file).
space-errors.lisp (file).
space-walking.lisp (file).
space-transforms.lisp (file).
pos-funcs.lisp (file).
vector-space.lisp (file).
spatial-vector.lisp (file).
gpu.lisp (file).
docs.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
cepl.spaces/cepl.spaces.asdcepl.spaces/package.lispcepl.spaces/constants.lispcepl.spaces/nht-routes.lispcepl.spaces/space.lispcepl.spaces/predefined-spaces.lispcepl.spaces/pos.lispcepl.spaces/space-errors.lispcepl.spaces/space-walking.lispcepl.spaces/space-transforms.lispcepl.spaces/pos-funcs.lispcepl.spaces/vector-space.lispcepl.spaces/spatial-vector.lispcepl.spaces/gpu.lispcepl.spaces/docs.lispcepl.spaces/constants.lisppackage.lisp (file).
cepl.spaces (system).
+default-subtable-count+ (constant).
+subtable-length+ (constant).
cepl.spaces/nht-routes.lispconstants.lisp (file).
cepl.spaces (system).
%has-route (function).
%make-route-table (function).
%make-routes-array (function).
%next-step (function).
%route-len (function).
%set-route (function).
%walk-leaving-trail (function).
connect-to-0 (function).
connect-to-1 (function).
connect-to-many (function).
copy-route-table (function).
extend-routes (function).
fart-route (function).
get-current-id-count (function).
get-current-subtable-count (function).
get-route-cache (function).
get-routes (function).
id-neighbours (function).
make-cache (function).
make-route-subtable (function).
make-route-table (function).
maybe-subtable (type).
on-route-p (function).
propagate-routes (function).
reset-ids (function).
route-table (structure).
route-table-p (function).
route-table-sparse-part (reader).
(setf route-table-sparse-part) (writer).
rt-elem (function).
rt-elem-len (function).
rt-elem-step (function).
set-rt-elem (function).
subtable (type).
update-all-route-tables (function).
with-sparse-elem (macro).
cepl.spaces/space.lispnht-routes.lisp (file).
cepl.spaces (system).
free (method).
make-space (function).
make-space* (function).
model-space-p (function).
parent-space (function).
print-object (method).
print-object (method).
relational-space-p (function).
vec-space (structure).
%add-space-to-array (function).
%make-heirarchical-space (function).
%make-model-space (function).
%make-relational-space (function).
%make-space (function).
%make-sr (function).
%mspace-only-sr (function).
%rspace-to-neighbour-relationship (function).
%rspace-to-neighbour-transform (function).
%set-rspace-to-neighbour-transform (function).
%space-children (reader).
%space-depth (reader).
(setf %space-depth) (writer).
%space-kind (reader).
%space-neighbours (reader).
%space-nht-id (reader).
%space-parent (reader).
%space-ref (function).
%space-root (reader).
%space-uid (reader).
%update-mspace-transform (function).
*last-space-id* (special variable).
*spaces-array-growth-rate* (special variable).
+hierachical-space+ (constant).
+model-space+ (constant).
+relational-space+ (constant).
copy-spatial-relationship (function).
copy-vec-space (function).
disconnect-space (function).
free-space (function).
kind-case (macro).
kind-case* (macro).
make-relational-space (function).
make-space-array (function).
make-spatial-relationship (function).
parse-relationship (function).
parse-relationships (function).
spaces (special variable).
spatial-relationship (structure).
spatial-relationship-p (function).
sr-from (reader).
(setf sr-from) (writer).
sr-source-id (reader).
sr-target-id (reader).
sr-to (reader).
(setf sr-to) (writer).
upgrade-from-model-space (function).
vec-space-p (function).
cepl.spaces/predefined-spaces.lispspace.lisp (file).
cepl.spaces (system).
*clip-space* (special variable).
*ndc-space* (special variable).
*screen-space* (special variable).
*world-space* (special variable).
*identity-eye-space* (special variable).
cepl.spaces/pos.lisppredefined-spaces.lisp (file).
cepl.spaces (system).
svec4 (structure).
%%-svec3! (function).
%%-svec4! (function).
*default-pos-space* (special variable).
copy-pos (function).
copy-svec3 (function).
copy-svec4 (function).
make-pos (function).
pos (structure).
pos-p (function).
pos-space (reader).
svec3 (structure).
svec3-p (function).
svec3-point (reader).
(setf svec3-point) (writer).
svec3-space (function).
svec4-p (function).
svec4-point (reader).
(setf svec4-point) (writer).
svec4-space (function).
cepl.spaces/space-errors.lisppos.lisp (file).
cepl.spaces (system).
not-ancestor (condition).
position->no-space (condition).
cepl.spaces/space-walking.lispspace-errors.lisp (file).
cepl.spaces (system).
%reduce-ancestors (function).
%reduce-ancestors-until-space (function).
reduce-ancestors (compiler macro).
reduce-ancestors (function).
cepl.spaces/space-transforms.lispspace-walking.lisp (file).
cepl.spaces (system).
get-transform (function).
(setf get-transform) (function).
get-transform-via (function).
with-space-routing-via (macro).
%check-not-illegal-space (function).
%get-hierarchical-transform (function).
%hspace-inverse-transform (function).
%hspace-to-hspace-transform (function).
%hspace-to-mspace-transform (function).
%hspace-to-rspace-transform (function).
%hspace-transform (function).
%mspace-to-hspace-transform (function).
%mspace-to-mspace-transform (function).
%mspace-to-rspace-transform (function).
%mspace-transform (function).
%rspace-to-hspace-transform (function).
%rspace-to-mspace-transform (function).
%rspace-to-rspace-ids-transform (function).
%rspace-to-rspace-transform (function).
%set-hspace-transform (function).
%set-mspace-transform (function).
%set-rspace-transform (function).
collect-inverse-to (function).
collect-transform-to (function).
find-common-ancestor (function).
restrict-route (function).
route-restriction (function).
un-restrict-routes (function).
cepl.spaces/pos-funcs.lispspace-transforms.lisp (file).
cepl.spaces (system).
sv! (function).
cepl.spaces/vector-space.lisppos-funcs.lisp (file).
cepl.spaces (system).
infer-implicit-uniform-type (method).
meta-kinds-to-infer (method).
vec-space-g (class).
cepl.spaces/spatial-vector.lispvector-space.lisp (file).
cepl.spaces (system).
combine-metadata (method).
initialize-instance (method).
print-object (method).
get-current-space (function).
in-space (generic function).
infer-meta-by-type (method).
infer-meta-by-type (method).
meta-kinds-to-infer (method).
meta-kinds-to-infer (method).
spatial-meta (class).
svec3-g (class).
svec4-g (class).
cepl.spaces/gpu.lispspatial-vector.lisp (file).
cepl.spaces (system).
in (macro).
compile-implicit-mat4 (function).
convert-between-spaces (function).
inject-clip-or-ndc-reverse-transform (function).
inject-regular-space-transform (function).
cepl.spaces/docs.lispgpu.lisp (file).
cepl.spaces (system).
Packages are listed by definition order.
cepl.spaces.routescepl-utils.
cepl.defn.
cepl.errors.
common-lisp.
editor-hints.named-readtables.
fn.
%has-route (function).
%make-route-table (function).
%make-routes-array (function).
%next-step (function).
%route-len (function).
%set-route (function).
%walk-leaving-trail (function).
+default-subtable-count+ (constant).
+subtable-length+ (constant).
connect-to-0 (function).
connect-to-1 (function).
connect-to-many (function).
copy-route-table (function).
extend-routes (function).
fart-route (function).
get-current-id-count (function).
get-current-subtable-count (function).
get-route-cache (function).
get-routes (function).
id-neighbours (function).
make-cache (function).
make-route-subtable (function).
make-route-table (function).
maybe-subtable (type).
on-route-p (function).
propagate-routes (function).
reset-ids (function).
route-table (structure).
route-table-p (function).
route-table-sparse-part (reader).
(setf route-table-sparse-part) (writer).
rt-elem (function).
rt-elem-len (function).
rt-elem-step (function).
set-rt-elem (function).
subtable (type).
update-all-route-tables (function).
with-sparse-elem (macro).
cepl.spacescepl-utils.
cepl.defn.
cepl.errors.
cepl.internals.
cepl.memory.
cepl.pipelines.
cepl.types.
common-lisp.
editor-hints.named-readtables.
rtg-math.
rtg-math.types.
vari.
varjo.
*clip-space* (special variable).
*ndc-space* (special variable).
*screen-space* (special variable).
*world-space* (special variable).
get-transform (function).
(setf get-transform) (function).
get-transform-via (function).
in (macro).
make-space (function).
make-space* (function).
model-space-p (function).
parent-space (function).
relational-space-p (function).
sv! (function).
svec4 (structure).
vec-space (structure).
with-space-routing-via (macro).
%%-svec3! (function).
%%-svec4! (function).
%add-space-to-array (function).
%check-not-illegal-space (function).
%get-hierarchical-transform (function).
%hspace-inverse-transform (function).
%hspace-to-hspace-transform (function).
%hspace-to-mspace-transform (function).
%hspace-to-rspace-transform (function).
%hspace-transform (function).
%make-heirarchical-space (function).
%make-model-space (function).
%make-relational-space (function).
%make-space (function).
%make-sr (function).
%mspace-only-sr (function).
%mspace-to-hspace-transform (function).
%mspace-to-mspace-transform (function).
%mspace-to-rspace-transform (function).
%mspace-transform (function).
%reduce-ancestors (function).
%reduce-ancestors-until-space (function).
%rspace-to-hspace-transform (function).
%rspace-to-mspace-transform (function).
%rspace-to-neighbour-relationship (function).
%rspace-to-neighbour-transform (function).
%rspace-to-rspace-ids-transform (function).
%rspace-to-rspace-transform (function).
%set-hspace-transform (function).
%set-mspace-transform (function).
%set-rspace-to-neighbour-transform (function).
%set-rspace-transform (function).
%space-children (reader).
%space-depth (reader).
(setf %space-depth) (writer).
%space-kind (reader).
%space-neighbours (reader).
%space-nht-id (reader).
%space-parent (reader).
%space-ref (function).
%space-root (reader).
%space-uid (reader).
%update-mspace-transform (function).
*default-pos-space* (special variable).
*identity-eye-space* (special variable).
*last-space-id* (special variable).
*spaces-array-growth-rate* (special variable).
+hierachical-space+ (constant).
+model-space+ (constant).
+relational-space+ (constant).
collect-inverse-to (function).
collect-transform-to (function).
compile-implicit-mat4 (function).
convert-between-spaces (function).
copy-pos (function).
copy-spatial-relationship (function).
copy-svec3 (function).
copy-svec4 (function).
copy-vec-space (function).
disconnect-space (function).
find-common-ancestor (function).
free-space (function).
get-current-space (function).
in-space (generic function).
inject-clip-or-ndc-reverse-transform (function).
inject-regular-space-transform (function).
kind-case (macro).
kind-case* (macro).
make-pos (function).
make-relational-space (function).
make-space-array (function).
make-spatial-relationship (function).
not-ancestor (condition).
parse-relationship (function).
parse-relationships (function).
pos (structure).
pos-p (function).
pos-space (reader).
position->no-space (condition).
re-space (function).
reduce-ancestors (compiler macro).
reduce-ancestors (function).
restrict-route (function).
route-restriction (function).
spaces (special variable).
spatial-meta (class).
spatial-relationship (structure).
spatial-relationship-p (function).
sr-from (reader).
(setf sr-from) (writer).
sr-source-id (reader).
sr-target-id (reader).
sr-to (reader).
(setf sr-to) (writer).
svec3 (structure).
svec3-g (class).
svec3-p (function).
svec3-point (reader).
(setf svec3-point) (writer).
svec3-space (function).
svec4-g (class).
svec4-p (function).
svec4-point (reader).
(setf svec4-point) (writer).
svec4-space (function).
to-space (function).
un-restrict-routes (function).
upgrade-from-model-space (function).
vec-space-g (class).
vec-space-p (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
This is the vec-space that describes clip-space in CEPL.
This is the vec-space that describes ndc-space in CEPL.
This is the vec-space that describes screen-space in CEPL.
It could also be thought of as FBO space when you are not rendering into the default framebuffer object.
This is the vec-space that describes world-space in CEPL.
Whilst it is perfectly possible to use CEPL’s vec-space feature to define your own world-space, we strongly suggest you do not as CEPL has some specific optimizations it can do you you use *world-space* instead of your own.
This macro is only valid inside gpu functions.
It defines a scope which is said to be ’in the vec-space’ given as the first
argument. This means that any spatial-vectors created in this scope will be
declared in this space.
If the value that is returned from the scope of the ’in’ is a spatial-vector
then the vector is transformed from the space of the inner scope to the space of
the outer scope.
For example:
(in *clip-space*
(let ((z (in *world-space*
(let ((x (sv! 0 1 2 3)))
...
x))))
z))
In the code above the spatial-vector x is defined in *world-space*. However
as it is used in the tail position of the innermost let, it will leave the
*world-space* scope and enter the *clip-space* scope. At that point the
spatial-vector will be multiplied with the mat4 that describes the
*world-space* → *clip-space* transform.
All of this information is resolved statically at compile-time by CEPL. The ’in’
forms are removed and the spatial-vectors are replaced with regular ones. CEPL
will calculate the mat4 transforms between the used spaces on the CPU and upload
them as uniforms.
This means that the final glsl will only contain standard glsl vectors and matrices and will perform as well as any other handwritten glsl code.
This macro ensures that all routes calculated between spaces go via the specifed
vec-space.
This behaves as if all the calls to #’get-transform were actually called to #’get-transform-via with the given vec-space used as the via-space.
This function will return the mat4 that describes the transform between
from-space and to-space.
If you have an existing matrix you wish to use as the base of the transform then you case pass it as the initial-m4 argument
This function will return the mat4 that describes the transform between
from-space and to-space, via the specified via-space.
This is very useful in cases where there are multiple possible routes to the to-space and you wish to restrict which route is taken.
This function returns a new vec-space when passed:
- The space which this new space will be defined in relation to
- A mat4 which describes the transform from this new space to the target-space
- (optional) A mat4 which describes the transform from the target-space to this
new space.
As the new vec-space will have only 1 neighbour it will be a model-space
This function returns a new vec-space when passed as in the following format:
(list (neighbour-space1 mat4-to-neighbour-space1 mat4-from-neighbour-space1)
(neighbour-space2 mat4-to-neighbour-space2 mat4-from-neighbour-space2)
... etc ...)
Just like in #’make-space, the mat4-from-neighbour-space transform is optional.
As this function produces a vec-space with multiple neighbour spaces, the resulting vec-space is known as a relational-space.
When passed a vec-space this function will return t if the vec-space is a
’model-space’
In CEPL this means that this vec-space on has one non-hierarchical relationship with another space.
When given a hierarchical vec-space, this function will return the space that has this vec-space as a child
When passed a vec-space this function will return t if the vec-space is a
’relational-space’
In CEPL this means that this vec-space is a child of another vec-space.
This function is only useful inside gpu functions.
It returns a new spatial vector. A spatial vector is much like a regular vector
except that the vector-space in which it resides is stored along with the
vector’s components.
If a spatial vector leaves the lexical scope of the vec-space it was defined in,
then it is automatically transformed into the vec-space of the surrounding
scope.
See the docstring for the ’in’ macro for more details.
For more info on the behaviour of CEPL’s space feature as a whole please see the docstring for the vec-space struct.
spatial-meta) (meta-b spatial-meta)) ¶varjo.internals.
spatial-meta) &rest all-args &key in-space) ¶spatial-meta) stream) ¶spatial-relationship) stream) ¶This is a 4 component spatial vector type. A spatial vector is a vector that also stores which vector-space it is in.
This type is an abstraction over the concept of a vector-space.
In graphics programming we are very used to using matrices to describe
transforms. The matrix describes the transform for any given point in
vector-space to a point in another vector-space.
Some spaces are very commonly mentioned when discuss rendering, spaces like world-space, camera-space, clip-space, etc. However when it comes to our programs we have to work with the transform (matrix) rather the space directly.
In CEPL we have a feature to allow working with vector spaces as a first class
object, the vec-space. We uses these vec-spaces in our GPU code and CEPL
statically analyses our code to work out what matrices are needed and uploads
them as uniforms.
By doing this, our GPU ends up running code that only has the ’normal’
types (matrices and vectors) which means we pay no performace cost for the
features
Working with vec-spaces directly means our code more closely reflects how we
talk about the problems we are trying to solve. As we will see below it also
makes it much harder to perform ’invalid’ spatial calculations.
– Lexical Space –
In many graphics related texts we talk about performing a calculation in a
certain space.
In CEPL we express this with the ’in’ macro
(in *world-space*
(some-calculation)
(more-calculations))
Everything that is happening in this scope is happening ’in *world-space*’
the ’in’ macro can be nested:
(in *clip-space*
(let ((z (in *world-space*
(let ((x (sv! 0 1 2 3)))
...
x))))
z))
Here z is in *clip-space* and x is in *world-space*
– Spatial Vectors –
In the above example we also introduce another type: spatial-vectors
sv! behave exactly the same as v! in that it produces a vector, however instead of making a regular vector the code above will make a spatial-vector.
Spatial vectors are vectors which store which space they were created in.
The advantage of this is that CEPL can detect if they leave that space and enter
a different space. When that happens CEPL will automatically transform the
vector to the new space.
We can see this in the example above. The value in ’x’ is a spatial vector that
was created in world space, however as the value moves up the stack to be
stored in ’z’ it leaves the scope of *world-space* and enters *clip-space*.
At this point CEPL will multiply the vector with a
’world-space-to-clip-space matrix’.
This is awesome as it means that if you are working with spatial vectors in the
same scope, you are guarenteed that they are in the same space.
Another advantage is that in most case CEPL can calculate these transform
matrices on the CPU and upload them as uniforms, which makes this code very
fast.
– Defining Spaces –
Currently vec-spaces can only be defined in cpu code. They must be passed to
gpu functions as uniforms.
All spaces are defined relative to another space. A vec-space is either a
hierarchical-space, relational-space or a model-space.
A hierarchical-space is a space which is a child of another space. When the
parent space is transformed, the child space is also transformed. You can
see this relationship as how your hand has a position and orientation but will
be transformed by the parent, the lower-arm. The lower arm in turn is a child
of the upper arm, and so on. Hierarchical spaces are WIP and not currently
exposed in CEPL
A relational-space x is a space whose relationship to another space can be defined with a matrix, but which is not affected by changes to that other space.
A relational-space can have any number of spaces as neighbours, however
in the case where there is only one neighbour space, the space is known as a
model-space.
Making a model space is very easy.
(make-space neighbour-space
transform-to-neighbour-matrix4
transform-from-neighbour-matrix4)
the transform-from-neighbour-matrix4 transform is optional where the inverse can
be calculated.
To make a relational space you use #’make-space* and pass in a list where the
sublists are the same as the arguments to make-space
– Spaces & Implicit-Uniforms
If the vec-space is stored in a variable with global scope then CEPL’s
implicit-uniforms feature means you can use the space without explicitly adding
the uniform argument yourself.
See the docstring for defun-g for more details on implicit-uniforms.
– Immutable Relationships –
Whilst the transforms between neighbouring spaces are mutable.
It is not possible to add new neighbours to an existing vec-space x, except by
making a new vec-space as specifying x as its neighbour.
– Predefined Spaces –
CEPL defines a few commonly used spaces for you. Other than *world-space* they
are all spaces used in the GLSL pipeline:
*world-space*
*clip-space*
*ndc-space*
*screen-space*
structure-object.
fixnum
(incf cepl.spaces::*last-space-id*)
This slot is read-only.
fixnum
(error "id must be provided")
This slot is read-only.
vari.cl.
(mod 3)
(error "space kind must be provided")
This slot is read-only.
(or null cepl.spaces:vec-space)
This slot is read-only.
(or null (array cepl.spaces:vec-space (*)))
This slot is read-only.
(or null cepl.spaces:vec-space)
This slot is read-only.
(array cepl.spaces::spatial-relationship (*))
(make-array 0 :element-type (quote cepl.spaces::spatial-relationship) :initial-element (cepl.spaces::%make-sr))
This slot is read-only.
fixnum
(error "space depth must be provided")
makes a new point in the same location as the first but relative to the provided new space
spatial-meta)) ¶list)) ¶svec3-g) (kind1 (eql cepl.spaces::spatial-meta)) env) ¶varjo.internals.
svec4-g) (kind1 (eql cepl.spaces::spatial-meta)) env) ¶varjo.internals.
vec-space-g)) ¶varjo.internals.
error.
:start-space
structure-object.
(array cepl.spaces.routes::maybe-subtable (*))
(error "subtable array must be provided")
structure-object.
fixnum
0
This slot is read-only.
fixnum
0
This slot is read-only.
(or null glsl-symbols.types:mat4)
(or null glsl-symbols.types:mat4)
standard-value-metadata.
:in-space
v-shadow-type.
varjo.internals.
(quote cepl.spaces::svec3-g)
varjo.internals.
(quote vari.types:v-shadow-type)
varjo.internals.
#<vari.types:v-vec3 {100b886313}>
varjo.internals.
"vec3"
v-shadow-type.
varjo.internals.
(quote cepl.spaces::svec4-g)
varjo.internals.
(quote vari.types:v-shadow-type)
varjo.internals.
#<vari.types:v-vec4 {100b886043}>
varjo.internals.
"vec4"
| Jump to: | %
(
A C D E F G I K M O P R S T U V W |
|---|
| Jump to: | %
(
A C D E F G I K M O P R S T U V W |
|---|
| Jump to: | *
+
A C D F G I K N P R S T U |
|---|
| Jump to: | *
+
A C D F G I K N P R S T U |
|---|
| Jump to: | C D F G M N P R S T V |
|---|
| Jump to: | C D F G M N P R S T V |
|---|