Table of Contents

12. Table renderizable ¶

Table renderizable is a base class for all object that are ‘renderizable’ in the engine.

All table which inherit from renderizable will have these commons methods and attributes in this section.

If you set the property visible as true and check the isOnScreen method next (same step), the result always will be true even if the object is not on screen. This happens because it has to wait for at least one loop to the engine update the objects that are on screen.

Here a example of a false positive logic as explained before:

Note the ^highlighted lines bellow demonstrating the logic error.

local tSprite =  sprite:new('2DW',500,800)
tSprite:load('tSprite.spt')

function loop(delta)
   tSprite.x = -99999999 -- far far away from screen (isOnScreen should return false)
   tSprite.visible = true --force to be on screen

   -- tSprite:isOnScreen() is always true because the
   -- tSprite.visible it was set to true in the same step.
   -- next loop should be false (if not set again the visible property)
   if tSprite:isOnScreen() then
      print('Sprite on screen: True')
   else
      print('Sprite on screen: False')
   end
end

12.1.14. Renderizable isLoaded ¶

isLoaded¶

Check if the renderizable is loaded.

Returns: boolean - true if the renderizable is loaded.

Example:

local tSprite =  sprite:new('2DW',500,800)
tSprite:load('tSprite.spt')

if tSprite:isLoaded() then
   print('Sprite is loaded')
else
   print('Sprite is not loaded')
end

12.1.15. Renderizable onEndFx ¶

Set a renderizable’s shader effect callback.

The callback must have the following signature:

function callBack(renderizable self,string shader_fileName)

Note

Some shader effect may never end because it is flagged as loop.

See animation table animation table.

onEndFx(string)¶

Set a renderizable’s shader effect callback passing a string name from a function defined somewhere.

Parameters: string – function name callback.

Example:

--example callback
function fFxCallBack(self,shader_fileName)
   if shader_fileName == 'bloom.ps' then
      self:setAnim('destroy')
   end
end

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')
tSprite:onEndFx('fFxCallBack')
tSprite:setAnim('fall')

onEndFx(function)¶

Set a renderizable’s shader effect callback passing a function.

Parameters: function – callback.

Example:

--example callback
function fFxCallBack(self,shader_fileName)
   if shader_fileName == 'bloom.ps' then
      self:setAnim('destroy')
   end
end

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')
tSprite:onEndFx(fFxCallBack)--named function


local otherSprite =  sprite:new('2DW')
otherSprite:load('tSprite.spt')
otherSprite:onEndFx(
   function (self,shader_fileName)      --anonymous function
      if shader_fileName == 'bloom.ps' then
         self:setAnim('destroy')
      end
   end
)

12.1.16. Renderizable forceEndAnimFx ¶

forceEndAnimFx(boolean bEndAnim, boolean bEndFx)¶

Force to end an animation and / or shader effect from a renderizable.

Parameters

boolean – end animation.
boolean – end effect shader.

Example:

--example callback
function fFxCallBack(self,shader_fileName)
   if shader_fileName == 'bloom.ps' then
      self:setAnim('destroy')
   end
end

--example callback
function myCallBackSprite(self,nameAnimation)
   if nameAnimation == 'fall' then
      self:setAnim('destroy')
   end
end

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')
tSprite:onEndAnim(myCallBackSprite)--named function
tSprite:onEndFx(fFxCallBack)--named function
tSprite:forceEndAnimFx(true,true) --force and both (animation and fx) and do a callback to functions.

12.1.17. Renderizable getTotalFrame ¶

getTotalFrame¶

Retrieve the total frame from a renderizable independent of animation.

Returns: number - total frame from renderizable.

Example:

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')
local iTotal = tSprite:getTotalFrame()

12.1.18. Renderizable destroy ¶

destroy¶

Force to destroy an object renderizable.

Example:

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')
tSprite:destroy() -- can not be used anymore
tSprite = nil     -- so set to nil be be collected ASAP

Note

When an object destroyed it does not means that will be collected immediately. To force that you can call collectgarbage from LUA API.

12.2. Blending ¶

Blend state or Blending is the stage of OpenGL rendering pipeline that takes the fragment color outputs from the Fragment Shader and combines them with the colors in the color buffers that these outputs map to.

Blending parameters can allow the source and destination colors for each output to be combined in various ways.

The color S is the source color; the color D is the destination color; the color O is the output color that is written to the buffer.

The S, D, and so forth represent all of the components of that color.

Srgb represents only the RGB components of the source color. Da represents the alpha component of the destination color.

You can learn more at wiki Blending.

Blend operation can also be accessed by shader blend state methods.

Function

Explanation

ADD

The source and destination colors are added to each other. O = sS + dD.

The s and d are blending parameters that are multiplied into each of S and D before the addition.

SUBTRACT

Subtracts the destination from the source. O = sS - dD.

The source and dest are multiplied by blending parameters.

REVERSE_SUBTRACT

Subtracts the source from the destination. O = dD - sS.

The source and dest are multiplied by blending parameters.

MIN

The output color is the component-wise minimum value of the source and dest colors.

So performing GL_MIN in the RGB equation means that Or = min(Sr, Dr), Og = min(Sg, Dg), and so forth.

The parameters s and d are ignored for this equation.

MAX

The output color is the component-wise maximum value of the source and dest colors.

The parameters s and d are ignored for this equation.

Following the constant table for blend state used by this engine:

Blend State

Constant Name

String Name

DISABLE

disable

ZERO

zero

ONE

one

SRC_COLOR

src_color

INV_SRC_COLOR

inv_src_color

SRC_ALPHA

src_alpha

INV_SRC_ALPHA

inv_src_alpha

DEST_ALPHA

dest_alpha

INV_DEST_ALPHA

inv_dest_alpha

DEST_COLOR

dest_color

INV_DEST_COLOR

inv_dest_color

Following the constant table for blend operation used by this engine:

Blend Operation

Constant Name

String Name

ADD

ADD

SUBTRACT

SUBTRACT

REVERSE_SUBTRACT

REVERSE_SUBTRACT

MIN

MIN

MAX

MAX

12.2.1. Blending setBlend ¶

setBlend(string name)¶

Set the blend state to a renderizable.

Parameters: string – name regard the blend state.

Example:

local tShape =  shape:new('2DW')
tShape:create('circle')
tShape:setBlend('inv_src_color') -- same as mbm.INV_SRC_COLOR
local nameBlend, constantBlend = tShape:getBlend()
print(nameBlend) -- inv_src_color
if constantBlend == mbm.INV_SRC_COLOR then
   print('expected constant: INV_SRC_COLOR')
end

Figure 12.1 setting blend by string name¶

setBlend(number constant)¶

Set the blend state to a renderizable.

Parameters: number – index regard the blend state.

Example:

local tShape =  shape:new('2DW')
tShape:create('circle')
tShape:setBlend(mbm.DEST_ALPHA) -- same as 'dest_alpha'
local nameBlend, constantBlend = tShape:getBlend()
print(nameBlend) -- dest_alpha
if constantBlend == mbm.DEST_ALPHA then
   print('expected constant: DEST_ALPHA')
end

Figure 12.2 setting blend by string name¶

12.2.2. Blending getBlend ¶

getBlend¶

Get the blend state from a renderizable.

Returns: string name, number index - blend state of renderizable.

Example:

local tShape =  shape:new('2DW')
tShape:create('circle')
local nameBlend, constantBlend = tShape:getBlend()
print(nameBlend) -- DISABLE
if constantBlend == mbm.DISABLE then
   print('expected constant: DISABLE')
end

Figure 12.3 getting blend¶

12.2.3. Blend Operation ¶

Blend operation is part of shader.

See shader blend operation.

12.3. Animation ¶

All inheritable table from renderizable might have one or more animation.

An animation is basically a change of frames regularly.

An can be added through the method addAnim.

Each animation has its own shader.

An animation changes the frame regularly according to this table:

Animation

Name

Explanation

callback end

of animation ?

PAUSED

The animation is paused

false

GROWING

Increment the frames till the final frame.

Stop animation in the final frame.

true

GROWING_LOOP

Increment the frames till the final frame.

repeat when reach the final frame.

false

DECREASING

Decrement the frames till the initial frame.

Stop animation in the initial frame.

true

DECREASING_LOOP

Decrement the frames till the initial frame.

repeat when reach the initial frame.

false

RECURSIVE

Increment the frames till the final frame.

Decrement the frames till the initial frame.

Stop animation in the initial frame.

true

RECURSIVE_LOOP

Increment the frames till the final frame.

Decrement the frames till the initial frame.

repeat when reach the initial frame.

true

All member are constant and can be accessible through mbm table.

Example:

tShape = shape:new('2dw')
tShape:create('Circle')

--Added an animation type GROWING
tShape:addAnim('rolling', mbm.GROWING)


local tShader = tShape:getShader()

if tShader:load(nil,'scale.vs',1,0,2.0,0) then
   --Added an animation type GROWING_LOOP to shader
   tShader:setVStype(mbm.GROWING_LOOP)
end

local nameAnim, indexAnim = tShape:getAnim()
print(nameAnim, indexAnim) -- 'rolling', 2

12.3.1. Animation setAnim ¶

setAnim(string name)¶

Set the animation to a renderizable.

Parameters: string – name of animation.

Example:

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')
tSprite:setAnim('walk')

setAnim(number index)¶

Set the animation to a renderizable.

Parameters: number – index of animation (one based index).

Example:

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')
tSprite:setAnim(1) --first animation

12.3.2. Animation getAnim ¶

getAnim(number * index_anim)¶

Get the name and index (1 based) of the animation from a renderizable.

Parameters: number – index of animation (one based index). If not supplied get the current.
Returns: string name, number index (1 based) - animation of renderizable.

Example:

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')
local nameAnim, indexAnim = tSprite:getAnim()
print(nameAnim, indexAnim) -- 'walk 0' for current animation 1

12.3.3. Animation setTypeAnim ¶

setTypeAnim(number type_animation)¶

Set a new type to animation.

Parameters: number – type of animation.
Returns: number old_type - type of animation.

Example:

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')
local iOldTypeAnimation = tSprite:setTypeAnim(mbm.PAUSED) -- pause the current animation
tSprite:setTypeAnim(iOldTypeAnimation) -- set animation type defined previously

12.3.4. Animation restartAnim ¶

Restart an renderizable’s animation.

Example:

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')
tSprite:restartAnim()

12.3.5. Animation onEndAnim ¶

Set a renderizable’s animation callback.

The callback must have the following signature:

function callBack(renderizable self,string name_animation)

Note

Some animation may never end because it is flagged as loop.

See animation table animation table.

onEndAnim(string)¶

Set a renderizable’s animation callback passing a string name from a function defined somewhere.

Parameters: string – function name callback.

Example:

--example
function myCallBackSprite(self,nameAnimation)
   if nameAnimation == 'fall' then
      self:setAnim('destroy')
   end
end

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')
tSprite:onEndAnim('myCallBackSprite')
tSprite:setAnim('fall')

local otherSprite =  sprite:new('2DW')
otherSprite:load('tSprite.spt')
otherSprite:onEndAnim('myCallBackSprite')
otherSprite:setAnim('fall')

onEndAnim(function)¶

Set a renderizable’s animation callback passing a function.

Parameters: function – callback.

Example:

--example
function myCallBackSprite(self,nameAnimation)
   if nameAnimation == 'fall' then
      self:setAnim('destroy')
   end
end

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')
tSprite:onEndAnim(myCallBackSprite)--named function
tSprite:setAnim('fall')

local otherSprite =  sprite:new('2DW')
otherSprite:load('tSprite.spt')
otherSprite:onEndAnim(
   function (self,nameAnimation)      --anonymous function
      if nameAnimation == 'fall' then
         self:setAnim('destroy')
      end
   end
)
otherSprite:setAnim('fall')

12.3.6. Animation isEndedAnim ¶

isEndedAnim¶

Check if the animation from a renderizable has ended the animation.

Returns: boolean - true if animation has ended.

Example:

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')

function loop(delta)
   if tSprite:isEndedAnim() then
      print('Animation has ended')
      tSprite:restartAnim()
   end
end

12.3.7. Animation getIndexFrame ¶

getIndexFrame¶

Return which index frame is currently to the renderizable (1 based).

Returns: number - index of frame from current renderizable.

Example:

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')

function loop(delta)
   if tSprite:getIndexFrame() == 2 then
      print('reach index 2 from animation')
      tSprite:restartAnim()
   end
end

12.3.8. Animation setTexture ¶

setTexture(string file_name_texture, boolean* alpha, number* stage)¶

Set a new texture for a renderizable. It considers the current animation.

Parameters

string – file name texture to be set to current animation.
boolean – alpha apply alpha if texture not loaded before. Default is true.
number – stage to apply. (1 or 2). Default is 1.

Example:

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')
tSprite:setTexture('mario.png',true,1)

Note

Stage 1 means apply the texture for the current animation
- Each animation hold the texture for stage 1.
Stage 2 means apply the texture for the current shader.
- If the current shader does not use the texture stage 2, nothing happens.

setTexture(number red, number green, number blue, number * alpha)¶

Set a new solid texture for a renderizable. It considers the current animation.

Parameters

number – red color (0-1).
number – green color (0-1).
number – blue color (0-1).
number – alpha color (0-1) (optional, default 1).

Example:

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')
tSprite:setTexture(1,0,0) --Apply a solid (red color) to the sprite

setColor(number red, number green, number blue, number * alpha)¶

Set a new solid texture for a renderizable. It considers the current animation.

Parameters

number – red color (0-1).
number – green color (0-1).
number – blue color (0-1).
number – alpha color (0-1) (optional, default 1).

Example:

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')
tSprite:setColor(1,0,0) --Apply a solid (red color) to the sprite (same as setTexture)

12.3.9. Animation getTotalAnim ¶

getTotalAnim¶

Retrieve the total animation from a renderizable.

Returns: number - total animation for the renderizable.

Example:

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')
local iTotal = tSprite:getTotalAnim()

12.3.10. Animation addAnim ¶

addAnim(string* name, number* type, number* start_frame, number* final_Frame, number * interval)¶

Create a new animation to a renderizable based on animation table.

Parameters

string – name of animation.
number – type of animation (see animation table index type).
number – start frame of animation.
number – final frame of animation.
number – interval between frames of animation.

Returns

string name, number index (1 based) - animation of renderizable created.

Example:

local tSprite =  sprite:new('2DW')
tSprite:load('sprite.spt')
tSprite:addAnim('walk',mbm.GROWING_LOOP,1,5,0.2)

12.3.11. Animation getShader ¶

getShader¶

Retrieve the shader used by renderizable for the current animation.

Returns: shader - from renderizable.

Example:

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')
local shader = tSprite:getShader()

12.4. Physics ¶

It is possible to retrieve the physics information applied to renderizable however it is not possible to change in the mesh. You only can change the info retrieved.

getPhysics¶

Returns: table - array with each physics applied to this renderizable.

Example:

local tSprite =  sprite:new('2DW')
tSprite:load('tSprite.spt')
local tInfoPhysics = tSprite:getPhysics()
for i=1, #tInfoPhysics do
   print(tInfoPhysics[i].type)
   if tInfoPhysics[i].type == 'cube' then
      print('center x:',tInfoPhysics[i].x)
      print('center y:',tInfoPhysics[i].y)
      print('center z:',tInfoPhysics[i].z)
      print('width:',   tInfoPhysics[i].width)
      print('height:',  tInfoPhysics[i].height)
      print('depth:',   tInfoPhysics[i].depth)
   elseif tInfoPhysics[i].type == 'sphere' then
      print('center x:',tInfoPhysics[i].x)
      print('center y:',tInfoPhysics[i].y)
      print('center z:',tInfoPhysics[i].z)
      print('ray:',     tInfoPhysics[i].ray)
   elseif tInfoPhysics[i].type == 'triangle' then
      print('a x:',tInfoPhysics[i].a.x)
      print('a y:',tInfoPhysics[i].a.y)
      print('a z:',tInfoPhysics[i].a.z)
      print('b x:',tInfoPhysics[i].b.x)
      print('b y:',tInfoPhysics[i].b.y)
      print('b z:',tInfoPhysics[i].b.z)
      print('c x:',tInfoPhysics[i].c.x)
      print('c y:',tInfoPhysics[i].c.y)
      print('c z:',tInfoPhysics[i].c.z)
   elseif tInfoPhysics[i].type == 'complex' then
      print('a x:',tInfoPhysics[i].a.x)
      print('a y:',tInfoPhysics[i].a.y)
      print('a z:',tInfoPhysics[i].a.z)
      print('b x:',tInfoPhysics[i].b.x)
      print('b y:',tInfoPhysics[i].b.y)
      print('b z:',tInfoPhysics[i].b.z)
      print('c x:',tInfoPhysics[i].c.x)
      print('c y:',tInfoPhysics[i].c.y)
      print('c z:',tInfoPhysics[i].c.z)
      print('d x:',tInfoPhysics[i].d.x)
      print('d y:',tInfoPhysics[i].d.y)
      print('d z:',tInfoPhysics[i].d.z)
      print('e x:',tInfoPhysics[i].e.x)
      print('e y:',tInfoPhysics[i].e.y)
      print('e z:',tInfoPhysics[i].e.z)
      print('f x:',tInfoPhysics[i].f.x)
      print('f y:',tInfoPhysics[i].f.y)
      print('f z:',tInfoPhysics[i].f.z)
      print('g x:',tInfoPhysics[i].g.x)
      print('g y:',tInfoPhysics[i].g.y)
      print('g z:',tInfoPhysics[i].g.z)
      print('h x:',tInfoPhysics[i].h.x)
      print('h y:',tInfoPhysics[i].h.y)
      print('h z:',tInfoPhysics[i].h.z)
   end
end

12.5. Renderizable attributes ¶

x, y, z [read / write]

Access the position x, y and z member from renderizable.

Example:

local tSprite =  sprite:new('2DW')
tSprite.x = 100
tSprite.y = 200
tSprite.z = -1

print(tSprite.x,tSprite.y,tSprite.z) -- 100 200 -1

sx, sy, sz [read / write]

Access the scale sx, sy and sz member from renderizable.

Example:

local tSprite =  sprite:new('2DW')
tSprite.sx = 0.8
tSprite.sy = 0.8
tSprite.sz = 1

print(tSprite.sx,tSprite.sy,tSprite.sz) -- 0.8 0.8 1

ax, ay, az [read / write]

Access the angle ax, ay and az member from renderizable.

Example:

local tSprite =  sprite:new('2DW')
tSprite.ax = math.rad(180)
tSprite.ay = math.rad(90)
tSprite.az = math.rad(45)

print(math.deg(tSprite.ax),math.deg(tSprite.ay),math.deg(tSprite.az)) -- 180 90 45

Note

The angle is radian.

visible [read / write]

Enable or disable the renderizable to be rendered.

Example:

local tSprite =  sprite:new('2DW')
tSprite.visible = false --turn invisible the object

Attention

If you set the property visible as true and check the isOnScreen method next (same step), the result always will be true even if the object is not on screen. This happens because it has to wait for at least one loop to the engine update the objects that are on screen.

More information at isOnScreen explanation.

alwaysRender [read / write]

Force always render the renderizable even if is not at the screen.

Example:

local tSprite =  sprite:new('2DW')
tSprite.alwaysRender = true -- always will be renderized

'variable' [read / write]

Create a variable read/write to renderizable. The type allowed is number, string, boolean, table and function.

Example:

local tSprite =  sprite:new('2DW')

function myPrint(self,message)
   print('message:', message or '')
end

tSprite.myFloat = 3.151413
tSprite.myInt = 9
tSprite.myString = 'Hi there!'
tSprite.myTable = {msg = 'Hi there!'}
tSprite.myFunction = myPrint
print('Accessing the variables myFloat:',tSprite.myFloat)
print('Accessing the variables myInt:',tSprite.myInt)
print('Accessing the variables myString:',tSprite.myString)
print('Accessing the variables myTable:',tSprite.myTable.msg)
tSprite:myPrint('Hello!')

12.6. User data acknowledgment ¶

This table uses the first index to store the userdata C++ class internally. So, if you want to store some values to the table you must use from the second element as exampled bellow:

Listing 12.1 You can do this:¶

tTexture = texture:new('2ds')
tTexture:setPos(12,5)

tTexture[2] = 'some value var'

print(tTexture[2]) -- 'some value var'

Error

It is important to understand that as all tables used in this engine, this table uses the first index to store the userdata pointing to the C++ class internally.

There is no mechanism to prevent to access the first index from renderizable. If you overload the userdata, probably the program will crash.

Listing 12.2 Do not do this:¶

tTexture = texture:new('2dw')
tTexture:setPos(100,300,-1)

print(tTexture[1]) -- read, okay will print userdata: 0x55957888a6a8 for example

tTexture[1] = 2 -- Error, this will do your program crash!

12. Table renderizable ¶

12.1. Renderizable methods ¶

12.1.1. Renderizable setPos ¶

12.1.2. Renderizable getPos ¶

12.1.3. Renderizable setScale ¶

12.1.4. Renderizable getScale ¶

12.1.5. Renderizable setAngle ¶

12.1.6. Renderizable getAngle ¶

12.1.7. Renderizable move ¶

12.1.8. Renderizable isOver ¶

12.1.9. Renderizable collide ¶

12.1.10. Renderizable rotate ¶

12.1.11. Renderizable getSize ¶

12.1.12. Renderizable getAABB ¶

12.1.13. Renderizable isOnScreen ¶

12.1.14. Renderizable isLoaded ¶

12.1.15. Renderizable onEndFx ¶

12.1.16. Renderizable forceEndAnimFx ¶

12.1.17. Renderizable getTotalFrame ¶

12.1.18. Renderizable destroy ¶

12.2. Blending ¶

12.2.1. Blending setBlend ¶

12.2.2. Blending getBlend ¶

12.2.3. Blend Operation ¶

12.3. Animation ¶

12.3.1. Animation setAnim ¶

12.3.2. Animation getAnim ¶

12.3.3. Animation setTypeAnim ¶

12.3.4. Animation restartAnim ¶

12.3.5. Animation onEndAnim ¶

12.3.6. Animation isEndedAnim ¶

12.3.7. Animation getIndexFrame ¶

12.3.8. Animation setTexture ¶

12.3.9. Animation getTotalAnim ¶

12.3.10. Animation addAnim ¶

12.3.11. Animation getShader ¶

12.4. Physics ¶

12.5. Renderizable attributes ¶

12.6. User data acknowledgment ¶