Added Window and Camera user guides, began work on Texture user manual

Documentation/Manuals/Native/User/cameras.md

@@ -1,6 +1,95 @@
 Cameras 						{#cameras}
 ===============
 
-Cameras represent the user's view into the scene. They are components represented by the @ref bs::CCamera "Camera" component.
+Cameras represent the user's view into the scene, and any graphical application will require at least one camera for the user to be able to see anything. 
 
-Their position and orientation defines which part of the scene will the user see. Their parameters like field of view, projection mode and aspect ratio define how is the 3D scene transformed into the 2D surface. And they also define an output surface into which the scene will be rendered to.
+They have parameters like position and orientation which define what part of the scene will the user see. Additionally, their parameters like field of view, projection mode and aspect ratio define how is the application scene transformed into the 2D output visible to the user. 
+
+Finally, everything that the camera sees is output to what we call a render target. Render targets can be windows, which we explained in the previous chapter, or off-screen surfaces, as we'll explain later.
+
+Cameras are represented by the @ref bs::CCamera "Camera" component, and they can be created as any other component. At minimum their constructor requires a render target onto which they will output their contents.
+
+Lets create a camera that renders to the primary render window:
+
+~~~~~~~~~~~~~{.cpp}
+SPtr<RenderWindow> primaryWindow = gApplication().getPrimaryWindow();
+
+HSceneObject cameraSO = SceneObject::create("Camera");
+HCamera camera = cameraSO->addComponent<CCamera>(primaryWindow);
+~~~~~~~~~~~~~
+
+Once the camera has been created we can move and orient it using the **SceneObject** transform, as explained earlier. For example:
+~~~~~~~~~~~~~{.cpp}
+// Move camera to 100 units high, and 500 units away from the center
+cameraSO->setPosition(Vector3(0f, 100f, 500f));
+
+// Orient the camera so it is looking at the center
+cameraSO->lookAt(Vector3(0f, 0f, 0f));
+~~~~~~~~~~~~~
+
+Once set up, any rendered objects in the camera's view will be displayed on the selected render target, which is in this case the primary application window.
+
+However you might want to customize camera's parameters to get the exact feel you need. Lets cover some of the available parameters.
+
+# Projection type
+All cameras can be in two projection modes: *Perspective* and *Ortographic*. They can be changed by calling @ref bs::CCamera::setProjectionType "CCamera::setProjectionType()".
+
+## Perspective cameras
+This mode simulates human vision, where objects farther away appear smaller. This is what you will need for most 3D applications.
+
+~~~~~~~~~~~~~{.cpp}
+camera->setProjectionType(PT_PERSPECTIVE);
+~~~~~~~~~~~~~
+
+![Dragon drawn using the perspective camera](PerspectiveCamera.png)  
+
+## Ortographic
+Renders the image without perspective distortion, ensuring objects remain the same size regardless of the distance from camera, essentially "flattening" the image. Useful for 2D applications.
+
+~~~~~~~~~~~~~{.cpp}
+camera->setProjectionType(PT_ORTHOGRAPHIC);
+~~~~~~~~~~~~~
+
+![Dragon drawn using the ortographic camera](OrtographicCamera.png)  
+
+# Field of view
+This is a parameter only relevant for perspective cameras. It controls the horizontal angle of vision - increasing it means the camera essentially has a wider lens. Modify it by calling @ref bs::CCamera::setHorzFOV "CCamera::setHorzFOV()".
+
+Example of setting the FOV to 90 degrees:
+~~~~~~~~~~~~~{.cpp}
+camera->setHorzFOV(Degree(90));
+~~~~~~~~~~~~~
+
+Vertical FOV is automatically determined from the aspect ratio.
+
+# Aspect ratio
+Aspect ratio allows you to control the ratio of the camera's width and height. It can be set by calling @ref bs::CCamera::setAspectRatio "CCamera::setAspectRatio()". 
+
+Normally you want to set it to the ratio of the render target's width and height, as shown below.
+
+~~~~~~~~~~~~~{.cpp}
+SPtr<RenderWindow> primaryWindow = gApplication().getPrimaryWindow();
+auto& windowProps = newWindow->getProperties();
+
+float aspectRatio = windowProps.getWidth() / (float)windowProps.getHeight();
+camera->setAspectRatio(aspectRatio);
+~~~~~~~~~~~~~
+
+But you are also allowed to freely adjust it for different effects.
+
+# Ortographic size
+This parameter has a similar purpose as field of view, but is used for ortographic cameras instead. It controls the width and height (in world space) of the area covered by the camera. It is set by calling @ref bs::CCamera::setOrthoWindow "CCamera::setOrthoWindow()".
+
+Set up ortographic view that shows 500x500 units of space, along the current orientation axis.
+~~~~~~~~~~~~~{.cpp}
+camera->setOrthoWindow(500, 500);
+~~~~~~~~~~~~~
+
+For example, if you are making a 2D game, your world units are most likely pixels. In which case you will want to set the ortographic size to the same size as the render target size (resolution):
+
+~~~~~~~~~~~~~{.cpp}
+SPtr<RenderWindow> primaryWindow = gApplication().getPrimaryWindow();
+auto& windowProps = newWindow->getProperties();
+
+camera->setOrthoWindow(windowProps.getWidth(), windowProps.getHeight());
+~~~~~~~~~~~~~

Documentation/Manuals/Native/User/importingTextures.md

@@ -0,0 +1,68 @@
+Importing textures 						{#importingTextures}
+===============
+
+Textures are images that are applied to meshes in order to achieve greater surface detail. In Banshee they are represented with the @ref bs::Texture "Texture" class. A texture is a resource, meaning it can be imported, saved and loaded as we described in Resource manuals.
+
+![Mesh without (left) and with (right) a texture](TexturedMesh.png)  
+
+# Importing a texture
+Textures can be imported from various third party formats, using the importer.
+
+~~~~~~~~~~~~~{.cpp}
+// Import a texture named "myTexture.jpg" from the disk
+HTexture texture = gImporter().import<Texture>("myTexture.jpg");
+~~~~~~~~~~~~~
+
+Supported formats are:
+ - BMP
+ - DDS
+ - EXR
+ - GIF
+ - HDR
+ - ICO
+ - JPG
+ - PNG
+ - PSD
+ - RAW
+ - TARGA
+ - TIFF
+ 
+# Customizing import
+Texture import can be customized by providing a @ref bs::TextureImportOptions "TextureImportOptions" object to the importer.
+
+~~~~~~~~~~~~~{.cpp}
+auto importOptions = TextureImportOptions::create();
+// Set required options here (as described below)
+
+HTexture texture = gImporter().import<Texture>("myTexture.jpg", importOptions);
+~~~~~~~~~~~~~
+
+A variety of properties can be customized on import, the most important of which being image format, mip-map generation, sRGB state and caching.
+
+## Image format
+// TODO
+
+## Mip-maps
+// TODO
+
+## sRGB
+// TODO
+
+## Caching
+// TODO
+
+# Texture properties
+Once a texture has been imported, you can retrieve its properties like width, height and format by calling @ref bs::Texture::getProperties "Texture::getProperties()", which returns a @ref bs::TextureProperties "TextureProperties" object.
+
+~~~~~~~~~~~~~{.cpp}
+// Retrieve and print out various texture properties
+auto& props = texture->getProperties();
+
+gDebug().logDebug("Width: " + toString(props.getWidth()));
+gDebug().logDebug("Height: " + toString(props.getHeight()));
+gDebug().logDebug("Format: " + toString(props.getFormat()));
+gDebug().logDebug("Num. mip maps: " + toString(props.getNumMipmaps()));
+~~~~~~~~~~~~~
+
+# Rendering using textures
+Once imported a texture can be assigned to a **Material** in order to be used for rendering. We will cover materials in a later chapter.

Documentation/Manuals/Native/User/windows.md

@@ -1,12 +1,12 @@
-Windows					{#window}
+Windows					{#windows}
 ===============
 
-A window represents the final destination where the applications rendered output gets displayed to the user. It has a title, size and a position. Window can cover the entirety of the user's screen (fullscreen mode) or just part of it (windowed mode). In Banshee a window is represented using the @ref bs::RenderWindow "RenderWindow" class.
+A window represents the final destination where the application's rendered output gets displayed to the user. It has a title, size and a position. Window can cover the entirety of the user's screen (fullscreen mode) or just part of it (windowed mode). In Banshee a window is represented using the @ref bs::RenderWindow "RenderWindow" class.
 
 ![Render window](RenderWindow.png)  
 
 # Primary window
-When we initialized the application by calling **Application::startUp** in a previous chapter a primary window was created for us by default. You can access this window through @ref bs::Application::getPrimaryWindow "Application::getPrimaryWindow".
+When we initialized the application by calling **Application::startUp** in a previous chapter a primary window was created for us by default. You can access this window through @ref bs::Application::getPrimaryWindow "Application::getPrimaryWindow()".
 
 ~~~~~~~~~~~~~{.cpp}
 SPtr<RenderWindow> primaryWindow = gApplication().getPrimaryWindow();
@@ -15,7 +15,7 @@ SPtr<RenderWindow> primaryWindow = gApplication().getPrimaryWindow();
 > **gApplication()** is just a shortcut for **Application::instance()** we used earlier.
 
 # Creating windows
-You can also create your own windows by filling out the @ref bs::RENDER_WINDOW_DESC "RENDER_WINDOW_DESC" structure and calling @ref bs::RenderWindow::create "RenderWindow::create".
+You can also create your own windows by filling out the @ref bs::RENDER_WINDOW_DESC "RENDER_WINDOW_DESC" structure and calling @ref bs::RenderWindow::create "RenderWindow::create()".
 
 ~~~~~~~~~~~~~{.cpp}
 RENDER_WINDOW_DESC desc;
@@ -23,11 +23,12 @@ desc.videoMode = VideoMode(1280, 720);
 desc.fullscreen = false;
 desc.title = "Helper window".
 
+// Creates a new non-fullscreen window with size 1280x720, at the center of the screen
 SPtr<RenderWindow> newWindow = RenderWindow::create(desc);
 ~~~~~~~~~~~~~
 
 # Destroying windows
-You can destroy a window by calling @ref RenderWindow::destroy "RenderWindow::destroy". 
+You can destroy a window by calling @ref bs::RenderWindow::destroy "RenderWindow::destroy()". 
 
 ~~~~~~~~~~~~~{.cpp}
 newWindow->destroy();
@@ -36,4 +37,92 @@ newWindow->destroy();
 > Do not destroy the primary window, as it will result in undefined behaviour.
 
 # Manipulating windows
+Window size can be changed by calling @ref bs::RenderWindow::resize "RenderWindow::resize()".
 
+~~~~~~~~~~~~~{.cpp}
+newWindow->resize(1920, 1080);
+~~~~~~~~~~~~~
+
+And they can be moved by calling @ref bs::RenderWindow::move "RenderWindow::move()". Movement is not relevant for windows in fullscreen mode.
+
+~~~~~~~~~~~~~{.cpp}
+newWindow->move(0, 0); // Move to top right of the screen
+~~~~~~~~~~~~~
+
+If you wish to switch from windowed to fullscreen mode call @ref bs::RenderWindow::setFullscreen "RenderWindow::setFullscreen()".
+
+~~~~~~~~~~~~~{.cpp}
+newWindow->setFullscreen(VideoMode(1920, 1080));
+~~~~~~~~~~~~~
+
+And if you wish to switch from fullscreen to windowed call @ref bs::RenderWindow::setWindowed "RenderWindow::setWindowed()".
+
+~~~~~~~~~~~~~{.cpp}
+newWindow->setWindowed(1280, 720);
+~~~~~~~~~~~~~
+
+# Window properties
+You can access current properties of the window, like its size and position, by calling @ref bs::RenderWindow::getProperties "RenderWindow::getProperties", which returns a @ref bs::RenderWindowProperties "RenderWindowProperties" object. For example let's print out current window's size:
+
+~~~~~~~~~~~~~{.cpp}
+auto& props = newWindow->getProperties();
+
+gDebug().logDebug(toString(props.getWidth()) + " x " + toString(props.getHeight()));
+~~~~~~~~~~~~~
+
+> gDebug() is a shortcut to the logging system, as explained in the [logging manual](@ref logging), covered later.
+
+# Window events
+Sometimes you might want to be notified if the user resizes the window externally, in which case use the @ref bs::RenderWindow::onResized "RenderWindow::onResized" event.
+
+~~~~~~~~~~~~~{.cpp}
+void notifyResized()
+{
+	gDebug().logDebug("Window was resized.");
+}
+
+newWindow->onResized.connect(&notifyResized);
+~~~~~~~~~~~~~
+
+> **RenderWindow::onResized** is an example of an event. They are explained later in the [event manual](@ref events).
+
+# Video modes
+During window creation and calls to **RenderWindow::setFullscreen** we have seen the use of the @ref bs::VideoMode "VideoMode" class. This class allows you to specify the resolution of the window, along with an optional refresh rate and output monitor (in case of multi-monitor setups, to choose on which monitor to show the window). 
+
+You can create your own **VideoMode** with custom parameters (as we did so far), or you can query for all video modes supported by the user's GPU by calling @ref bs::RenderAPI::getVideoModeInfo() "RenderAPI::getVideoModeInfo()". This will return a @ref bs::VideoModeInfo "VideoModeInfo" object that contains information about all available monitors, their supported resolutions and refresh rates.
+
+An example on how to use the video mode enumeration to set a window to fullscreen mode using the user's desktop resolution of the primary monitor:
+~~~~~~~~~~~~~{.cpp}
+VideoModeInfo videoModeInfo = RenderAPI::getVideoModeInfo();
+VideoOutputInfo primaryMonitorInfo = videoModeInfo.getOutputInfo(0); // 0th monitor is always primary
+
+newWindow->setFullscreen(primaryMonitorInfo.getDesktopVideoMode());
+~~~~~~~~~~~~~
+
+An example to make a window fullscreen on a secondary monitor if one is available:
+~~~~~~~~~~~~~{.cpp}
+VideoModeInfo videoModeInfo = RenderAPI::getVideoModeInfo();
+
+UINT32 numOutputs = videoModeInfo.getNumOutputs();
+if(numOutputs > 1)
+{
+	VideoOutputInfo secondaryMonitorInfo = videoModeInfo.getOutputInfo(1);
+	newWindow->setFullscreen(secondaryMonitorInfo.getDesktopVideoMode());
+}
+~~~~~~~~~~~~~
+
+And an example how to enumerate and print all available resolutions on the primary monitor:
+~~~~~~~~~~~~~{.cpp}
+VideoModeInfo videoModeInfo = RenderAPI::getVideoModeInfo();
+VideoOutputInfo primaryMonitorInfo = videoModeInfo.getOutputInfo(0);
+
+UINT32 numVideoModes = primaryMonitorInfo.getNumVideoModes();
+for (UINT32 i = 0; i < numVideoModes; i++)
+{
+	const VideoMode& curVideoMode = primaryMonitorInfo.getVideoMode(i);
+
+	String videoModeString = toString(curVideoMode.getWidth()) + " x " + toString(curVideoMode.getHeight()) + " at " + toString(curVideoMode.getRefreshRate()) + "Hz";
+	
+	gDebug().logDebug(videoModeString);
+}
+~~~~~~~~~~~~~

Documentation/Manuals/Native/manuals.md

@@ -6,11 +6,14 @@ Manuals									{#manuals}
 
 - [Startup and main loop](@ref startup)
 - [Scene objects and components](@ref scenesAndComponents)
-- Resources
+- **Resources**
  - [Basics and import](@ref resourceBasicsAndImport)
  - [Saving and loading](@ref resourceSavingAndLoading)
-- Graphics 
+- **Graphics**
  - [Windows](@ref windows)
+ - [Cameras](@ref cameras)
+ - [Importing textures](@ref importingTextures)
+ - [Importing meshes](@ref importingMeshes)
  
 # Developer guides