LoadAtlas

LoadAtlas

Command Index · Blitz3D · Textures

LoadAtlas:Int32 file:String, flags:Int32=1, gutter:Int32=0

Parameter	Mode	Type	Default	Description
file	In	String	required	Picture file that contains all tiles.
flags	In	Int32	1	Texture flags, see LoadTexture. Defaults to 1.
gutter	In	Int32	0	Pixels of repeated edge color around every tile in the picture. Defaults to 0, which means there are none.

Returns: A texture handle, or 0 if the file could not be loaded.

Description

Loads a picture as a texture atlas: one image that holds many small pictures (tiles), which AtlasTexture cuts out as textures of their own. Every tile you cut out shares the one image on the graphics card, so a thousand tiles cost as much memory as the picture itself, and tiles of the same atlas need no texture change between draws.

The flags are the same as for LoadTexture. An atlas always clamps at its edges (flags 16 and 32 are added), as a repeating atlas has no use. You can also use the atlas itself as a texture. FreeTexture on the atlas only takes its handle away while tiles made from it exist; the picture is released with the last of them.

Gutter. Tiles are drawn from the first mip level only, as the smaller levels mix neighbouring tiles, and are kept half a texel away from their neighbours so that linear filtering does not read them. If you pack the picture with a gutter instead, pass its size in gutter: every tile then has that many pixels around it in the picture that repeat the colors of its edge (extruded by your packing tool). The tile rectangles you give AtlasTexture are the tiles without the gutter. With a gutter, tiles map exactly (no half texel zoom) and, if the atlas has mip maps (flag 8), they use them down to level log2(gutter): a gutter of 1 gives the first level only, 2 gives two levels, 4 gives three, and so on.

Examples

Graphics3D 320, 240, 0, 2
SetBuffer BackBuffer()
camera = CreateCamera()
CameraClsColor camera, 70, 100, 160
; A picture of four tiles, 32 pixels each, saved to a file.
sheet = CreateTexture(64, 64, 1 + 4096)
SetBuffer TextureBuffer(sheet)
Color 230, 60, 60 : Rect 0, 0, 32, 32, 1
Color 60, 200, 80 : Rect 32, 0, 32, 32, 1
Color 70, 110, 230 : Rect 0, 32, 32, 32, 1
Color 240, 220, 60 : Rect 32, 32, 32, 32, 1
Color 255, 255, 255
For i = 0 To 3
	Rect (i Mod 2) * 32 + 6, (i / 2) * 32 + 6, 20, 20, 0
	Text (i Mod 2) * 32 + 16, (i / 2) * 32 + 16, Str(i + 1), 1, 1
Next
SaveBuffer TextureBuffer(sheet), "wiki_atlas.bmp"
SetBuffer BackBuffer()
FreeTexture sheet

atlas = LoadAtlas("wiki_atlas.bmp")
For i = 0 To 3
	cube = CreateCube()
	EntityFX cube, 1
	EntityTexture cube, AtlasTexture(atlas, (i Mod 2) * 32, (i / 2) * 32, 32, 32)
	PositionEntity cube, (i Mod 2) * 2.6 - 1.3, 1.3 - (i / 2) * 2.6, 8
	TurnEntity cube, 20, 30, 0
Next
RenderWorld
Flip
WaitKey

Media

Related Commands

AtlasTexture, GetSamplerLodMin 〔BlitzLLVM〕, LoadAnimTexture, LoadTexture

Command Index · Blitz3D · Textures