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.

The 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_ prefix

  • test_vector2, test_vector3, test_vector4: Tests for the Vector2, Vector3 and Vector4 classes
  • test_quaternion, test2_quaternion: Tests for the Quaternion class
  • test_matrix4x4, test2_matrix4x4: Tests for the Matrix4x4 class
  • test_array, test_hashmap, test2_hashmap, test_list, test_staticarray, test_string: Tests for the Array, Hashmap, List, StaticArray and String classes, plus their iterators
  • test_algorithms_array, test_algorithms_hashmap, test_algorithms_list: Tests for the template based algorithms operating on the Array, Hashmap and List classes

Samples with the apptest_ prefix

  • 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 onFrameStart() and onFrameEnd() functions.

Similarly to the onInit() function, there is a callback that is invoked when the user quits the application: the onShutdown() function.

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.