→ ↺

Kons-9 API Reference

Table of Contents

• 1 KONS-9 ASDF System
• 2 Introduction
• 3 Points
  • 3.1 Point arithmetic
  • 3.2 Point metrics
  • 3.3 Computing new points
  • 3.4 Vectors as points
    • 3.4.1 Trigonometry
  • 3.5 Geometry operations on points
  • 3.6 Lisp object operations on points
• 4 Color
• 5 Matrix
• 6 Shape
  • 6.1 Point cloud
    • 6.1.1 Polyhedron
• 7 Groups (mixin)
  • 7.1 Shape Groups
• 8 Scene and item
• 9 Command table
• 10 Top-level

[in package KONS-9]

← ↑ → ↺

1 KONS-9 ASDF System

• Description: Common Lisp 3D Graphics System
• Licence: MIT
• Author: Kaveh Kardan

← ↑ → ↺

2 Introduction

Kons-9 is a 3D IDE written in Common Lisp.

This manual aspires to be a full description of the Lisp programming interface to Kons-9. This manual presumes that you are familiar with Common Lisp programming. (If you are not already a Common Lisp hacker then consider reading Practical Common Lisp.)

Beware! This manual is new and incomplete. It will require the contributions of many authors to achieve its goal of completeness. If the documentation you are looking for is not yet written then please consider writing the first draft.

The documentation is prepared using MGL-PAX by Gábor Melis.

Now let's get cracking!

← ↑ → ↺

3 Points

Points are three-dimensional coordinates represented as specialized single-float vectors.

Point operations are all non-destructive unless stated otherwise.

• [function] P! X Y Z

  Construct a new point object.

• [variable] +ORIGIN+ #(0.0 0.0 0.0)

← ↑ → ↺

3.1 Point arithmetic

Point-arithmetic supports either a point or a scalar on the right-hand-side (VAL).

• [function] P+ P VAL

  (p+ (p! 1 2 3)
      (p! 10 20 30))
  => #(11.0 22.0 33.0)

• [function] P- P VAL

  (p- (p! 1 2 3) 1)
  => #(0.0 1.0 2.0)

• [function] P* P VAL

  (p* (p! 1 2 3)
      (p! 10 20 30))
  => #(10.0 40.0 90.0)

• [function] P/ P VAL

  (p/ (p! 1 2 3) 2)
  => #(0.5 1.0 1.5)

← ↑ → ↺

3.2 Point metrics

• [function] P-DIST P1 P2

  Return the distance between points P1 and P2.

• [function] P-DIST-SQUARED P1 P2

  Return the square of the distance between points P1 and P2.

← ↑ → ↺

3.3 Computing new points

• [function] P-CENTER POINTS

  Return the center (average) of POINTS.

• [function] P-AVERAGE &REST POINTS

  See P-CENTER.

• [function] P-MIDPOINT P1 P2

• [function] P-SMOOTH-LERP F P1 P2

  Return a point interpolated smoothly (cubic) between P1 and P2 by factor F.

  (loop with p1 = (p! 0 0 0)
        with p2 = (p! 0 0 1)
        for f from 0.0 to 1.0 by 0.1
        do (print (p-smooth-lerp f p1 p2)))
  ..
  .. #(0.0 0.0 0.0) 
  .. #(0.0 0.0 0.028) 
  .. #(0.0 0.0 0.104) 
  .. #(0.0 0.0 0.216) 
  .. #(0.0 0.0 0.352) 
  .. #(0.0 0.0 0.5) 
  .. #(0.0 0.0 0.648) 
  .. #(0.0 0.0 0.7840001) 
  .. #(0.0 0.0 0.896) 
  .. #(0.0 0.0 0.9720001) 
  => NIL

• [function] P-JITTER P AMOUNT

  Return a new point with a uniform random number in -AMOUNT,AMOUNT added to each of the coordinates of P.

  (loop repeat 5
        with p = (p! 0 0 0)
        do (print (p-jitter p 0.1)))
  ..
  .. #(-0.080474615 -0.06286216 -0.013924263) 
  .. #(0.03770628 -0.05889466 0.043178223) 
  .. #(-0.08204675 0.03890068 0.06946192) 
  .. #(-0.05057454 -0.041642357 0.05375267) 
  .. #(0.07503488 0.019013837 0.056709193) 
  => NIL

← ↑ → ↺

3.4 Vectors as points

Vectors are conveniently represented as points too.

• [variable] +X-AXIS+ #(1.0 0.0 0.0)

• [variable] +Y-AXIS+ #(0.0 1.0 0.0)

• [variable] +Z-AXIS+ #(0.0 0.0 1.0)

• [function] P-FROM-TO P1 P2

• [function] P-RAND &OPTIONAL (MAG 1.0)

  Return a random vector with magnitude MAG.

  (dotimes (i 5)
   (print (p-rand 10.0)))
  ..
  .. #(-7.8083973 -6.0994725 -1.351062) 
  .. #(4.587864 -7.165933 5.253656) 
  .. #(-7.17671 3.4026814 6.0759025) 
  .. #(-5.9680557 -4.9140115 6.34309) 
  .. #(7.819659 1.9815011 5.9098725) 
  => NIL

• [function] P-RAND1 P &OPTIONAL (PIVOT (P! 0 0 0))

  (values (p-rand1 (p! 10 0 0))
          (p-rand1 (p! 10 0 0) (p! 0 0 100)))
  => #(-8.0474615 0.0 0.0)
  => #(-6.286216 0.0 100.0)

• [function] P-RAND2 VAL1 VAL2

  (dotimes (i 5)
    (print (p-rand2 +origin+ (p! 1 10 100))))
  ..
  .. #(0.097626925 1.8568921 43.03787) 
  .. #(0.6885314 2.055267 71.58911) 
  .. #(0.089766264 6.945034 84.73096) 
  .. #(0.2471273 2.9178822 76.87633) 
  .. #(0.8751744 5.9506917 78.3546) 
  => NIL

← ↑ → ↺

3.4.1 Trigonometry

Trigonometric functions are defined on vectors (represented as points.)

• [function] P-ANGLE-COSINE P1 P2

• [function] P-ANGLE-SINE P1 P2

• [function] P-ANGLE P1 P2

• [function] P-Z-ALIGNMENT-ANGLES POINT

← ↑ → ↺

3.5 Geometry operations on points

• [function] TRIANGLE-NORMAL P0 P1 P2

• [function] QUAD-NORMAL P0 P1 P2 P3

• [function] TRIANGLE-AREA P0 P1 P2

• [function] BARYCENTRIC-POINT P0 P1 P2 A B

• [function] RANDOM-BARYCENTRIC-POINT P0 P1 P2

• [function] POINTS-BOUNDS POINT-ARRAY

• [function] P-SPHERICIZE P RADIUS &OPTIONAL (FACTOR 1.0) (CENTER +ORIGIN+)

• [function] POINT-LINE-SEGMENT-DIST P A B

• [function] POINT-CURVE-DIST POINT POINTS IS-CLOSED-CURVE?

• [function] POINT-ON-PLANE POINT PLANE-POINT PLANE-NORMAL

• [function] POINT-ON-TRIANGLE-PLANE P A B C

• [function] POINT-BARYCENTRIC-COORDINATES P A B C

• [function] POINT-INSIDE-TRIANGLE P A B C

• [function] POINT-LINE-SEGMENT-CLOSEST-POINT P A B

• [function] POINT-TRIANGLE-CLOSEST-POINT P A B C

← ↑ → ↺

3.6 Lisp object operations on points

• [function] POINT->LIST P

• [function] P-SET! P X Y Z

• [function] P-VEC VEC3

• [function] COPY-POINTS POINTS

• [function] COPY-POINT-ARRAY POINT-ARRAY

← ↑ → ↺

4 Color

Colors are four-channel RGBA values represented as vectors of single-float levels between 0.0 and 1.0.

Operations on colors are non-destructive unless stated otherwise.

• [function] C! R G B &OPTIONAL (A 1.0)

• [function] C-RED C

  Return the red component of color C. cl-transcript (:dynenv pax-dynenv) (c-red (c! 0.1 0.2 0.3)) => 0.1

• [function] C-GREEN C

  Return the green component of color C.

  (c-green (c! 0.1 0.2 0.3))
  => 0.2

• [function] C-BLUE C

  Return the blue component of color C.

  (c-blue (c! 0.1 0.2 0.3))
  => 0.3

• [function] C-ALPHA C

  Return the alpha component of color C.

  (c-alpha (c! 0.1 0.2 0.3 0.4))
  => 0.4

• [function] C-SET-RGB C1 C2

  Destructively copy the RGB (but not alpha) values from C1 to C2.

• [function] C-SET-ALPHA C ALPHA

  Destructively set the alpha value of C to ALPHA.

• [function] C-LERP F C1 C2

  Return a color linearly interpolated by factor F between C1 and C2.

  (c-lerp 0.5 (c! 0 0 0 0) (c! 0.2 0.4 0.6 0.8))
  => #(0.1 0.2 0.3 0.4)

• [function] C-RAND

  Return an opaque color with uniform RGB channel values.

  (dotimes (i 3)
    (print (c-rand)))
  ..
  .. #(0.097626925 0.18568921 0.43037868 1.0) 
  .. #(0.6885314 0.20552671 0.7158911 1.0) 
  .. #(0.089766264 0.6945034 0.8473096 1.0) 
  => NIL

• [function] C-RAND-WITH-ALPHA

  Return a color with uniform random RGB and alpha values.

  (dotimes (i 3)
    (print (c-rand-with-alpha)))
  ..
  .. #(0.097626925 0.18568921 0.43037868 0.6885314) 
  .. #(0.20552671 0.7158911 0.089766264 0.6945034) 
  .. #(0.8473096 0.2471273 0.29178822 0.7687633) 
  => NIL

• [function] C-RAND2 C1 C2

• [function] C+ C1 C2

• [function] C-SCALE C1 X

• [function] C-JITTER C C-DELTA

• [function] C-RAINBOW F &OPTIONAL (ALPHA 1.0)

← ↑ → ↺

5 Matrix

A matrix is a 4x4 array of numbers that represents an affine transformation in 3D space.

• [function] MAKE-MATRIX

• [function] MAKE-MATRIX-WITH CONTENTS

• [function] MAKE-ID-MATRIX

• [function] MATRIX->LIST MATRIX

• [function] MATRIX->VECTOR MATRIX

• [function] MATRIX-COPY MATRIX

• [function] MAKE-TRANSLATION-MATRIX POINT

• [function] MAKE-ROTATION-MATRIX POINT ORDER &OPTIONAL (PIVOT NIL)

• [function] MAKE-X-ROTATION-MATRIX ANGLE

• [function] MAKE-Y-ROTATION-MATRIX ANGLE

• [function] MAKE-Z-ROTATION-MATRIX ANGLE

• [function] MAKE-AXIS-ROTATION-MATRIX ANGLE AXIS &OPTIONAL (PIVOT NIL)

• [function] MAKE-SCALE-MATRIX POINT &OPTIONAL (PIVOT NIL)

• [function] MAKE-SHEAR-MATRIX POINT

• [function] MAKE-Z-ALIGNMENT-MATRIX POINT

• [function] MAKE-LOOK-AT-FROM-MATRIX FROM TO &OPTIONAL (UP (P! 0 1 0))

• [function] MAKE-LOOK-DIR-FROM-MATRIX FROM DIR &OPTIONAL (UP (P! 0 1 0))

• [function] MATRIX-MULTIPLY MATRIX-1 MATRIX-2

• [function] MATRIX-MULTIPLY-N &REST MATRICES

• [function] TRANSFORM-POINT POINT MATRIX

• [function] TRANSFORM-POINTS POINTS MATRIX

• [function] TRANSFORM-POINT! POINT MATRIX

• [function] TRANSFORM-POINT-ARRAY! POINT-ARRAY MATRIX

← ↑ → ↺

6 Shape

• [class] SHAPE SCENE-ITEM

• [accessor] TRANSFORM SHAPE (:TRANSFORM = (MAKE-INSTANCE 'EULER-TRANSFORM))

• [accessor] IS-VISIBLE? SHAPE (:IS-VISIBLE? = T)

• [accessor] SHOW-AXIS SHAPE (:SHOW-AXIS = NIL)

• [accessor] SHOW-BOUNDS? SHAPE (:SHOW-BOUNDS? = NIL)

Relative.

• [method] TRANSLATE-BY (SELF SHAPE) P

• [method] ROTATE-BY (SELF SHAPE) P

• [method] SCALE-BY (SELF SHAPE) P

Absolute.

• [method] TRANSLATE-TO (SELF SHAPE) P

• [method] ROTATE-TO (SELF SHAPE) P

• [method] SCALE-TO (SELF SHAPE) P

• [method] SCALE-BY (SELF SHAPE) (S NUMBER)

Special.

• [method] RESET-TRANSFORM (SELF SHAPE)

• [method] CENTER-AT-ORIGIN (SELF SHAPE)

• [method] SCALE-TO-SIZE (SELF SHAPE) MAX-SIZE

• [method] GET-BOUNDS (SELF SHAPE)

← ↑ → ↺

6.1 Point cloud

A point-cloud is a shape made up of colored points.

• [class] POINT-CLOUD SHAPE

• [accessor] POINTS POINT-CLOUD (:POINTS = (MAKE-ARRAY 0 :ADJUSTABLE T :FILL-POINTER T))

• [accessor] POINT-COLORS POINT-CLOUD (:POINT-COLORS = NIL)

• [function] MAKE-POINT-CLOUD POINTS &OPTIONAL (COLORS NIL)

• [function] MAKE-LINE-POINTS P1 P2 NUM-SEGMENTS

• [function] MAKE-RECTANGLE-POINTS WIDTH HEIGHT &OPTIONAL (NUM-SEGMENTS 1)

• [function] MAKE-CIRCLE-POINTS DIAMETER NUM-SEGMENTS

• [function] MAKE-ARC-POINTS DIAMETER START-ANGLE END-ANGLE NUM-SEGMENTS

• [function] MAKE-SPIRAL-POINTS START-DIAMETER END-DIAMETER AXIS-LENGTH NUM-LOOPS NUM-SEGMENTS

• [function] MAKE-SINE-CURVE-POINTS PERIOD FREQUENCY X-SCALE Y-SCALE NUM-SEGMENTS

• [function] MAKE-RANDOM-POINTS NUM BOUNDS-LO BOUNDS-HI

• [function] MAKE-GRID-POINTS NX NY NZ BOUNDS-LO BOUNDS-HI

• [method] FREEZE-TRANSFORM (P-CLOUD POINT-CLOUD)

• [method] ALLOCATE-POINT-COLORS (P-CLOUD POINT-CLOUD)

• [method] RESET-POINT-COLORS (P-CLOUD POINT-CLOUD)

• [method] SET-POINT-COLORS-BY-XYZ (P-CLOUD POINT-CLOUD) COLOR-FN

• [method] RANDOMIZE-POINTS (P-CLOUD POINT-CLOUD) DELTA

← ↑ → ↺

6.1.1 Polyhedron

A polyhedron is a 3D shape formed by flat polygonal faces. The faces of a polyhedron are represented in terms of the vertices of an underlying point-cloud.

• [class] POLYHEDRON POINT-CLOUD

• [accessor] FACES POLYHEDRON (:FACES = (MAKE-ARRAY 0 :ADJUSTABLE T :FILL-POINTER T))

• [accessor] FACE-NORMALS POLYHEDRON (:FACE-NORMALS = (MAKE-ARRAY 0 :ADJUSTABLE T :FILL-POINTER T))

• [accessor] POINT-NORMALS POLYHEDRON (:POINT-NORMALS = (MAKE-ARRAY 0 :ADJUSTABLE T :FILL-POINTER T))

• [accessor] SHOW-NORMALS POLYHEDRON (:SHOW-NORMALS = NIL)

• [accessor] POINT-SOURCE-USE-FACE-CENTERS? POLYHEDRON (:POINT-SOURCE-USE-FACE-CENTERS? = NIL)

Polyhedrons can be constructed to represent (or approximate) many common geometric shapes.

• [function] MAKE-POLYHEDRON POINTS FACES &KEY (NAME NIL) (MESH-TYPE 'POLYHEDRON)

• [function] MAKE-POLYHEDRON POINTS FACES &KEY (NAME NIL) (MESH-TYPE 'POLYHEDRON)

• [function] MAKE-RECTANGLE-POLYHEDRON WIDTH HEIGHT &KEY (NAME NIL) (MESH-TYPE 'POLYHEDRON)

• [function] MAKE-SQUARE-POLYHEDRON SIDE &KEY (NAME NIL) (MESH-TYPE 'POLYHEDRON)

• [function] MAKE-CIRCLE-POLYHEDRON DIAMETER NUM-SEGMENTS &KEY (NAME NIL) (MESH-TYPE 'POLYHEDRON)

• [function] MAKE-TETRAHEDRON DIAMETER &KEY (NAME NIL) (MESH-TYPE 'POLYHEDRON)

• [function] MAKE-BOX X-SIZE Y-SIZE Z-SIZE &KEY (NAME NIL) (MESH-TYPE 'POLYHEDRON)

• [function] MAKE-CUBE SIDE &KEY (NAME NIL) (MESH-TYPE 'POLYHEDRON)

• [function] MAKE-CUT-CUBE SIDE &KEY (NAME NIL) (MESH-TYPE 'POLYHEDRON)

• [function] MAKE-OCTAHEDRON DIAMETER &KEY (NAME NIL) (MESH-TYPE 'POLYHEDRON)

• [function] MAKE-DODECAHEDRON DIAMETER &KEY (NAME NIL) (MESH-TYPE 'POLYHEDRON)

• [function] MAKE-ICOSAHEDRON DIAMETER &KEY (NAME NIL) (MESH-TYPE 'POLYHEDRON)

• [function] MAKE-CUBE-SPHERE SIDE SUBDIV-LEVELS &KEY (NAME NIL) (MESH-TYPE 'POLYHEDRON)

• [method] EMPTY-POLYHEDRON (POLYH POLYHEDRON)

• [method] SET-FACE-POINT-LISTS (POLYH POLYHEDRON) POINT-LISTS

• [method] SET-TRIANGLE-ARRAYS (POLYH POLYHEDRON) TRIANGLE-ARRAYS

• [method] FACE-CENTER (POLYH POLYHEDRON) FACE

• [method] FACE-CENTERS (POLYH POLYHEDRON)

• [method] FACE-NORMAL (POLYH POLYHEDRON) FACE

• [method] COMPUTE-FACE-NORMALS (POLYH POLYHEDRON)

• [method] COMPUTE-POINT-NORMALS (POLYH POLYHEDRON)

• [method] COMPUTE-POINT-NORMALS-SAV (POLYH POLYHEDRON)

• [method] FACE-POINTS-LIST (POLYH POLYHEDRON) (I INTEGER)

• [method] FACE-POINTS-LIST (POLYH POLYHEDRON) (FACE LIST)

• [method] FACE-POINTS-ARRAY (POLYH POLYHEDRON) (I INTEGER)

• [method] FACE-POINTS-ARRAY (POLYH POLYHEDRON) (FACE LIST)

• [method] REVERSE-FACE-NORMALS (POLYH POLYHEDRON)

• [method] SET-POINT-COLORS-BY-POINT-AND-NORMAL (POLYH POLYHEDRON) COLOR-FN

• [method] SET-POINT-COLORS-UNIFORM (POLYH POLYHEDRON) COLOR

← ↑ → ↺

7 Groups (mixin)

• [class] GROUP-MIXIN

• [accessor] CHILDREN GROUP-MIXIN (:CHILDREN = (MAKE-ARRAY 0 :ADJUSTABLE T :FILL-POINTER 0))

• [method] PRINTABLE-DATA (SELF GROUP-MIXIN)

• [method] NUM-CHILDREN (GROUP GROUP-MIXIN)

• [method] GET-CHILD (GROUP GROUP-MIXIN) I

• [method] CHILDREN-AS-LIST (GROUP GROUP-MIXIN)

• [method] ADD-CHILD (GROUP GROUP-MIXIN) (ITEM SCENE-ITEM)

• [method] REMOVE-CHILD (GROUP GROUP-MIXIN) (ITEM SCENE-ITEM)

• [method] SET-CHILDREN (GROUP GROUP-MIXIN) SCENE-ITEMS

• [method] REMOVE-ALL-CHILDREN (GROUP GROUP-MIXIN)

← ↑ → ↺

7.1 Shape Groups

• [class] SHAPE-GROUP SHAPE GROUP-MIXIN

• [function] MAKE-SHAPE-GROUP SHAPES &KEY (NAME NIL)

• [method] GET-BOUNDS (GROUP SHAPE-GROUP)

• [method] SET-POINT-COLORS-BY-XYZ (GROUP SHAPE-GROUP) COLOR-FN

• [function] SCATTER-SHAPES-IN-GROUP SHAPE-FN POINT-ARRAY

• [function] SCATTER-SHAPES SHAPES POINT-ARRAY

• [function] SCATTER-SHAPE-INSTANCES SHAPES POINT-ARRAY

← ↑ → ↺

8 Scene and item

Item

• [class] ITEM

Scene item

• [class] SCENE-ITEM ITEM

Scene

• [class] SCENE ITEM

• [accessor] SHAPE-ROOT SCENE (:SHAPE-ROOT = (MAKE-INSTANCE 'SHAPE-GROUP :NAME 'SHAPES))

• [accessor] MOTION-ROOT SCENE (:MOTION-ROOT = (MAKE-INSTANCE 'MOTION-GROUP :NAME 'MOTIONS))

• [accessor] INTERACTOR SCENE (:INTERACTOR = NIL)

• [accessor] INITIALIZED? SCENE (:INITIALIZED? = NIL)

• [accessor] SELECTION SCENE (:SELECTION = 'NIL)

• [accessor] START-FRAME SCENE (:START-FRAME = 0)

• [accessor] END-FRAME SCENE (:END-FRAME = 240)

• [accessor] CURRENT-FRAME SCENE (:CURRENT-FRAME = 0)

• [accessor] FPS SCENE (:FPS = 24)

← ↑ → ↺

9 Command table

• [class] COMMAND-TABLE

  A command table defines a menu of keyboard-driven user interface commands. Each command either performs an action or recursively opens a new command table as a submenu.

  MAKE-INSTANCE is used to create command table objects.

• [accessor] TITLE COMMAND-TABLE (:TITLE = NIL)

• [accessor] ENTRIES COMMAND-TABLE (:ENTRIES = (MAKE-ARRAY 0 :ADJUSTABLE T :FILL-POINTER T))

One command table is active at any given time.

• [function] ACTIVE-COMMAND-TABLE

  Return the currently active command table.

• [function] MAKE-ACTIVE-COMMAND-TABLE TABLE

  Make TABLE the active command table.

Commands and nested command tables are defined using macros.

• [macro] CT-ENTRY KEY-BINDING HELP &REST EXPR

  Define a user interface command. The new command is added to the command table named table (a variable captured by this macro.)

  KEY-BINDING is a keyword designating the keyboard input that invokes the command.

  HELP is a short string description e.g. "Open Scene File".

  EXPR is one or more Lisp forms to be evaluated when the command is invoked.

• [macro] CT-SUBTABLE KEY-BINDING TITLE C-TABLE-FN

  Define a nested table of user interface commands.

  KEY-BINDING is as in the CT-ENTRY macro.

  TITLE is the string name of the menu e.g. "Edit".

  C-TABLE-FN is an expression to be evaluated to return the command table.

Here is an example of constructing a command table:

   (let ((table (make-instance 'command-table :title "Example")))
     ;; note: these macros depend on the variable name 'table'
     (ct-entry :C "Make a Cube" (make-cube 2.0))
     (ct-subtable :S "My Submenu" (make-command-table 'my-submenu))
     (entries table))

← ↑ ↺

10 Top-level

Kons-9 runs on a dedicated thread.

• [function] RUN &OPTIONAL (COMMAND-TABLE NIL)

  Open the Kons-9 user interface window and operate it using a dedicated thread.

  COMMAND-TABLE can optionally be supplied as a custom top-level command table. See Command tables.

• [variable] *SCENE* #<SCENE , frame bounds: 0 240, current: 0 {100385F943}>

  Global scene object.