bsp

Documentation

Overview

Package bsp loads Quake BSP files.

QPov

Copyright (C) Thomas Habets <thomas@habets.se> 2015 https://github.com/ThomasHabets/qpov

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

References: * https://developer.valvesoftware.com/wiki/Source_BSP_File_Format * http://www.gamers.org/dEngine/quake/spec/quake-spec34/qkspec_4.htm * http://www.gamers.org/dEngine/quake/QDP/qmapspec.html

Index

• Constants
• Variables
• func ModelMacroPrefix(s string) string
• type BSP
  • func Load(r myReader) (*BSP, error)
  • func (bsp *BSP) POVLights() string
  • func (bsp *BSP) POVTriangleMesh(prefix string, withTextures bool, flatColor string) (string, error)
• type Entity
• type Polygon
• type Raw
  • func LoadRaw(r myReader) (*Raw, error)
• type RawEdge
• type RawFace
• type RawHeader
• type RawMipTex
  • func (f *RawMipTex) Name() string
• type RawModel
• type RawTexInfo
• type Vertex
  • func (v *Vertex) DotProduct(w Vertex) float64
  • func (v *Vertex) String() string
  • func (v *Vertex) Sub(w Vertex) *Vertex

Constants

const (

	// BSP file version.
	Version = 29
)

Variables

var (
	Verbose = false
)

Functions

func ModelMacroPrefix

func ModelMacroPrefix(s string) string

ModelMacroPrefix returns the model macro prefix for a given model filename.

Types

type BSP

type BSP struct {
	Raw *Raw
}

func Load

func Load(r myReader) (*BSP, error)

Load loads a BSP model (map) from something that reads and seeks.

func (*BSP) POVLights

func (bsp *BSP) POVLights() string

POVLights returns the static light sources in a BSP, in POV-Ray format.

func (*BSP) POVTriangleMesh

func (bsp *BSP) POVTriangleMesh(prefix string, withTextures bool, flatColor string) (string, error)

POVTriangleMesh returns the triangle mesh of the BSP as macros starting with the prefix given. One BSP can contain multiple models. If withTextures is false, everything will be flatshaded with the flatColor.

type Entity

type Entity struct {
	EntityID int
	Data     map[string]string
	Pos      Vertex
	Angle    Vertex
	Frame    uint8
}

type Polygon

type Polygon struct {
	Texture string
	Vertex  []Vertex
}

type Raw

type Raw struct {
	Header     RawHeader
	Vertex     []Vertex
	Face       []RawFace     // Polygons.
	MipTex     []RawMipTex   // Texture metadata.
	MipTexData []image.Image // Textures.
	Entities   []Entity      // Player start point, weapons, enemies, ...
	Edge       []RawEdge     // Connections between vertices.
	LEdge      []int32       // Connect faces with edges.
	TexInfo    []RawTexInfo  // How to apply a miptex to a face.
	Models     []RawModel    // Parts of geometry. For levels 0 is everything non-movable.
}

Raw is the raw BSP file data.

Well, it's slightly parsed, such as textures being turned into image.Image objects. But indirections such as Face->LEdge->Edge->Vertex are not removed.

func LoadRaw

func LoadRaw(r myReader) (*Raw, error)

LoadRaw loads a BSP file, doing minimal parsing.

type RawEdge

type RawEdge struct {
	From uint16
	To   uint16
}

A RawEdge is the edge of one or more polygons in the file. From and To are indices in the vertex table. Edges are not referenced directly from polygons, only via LEdges.

type RawFace

type RawFace struct {
	PlaneID   uint16
	Side      uint16 // 0 if in front of the plane. This doesn't appear to be needed.
	LEdge     uint32 // First LEdge (see "RawLEdge" for more info).
	LEdgeNum  uint16 // Number of LEdges.
	TexinfoID uint16 // Texture information.

	// 0 = normal light map.
	// 1 = fast pulse.
	// 2 = slow pulse.
	// 3-10 = other light effects.
	// 0xff = no light map
	LightType uint8

	LightBase uint8 // 0xff = dark, 0 = bright.
	Light     [2]uint8
	Lightmap  uint32 // File offset
}

A RawFace is a polygon as it appears in the BSP file.

type RawHeader

type RawHeader struct {
	Version   uint32 // 29 (const Version)
	Entities  dentry // Entities (lights, start points, weapons, enemies...)
	Planes    dentry
	Miptex    dentry // Textures.
	Vertices  dentry
	Visilist  dentry // PVS.
	Nodes     dentry // BSP nodes.
	TexInfo   dentry // How to apply a miptex to a face.
	Faces     dentry // Polygons.
	Lightmaps dentry
	Clipnodes dentry
	Leaves    dentry // BSP leaves.
	Lface     dentry // List of faces. Used for BSP.
	Edges     dentry
	LEdges    dentry
	Models    dentry // See RawModel comment.
}

RawHeader is the first thing in the file.

type RawMipTex

type RawMipTex struct {
	NameBytes [16]byte // Name of the texture.
	Width     uint32   // Width of picture, must be a multiple of 8
	Height    uint32   // Height of picture, must be a multiple of 8
	Offset1   uint32   // Offset to full scale texture.
	Offset2   uint32   // Offset to 1/2 scale texture.
	Offset4   uint32   // Offset to 1/4 scale texture.
	Offset8   uint32   // Offset to 1/8 scale texture.
}

A RawMipTex is the metadata about a texture. Textures are stored four times. One in original size, and three precalculated downsamples. Offsets are relative to where the current MipTex structure, not to beginning of file, beginning of texture area, or anything else sane. The textures are probably right after the miptex metadata (meaning Offset1 is 40), but it's not guaranteed.

func (*RawMipTex) Name

func (f *RawMipTex) Name() string

Name returns the string representation of the ASCIIZ name. This is not put in RawMipTex because the struct must be fixed size.

type RawModel

type RawModel struct {
	BoundBoxMin, BoundBoxMax Vertex // The bounding box of the Model.
	Origin                   Vertex // Origin of model, usually (0,0,0).
	NodeID0                  uint32 // Index of first BSP node.
	NodeID1                  uint32 // Index of the first Clip node.
	NodeID2                  uint32 // Index of the second Clip node.
	NodeID3                  uint32 // Usually zero.
	NumLeafs                 uint32 // Number of BSP leaves.
	FaceID                   uint32 // Index of Faces
	FaceNum                  uint32 // Number of faces.
}

A RawModel is the model definition of a some polygons. Most of level is in model 0. Others are doors and other movables.

Models from BSP files show up in game as entities with model name "*N", where N is the index into this .bsp table.

type RawTexInfo

type RawTexInfo struct {
	VectorS   Vertex  // S vector, horizontal in texture space.
	DistS     float32 // Horizontal offset in texture space
	VectorT   Vertex  // T vector, vertical in texture space.
	DistT     float32 // Vertical offset in texture space
	TextureID uint32  // Index of Mip Texture must be in [0,numtex[
	Animated  uint32  // 0 for ordinary textures, 1 for water, etc.
}

A RawTexInfo is information about how to apply a texture (MipTex) onto a polygon. Texture coordinates are not attached to vertices directly and interpolated in 2D space, but are instead calculated by mapping world 3D coordinates onto the polygon plane.

The polygon plane is defined here in the TexInfo by the two vectors VectorS and VectorT, which is strange since the RawFace already points to the plane definition that would reconstruct the vectors. DistS and DistT is used to align the texture (slide it around in the plane).

A vertex's texture coordinates can be obtained with:

s = (v dot VectorS) + distS
t = (v dot VectorT) + distT

I guess it's more space efficient to calculate s&t as needed from the texinfo rather than to store it with the LEdges, and that's why.

type Vertex

type Vertex struct {
	X, Y, Z float32
}

func (*Vertex) DotProduct

func (v *Vertex) DotProduct(w Vertex) float64

func (*Vertex) String

func (v *Vertex) String() string

func (*Vertex) Sub

func (v *Vertex) Sub(w Vertex) *Vertex