Module blitwizard.graphics

The blitwizard graphics namespace allows to set up the graphics device for graphical 2d/3d output.

Info:

  • Copyright: 2011-2013
  • License: zlib
  • Author: Jonas Thiem (jonas.thiem@gmail.com) et al

Functions

setMode (width, height, title, fullscreen, renderer) This function sets the graphics mode.
getCameras () Get a table array with all currently active cameras.

Class camera

camera:destroy (camera) Destroy the given camera.
camera:new () Add a new camera.
camera:set2dCenter (x_position, y_position) Set the camera's 2d center which is the position in the 2d world centered by the camera.
camera:getVisible2dAreaDimensions (consider_zoom) Get the game units of the visible 2d area of the game world shown through this camera.
camera:getPixelDimensionsOnScreen () Get the dimensions of a camera on the actual screen.
camera:setPixelDimensionsOnScreen (width, height) Set the dimensions of a camera on the screen.
camera:get2dZoomFactor () Get the 2d zoom factor (defaults to 1).
camera:set2dZoomFactor (zoom_factor) Set the 2d zoom factor.
camera:gameUnitToPixels () Get the extend in pixels a game unit in the 2d world has at the default camera zoom level of 1.


Functions

setMode (width, height, title, fullscreen, renderer)
This function sets the graphics mode. You can specify a resolution, whether your game should run in a window or fullscreen, and if windowed whether the window is resizable. Feel free to use this function multiple times to change the mode again if you feel like doing so.

If you specify no parameters, the graphics output will be closed again.

Throws an error if graphics initialisation fails.

Parameters:

  • width number Set the width of the output in pixels
  • height height Set the height of the output in pixels
  • title string (optional) Set the window title shown in the title bar. You can also specify nil if you want the default
  • fullscreen boolean (optional) Specify if you want to run fullscreen or windowed
  • renderer string (optional) Specify a specific renderer you want. Available renderers are "direct3d" (Windows only), "opengl" and "software". Software rendering is slow and should only be used as a fallback. It's also only available if you compiled with SDL graphics. If you don't specify a renderer, the best one will be used

Usage:

     -- Open a window with 800 x 600 pixel size and title "Test"
 blitwizard.graphics.setMode(800, 600, "Test")
getCameras ()
Get a table array with all currently active cameras. (per default, this is only one)

Returns:

    table a table list array containing camera items

Class camera

Blitwizard camera object which represents a render camera.

A render camera has a rectangle on the screen which is a sort of "window" that shows a view into the 2d/3d world of your blitwizard game.

Per default, you have one camera that fills up the whole screen with one single large view. But if you want to split the screen up e.g. for split screen multiplayer games, and show different world views side by side, you would want multiple cameras.

IMPORTANT: If you want to show a different part of the game world, this is where you want to be! Grab the first camera from blitwizard.graphics.getCameras and let's go:

Use camera:set2dCenter to modify the 2d world position shown, and ??? to modify the 3d world position shown if you use any 3d objects.

Please note the SDL 2d renderer doesn't support more than one camera. The OGRE 3d renderer supports multiple cameras.

camera:destroy (camera)
Destroy the given camera.

It will be removed from the blitwizard.graphics.getCameras list and all references you still have to it will become invalid.

Parameters:

  • camera userdata the camera to be destroyed
camera:new ()
Add a new camera. Returns the new camera, and it will be automatically part of the list of all followup blitwizard.graphics.getCameras calls aswell.

If you want to get rid of it again, check out blitwizard.graphics.camera:destroy.

camera:set2dCenter (x_position, y_position)
Set the camera's 2d center which is the position in the 2d world centered by the camera. This allows you to move the camera's shown part of the 2d world around, focussing on other places.

The position is specified in game units (the same units used for specifying the position of objects). The camera initially looks at position 0, 0.

If you want the camera to follow a 2d object, simply use this function to set the 2d center to the coordinates of the object (you can do this in the object's doAlways function).

Parameters:

  • x_position number X position of the 2d point to look at
  • y_position number Y position of the 2d point to look at

Usage:

     -- make the default camera look at position 3, 3:
 local camera = blitwizard.graphics.getCameras()[1]
 camera:set2dCenter(3, 3)
camera:getVisible2dAreaDimensions (consider_zoom)
Get the game units of the visible 2d area of the game world shown through this camera. This depends on the camera's actual size in pixels on the screen, the camera's 2d zoom factor and the camera's ???.

Note on 3d objects: There is no similar function for 3d objects, because in 3d it largely depends on the camera's position and angle which objects will be visible how large on the screen, while for 2d it only depends on zoom and aspect ratio.

Note on pinned 2d objects: If you want to know the area visible in game units for pinned objects which are unaffected by camera zoom when drawn, specify false as first parameter for not taking the zoom into account.

Parameters:

  • consider_zoom boolean (optional) defaults to true. Specifies whether the zoom factor should be taken into account. Set to true if yes, false if not.

Returns:

  1. number width the width of the visible 2d world area
  2. number height the height of the visible 2d world area
camera:getPixelDimensionsOnScreen ()
Get the dimensions of a camera on the actual screen. It usually fills the whole window (= the full size of the resolution you specified in blitwizard.graphics.setMode), but that may be changed with camera:setPixelDimensionsOnScreen.

Returns:

  1. number width Width of the camera on the screen in pixels
  2. number height Height of the camera on the screen in pixels
camera:setPixelDimensionsOnScreen (width, height)
Set the dimensions of a camera on the screen.

Parameters:

  • width number Width of the camera on the screen in pixels
  • height number Height of the camera on the screen in pixels
camera:get2dZoomFactor ()
Get the 2d zoom factor (defaults to 1).

Returns:

    number zoom_factor the zoom factor of the camera
camera:set2dZoomFactor (zoom_factor)
Set the 2d zoom factor. Only the 2d layer will be affected. A large zoom factor will zoom into the details of the scene, a small zoom factor will show more surroundings from a larger distance.

Parameters:

  • zoom_factor number the new zoom factor
camera:gameUnitToPixels ()
Get the extend in pixels a game unit in the 2d world has at the default camera zoom level of 1.

For 3d, a game unit should be roughly one meter and there is no generic way to tell how this ends up in pixels due to the very dynamic way objects look depending on your position in the world etc.

Returns:

    number pixels The amount of pixels that equals one game unit at default zoom of 1

Usage:

     -- Get the amount of pixels for one game unit for the first (=default) camera:
 local pixels = blitwizard.graphics.getCameras()[1]:gameUnitToPixels()
generated by LDoc 1.3.11