4. Table backGround

A table backGround inherit from renderizable and implement all methods as usual. It is a simpler renderizable meant to draw a single full texture (or a font) behind (or in front of) everything else, typically used as a scene backdrop.

4.1. backGround methods

4.1.1. backGround new

new(string * type)

Create a new instance of a backGround.

Parameters

string – type can be 3d to create a 3d background. Any other value (or omitted) creates a 2d background (optional).

Returns

backGround table.

Example:

tBackGround = backGround:new('3d') --note that backGround inherits from renderizable

4.1.2. backGround load

load(string file_name, boolean * has_alpha)

Load a backGround from a texture or binary mesh file.

Parameters

  • string – file name from file.

  • boolean – has alpha informs whether the texture has an alpha channel (optional, default false).

Returns

boolean - result.

Example:

tBackGround = backGround:new('2dw')
if tBackGround:load('sky.png', true) then
   print('Successfully loaded background:','sky.png')
else
   print('Failed to loaded background:','sky.png')
end
load(string file_name, string text)

Load a font as backGround, rendering the given text.

Parameters

  • string – file name of the font file.

  • string – text to render.

Returns

boolean - result.

Example:

tBackGround = backGround:new('2dw')
tBackGround:load('arial.ttf', 'Loading...')

Note

The load method will search in all known path.
You can add a path to search by the method addPath.

4.1.3. backGround loadAsync

loadAsync(string file_name, boolean * has_alpha, function callback)
Load a backGround from a texture or binary mesh file the same way load does, but the file reading and parsing happens on a background thread instead of blocking the caller.
The callback argument is always the last argument passed to the function.
The callback is always invoked from the main thread on a later frame, never inline, so it is safe to touch any other engine object from inside it.
Parameters

  • string – file name from file.

  • boolean – has alpha informs whether the texture has an alpha channel (optional, default false).

  • function – callback invoked as callback(self, success) once the load finishes, where self is the backGround object itself and success is a boolean.

Example:

tBackGround = backGround:new('2dw')
tBackGround:loadAsync('sky.png', true, function(self, success)
   if success then
      print('Successfully loaded background:','sky.png')
   else
      print('Failed to loaded background:','sky.png')
   end
end)

Note

The loadAsync method will search in all known path, same as load.
The engine keeps a reference to self and to the callback until the load finishes, so the backGround object stays alive even if the script drops every other reference to it before that.
There is no asynchronous variant for the font-loading overload of load.
Only the mesh-file path (.mbm/.spt/.msh) is actually deferred to a background thread. Loading a plain texture file has no asynchronous primitive in the engine, so in that case the load still completes synchronously, even though the callback API is the same.