terrable

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

System Information

Definition Index

• TERRABLE

  • ORG.SHIRAKUMO.FRAF.TERRABLE

  Source

  No documentation provided.

  • EXTERNAL CLASS

    TERRAIN

    Source

    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

  • EXTERNAL CONDITION

    INVALID-HEADER

    Source

    Error signalled when the file header is invalid.
    
    See HEADER
    See TERRABLE-CONDITION

  • EXTERNAL CONDITION

    TERRABLE-CONDITION

    Source

    Base condition for all problems related to Terragen files.
    
    See STREAM-POSITION

  • EXTERNAL CONDITION

    UNKNOWN-CHUNK-TYPE

    Source

    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

  • EXTERNAL CONDITION

    UNKNOWN-CURVATURE-TYPE

    Source

    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

  • EXTERNAL GENERIC-FUNCTION

    CHUNK-TYPE

    • CONDITION

    Returns the unknown 4-letter string chunk-type that was encountered.
    
    See UNKNOWN-CHUNK-TYPE

  • EXTERNAL GENERIC-FUNCTION

    CURVATURE-TYPE

    • CONDITION

    Returns the unknown curvature type.
    
    See UNKNOWN-CURVATURE-TYPE

  • EXTERNAL 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

  • EXTERNAL GENERIC-FUNCTION

    (SETF CURVE-MODE)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL 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

  • EXTERNAL GENERIC-FUNCTION

    (SETF CURVE-RADIUS)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL 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

  • EXTERNAL GENERIC-FUNCTION

    (SETF DATA)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL 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

  • EXTERNAL GENERIC-FUNCTION

    HEADER

    • CONDITION

    Returns the offending header that did not match.
    
    See INVALID-HEADER

  • EXTERNAL GENERIC-FUNCTION

    HEIGHT

    • OBJECT

    Returns the height (in pixels) of the terrain.
    
    See TERRAIN

  • EXTERNAL GENERIC-FUNCTION

    (SETF HEIGHT)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL 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

  • EXTERNAL GENERIC-FUNCTION

    (SETF HEIGHT-BASE)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL 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

  • EXTERNAL GENERIC-FUNCTION

    (SETF HEIGHT-SCALE)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    READ-TERRAIN

    • INPUT

    Source

    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

  • EXTERNAL 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

  • EXTERNAL GENERIC-FUNCTION

    (SETF SCALE)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    STREAM-POSITION

    • CONDITION

    Returns the fast-io buffer/stream's position at which the problem occurred.
    
    See TERRABLE-CONDITION

  • EXTERNAL GENERIC-FUNCTION

    WIDTH

    • OBJECT

    Returns the width (in pixels) of the terrain.
    
    See TERRAIN

  • EXTERNAL GENERIC-FUNCTION

    (SETF WIDTH)

    • NEW-VALUE
    • OBJECT

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    WRITE-TERRAIN

    • TERRAIN
    • OUTPUT

    Source

    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