The terrable Reference Manual

Table of Contents

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

The terrable Reference Manual

This is the terrable Reference Manual, version 1.0.0, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Jul 29 16:46:05 2019 GMT+0.


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

1 Introduction

About Terrable

Terrable implements a parser for the Terragen terrain file format (.TER). You can find a format reference here.

How To

To parse a file, you can pass a file, vector, or fast-io buffer to read-terrain.

(terrable:read-terrain #p"~/heightmap.ter")

If everything goes well, you should have a fresh terrain instance with width, height, scale, curve-radius, curve-mode, height-base, height-scale, and data slots all filled out for you. The data is parsed as a static-vector, meaning it is directly passable to C libraries like OpenGL for further processing.

(gl:tex-image-2d :texture-2d 0 :R16I (terrable:width *) (terrable:height *) 0 :RED-INTEGER :SHORT
                 (static-vectors:static-vector-pointer (terrable:data *)))

And that's it. Note that finalizers are used to automatically deallocate the data array when the terrain instance is garbage collected. If you want to manually free the terrain data instantly, you can use free-terrain.

(terrable:free-terrain **)

Finally, if you would like to generate terrain files, you can simply call write-terrain on a complete Terrain object. It'll write out all known chunks to the file, even if they might be superfluous.


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 terrable

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://github.com/Shirakumo/terrable

License

zlib

Description

Terragen TER file format reader

Version

1.0.0

Dependencies
Source

terrable.asd (file)

Components

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

3 Files

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


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

3.1 Lisp


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

3.1.1 terrable.asd

Location

terrable.asd

Systems

terrable (system)


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

3.1.2 terrable/package.lisp

Parent

terrable (system)

Location

package.lisp

Packages

terrable


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

3.1.3 terrable/terrable.lisp

Dependency

package.lisp (file)

Parent

terrable (system)

Location

terrable.lisp

Exported Definitions
Internal Definitions

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

3.1.4 terrable/documentation.lisp

Dependency

terrable.lisp (file)

Parent

terrable (system)

Location

documentation.lisp


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

4 Packages

Packages are listed by definition order.


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

4.1 terrable

Source

package.lisp (file)

Nickname

org.shirakumo.fraf.terrable

Use List

common-lisp

Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Generic functions

Generic Function: chunk-type CONDITION

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

See UNKNOWN-CHUNK-TYPE

Package

terrable

Methods
Method: chunk-type (CONDITION unknown-chunk-type)
Source

terrable.lisp (file)

Generic Function: curvature-type CONDITION

Returns the unknown curvature type.

See UNKNOWN-CURVATURE-TYPE

Package

terrable

Methods
Method: curvature-type (CONDITION unknown-curvature-type)
Source

terrable.lisp (file)

Generic Function: 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

Writer

(setf curve-mode) (generic function)

Methods
Method: curve-mode (TERRAIN terrain)

automatically generated reader method

Source

terrable.lisp (file)

Generic Function: (setf curve-mode) NEW-VALUE OBJECT
Package

terrable

Reader

curve-mode (generic function)

Methods
Method: (setf curve-mode) NEW-VALUE (TERRAIN terrain)

automatically generated writer method

Source

terrable.lisp (file)

Generic Function: 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

Writer

(setf curve-radius) (generic function)

Methods
Method: curve-radius (TERRAIN terrain)

automatically generated reader method

Source

terrable.lisp (file)

Generic Function: (setf curve-radius) NEW-VALUE OBJECT
Package

terrable

Reader

curve-radius (generic function)

Methods
Method: (setf curve-radius) NEW-VALUE (TERRAIN terrain)

automatically generated writer method

Source

terrable.lisp (file)

Generic Function: 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

Writer

(setf data) (generic function)

Methods
Method: data (TERRAIN terrain)

automatically generated reader method

Source

terrable.lisp (file)

Generic Function: (setf data) NEW-VALUE OBJECT
Package

terrable

Reader

data (generic function)

Methods
Method: (setf data) NEW-VALUE (TERRAIN terrain)

automatically generated writer method

Source

terrable.lisp (file)

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 (file)

Generic Function: header CONDITION

Returns the offending header that did not match.

See INVALID-HEADER

Package

terrable

Methods
Method: header (CONDITION invalid-header)
Source

terrable.lisp (file)

Generic Function: height OBJECT

Returns the height (in pixels) of the terrain.

See TERRAIN

Package

terrable

Writer

(setf height) (generic function)

Methods
Method: height (TERRAIN terrain)

automatically generated reader method

Source

terrable.lisp (file)

Generic Function: (setf height) NEW-VALUE OBJECT
Package

terrable

Reader

height (generic function)

Methods
Method: (setf height) NEW-VALUE (TERRAIN terrain)

automatically generated writer method

Source

terrable.lisp (file)

Generic Function: 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

Writer

(setf height-base) (generic function)

Methods
Method: height-base (TERRAIN terrain)

automatically generated reader method

Source

terrable.lisp (file)

Generic Function: (setf height-base) NEW-VALUE OBJECT
Package

terrable

Reader

height-base (generic function)

Methods
Method: (setf height-base) NEW-VALUE (TERRAIN terrain)

automatically generated writer method

Source

terrable.lisp (file)

Generic Function: 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

Writer

(setf height-scale) (generic function)

Methods
Method: height-scale (TERRAIN terrain)

automatically generated reader method

Source

terrable.lisp (file)

Generic Function: (setf height-scale) NEW-VALUE OBJECT
Package

terrable

Reader

height-scale (generic function)

Methods
Method: (setf height-scale) NEW-VALUE (TERRAIN terrain)

automatically generated writer method

Source

terrable.lisp (file)

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 (file)

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 Function: 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

Writer

(setf scale) (generic function)

Methods
Method: scale (TERRAIN terrain)

automatically generated reader method

Source

terrable.lisp (file)

Generic Function: (setf scale) NEW-VALUE OBJECT
Package

terrable

Reader

scale (generic function)

Methods
Method: (setf scale) NEW-VALUE (TERRAIN terrain)

automatically generated writer method

Source

terrable.lisp (file)

Generic Function: stream-position CONDITION

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

See TERRABLE-CONDITION

Package

terrable

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

terrable.lisp (file)

Generic Function: width OBJECT

Returns the width (in pixels) of the terrain.

See TERRAIN

Package

terrable

Writer

(setf width) (generic function)

Methods
Method: width (TERRAIN terrain)

automatically generated reader method

Source

terrable.lisp (file)

Generic Function: (setf width) NEW-VALUE OBJECT
Package

terrable

Reader

width (generic function)

Methods
Method: (setf width) NEW-VALUE (TERRAIN terrain)

automatically generated writer method

Source

terrable.lisp (file)

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 (file)

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)

Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Conditions

Condition: invalid-header ()

Error signalled when the file header is invalid.

See HEADER
See TERRABLE-CONDITION

Package

terrable

Source

terrable.lisp (file)

Direct superclasses
Direct methods

header (method)

Direct slots
Slot: header
Initargs

:header

Readers

header (generic function)

Condition: terrable-condition ()

Base condition for all problems related to Terragen files.

See STREAM-POSITION

Package

terrable

Source

terrable.lisp (file)

Direct superclasses

condition (condition)

Direct subclasses
Direct methods

stream-position (method)

Direct slots
Slot: position
Initargs

:position

Readers

stream-position (generic function)

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 (file)

Direct superclasses
Direct methods

chunk-type (method)

Direct slots
Slot: chunk-type
Initargs

:chunk-type

Readers

chunk-type (generic function)

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 (file)

Direct superclasses
Direct methods

curvature-type (method)

Direct slots
Slot: curvature-type
Initargs

:curvature-type

Readers

curvature-type (generic function)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 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 (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: width
Readers

width (generic function)

Writers

(setf width) (generic function)

Slot: height
Readers

height (generic function)

Writers

(setf height) (generic function)

Slot: scale
Initform

(list 30 30 30)

Readers

scale (generic function)

Writers

(setf scale) (generic function)

Slot: curve-radius
Initform

6370.0

Readers

curve-radius (generic function)

Writers

(setf curve-radius) (generic function)

Slot: curve-mode
Initform

:flat

Readers

curve-mode (generic function)

Writers

(setf curve-mode) (generic function)

Slot: height-base
Initform

0

Readers

height-base (generic function)

Writers

(setf height-base) (generic function)

Slot: height-scale
Initform

1.0

Readers

height-scale (generic function)

Writers

(setf height-scale) (generic function)

Slot: data
Readers

data (generic function)

Writers

(setf data) (generic function)


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

5.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: check-header BUFFER MARKER EXPECTED
Package

terrable

Source

terrable.lisp (file)

Function: read-buffer BUFFER
Package

terrable

Source

terrable.lisp (file)

Function: read-chunk BUFFER MARKER TERRAIN
Package

terrable

Source

terrable.lisp (file)

Function: read-marker BUFFER MARKER &key START END
Package

terrable

Source

terrable.lisp (file)

Function: write-buffer BUFFER TERRAIN
Package

terrable

Source

terrable.lisp (file)

Function: write-marker BUFFER MARKER
Package

terrable

Source

terrable.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   T  
Index Entry  Section

F
File, Lisp, terrable.asd: The terrable<dot>asd file
File, Lisp, terrable/documentation.lisp: The terrable/documentation<dot>lisp file
File, Lisp, terrable/package.lisp: The terrable/package<dot>lisp file
File, Lisp, terrable/terrable.lisp: The terrable/terrable<dot>lisp file

L
Lisp File, terrable.asd: The terrable<dot>asd file
Lisp File, terrable/documentation.lisp: The terrable/documentation<dot>lisp file
Lisp File, terrable/package.lisp: The terrable/package<dot>lisp file
Lisp File, terrable/terrable.lisp: The terrable/terrable<dot>lisp file

T
terrable.asd: The terrable<dot>asd file
terrable/documentation.lisp: The terrable/documentation<dot>lisp file
terrable/package.lisp: The terrable/package<dot>lisp file
terrable/terrable.lisp: The terrable/terrable<dot>lisp file

Jump to:   F   L   T  

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

A.2 Functions

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

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

C
check-header: Internal functions
chunk-type: Exported generic functions
chunk-type: Exported generic functions
curvature-type: Exported generic functions
curvature-type: Exported generic functions
curve-mode: Exported generic functions
curve-mode: Exported generic functions
curve-radius: Exported generic functions
curve-radius: Exported generic functions

D
data: Exported generic functions
data: Exported generic functions

F
free-terrain: Exported generic functions
free-terrain: Exported generic functions
Function, check-header: Internal functions
Function, read-buffer: Internal functions
Function, read-chunk: Internal functions
Function, read-marker: Internal functions
Function, write-buffer: Internal functions
Function, write-marker: Internal functions

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

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

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

R
read-buffer: Internal functions
read-chunk: Internal functions
read-marker: Internal functions
read-terrain: Exported generic functions
read-terrain: Exported generic functions
read-terrain: Exported generic functions
read-terrain: Exported generic functions
read-terrain: Exported generic functions
read-terrain: Exported generic functions

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

W
width: Exported generic functions
width: Exported generic functions
write-buffer: Internal functions
write-marker: Internal functions
write-terrain: Exported generic functions
write-terrain: Exported generic functions
write-terrain: Exported generic functions
write-terrain: Exported generic functions
write-terrain: Exported generic functions

Jump to:   (  
C   D   F   G   H   M   R   S   W  

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

A.3 Variables

Jump to:   C   D   H   P   S   W  
Index Entry  Section

C
chunk-type: Exported conditions
curvature-type: Exported conditions
curve-mode: Exported classes
curve-radius: Exported classes

D
data: Exported classes

H
header: Exported conditions
height: Exported classes
height-base: Exported classes
height-scale: Exported classes

P
position: Exported conditions

S
scale: Exported classes
Slot, chunk-type: Exported conditions
Slot, curvature-type: Exported conditions
Slot, curve-mode: Exported classes
Slot, curve-radius: Exported classes
Slot, data: Exported classes
Slot, header: Exported conditions
Slot, height: Exported classes
Slot, height-base: Exported classes
Slot, height-scale: Exported classes
Slot, position: Exported conditions
Slot, scale: Exported classes
Slot, width: Exported classes

W
width: Exported classes

Jump to:   C   D   H   P   S   W  

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

A.4 Data types

Jump to:   C   I   P   S   T   U  
Index Entry  Section

C
Class, terrain: Exported classes
Condition, invalid-header: Exported conditions
Condition, terrable-condition: Exported conditions
Condition, unknown-chunk-type: Exported conditions
Condition, unknown-curvature-type: Exported conditions

I
invalid-header: Exported conditions

P
Package, terrable: The terrable package

S
System, terrable: The terrable system

T
terrable: The terrable system
terrable: The terrable package
terrable-condition: Exported conditions
terrain: Exported classes

U
unknown-chunk-type: Exported conditions
unknown-curvature-type: Exported conditions

Jump to:   C   I   P   S   T   U