README
¶
Toolbox - a simple, minimal wrapper over the go SDL bindings
Package Toolbox is a package that simplifies the handling graphics, windows and key presses offered by the underlying SDL library.
The package is not intended as a generic game library or as a simplification of the SDL library. The package is intended solely for use in the Code Club to support very simple games.
Warning: This package is not safe in the presence of multiple go routines. This is by design. This package contains an internal, unguarded, unexported global variables. Given the use cases of this package, this is an acceptable trade off.
Dependencies
Toolbox relies on the go-sdl2 package. See here
for the installation instructions.
Please see the COPYRIGHT file for copyright information.
Please see the LICENSE file for license information.
Documentation
¶
Overview ¶
Package toolbox is a package that simplifies the handling graphics, windows and key presses offered by the underlying SDL library. The package is not intended as a generic game library or as a simplification of the SDL library. The package is intended solely for use in the Code Club to support very simple games.
Warning: This package is not safe in the presence of multiple go routines. This is by design. This package contains an internal, unguarded, unexported global variables. Given the use cases of this package, this is an acceptable trade off.
Index ¶
- Constants
- func ClearBackground()
- func Close()
- func DestroyGraphic(g Graphic)
- func DestroyWindow(window Window)
- func DrawPoint(x, y int)
- func GetSizeOfGraphic(g Graphic) (width, height int)
- func GetTickCount() int64
- func Initialise()
- func Pause(numberOfTicks int64)
- func RenderGraphic(g Graphic, x, y, width, height int)
- func SetBackgroundColour(r, g, b int)
- func SetDrawColour(c Colour)
- func ShowWindow()
- type Colour
- type Graphic
- type Key
- type Window
Constants ¶
const ( KeyNone = iota // no key was pressed KeyUp // the up cursor key was pressed KeyDown // the down cursor key was pressed KeyPause // the Pause key was pressed ButtonClose // the windows close button was clicked on )
Possible constants returned from GetKey()
Variables ¶
This section is empty.
Functions ¶
func ClearBackground ¶
func ClearBackground()
ClearBackground clears the window using the background colour set with SetBackgroundColour The effect will not be seen until ShowWindow is called.
ClearBackgroundColour panics if:
1. The toolbox has not been initialised.
2. CreateWindow has not been called.
func Close ¶
func Close()
Close closes the toolbox, releasing any underlying resources. It must be called before the program exits to prevent a resource leak. The toolbox cannot be used again until the Initialise function is called again.
func DestroyGraphic ¶
func DestroyGraphic(g Graphic)
DestroyGraphic destroys a Graphic that has been previously loaded by LoadGraphic. It must be called once for each graphic that has been loaded before the program exists.
DestroyGraphic will panic if:
1. The Graphic, g, does not contain a Graphic type.
2. The toolbox has not been initialised.
func DestroyWindow ¶
func DestroyWindow(window Window)
DestroyWindow closes the window, freeing any resources as it does so. It must be called for each window that has been created before the program exists.
DestroyWindow will panic if:
1. The toolbox has not been initialised.
2. The window is invalid
3. CreateWindow has not been called.
func DrawPoint ¶
func DrawPoint(x, y int)
DrawPoint plots a single point (pixel) on the screen. The colour is set via SetDrawColour. The effect will not be seen until after ShowWindow has been called.
The colour is specified as a Colour type.
DrawPoint panics if:
1. The toolbox has not been initialised.
2. CreateWindow has not been called.
3. Plotting the point itself fails. This would indicate in internal invarient failure.
func GetSizeOfGraphic ¶
GetSizeOfGraphic returns the width and heigth of the Graphic, g. GetSizeOfGraphic returns two numbers of type int. The first numnber, marked as 'width', is the width of the Graphic, g, in pixels. The second number, marked as 'height' is the height of the Graphic, g, in pixels.
GetSizeOfGraphic will panic if:
1. The Graphic, g, does not contain a Graphic type.
2. The toolbox has not been initialised.
func GetTickCount ¶
func GetTickCount() int64
GetTickCount returns the amount of time that has passed since the toolbox was initialised.
The toolbox counts time in 'ticks'. One 'tick' is 1/1000th of a second. Time starts when Initialise() is called. The number for ticks always increases. The number of ticks cannot be reset, and time does cannot run backwards.
If the function succeeds then a variable of type int64 will be returned back to the calling function. It is the programmers responsibility to store this in a variable of type int64. GetTickCount returns an int64 type, not an int because the maximum number of ticks is to large to store in an int.
GetTickCount will panic if:
1. The toolbox has not been initialised.
func Initialise ¶
func Initialise()
Initialise prepares the toolbox for use. It must be called before any other functions in the tool box are used.
func Pause ¶
func Pause(numberOfTicks int64)
Pause pauses execution of the game for the specified number of ticks. During the pause period nothing will happen. All input will be ignored and the window will not redraw.
The duration of the pause must be specified in ticks in a variable of type int64
Pause will panic if:
1. The toolbox has not been initialised.
2. The numnber of ticks is negative.
func RenderGraphic ¶
RenderGraphic draws the Graphic, g, on the screen at postion (x,y). 'width' and 'height' specifiy the width and height of the Graphic, g.
RenderGraphic will panic if: 1. The Graphic, g, does not contain a Graphic type.
2. The toolbox has not been initialised.
3. Any one of x, y, width or height are negative
func SetBackgroundColour ¶
func SetBackgroundColour(r, g, b int)
SetBackgroundColour sets the background colour of the window. This is the colour that will be used to fill the window when ClearBackground() is called. The effect will not be seen until ShowWindow is called.
The colour is specified as 3 integers. One for red, one for green and one for blue. The range of each of these numbers is 0..255, including 0 and 255.
SetBackgroundColour panics if:
1. The toolbox has not been initialised.
2. CreateWindow has not been called.
3. If any of r, g, or b lies outside the range.
func SetDrawColour ¶
func SetDrawColour(c Colour)
SetDrawColour sets the colour that will be used when a point is plotted. The effect will not be seen until after DrawPoint and ShowWindow have been called.
The colour is specified as a Colour type.
SetDrawColour panics if:
1. The toolbox has not been initialised.
2. CreateWindow has not been called.
3. If any of red, green, blue, or alpha components of the colour are outside of the range [0..255].
func ShowWindow ¶
func ShowWindow()
ShowWindow redraws the window, displaying any changes that have been made.
ShowWindow panics if:
1. The toolbox has not been initialised.
2. CreateWindow has not been called.
Types ¶
type Colour ¶
Colour is the tye that represens a solout, held as a Read, Green Blue, Alpha tuple. Note: the English spelling.
type Graphic ¶
Graphic is the type used for an image or graphic.
func LoadGraphic ¶
LoadGraphic loads a graphic from disk or panics trying. The image can be in BMP, GIF, JPEG, LBM, PCX, PNG, PNM, TGA, TIFF, WEBP, XCF, XPM, or XV format. The user must supply the filename of the graphic file to load, in the parameter filename.
If the function succeeds then a variable of type Graphic will be returned back to the calling function. It is the programmers responsibility to store this in a variable of type Graphic.
If the function fails it will panic and crash the program. The reasons for a panic are:
1. The toolbox has not been initalised
2. The filename does not exist, or is otherwise inaccessable. The specific reason will be contained in the panic message itself. This message will be prefixed with "Failed to load file: ".
3. The file could not be converted into a Graphic type. Again the specific reason will be contained in the panic message itself. This message will be prefixed with "Failed to create Graphic: "
type Key ¶
type Key int
Key is the type that represents the key or window button that has been pressed.
func GetKey ¶
func GetKey() Key
GetKey returns the key or button that has been pressed by the user. Possible return values are the constants:
KeyNone - indicating that no key, or an unrecognised key as been pressed KeyUp - indicating that the up cursor key has been pressed KeyDown - indicating that the down cursor key has been pressed KeyPause - indicating that the pause key has been presses ButtonClose - indicating that the windows close button has been pressed
GetKey will panic if:
1. The toolbox has not been initialised.
2. If an internal check fails. In this case the panic message is "KeyDownEvent type assertion failed!" This is highly unlikely to occur and indcates a problem with the underlying graphics llibrary.
type Window ¶
Window is the type of the window that the game takes place within.
func CreateWindow ¶
CreateWindow creates a window with the specified title, width and height. The resulting window will be created with a title bar, a title, a close button and is moveable. The window cannot be resized.
Create window is designed to create a single window. You cannot use CreateWindow more than once without first calling DestroyWindow.
If the function succeeds then a variable of type Window will be returned back to the calling function. It is the programmers responsibility to store this in a variable of type Window.
CreateWindow will panic if:
1. The toolbox has not been initialised.
2. Either of the width or height are negative
3. CreateWindow has been called more than once.
Source Files
Directories