Probably the easiest way to start understading how to use the nCine API is through the sample sources installed alongside the project.
Please refer to the Build the samples page for instructions on how to build them on your platform.
There are two kinds of samples, the ones with a
test_ prefix are console only programs aimed to test the containers, the iterators and the algorithms.
apptest_ prefixed samples open a window, use input and events and they all have a common
main() function as an entry point to set things up.
Samples with the
test_vector4: Tests for the
test2_quaternion: Tests for the
test2_matrix4x4: Tests for the
test_string: Tests for the
Stringclasses, plus their iterators
test_algorithms_list: Tests for the template based algorithms operating on the
Samples with the
apptest_animsprites: A test showing an animated sprite walking around the screen that you can control with different input devices
apptest_audio: A test playing a sound and a background music and that you can control with the keyboard
apptest_font: A test showing various font rendering examples with different settings for kerning, color and typeface
apptest_joystick: A test that shows on screen every value for joystick axes and buttons, with an additional visual feedback
apptest_multitouch: A test that uses multiple touch pointers to move sprites on the screen. It also shows information about touch events.
apptest_particles: A test that shows how to use a particle system. You can move the emitter around with different input devices
apptest_rotozoom: A test rendering many rotating sprites on screen with a common dummy parent that is also rotating and zooming
apptest_scene: A test rendering some bouncing sprites on screen
apptest_texformats: A test about texture loading and MIP maps. You can change the texture and the MIP level with different input devices
Understand the basics
Application events: IAppEventHandler
The entry point of every nCine application is a class that implements the
IAppEventHandler interface and a function that returns a new object of that type.
The function is called inside the
main() function and allows the engine to dispatch events about the lifecycle of the application.
The first callback function to be called is
onPreInit(), it is called with the application configuration as its only parameter, allowing for the user to specify some initialization settings. Be aware that inside this function you cannot invoke any engine API call as the engine is yet to be fully initialized.
After that it is the turn of the
onInit() callback function, which is called once the engine is fully initialized and you can start using it.
At this point the test applications usually load resources (textures, fonts, sounds), retrieve a reference to the root of the scene graph and start populating it with nodes like sprites or particle systems.
Once this last callback returns your application is considered initialized and it will begin to render frames. To update the state of an object in the scenegraph per frame you can use
Similarly to the
onInit() function, there is a callback that is invoked when the user quits the application: the
Input events: IInputEventHandler
The class handling the application events is usually also handling input events by implementing the IInputEventHandler.
There are different types of input events that the handler can listen for: mouse, keyboard, touchscreen, joystick. In order for your application to listen for a particular event just implement the callback function and process the generated event.