More work on user manuals

Documentation/Manuals/Native/User/advancedStartup.md

@@ -0,0 +1,67 @@
+Advanced startup				{#advancedStartup}
+===============
+
+We have already shown how to perform basic start-up of a Banshee application.
+
+~~~~~~~~~~~~~{.cpp}
+Application::startUp(VideoMode(1280, 720), "My app", false);
+
+// Set up your scene here
+
+Application::instance().runMainLoop();
+Application::shutDown();
+~~~~~~~~~~~~~
+
+This form of start-up is adequate for applications using only the scene object/component system for implementing game logic. Applications wishing to implement systems that aren't components must use a more advanced form of start up. Implementing systems in such a way is necessary when extending the engine with new features, using low level rendering API, or if its just a preference.
+
+To perform advanced start-up you must create your own version of the **Application** class by deriving from it. Once derived you can override any of the following methods:
+ - @ref bs::Application::onStartUp "Application::onStartUp()" - Called when the application is first starting up.
+ - @ref bs::Application::preUpdate "Application::preUpdate()" - Called every frame, just before component and plugin updates are triggered.
+ - @ref bs::Application::postUpdate "Application::postUpdate()" - Called every frame, after component and plugin updates are triggered.
+ - @ref bs::Application::onShutDown "Application::onShutDown()" - Called just before the application is about to shut down.
+ 
+~~~~~~~~~~~~~{.cpp}
+class MyApplication : public Application
+{
+public:
+	// Pass along the start-up structure to the parent
+	MyApplication(const START_UP_DESC& desc)
+		:Application(desc)
+	{ }
+
+private:
+	void onStartUp() override
+	{
+		// Ensure all parent systems are initialized first
+		Application::onStartUp();
+
+		// Do your own initialization (i.e. start your custom systems)
+	}
+
+	void onShutDown() override
+	{
+		// Do your own shut-down (i.e. shut down your custom systems)
+
+		// Shut-down engine components
+		Application::onShutDown();
+	}
+
+	void preUpdate() override
+	{
+		// Execute per-frame logic of your custom systems (optionally do it in postUpdate)
+	}
+};
+~~~~~~~~~~~~~
+
+Once you have your own application override, you can now start the application by calling @ref bs::Application::startUp<T> "Application::startUp<T>()" with the template parameter being your application override class. Everything else regarding start-up remains the same.
+
+~~~~~~~~~~~~~{.cpp}
+Application::startUp<MyApplication>(VideoMode(1280, 720), "My app", false);
+
+// Set up your scene here
+
+Application::instance().runMainLoop();
+Application::shutDown();
+~~~~~~~~~~~~~
+
+Take a look at the *ExampleLowLevelRendering* for a working example of how to use advanced start-up in order to perform low-level rendering.

Documentation/Manuals/Native/User/cursors.md

@@ -0,0 +1,68 @@
+Cursors					{#cursors}
+===============
+
+If developing an application that accepts mouse input, you can control the behaviour of the cursor through the @ref bs::Cursor "Cursor" class, accessible globally through @ref bs::gCursor "gCursor()". It allows you to manipulate cursor position, look and clipping behaviour.
+
+# Position
+You can retrieve the current position of the cursor by calling @ref bs::Cursor::getScreenPosition "Cursor::getScreenPosition()". Note that this same information is reported by the input system, and is generally preferred to use those values instead.
+
+You can also change the cursor position directly by calling @ref bs::Cursor::setScreenPosition "Cursor::setScreenPosition()". Values for both methods will be in pixels relative to the user's screen (or screens).
+
+~~~~~~~~~~~~~{.cpp}
+// Move cursor to the top left corner of the screen
+gCursor().setScreenPosition(Vector2I(0, 0));
+~~~~~~~~~~~~~
+
+# Visibility
+Cursor can be hidden by calling @ref bs::Cursor::hide "Cursor::hide()", and shown again by calling @ref bs::Cursor::show "Cursor::show()".
+
+~~~~~~~~~~~~~{.cpp}
+// Hide the cursor if user is holding right mouse button (e.g. rotating the camera)
+if(gInput().isButtonHeld(BC_MOUSE_RIGHT))
+	gCursor().hide();
+else
+	gCursor().show();	
+~~~~~~~~~~~~~
+
+# Icon
+You can change the cursor's icon by calling @ref bs::Cursor::setCursor(CursorType) "Cursor::setCursor()" and specifying one of the builtin cursor types, as @ref bs::CursorType "CursorType" enum.
+
+~~~~~~~~~~~~~{.cpp}
+// Change to wait cursor in case we're doing some processing
+gCursor().setCursor(CursorType::Wait);
+~~~~~~~~~~~~~
+
+You can also define your own cursor icons by calling @ref bs::Cursor::setCursorIcon(const String&, const PixelData&, const Vector2I&) "Cursor::setCursorIcon()". You'll need to provide a unique name for your cursor, a **PixelData** object containing the image to use, and a cursor *hot-spot*. Hot spot determines at which part of the image will the user's clicks be registered (e.g. in case of an arrow icon, it would be at the top of the arrow).
+
+~~~~~~~~~~~~~{.cpp}
+SPtr<PixelData> pixelData = ...; // Manually fill or read pixel data from a texture
+Vector2I hotSpot(5, 5);
+
+gCursor().setCursorIcon("MyCustomCursor", *pixelData, hotSpot);
+~~~~~~~~~~~~~
+
+Once you have registered the icon you can apply it by calling an overload of @ref bs::Cursor::setCursor(const String&) "Cursor::setCursor()" that accepts a cursor name.
+
+~~~~~~~~~~~~~{.cpp}
+gCursor().setCursor("MyCustomCursor");
+~~~~~~~~~~~~~
+
+You can also change icons of the built-in cursor types by calling @ref bs::Cursor::setCursorIcon(CursorType, const PixelData&, const Vector2I&) "Cursor::setCursorIcon()" overload that accepts a **CursorType** as its first parameter.
+
+# Clipping
+Sometimes it is useful to limit the cursor to a specific area of the screen (e.g. if playing in windowed mode its useful to limit the cursor to the window). For this purpose you can use either of these methods:
+ - @ref bs::Cursor::clipToWindow "Cursor::clipToWindow()" - Accepts a **RenderWindow** as a parameter, and will limit cursor movement within that window.
+ - @ref bs::Cursor::clipToRect "Cursor::clipToRect()" - Accepts an area relative to the user's screen, to which to limit the movement to.
+
+~~~~~~~~~~~~~{.cpp}
+// Limit cursor movement to the primary application window
+SPtr<RenderWindow> window = gApplication().getPrimaryWindow();
+gCursor().clipToWindow(window);
+~~~~~~~~~~~~~
+
+When you wish to disable clipping, you can call @ref bs::Cursor::clipDisable "Cursor::clipDisable()".
+
+~~~~~~~~~~~~~{.cpp}
+// Remove any limits to cursor movement
+gCursor().clipDisable();
+~~~~~~~~~~~~~

Documentation/Manuals/Native/manuals.md

@@ -1,9 +1,11 @@
 Manuals									{#manuals}
 ===============
-[TOC]
 
-# User guides
+# Quick start
+[Getting started](@ref gettingStarted) - This is a short guide on how to create a fully functional Banshee application, aimed to get you up and running quickly, without going into too much detail.
 
+# User manuals
+A complete set of manuals covering all major functionality provided by Banshee, starting with basics and slowly guiding you through more advanced concepts. This should be the primary entry point for new users.
 - [Startup and main loop](@ref startup)
 - [Scene objects and components](@ref scenesAndComponents)
 - **Resources**
@@ -62,16 +64,16 @@ Manuals									{#manuals}
  - [Manipulating textures](@ref advancedTextures)
  - [Offscreen rendering](@ref offscreenRendering)
  - [Creating meshes](@ref creatingMeshes)
- - [Advanced RTTI](@ref advancedRtti) 
+ - [Advanced startup](@ref advancedStartup)
+ - [Advanced RTTI](@ref advancedRtti)
+ - [Cursors](@ref cursors)
  
-# Developer guides
-
-Here you will find a list of all manuals relating to Banshee's native code, primarily focusing on explaining the engine internals instead of the user-facing code. The manuals are roughly ordered in the way they should be read, although if you are interested in a specific topic feel free to skip ahead as manuals often contain cross references to prerequisite manuals.
+# Developer manuals
+A set of manuals covering advanced functionality intented for those wanting to extend the engine or tinker with the internals, rather than for normal users. You are expected to have read the user manuals first.
 
 ## General guides
 Name                                      | Description
 ------------------------------------------|-------------
-[Getting started](@ref gettingStarted)    | Shows how to perform some basic operations using Banshee's user-facing interface. Allows you to get a general idea of how Banshee works.
 [Architecture](@ref architecture)         | Gives you an overview of the entire architecture of Banshee. Useful starting point for those modifying engine internals as it provides a way to identify major systems.
 [Utilities](@ref utilities)               | Provides an overview of a variety of utility systems used throughout Banshee.
 [Core thread](@ref coreThread)            | Explains how core (rendering) thread works, how it interacts with simulation thread, what are core objects and how to create your own.

Source/BansheeEngine/Include/BsCursor.h

@@ -116,5 +116,8 @@ namespace bs
 		INT32 mActiveCursorId;
 	};
 
+	/** Easy way to access Cursor. */
+	BS_EXPORT Cursor& gCursor();
+
 	/** @} */
 }

Source/BansheeEngine/Source/BsCursor.cpp

@@ -177,4 +177,9 @@ namespace bs
 		CustomIcon& customIcon = mCustomIcons[mActiveCursorId];
 		Platform::setCursor(customIcon.pixelData, customIcon.hotSpot);
 	}
+
+	Cursor& gCursor()
+	{
+		return static_cast<Cursor&>(Cursor::instance());
+	}
 }