render

package
v0.15.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 10, 2026 License: MIT Imports: 15 Imported by: 21

Documentation

Overview

Package render can be used to render parsed map to image. Currently supports only orthogonal rendering out-of-the-box.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrUnsupportedOrientation represents an error in the unsupported orientation for rendering.
	ErrUnsupportedOrientation = errors.New("tiled/render: unsupported orientation")
	// ErrUnsupportedRenderOrder represents an error in the unsupported order for rendering.
	ErrUnsupportedRenderOrder = errors.New("tiled/render: unsupported render order")

	// ErrOutOfBounds represents an error that the index is out of bounds
	ErrOutOfBounds = errors.New("tiled/render: index out of bounds")
)

Functions

This section is empty.

Types

type HexagonalRendererEngine added in v0.15.0

type HexagonalRendererEngine struct {
	// contains filtered or unexported fields
}

HexagonalRendererEngine represents a hexagonal rendering engine (Tiled's "Hexagonal (Staggered)" map type, orientation="hexagonal"), supporting both pointy-top (StaggerAxis "y") and flat-top (StaggerAxis "x") variants, with an arbitrary HexSideLength and either StaggerIndex. See StaggeredRendererEngine for orientation="staggered" (Tiled's "Isometric (Staggered)" map type), which is not a hexagonal map but shares this same geometry engine.

The geometry below mirrors Tiled's own HexagonalRenderer::RenderParams and tileToScreenCoords/boundingRect exactly (see https://github.com/mapeditor/tiled/blob/master/src/libtiled/hexagonalrenderer.cpp), rather than assuming HexSideLength is always exactly half of TileWidth/TileHeight.

func (*HexagonalRendererEngine) GetFinalImageSize added in v0.15.0

func (e *HexagonalRendererEngine) GetFinalImageSize() image.Rectangle

GetFinalImageSize returns final image size based on map data.

func (*HexagonalRendererEngine) GetObjectAnchor added in v0.15.0

func (e *HexagonalRendererEngine) GetObjectAnchor(imgSize image.Point) image.Point

GetObjectAnchor returns the bottom-left point of a tile object's image. Tiled's default tile-object alignment is bottom-center only for isometric maps; every other orientation, including hexagonal, defaults to bottom-left.

func (*HexagonalRendererEngine) GetTilePosition added in v0.15.0

func (e *HexagonalRendererEngine) GetTilePosition(x, y int, imgSize image.Point) image.Point

GetTilePosition returns tile position in image.

As with the orthogonal/isometric engines, a tile image taller than the map's TileHeight is anchored to the bottom of its (TileHeight-tall) grid cell per the Tiled spec, using imgSize rather than assuming it matches TileHeight.

func (*HexagonalRendererEngine) Init added in v0.15.0

func (e *HexagonalRendererEngine) Init(m *tiled.Map)

Init initializes rendering engine with provided map options.

func (*HexagonalRendererEngine) PixelToScreenCoords added in v0.15.0

func (e *HexagonalRendererEngine) PixelToScreenCoords(x, y float64) (float64, float64)

PixelToScreenCoords returns screen coordinates for a raw object pixel position. Tiled's HexagonalRenderer doesn't project object positions (unlike isometric); they're stored directly in screen pixel space, so this is the identity transform.

func (*HexagonalRendererEngine) RotateTileImage added in v0.15.0

func (e *HexagonalRendererEngine) RotateTileImage(tile *tiled.LayerTile, img image.Image) image.Image

RotateTileImage rotates the provided tile image according to its flip and rotation flags.

Hexagonal tiles don't use the flip-composition order that orthogonal and isometric tiles do (Tiled's own docs note "for hexagonal tiles the order does not matter"); instead, HorizontalFlip/VerticalFlip/DiagonalFlip/ RotatedHexagonal120 combine to select one of the 6 clockwise rotations of a hex tile in 60-degree steps, confirmed via https://discourse.mapeditor.org/t/rotatedhexagonal120/4795:

no flags set                                -> 0
DiagonalFlip                                -> 60
RotatedHexagonal120                         -> 120
HorizontalFlip+VerticalFlip                 -> 180
HorizontalFlip+VerticalFlip+DiagonalFlip    -> 240
HorizontalFlip+VerticalFlip+RotatedHexagonal120 -> 300

Tiled's own hex-rotate editor action only ever produces these 6 combinations; any other combination falls back to applying each flag as an independent flip/rotation, best-effort.

type IsometricRendererEngine added in v0.15.0

type IsometricRendererEngine struct {
	// contains filtered or unexported fields
}

IsometricRendererEngine represents isometric rendering engine.

func (*IsometricRendererEngine) GetFinalImageSize added in v0.15.0

func (e *IsometricRendererEngine) GetFinalImageSize() image.Rectangle

GetFinalImageSize returns final image size based on map data.

func (*IsometricRendererEngine) GetObjectAnchor added in v0.15.0

func (e *IsometricRendererEngine) GetObjectAnchor(imgSize image.Point) image.Point

GetObjectAnchor returns the bottom-center point of a tile object's image, per the Tiled spec's isometric alignment rule.

func (*IsometricRendererEngine) GetTilePosition added in v0.15.0

func (e *IsometricRendererEngine) GetTilePosition(x, y int, imgSize image.Point) image.Point

GetTilePosition returns tile position in image.

The horizontal component matches Tiled's own IsometricRenderer::tileToScreenCoords (shifted left by half a tile width so the image is centered on the diamond grid vertex, as Tiled's drawTileLayer does). The vertical component anchors the image to the bottom of the tile's diamond footprint: imgSize.Y is used rather than assuming it equals the map's TileHeight, so tilesets mixing flat ground tiles with taller wall/structure tiles (of any height) are positioned correctly.

func (*IsometricRendererEngine) Init added in v0.15.0

func (e *IsometricRendererEngine) Init(m *tiled.Map)

Init initializes rendering engine with provided map options.

func (*IsometricRendererEngine) PixelToScreenCoords added in v0.15.0

func (e *IsometricRendererEngine) PixelToScreenCoords(x, y float64) (float64, float64)

PixelToScreenCoords converts a raw object pixel position (as stored in the TMX file) into final screen coordinates, matching Tiled's own IsometricRenderer::pixelToScreenCoords exactly.

Note that x is divided by TileHeight, not TileWidth: Tiled treats an isometric map's unprojected object space as using a square unit cell sized by TileHeight for both axes, and only brings in TileWidth for the final horizontal scaling. This is confirmed by Tiled's own source and its maintainer (see https://discourse.mapeditor.org/t/whats-the-algorithm-of-object-position-in-iso-map/1790).

func (*IsometricRendererEngine) RotateTileImage added in v0.15.0

func (e *IsometricRendererEngine) RotateTileImage(tile *tiled.LayerTile, img image.Image) image.Image

RotateTileImage rotates provided tile layer.

type OrthogonalRendererEngine

type OrthogonalRendererEngine struct {
	// contains filtered or unexported fields
}

OrthogonalRendererEngine represents orthogonal rendering engine.

func (*OrthogonalRendererEngine) GetFinalImageSize

func (e *OrthogonalRendererEngine) GetFinalImageSize() image.Rectangle

GetFinalImageSize returns final image size based on map data.

func (*OrthogonalRendererEngine) GetObjectAnchor added in v0.15.0

func (e *OrthogonalRendererEngine) GetObjectAnchor(imgSize image.Point) image.Point

GetObjectAnchor returns the bottom-left point of a tile object's image, per the Tiled spec's orthogonal alignment rule.

func (*OrthogonalRendererEngine) GetTilePosition

func (e *OrthogonalRendererEngine) GetTilePosition(x, y int, imgSize image.Point) image.Point

GetTilePosition returns tile position in image.

Per the Tiled spec, a tile image larger than the map's grid cell "extends at the top and right (anchored to the bottom left)", so the image's bottom edge is aligned to the bottom of the grid cell rather than its top.

func (*OrthogonalRendererEngine) Init

func (e *OrthogonalRendererEngine) Init(m *tiled.Map)

Init initializes rendering engine with provided map options.

func (*OrthogonalRendererEngine) PixelToScreenCoords added in v0.15.0

func (e *OrthogonalRendererEngine) PixelToScreenCoords(x, y float64) (float64, float64)

PixelToScreenCoords returns screen coordinates for a raw object pixel position. Orthogonal maps store object positions directly in screen pixel space already, so this is the identity transform.

func (*OrthogonalRendererEngine) RotateTileImage

func (e *OrthogonalRendererEngine) RotateTileImage(tile *tiled.LayerTile, img image.Image) image.Image

RotateTileImage rotates provided tile layer.

type Renderer

type Renderer struct {
	Result *image.NRGBA // The image result after rendering using the Render functions.
	// contains filtered or unexported fields
}

Renderer represents an rendering engine.

func NewRenderer

func NewRenderer(m *tiled.Map) (*Renderer, error)

NewRenderer creates new rendering engine instance.

func NewRendererWithFileSystem added in v0.10.0

func NewRendererWithFileSystem(m *tiled.Map, fs fs.FS) (*Renderer, error)

NewRendererWithFileSystem creates new rendering engine instance with a custom file system.

func (*Renderer) Clear

func (r *Renderer) Clear()

Clear clears the render result to allow for separation of layers. For example, you can render a layer, make a copy of the render, clear the renderer, and repeat for each layer in the Map.

func (*Renderer) RenderGroup added in v0.12.0

func (r *Renderer) RenderGroup(groupID int) error

RenderGroup renders single group.

func (*Renderer) RenderGroupLayer added in v0.12.0

func (r *Renderer) RenderGroupLayer(groupID, layerID int) error

RenderGroupLayer renders single map layer in a certain group.

func (*Renderer) RenderGroupObjectGroup added in v0.12.0

func (r *Renderer) RenderGroupObjectGroup(groupID, objectGroupID int) error

RenderGroupObjectGroup renders single object group in a certain group.

func (*Renderer) RenderLayer

func (r *Renderer) RenderLayer(id int) error

RenderLayer renders single map layer.

func (*Renderer) RenderObjectGroup added in v0.12.0

func (r *Renderer) RenderObjectGroup(i int) error

RenderObjectGroup renders a single object group

func (*Renderer) RenderVisibleGroups added in v0.12.0

func (r *Renderer) RenderVisibleGroups() error

RenderVisibleGroups renders all visible groups

func (*Renderer) RenderVisibleLayers

func (r *Renderer) RenderVisibleLayers() error

RenderVisibleLayers renders all visible map layers.

func (*Renderer) RenderVisibleLayersAndObjectGroups added in v0.12.0

func (r *Renderer) RenderVisibleLayersAndObjectGroups() error

RenderVisibleLayersAndObjectGroups render all layers and object groups, layer first, objectGroup second so the order may be incorrect, you may put them into different groups, then call RenderVisibleGroups

func (*Renderer) RenderVisibleObjectGroups added in v0.12.0

func (r *Renderer) RenderVisibleObjectGroups() error

RenderVisibleObjectGroups renders all visible object groups

func (*Renderer) SaveAsGif

func (r *Renderer) SaveAsGif(w io.Writer, options *gif.Options) error

SaveAsGif writes rendered layers as GIF image to provided writer.

func (*Renderer) SaveAsJpeg

func (r *Renderer) SaveAsJpeg(w io.Writer, options *jpeg.Options) error

SaveAsJpeg writes rendered layers as JPEG image to provided writer.

func (*Renderer) SaveAsPng

func (r *Renderer) SaveAsPng(w io.Writer) error

SaveAsPng writes rendered layers as PNG image to provided writer.

type RendererEngine

type RendererEngine interface {
	Init(m *tiled.Map)
	GetFinalImageSize() image.Rectangle
	RotateTileImage(tile *tiled.LayerTile, img image.Image) image.Image
	// GetTilePosition returns the top-left position at which a tile image of the given
	// size should be drawn for grid cell (x, y). imgSize is passed through (rather than
	// assumed to match the map's nominal tile width/height) because tile images commonly
	// differ in size from the grid cell, e.g. tall isometric wall/structure tiles that
	// must remain anchored to the bottom of their cell per the Tiled spec.
	GetTilePosition(x, y int, imgSize image.Point) image.Point
	// PixelToScreenCoords converts an object's raw x/y position, as stored in the TMX
	// file, into final screen pixel coordinates. Per the Tiled spec, object positions
	// are stored in the map's unprojected pixel space rather than already-projected
	// screen space, so orientations that reshape the grid (e.g. isometric) must project
	// them the same way tile positions are projected.
	PixelToScreenCoords(x, y float64) (float64, float64)
	// GetObjectAnchor returns the point within a tile object's (unrotated) image,
	// sized imgSize, that should align to the object's projected screen position.
	// Per the Tiled spec this is orientation-dependent: bottom-left for orthogonal
	// maps, bottom-center for isometric maps.
	GetObjectAnchor(imgSize image.Point) image.Point
}

RendererEngine is the interface implemented by objects that provide rendering engine for Tiled maps.

type StaggeredRendererEngine added in v0.15.0

type StaggeredRendererEngine struct {
	HexagonalRendererEngine
}

StaggeredRendererEngine represents a staggered rendering engine, supporting both StaggerAxis "x" and "y" with either StaggerIndex.

Despite the name, orientation="staggered" is not a hexagonal map -- it's what Tiled's own "New Map" dialog calls "Isometric (Staggered)": ordinary (non-hex) diamond-ish tile art arranged in a staggered/offset grid to fake an isometric look without true isometric projection. "Hexagonal (Staggered)" is the separate orientation="hexagonal", for actual hex tiles.

The two share an implementation in Tiled itself, though: hex support was added later by generalizing the pre-existing isometric-staggered renderer with a HexSideLength (see https://discourse.mapeditor.org/t/support-for-hexagonal-maps-added/47), and Tiled's StaggeredRenderer still literally inherits from HexagonalRenderer today with no changes to tile placement or bounding-box math (see https://github.com/mapeditor/tiled/blob/master/src/libtiled/staggeredrenderer.h). The "staggered" orientation has no hexsidelength attribute at all, so tiled.Map.HexSideLength is naturally its zero value for these maps, which reduces HexagonalRendererEngine's geometry to exactly this staggered, half-tile brick-like offset grid -- so this type only needs to embed it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址