.. contents:: Table of Contents

.. _background:

Table backGround
================

A table :ref:`backGround <background>` inherit from :ref:`renderizable <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.

backGround methods
-------------------

backGround new
^^^^^^^^^^^^^^

.. data:: new(string * type)
   :noindex:

   Create a new instance of a :ref:`backGround <background>`.

   :param string: **type** can be ``3d`` to create a 3d background. Any other value (or omitted) creates a 2d background (optional).
   :return: :ref:`backGround <background>` *table*.

   *Example:*
.. code-block:: lua

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


backGround load
^^^^^^^^^^^^^^^

.. data:: load(string file_name, boolean * has_alpha)
   :noindex:

   Load a :ref:`backGround <background>` from a texture or binary mesh file.

   :param string: **file name** from file.
   :param boolean: **has alpha** informs whether the texture has an alpha channel (optional, default ``false``).
   :return: ``boolean`` - result.

   *Example:*
.. code-block:: lua

   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

.. data:: load(string file_name, string text)
   :noindex:

   Load a font as :ref:`backGround <background>`, rendering the given text.

   :param string: **file name** of the font file.
   :param string: **text** to render.
   :return: ``boolean`` - result.

   *Example:*
.. code-block:: lua

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

.. Note::

   | The :guilabel:`load` method will search in all known path.
   | You can add a path to search by the method :ref:`addPath <addPath>`.


backGround loadAsync
^^^^^^^^^^^^^^^^^^^^

.. data:: loadAsync(string file_name, boolean * has_alpha, function callback)
   :noindex:

   | Load a :ref:`backGround <background>` from a texture or binary mesh file the same way :ref:`load <background>` 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.

   :param string: **file name** from file.
   :param boolean: **has alpha** informs whether the texture has an alpha channel (optional, default ``false``).
   :param function: **callback** invoked as ``callback(self, success)`` once the load finishes, where ``self`` is
      the :ref:`backGround <background>` object itself and ``success`` is a ``boolean``.

   *Example:*
.. code-block:: lua

   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 :guilabel:`loadAsync` method will search in all known path, same as :guilabel:`load`.
   | The engine keeps a reference to ``self`` and to the ``callback`` until the load finishes, so the
     :ref:`backGround <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 :guilabel:`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.