Getting started

This manual offers a quick overview of commonly used Banshee functionality, in order to give you a better idea of how Banshee works. For a fully working example check out the ExampleGettingStarted project available with the source code.

Starting an application

Banshee is started through the Application interface. To start the engine you need to provide it with a description of the primary render window.

The application is started by calling Application::startUp(), after which you can set up your custom code in the form of components (see later). Finally you can run the main loop with Application::runMainLoop() which will execute your code and actually get everything in motion.

Once the main loop terminates use Application::shutDown() to clean everything up.

// Start an application in windowed mode using 1280x720 resolution
Application::startUp(
VideoMode(1280, 720), // Window resolution
"My app", // Window title
false); // True for fullscreen, false for windowed
// Set up your scene here
Application::instance().runMainLoop();
Application::shutDown();

Importing resources

To import a resource from a third party format into an engine-readable format use the Importer module. A variety of formats like PNG, JPG, PSD, FBX, etc. are supported. Read the Resource basics and import manual for more information about resources and import.

In the example below we'll import a Mesh and a Texture.

HMesh dragonModel = gImporter().import<Mesh>("Dragon.fbx");
HTexture dragonTexture = gImporter().import<Texture>("Dragon.psd");

Setting up a material

Once we have a mesh and a texture we need some way to apply that texture to the mesh. For that reason we first import a Shader that describes how is an object rendered, which we then use to create a Material which allows us to apply our previously loaded Texture.

Banshee uses .bsl files to describe shaders and you can learn more about BSL syntax in the Banshee Shading Language manual. To learn more about materials and how to use them read the Materials manual.

HShader diffuse = gImporter().import<Shader>("Diffuse.bsl");
HMaterial dragonMaterial = Material::create(diffuse);
dragonMaterial->setTexture("albedo", dragonTexture);

Adding an object for rendering

To actually make our mesh render with our material, we need to add a SceneObject onto which we attach a CRenderable component. This component allows us to set up a mesh and a material, after which they will be automatically rendered to the active camera.

To learn more about scene objects and components read the Scene objects and components manual. You can use the same approach we followed here to add your own custom components, containing custom code - read more about custom components in the Creating custom components manual.

You can also read the Rendering objects manual to learn more about how the CRenderable component works.

HSceneObject dragonSO = SceneObject::create("Dragon");
HRenderable renderable = dragonSO->addComponent<CRenderable>();
renderable->setMesh(dragonModel);
renderable->setMaterial(dragonMaterial);

Adding a scene camera

In order to actually see our object we need to set up a camera. First create a new SceneObject onto which you can then attach a CCamera component. After that we position the SceneObject so it is looking at the object we set up in previous steps. Camera required an output surface, for which we use the primary application window as retrieved from Application::getPrimaryWindow(). Learn more about cameras in the Cameras manual.

SPtr<RenderWindow> window = gApplication().getPrimaryWindow();
HSceneObject sceneCameraSO = SceneObject::create("SceneCamera");
HCamera sceneCamera = sceneCameraSO->addComponent<CCamera>(window);
sceneCameraSO->setPosition(Vector3(40.0f, 30.0f, 230.0f));
sceneCameraSO->lookAt(Vector3(0, 0, 0));

Adding a GUI element

Finally you might want to add a GUI to your application. Similar to above, create a new SceneObject onto which we add a new CCamera used only for rendering GUI. Since we don't want it to render normal scene objects, we let it's filter layers to 0.

We also add a CGUIWidget component onto the same SceneObject, which is used as a container for all GUI elements. After that we add a couple of GUIButtons to the GUI.

Read the GUI elements and related manuals for more information about GUI.

HSceneObject guiSO = SceneObject::create("GUI");
HCamera guiCamera = guiSO->addComponent<CCamera>(window);
guiCamera->setLayers(0); // Force camera to ignore normal scene geometry
HGUIWidget gui = guiSO->addComponent<CGUIWidget>(guiCamera);
GUIPanel* guiPanel = gui->getPanel();
GUILayout* guiLayout = guiPanel->addNewElement<GUILayoutY>();
guiLayout->addNewElement<GUIButton>(HString(L"Click me!"));
guiLayout->addNewElement<GUIButton>(HString(L"Click me too!"));

Final result

TODO_IMAGE

There is a lot more to Banshee, but hopefully this gave you a quick taste of how it works. Continue reading other manuals and the API reference for more information.