The renderer keyword¶
The renderer is the main utility in Xentu used for drawing graphics onto the screen. In terms of functionality it is very similar to the SpriteBatch that you’ll find in Microsoft XNA and MonoGame.
At it’s core, the renderer groups organised batches of sprite calls together, and sends them to the GPU to be rendered. Doing this allows the engine to draw many graphics at once at a very fast rate.
A Quick example¶
Typically the renderer is used within the draw event in your
file. Here is an example of how you could use it:
game.on('draw', function(arg) renderer.clear() renderer.begin() renderer.draw_sprite( my_sprite ) renderer.draw_sprite( my_sprite2 ) renderer.present() end)
Notice that we use a
clear() function before everything which clears the frame
buffer. Then we call
present() call surrounding the actual
call to draw two sprites. This group constitutes as a single drawing layer. As
long as you finish a layer with the
present() call, you can begin a new one
straight after like so:
game.on('draw', function(arg) renderer.clear() -- layer #1 renderer.begin() renderer.draw_sprite( my_sprite ) renderer.draw_sprite( my_sprite2 ) renderer.present() -- layer #2 renderer.begin() renderer.draw_sprite( my_sprite3 ) renderer.present() end)
The above may not seem that useful at first. However once you start building your own games, you will understand why this can be so powerful.
The clear method tells the renderer to clear the frame buffer and should be called at the beginning of your draw callback.
The begin method tells the renderer to clear it’s instruction buffer, and prepare
for new draw instructions. If you dont do this after calling
result from the previous draw call will still be stored in the instruction buffer.
The present method tells the renderer to send all queued instructions from the instruction buffer to the GPU for rendering.
This method tells the renderer to queue an instruction in it’s buffer to draw a sprite. The sprite argument must be an instance of the Sprite struct setup earlier in your code.
renderer.draw_rect(color, x, y, width, height)¶
This method tells the renderer to draw a rectangle of a specific color, position, and dimensions.
Use this method to draw an individual layer from a loaded tilemap. To get a layer, first you will need to do something like the following in your init event handler:
tilemap = assets.load_tilemap("level1.tmx") layer0 = tilemap.get_layer(0)
Then in your draw event you could do something like:
A good use case for drawing layers individually, is that it allows you to do other things between rendering each layer. For example if you have a tilemap that has a ground, and foreground/sky layer. You could render a player sprite between those two layers. Alternatively you can also apply different shaders to each drawn layer for advanced effects.
renderer.draw_text(font, text, x, y, max_width)¶
This method tells the renderer to queue an instruction in it’s buffer to draw text onto the screen. The method requires you provide an instance to a Font struct , some text, an x-y position, and an optional maximum width before wrapping onto the next line.
The set_blend method is used to specify weather or not to use alpha blending when rendering. By default it is set to true, however you can switch it off if needed.
This method allows you to customise how the blending of graphics works.
the source factor, and
dfactor is the destination factor. The available
values for each argument are as follows:
A new method is currently in the works called
set_blend_preset() that will
instead only require more commonly known blend terms as described by the Mozilla
foundation’s documentation here.
This should be arriving over the next few weeks.
This method allows you to pick a color to clear the background with just before
present() sends new drawing calls to the GPU. The color argument requires
creating a new instance of the Color struct. Here is an example of how to
local blue = Color.from_hex('#0000ff') renderer.set_clear_color(blue)
Moving, rotating or scaling the graphics you draw is important for making interesting
games. So Xentu provides some straight forward methods for doing so. Transforms are
reset every time you call the
renderer.begin() method, then can be modified using
the following methods:
This method sets the transform origin for everything drawn after it. The origin typically starts as 0,0 (top left) meaning if you draw a sprite without any transformation. It’ll appear in the top left without any clipping.
Imagine that sprite is 100x100 pixels in size, and you call
This will move the origin to exactly the centre of that sprite. So when you draw
it, you’ll instead only see the bottom right quater of the sprite.
This method transforms the next rendered graphic by a angle based rotation. If we
expand on the
set_origin() example from above, using
would effectively rotate the sprite around it’s centre by 45 degrees clockwise.
This method transforms the next rendered graphic by scale. So if you wrote the following:
The next drawn graphic would be 200% tall, and 200% wide.
This method transforms the next rendered graphic by moving (translating). So if you wrote the following:
The next drawn graphic would move by 10 pixels to the right. Note that some drawing
methods also let you set a position. When using those after calling
both position values will be added up.
set_shader() method allows you to tell the renderer what shader program
to use when
present() is called. The shader argument should be the index integer
that you get from assets.load_shader()
earlier in your code.