Blitz3D+ Command Reference

LoadTexture ( file$[,flags] )

Parameters

file$ - image file to load
flags (optional) - texture flags, added together; 1 (default):
1: colour
2: alpha
4: masked - areas coloured 0,0,0 are not drawn
8: mipmapped
16: clamp u - no horizontal tiling
32: clamp v - no vertical tiling
64: spherical environment map
128: cubic environment map
256: store texture in vram (no effect on the modern renderer)
512: force high colour textures (no effect on the modern renderer)

Description

Loads an image file as a texture and returns its handle, or 0 if loading failed.

Apply the texture with EntityTexture, or put it in a brush with BrushTexture and paint it. Always check for 0 before using the handle.

Flags add together (3 = colour + alpha). For transparency: flag 2 uses the image's alpha channel for smooth translucency (with an image that has no alpha channel, brightness is used instead - dark means transparent); flag 4 is the cut-out style where pure black pixels (0,0,0) vanish. Mipmapping (8) is on for most games via the default texture filter - see below. The clamp flags (16/32) stop edge bleeding on non-tiling art. Flag 128 loads a cubic environment map: the file must hold the six cube faces side by side in one horizontal strip, in the order left, forward, right, backward, up, down (so the image is exactly six times wider than it is tall).

Loaded textures also pick up flags from active texture filters, which match against the filename. The default filter adds colour + mipmapped (1+8) to every load, so you usually get mipmaps without asking. See TextureFilter to change this per name pattern.

Block-compressed 2D DDS files are kept compressed and uploaded directly as native BC1 through BC7 GPU textures. This includes legacy DXT1, DXT3 and DXT5 files as well as DDS files with DX10 headers. With mipmapping flag 8, an authored DDS mip chain is retained; without flag 8, only its top level is used. The GPU samples the BC blocks without expanding the texture into a BGRA copy in system or video memory.

DDS texture arrays, volume textures and DDS cubemaps are not accepted by LoadTexture. Cubic environment map flag 128 continues to use the six-face horizontal image strip described above. A compressed DDS uses its encoded alpha; masked flag 4 cannot rewrite its blocks. Because it has no writable uncompressed pixel buffer, TextureBuffer returns 0 for a GPU-compressed DDS texture.

Loading the same file twice with the same flags shares the underlying texture data, so repeated loads are cheap.

See also: CreateTexture, LoadAnimTexture, EntityTexture, BrushTexture, TextureFilter, FreeTexture.

Example

; LoadTexture Example
; -------------------

Graphics3D 640,480,0,2
SetBuffer BackBuffer()

camera=CreateCamera()

light=CreateLight()
RotateEntity light,45,45,0

; A crate for our game scene
crate=CreateCube()
PositionEntity crate,0,0,5

; Load an image file as a texture (optional flags argument omitted)
tex=LoadTexture("media/b3dlogo.jpg")

; Apply the loaded texture to the crate
EntityTexture crate,tex

While Not KeyDown(1)

    TurnEntity crate,0,1,0

    ; Arrow keys move the camera
    If KeyDown(200) Then MoveEntity camera,0,0,0.1
    If KeyDown(208) Then MoveEntity camera,0,0,-0.1
    If KeyDown(203) Then TurnEntity camera,0,1,0
    If KeyDown(205) Then TurnEntity camera,0,-1,0

    RenderWorld

    Text 0,0,"Arrows: camera   Esc: exit"
    Text 0,20,"The crate is textured with media/b3dlogo.jpg"

    Flip

Wend

End

Index