objects3d

Documentation

Overview

Package objects3d implements reading of Total Annihilation 3DO model files.

3DO files contain hierarchical 3D objects with vertices, primitives (points, lines, triangles, quads), and texture references.

Index

• type FillOptions
• type FillStats
  • func FillModel(m *Model, opts FillOptions) FillStats
• type Material
• type Model
  • func LoadFromReader(r io.ReadSeeker) (*Model, error)
  • func (m *Model) RenderImage(opts RenderOptions) *image.RGBA
  • func (m *Model) RenderPNG(opts RenderOptions) ([]byte, error)
  • func (m *Model) RenderSpinAPNG(opts RenderOptions, frames, delayMs int) ([]byte, error)
  • func (m *Model) Textures() []string
  • func (m *Model) TotalPrimitives() int
  • func (m *Model) TotalVertices() int
• type Object
• type Primitive
• type RenderOptions
  • func DefaultRenderOptions() RenderOptions
• type Vertex

Types

type FillOptions

type FillOptions struct {
	// MaxLoopVertices skips boundary loops longer than this to avoid
	// capping large, intentionally-open shapes (e.g. a tube). Zero means
	// no limit.
	MaxLoopVertices int
	// PlanarTolerance is the maximum distance (in fixed-point world units)
	// any loop vertex may sit from the loop's best-fit plane before the
	// loop is filled with a centroid fan instead of an ear-clipped cap.
	// Zero falls back to a sensible default.
	PlanarTolerance float64
}

FillOptions controls how missing faces are reconstructed.

type FillStats

type FillStats struct {
	ObjectsTouched int
	LoopsFilled    int
	FacesAdded     int
	VerticesAdded  int
}

FillStats summarises the work done by FillModel.

func FillModel

func FillModel(m *Model, opts FillOptions) FillStats

FillModel reconstructs faces that TA's artists deleted as a fill-rate optimisation. For every object it finds the loops of boundary edges (edges used by exactly one face) that border a hole and caps each loop with synthetic triangles. This closes open box bottoms and makes lone single-sided sheets solid from both sides. The model is modified in place; added primitives carry Synthetic=true.

type Material

type Material interface {
	// Texture returns the decoded texture image for a 3DO texture name.
	Texture(name string) (*image.RGBA, bool)
	// PaletteColor returns the RGBA for a colour-keyed primitive's index.
	PaletteColor(index int) (color.RGBA, bool)
}

Material supplies surface appearance for a 3DO primitive, backed by the host's asset store (GAF textures + palette). The rasteriser stays VFS/GAF-agnostic; this is the boundary the studio implements against its session.

type Model

type Model struct {
	Root       *Object
	AllObjects []*Object // flattened list of all objects
}

Model is the root of a parsed 3DO file.

func LoadFromReader

func LoadFromReader(r io.ReadSeeker) (*Model, error)

LoadFromReader parses a 3DO file.

func (*Model) RenderImage

func (m *Model) RenderImage(opts RenderOptions) *image.RGBA

RenderImage rasterises a single still at the configured angle.

func (*Model) RenderPNG

func (m *Model) RenderPNG(opts RenderOptions) ([]byte, error)

RenderPNG rasterises a single still and returns PNG bytes.

func (*Model) RenderSpinAPNG

func (m *Model) RenderSpinAPNG(opts RenderOptions, frames, delayMs int) ([]byte, error)

RenderSpinAPNG renders an N-frame 360° spin about the model centre as a truecolor animated PNG. Uses the SAME scale/centre as RenderImage so hovering from the still into the spin doesn't jump. Falls back to a still when n<=1.

func (*Model) Textures

func (m *Model) Textures() []string

Textures returns the unique texture names used across all objects.

func (*Model) TotalPrimitives

func (m *Model) TotalPrimitives() int

TotalPrimitives returns the total primitive count across all objects.

func (*Model) TotalVertices

func (m *Model) TotalVertices() int

TotalVertices returns the total vertex count across all objects.

type Object

type Object struct {
	Name          string
	Vertices      []Vertex
	Primitives    []Primitive
	XFromParent   int32
	YFromParent   int32
	ZFromParent   int32
	SelectionPrim int32
	Children      []*Object
}

Object is a node in the 3DO hierarchy.

type Primitive

type Primitive struct {
	ColorIndex    int
	VertexIndices []int
	TextureName   string
	IsColored     bool
	// Synthetic marks primitives that were not present in the source file
	// but were generated to close gaps left by deleted faces. It is never
	// set by the loader; only FillModel produces synthetic primitives.
	Synthetic bool
}

Primitive is a rendered face/line/point.

type RenderOptions

type RenderOptions struct {
	Width, Height int
	AzimuthDeg    float64 // rotation about the vertical (Y) axis
	ElevationDeg  float64 // tilt about X; 90 = straight down, 0 = side-on
	Margin        float64 // padding as a fraction of the image (0..0.5)
	Ambient       float64 // ambient light floor (0..1)
	Gain          float64 // brightness multiplier applied after shading
	LightDir      [3]float64
	Background    color.Color // nil = transparent
	Base          color.Color // fallback colour for untextured/unresolved faces
	Material      Material    // optional texture/palette source
	// FitToFrame scales the model to fill the frame (for large hover previews)
	// instead of rendering at true scale.
	FitToFrame bool
	// UnitsPerPixel is the true 3DO-units-per-output-pixel scale (TA native is
	// 65536 units = 1px = 1/16th of a tile). Models render at this true scale,
	// shrinking only if they would otherwise overflow the frame.
	UnitsPerPixel float64
}

RenderOptions controls how a 3DO model is rasterised. Defaults give a TA-style steep top-down view at true game scale. Every camera/lighting/scale knob is exposed so snapshot angles can be tuned without touching the rasteriser.

func DefaultRenderOptions

func DefaultRenderOptions() RenderOptions

DefaultRenderOptions returns a TA-style steep top-down preview at true scale.

type Vertex

type Vertex struct {
	X, Y, Z int32
}

Vertex is a 3D point (fixed-point integers).