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.

The samples are all prefixed with apptest_, they open a window, use input and events and they all have a common main() function as the entry point to set things up.

List of samples

  • 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_camera: A test showing plenty of moving sprites on the screen and with a free camera that you can zoom, pan and rotate with different input devices
  • 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.