The terrable Reference Manual

This is the terrable Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 06:53:09 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 terrable

Terragen TER file format reader

Maintainer

Yukari Hafner <>

Author

Yukari Hafner <>

Home Page

https://github.com/Shirakumo/terrable

License

zlib

Version

1.0.0

Dependencies
  • fast-io (system).
  • ieee-floats (system).
  • static-vectors (system).
  • trivial-garbage (system).
  • documentation-utils (system).
Source

terrable.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 terrable/terrable.asd

Source

terrable.asd.

Parent Component

terrable (system).

ASDF Systems

terrable.


3.1.2 terrable/package.lisp

Source

terrable.asd.

Parent Component

terrable (system).

Packages

terrable.


3.1.3 terrable/terrable.lisp

Dependency

package.lisp (file).

Source

terrable.asd.

Parent Component

terrable (system).

Public Interface
Internals

3.1.4 terrable/documentation.lisp

Dependency

terrable.lisp (file).

Source

terrable.asd.

Parent Component

terrable (system).


4 Packages

Packages are listed by definition order.


4.1 terrable

Source

package.lisp.

Nickname

org.shirakumo.fraf.terrable

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Generic functions

Generic Reader: chunk-type (condition)

Returns the unknown 4-letter string chunk-type that was encountered.

See UNKNOWN-CHUNK-TYPE

Package

terrable.

Methods
Reader Method: chunk-type ((condition unknown-chunk-type))
Source

terrable.lisp.

Target Slot

chunk-type.

Generic Reader: curvature-type (condition)

Returns the unknown curvature type.

See UNKNOWN-CURVATURE-TYPE

Package

terrable.

Methods
Reader Method: curvature-type ((condition unknown-curvature-type))
Source

terrable.lisp.

Target Slot

curvature-type.

Generic Reader: curve-mode (object)

Returns the curvature mode of the terrain.

This value is a keyword for known curve modes, or an integer for unknown ones. The following known modes exist:

:FLAT — The terrain is a flat map.
:DRAPED — The terrain is draped over a sphere with a radius of (/ (* CURVE-RADIUS 1000) (third SCALE))
with its centre point being at
X: (/ WIDTH 2)
Y: (/ HEIGHT 2)
Z: (/ (* CURVE-RADIUS -1000) (third SCALE))

See TERRAIN

Package

terrable.

Methods
Reader Method: curve-mode ((terrain terrain))

automatically generated reader method

Source

terrable.lisp.

Target Slot

curve-mode.

Generic Writer: (setf curve-mode) (object)
Package

terrable.

Methods
Writer Method: (setf curve-mode) ((terrain terrain))

automatically generated writer method

Source

terrable.lisp.

Target Slot

curve-mode.

Generic Reader: curve-radius (object)

Returns the curve radius for spherical terrains.

This value is a float in the unit of kilometres. The default value is 6370, an approximation of Earth’s radius. Note that this value is only relevant if CURVE-MODE is :DRAPED.

See TERRAIN

Package

terrable.

Methods
Reader Method: curve-radius ((terrain terrain))

automatically generated reader method

Source

terrable.lisp.

Target Slot

curve-radius.

Generic Writer: (setf curve-radius) (object)
Package

terrable.

Methods
Writer Method: (setf curve-radius) ((terrain terrain))

automatically generated writer method

Source

terrable.lisp.

Target Slot

curve-radius.

Generic Reader: data (object)

Returns a static-vector of the pixel data that makes up the terrain.

This pixel-data is a sequence of 16 bit signed integers.

Note that these units are not directly in the scale of SCALE, but must first be normalised by adding HEIGHT-BASE and then multiplying by HEIGHT-SCALE.

Finally, note that this is a static-vector and is thus directly passable to C by using STATIC-VECTORS:STATIC-VECTOR-POINTER.

See HEIGHT-BASE
See HEIGHT-SCALE
See STATIC-VECTORS:STATIC-VECTOR-POINTER
See TERRAIN

Package

terrable.

Methods
Reader Method: data ((terrain terrain))

automatically generated reader method

Source

terrable.lisp.

Target Slot

data.

Generic Writer: (setf data) (object)
Package

terrable.

Methods
Writer Method: (setf data) ((terrain terrain))

automatically generated writer method

Source

terrable.lisp.

Target Slot

data.

Generic Function: free-terrain (terrain)

Instantly frees the data array in the terrain instance.

After calling this function on a TERRAIN instance, its data slot will contain NIL and all references to the former data array will be invalid.

See TERRAIN

Package

terrable.

Methods
Method: free-terrain ((terrain terrain))
Source

terrable.lisp.

Generic Reader: header (condition)

Returns the offending header that did not match.

See INVALID-HEADER

Package

terrable.

Methods
Reader Method: header ((condition invalid-header))
Source

terrable.lisp.

Target Slot

header.

Generic Reader: height (object)

Returns the height (in pixels) of the terrain.

See TERRAIN

Package

terrable.

Methods
Reader Method: height ((terrain terrain))

automatically generated reader method

Source

terrable.lisp.

Target Slot

height.

Generic Writer: (setf height) (object)
Package

terrable.

Methods
Writer Method: (setf height) ((terrain terrain))

automatically generated writer method

Source

terrable.lisp.

Target Slot

height.

Generic Reader: height-base (object)

Returns the base height of the terrain.

This height should be added to all points in the data terrain.

See TERRAIN

Package

terrable.

Methods
Reader Method: height-base ((terrain terrain))

automatically generated reader method

Source

terrable.lisp.

Target Slot

height-base.

Generic Writer: (setf height-base) (object)
Package

terrable.

Methods
Writer Method: (setf height-base) ((terrain terrain))

automatically generated writer method

Source

terrable.lisp.

Target Slot

height-base.

Generic Reader: height-scale (object)

Returns the height scaling factor of the terrain.

This factor should be multiplied with all points in the data terrain after HEIGHT-BASE has been added to receive a height that is properly scaled.

See TERRAIN
See HEIGHT-BASE

Package

terrable.

Methods
Reader Method: height-scale ((terrain terrain))

automatically generated reader method

Source

terrable.lisp.

Target Slot

height-scale.

Generic Writer: (setf height-scale) (object)
Package

terrable.

Methods
Writer Method: (setf height-scale) ((terrain terrain))

automatically generated writer method

Source

terrable.lisp.

Target Slot

height-scale.

Generic Function: read-terrain (input)

Parses the given thing as a Terragen terrain.

Returns the complete TERRAIN instance if successful. This function will signal conditions of type TERRABLE-CONDITION should problems occur while parsing the format.

The input can be either a FAST-IO:INPUT-BUFFER, a STREAM, a PATHNAME, a STRING, or a VECTOR with (UNSIGNED-BYTE 8) element-type.

See TERRAIN
See TERRABLE-CONDITION
See INVALID-HEADER
See UNKNOWN-CHUNK-TYPE
See UNKNOWN-CURVATURE-TYPE

Package

terrable.

Source

terrable.lisp.

Methods
Method: read-terrain ((vector vector))
Method: read-terrain ((string string))
Method: read-terrain ((pathname pathname))
Method: read-terrain ((stream stream))
Method: read-terrain ((buffer input-buffer))
Generic Reader: scale (object)

Returns the scaling factors to turn pixel coordinates into real-world units.

This is a list of three floats (X, Y, Z), each of which represent
the number of pixel units in that direction represent a metre.
The default is (30 30 30), meaning 30 pixels in any direction for a metre.

See TERRAIN

Package

terrable.

Methods
Reader Method: scale ((terrain terrain))

automatically generated reader method

Source

terrable.lisp.

Target Slot

scale.

Generic Writer: (setf scale) (object)
Package

terrable.

Methods
Writer Method: (setf scale) ((terrain terrain))

automatically generated writer method

Source

terrable.lisp.

Target Slot

scale.

Generic Reader: stream-position (condition)

Returns the fast-io buffer/stream’s position at which the problem occurred.

See TERRABLE-CONDITION

Package

terrable.

Methods
Reader Method: stream-position ((condition terrable-condition))
Source

terrable.lisp.

Target Slot

position.

Generic Reader: width (object)

Returns the width (in pixels) of the terrain.

See TERRAIN

Package

terrable.

Methods
Reader Method: width ((terrain terrain))

automatically generated reader method

Source

terrable.lisp.

Target Slot

width.

Generic Writer: (setf width) (object)
Package

terrable.

Methods
Writer Method: (setf width) ((terrain terrain))

automatically generated writer method

Source

terrable.lisp.

Target Slot

width.

Generic Function: write-terrain (terrain output)

Writes the given terrain object to a Terragen TER format.

The input can either be a FAST-IO:OUTPUT-BUFFER, a STREAM, a PATHNAME, the keyword :VECTOR, or the keyword :STATIC. In the latter two cases, a vector with the written output is returned. In the case of a pathname, an error is signalled if the file already exists.

See TERRAIN

Package

terrable.

Source

terrable.lisp.

Methods
Method: write-terrain (terrain (output symbol))
Method: write-terrain (terrain (pathname pathname))
Method: write-terrain (terrain (stream stream))
Method: write-terrain ((terrain terrain) (buffer output-buffer))

5.1.2 Standalone methods

Method: print-object ((terrain terrain) stream)
Source

terrable.lisp.


5.1.3 Conditions

Condition: invalid-header

Error signalled when the file header is invalid.

See HEADER
See TERRABLE-CONDITION

Package

terrable.

Source

terrable.lisp.

Direct superclasses
Direct methods

header.

Direct slots
Slot: header
Initargs

:header

Readers

header.

Writers

This slot is read-only.

Condition: terrable-condition

Base condition for all problems related to Terragen files.

See STREAM-POSITION

Package

terrable.

Source

terrable.lisp.

Direct superclasses

condition.

Direct subclasses
Direct methods

stream-position.

Direct slots
Slot: position
Package

common-lisp.

Initargs

:position

Readers

stream-position.

Writers

This slot is read-only.

Condition: unknown-chunk-type

Warning signalled when an unknown chunk type is encountered.

Since an unknown chunk type cannot be read, it is very likely that the rest of the file will be read as garbage as well and the read won’t succeed.

See CHUNK-TYPE
See TERRABLE-CONDITION

Package

terrable.

Source

terrable.lisp.

Direct superclasses
Direct methods

chunk-type.

Direct slots
Slot: chunk-type
Initargs

:chunk-type

Readers

chunk-type.

Writers

This slot is read-only.

Condition: unknown-curvature-type

Warning signalled when an unknown curvature type is encountered.

The curvature type is stored in its integer form in the TERRAIN instance’s CURVE-MODE slot.

See CURVATURE-TYPE
See TERRABLE-CONDITION

Package

terrable.

Source

terrable.lisp.

Direct superclasses
Direct methods

curvature-type.

Direct slots
Slot: curvature-type
Initargs

:curvature-type

Readers

curvature-type.

Writers

This slot is read-only.


5.1.4 Classes

Class: terrain

Container for all data read from a Terragen terrain file.

If some data is not explicitly provided by the terrain file, the slots will contain default values.

WARNING: When a TERRAIN instance is garbage-collected, its DATA vector is automatically deallocated with it. If you keep foreign references to the data, or reference it somewhere else, you will need to keep a reference to the TERRAIN instance around as well, copy the contents of the data vector elsewhere, or call TG:CANCEL-FINALIZATION on the TERRAIN instance to get rid of its automatic deallocation behaviour. If you would like to manually free the terrain instantly, use FREE-TERRAIN.

See WIDTH
See HEIGHT
See SCALE
See CURVE-RADIUS
See CURVE-MODE
See HEIGHT-BASE
See HEIGHT-SCALE
See DATA
See READ-TERRAIN
See FREE-TERRAIN

Package

terrable.

Source

terrable.lisp.

Direct methods
Direct slots
Slot: width
Readers

width.

Writers

(setf width).

Slot: height
Readers

height.

Writers

(setf height).

Slot: scale
Initform

(list 30 30 30)

Readers

scale.

Writers

(setf scale).

Slot: curve-radius
Initform

6370.0

Readers

curve-radius.

Writers

(setf curve-radius).

Slot: curve-mode
Initform

:flat

Readers

curve-mode.

Writers

(setf curve-mode).

Slot: height-base
Initform

0

Readers

height-base.

Writers

(setf height-base).

Slot: height-scale
Initform

1.0

Readers

height-scale.

Writers

(setf height-scale).

Slot: data
Readers

data.

Writers

(setf data).


5.2 Internals


5.2.1 Ordinary functions

Function: check-header (buffer marker expected)
Package

terrable.

Source

terrable.lisp.

Function: read-buffer (buffer)
Package

terrable.

Source

terrable.lisp.

Function: read-chunk (buffer marker terrain)
Package

terrable.

Source

terrable.lisp.

Function: read-marker (buffer marker &key start end)
Package

terrable.

Source

terrable.lisp.

Function: write-buffer (buffer terrain)
Package

terrable.

Source

terrable.lisp.

Function: write-marker (buffer marker)
Package

terrable.

Source

terrable.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
C   D   F   G   H   M   P   R   S   W  
Index Entry  Section

(
(setf curve-mode): Public generic functions
(setf curve-mode): Public generic functions
(setf curve-radius): Public generic functions
(setf curve-radius): Public generic functions
(setf data): Public generic functions
(setf data): Public generic functions
(setf height): Public generic functions
(setf height): Public generic functions
(setf height-base): Public generic functions
(setf height-base): Public generic functions
(setf height-scale): Public generic functions
(setf height-scale): Public generic functions
(setf scale): Public generic functions
(setf scale): Public generic functions
(setf width): Public generic functions
(setf width): Public generic functions

C
check-header: Private ordinary functions
chunk-type: Public generic functions
chunk-type: Public generic functions
curvature-type: Public generic functions
curvature-type: Public generic functions
curve-mode: Public generic functions
curve-mode: Public generic functions
curve-radius: Public generic functions
curve-radius: Public generic functions

D
data: Public generic functions
data: Public generic functions

F
free-terrain: Public generic functions
free-terrain: Public generic functions
Function, check-header: Private ordinary functions
Function, read-buffer: Private ordinary functions
Function, read-chunk: Private ordinary functions
Function, read-marker: Private ordinary functions
Function, write-buffer: Private ordinary functions
Function, write-marker: Private ordinary functions

G
Generic Function, (setf curve-mode): Public generic functions
Generic Function, (setf curve-radius): Public generic functions
Generic Function, (setf data): Public generic functions
Generic Function, (setf height): Public generic functions
Generic Function, (setf height-base): Public generic functions
Generic Function, (setf height-scale): Public generic functions
Generic Function, (setf scale): Public generic functions
Generic Function, (setf width): Public generic functions
Generic Function, chunk-type: Public generic functions
Generic Function, curvature-type: Public generic functions
Generic Function, curve-mode: Public generic functions
Generic Function, curve-radius: Public generic functions
Generic Function, data: Public generic functions
Generic Function, free-terrain: Public generic functions
Generic Function, header: Public generic functions
Generic Function, height: Public generic functions
Generic Function, height-base: Public generic functions
Generic Function, height-scale: Public generic functions
Generic Function, read-terrain: Public generic functions
Generic Function, scale: Public generic functions
Generic Function, stream-position: Public generic functions
Generic Function, width: Public generic functions
Generic Function, write-terrain: Public generic functions

H
header: Public generic functions
header: Public generic functions
height: Public generic functions
height: Public generic functions
height-base: Public generic functions
height-base: Public generic functions
height-scale: Public generic functions
height-scale: Public generic functions

M
Method, (setf curve-mode): Public generic functions
Method, (setf curve-radius): Public generic functions
Method, (setf data): Public generic functions
Method, (setf height): Public generic functions
Method, (setf height-base): Public generic functions
Method, (setf height-scale): Public generic functions
Method, (setf scale): Public generic functions
Method, (setf width): Public generic functions
Method, chunk-type: Public generic functions
Method, curvature-type: Public generic functions
Method, curve-mode: Public generic functions
Method, curve-radius: Public generic functions
Method, data: Public generic functions
Method, free-terrain: Public generic functions
Method, header: Public generic functions
Method, height: Public generic functions
Method, height-base: Public generic functions
Method, height-scale: Public generic functions
Method, print-object: Public standalone methods
Method, read-terrain: Public generic functions
Method, read-terrain: Public generic functions
Method, read-terrain: Public generic functions
Method, read-terrain: Public generic functions
Method, read-terrain: Public generic functions
Method, scale: Public generic functions
Method, stream-position: Public generic functions
Method, width: Public generic functions
Method, write-terrain: Public generic functions
Method, write-terrain: Public generic functions
Method, write-terrain: Public generic functions
Method, write-terrain: Public generic functions

P
print-object: Public standalone methods

R
read-buffer: Private ordinary functions
read-chunk: Private ordinary functions
read-marker: Private ordinary functions
read-terrain: Public generic functions
read-terrain: Public generic functions
read-terrain: Public generic functions
read-terrain: Public generic functions
read-terrain: Public generic functions
read-terrain: Public generic functions

S
scale: Public generic functions
scale: Public generic functions
stream-position: Public generic functions
stream-position: Public generic functions

W
width: Public generic functions
width: Public generic functions
write-buffer: Private ordinary functions
write-marker: Private ordinary functions
write-terrain: Public generic functions
write-terrain: Public generic functions
write-terrain: Public generic functions
write-terrain: Public generic functions
write-terrain: Public generic functions