More work on user manuals

Documentation/Manuals/Native/User/drawing.md

@@ -0,0 +1,23 @@
+Drawing									{#drawing}
+===============
+[TOC]
+
+With all the objects from the previous chapters bound to the pipeline we are almost ready to draw an object. When drawing you must ensure a pipeline state of **GraphicsPipelineState** type is bound, instead of **ComputePipelineState**.
+
+Next you need to specify what type of primitives you wish to draw by calling @ref bs::ct::RenderAPI::setDrawOperation "ct::RenderAPI::setDrawOperation()", which accepts any of the type defined in @ref bs::DrawOperationType "DrawOperationType". This determines how are contents of the index buffer interpreted (or vertex buffer if index isn't available). The available draw types are:
+ - @ref bs::DOT_POINT_LIST "DOT_POINT_LIST" - Each vertex represents a point.
+ - @ref bs::DOT_LINE_LIST "DOT_POINT_LIST" - Each sequential pair of vertices represent a line.
+ - @ref bs::DOT_LINE_STRIP "DOT_LINE_STRIP" - Each vertex (except the first) forms a line with the previous vertex.
+ - @ref bs::DOT_TRIANGLE_LIST "DOT_TRIANGLE_LIST" - Each sequential 3-tuple of vertices represent a triangle.
+ - @ref bs::DOT_TRIANGLE_STRIP "DOT_TRIANGLE_STRIP" - Each vertex (except the first two) form a triangle with the previous two vertices.
+ - @ref bs::DOT_TRIANGLE_FAN "DOT_TRIANGLE_FAN" - Each vertex (except the first two) form a triangle with the first vertex and previous vertex.
+
+~~~~~~~~~~~~~{.cpp}
+// We're drawing a triangle list
+RenderAPI& rapi = RenderAPI::instance();
+rapi.setDrawOperation(DOT_TRIANGLE_LIST);
+~~~~~~~~~~~~~
+
+Finally you can now draw the object by calling @ref bs::ct::RenderAPI::drawIndexed() "ct::RenderAPI::drawIndexed()".
+
+TODO

Documentation/Manuals/Native/gameObjects.md

@@ -1,118 +0,0 @@
-Game objects								{#gameObjects}
-===============
-[TOC]
-
-@ref bs::GameObject "Game objects" represent the core of your game and where most of the gameplay code will be located. There are two types of game objects:
- - @ref bs::SceneObject "SceneObject" - Contains zero or multiple @ref bs::Component "components". Has a position/rotation/scale in space, and can be parented to other scene objects.
- - @ref bs::Component "Components" - Provides a set of functionality used for customizing a @ref bs::SceneObject "SceneObject". You can build your own components, and if fact this is where majority of your gameplay code will belong. A variety of built-in components are also provided.
- 
-# Scene objects {#gameObjects_a}
-To create a @ref bs::SceneObject "SceneObject" call @ref bs::SceneObject::create "SceneObject::create" with a name of the object. The name doesn't have to be unique but is useful for identifying the object.
-
-~~~~~~~~~~~~~{.cpp}
-HSceneObject mySO = SceneObject::create("MySceneObject");
-~~~~~~~~~~~~~
-
-All @ref bs::SceneObject "SceneObjects" are organized in a hierarchy. Initially when a new @ref bs::SceneObject "SceneObject" is created it is parented to the scene root. However you can parent it to another scene object like so:
-
-~~~~~~~~~~~~~{.cpp}
-HSceneObject myParentSO = SceneObject::create("MyParentSceneObject");
-HSceneObject mySO = SceneObject::create("MySceneObject");
-mySO->setParent(myParentSO);
-~~~~~~~~~~~~~
-
-You can iterate over all children of a @ref bs::SceneObject "SceneObject" by calling @ref bs::SceneObject::getChild "SceneObjects::getChild"/@ref bs::SceneObject::getNumChildren "SceneObjects::getNumChildren". You can also search for a specific child by name with @ref bs::SceneObject::findChild "SceneObjects::findChild".
-
-@ref bs::SceneObject "SceneObjects" can also be moved, rotated and scaled in the coordinate system. Use methods like @ref bs::SceneObject::setPosition "SceneObject::setPosition", @ref bs::SceneObject::setRotation "SceneObject::setRotation", @ref bs::SceneObject::setScale "SceneObject::setScale" to set these values relative to the parent object. You can also use @ref bs::SceneObject::setWorldPosition "SceneObject::setWorldPosition", @ref bs::SceneObject::setWorldRotation "SceneObject::setWorldRotation", @ref bs::SceneObject::setWorldScale "SceneObject::setWorldScale" to set them relative to the world space. A variety of helper methods like @ref bs::SceneObject::lookAt "SceneObject::lookAt" also exists. For example:
-
-~~~~~~~~~~~~~{.cpp}
-HSceneObject mySO = SceneObject::create("MySceneObject");
-
-Vector3 position(0, 0, 50);
-Vector3 lookAt(0, 0, 0);
-
-// Object at (0, 0, 50) looking towards the origin
-mySO->setPosition(position);
-mySO->setLookAt(lookAt);
-~~~~~~~~~~~~~
-
-Once you are done with a scene object, call @ref bs::SceneObject::destroy "SceneObject::destroy". This will remove the scene object and all of its children out of the scene.
-~~~~~~~~~~~~~{.cpp}
-HSceneObject mySO = SceneObject::create("MySceneObject");
-mySO->destroy()
-~~~~~~~~~~~~~
-
-Scene objects aren't very useful on their own however. Each scene object can have multiple @ref bs::Component "Components" attached.
-
-# Components {#gameObjects_b}
-Components provide logic that customizes a scene object. To attach a @ref bs::Component "Component" to a scene object use @ref bs::SceneObject::addComponent<T, Args...> "SceneObject::addComponent<T>". For example if we wanted to add the built-in @ref bs::CCamera "CCamera" component:
-~~~~~~~~~~~~~{.cpp}
-HSceneObject mySO = SceneObject::create("MySceneObject");
-HCamera camera = mySO->addComponent<CCamera>();
-~~~~~~~~~~~~~
-
-Once a component is registered with a scene object its code will be executed as long as the scene object is active and not destroyed. Use @ref bs::SceneObject::setActive "SceneObject::setActive" to activate and deactivate a scene object. Deactive object will also deactivate all children and their components.
-
-To search for a component on a scene object use @ref bs::SceneObject::getComponent<T> "SceneObject::getComponent<T>" like so:
-~~~~~~~~~~~~~{.cpp}
-HCamera camera = mySO->getComponent<CCamera>(); // Returns CCamera component if it exists on the scene object
-~~~~~~~~~~~~~
-
-If you wish to remove a component, call @ref bs::Component::destroy "Component::destroy".
-~~~~~~~~~~~~~{.cpp}
-HCamera camera = mySO->getComponent<CCamera>();
-camera->destroy();
-~~~~~~~~~~~~~
-
-## Custom components {#gameObjects_b_a}
-Using existing components is useful, but main purpose of components is for the user to implement their own gameplay code. To create your own component simply implement the @ref bs::Component "Component" interface.
-
-The @ref bs::Component "Component" interface provides several methods which you can override with your own code:
- - @ref bs::Component::onInitialized "Component::onInitialized" - Called once when the component is first instantiated. You should use this instead of the constructor for initialization.
- - @ref bs::Component::update "Component::update" - Called every frame while the game is running and the component is enabled.
- - @ref bs::Component::onEnabled "Component::onEnabled" - Called whenever a component is enabled, or instantiated as enabled in which case it is called after @ref bs::Component::onInitialized "Component::onInitialized".
- - @ref bs::Component::onDisabled "Component::onDisabled" - Called whenever a component is disabled. This includes destruction where it is called before @ref bs::Component::onDestroyed "Component::onDestroyed". 
- - @ref bs::Component::onDestroyed "Component::onDestroyed" - Called before the component is destroyed. Destruction is usually delayed until the end of the current frame unless specified otherwise in a call to @ref bs::Component::destroy "Component::destroy". 
- - @ref bs::Component::onTransformChanged "Component::onTransformChanged" - Called when the transform of the owning scene object changes. You must subscribe to this event by calling @ref bs::Component::_setNotifyFlags "Component::_setNotifyFlags".
- 
-Since components are a part of the scene you must also make sure to implement their @ref bs::RTTITypeBase "RTTIType", so they can be saved and loaded. Read the [RTTI](@ref rtti) manual for more information. Their creation differs slightly to normal RTTI objects: when overloading @ref bs::RTTITypeBase::newRTTIObject "RTTIType::newRTTIObject" make sure to use `GameObjectRTTI::createGameObject<T>` to create the component, instead of manually creating the shared pointer. This ensures that the component handle is properly created.
-
-# Game object handles {#gameObjects_c}
-We have seen game object handles a lot in this manual, but haven't talked about them. All game objects are referenced via a @ref bs::GameObjectHandle<T> "GameObjectHandle<T>". They act similar to pointers where you can use the pointer member access "->" operator to access the underlying game object, while the normal member access "." operator can be used for operating directly on the handle data. 
-
-You can use @ref bs::GameObjectHandle<T>::isDestroyed "GameObjectHandle<T>::isDestroyed" to check if a game object a handle is pointing to has been destroyed.
-
-To create your own game object handle it is suggested you create a `typedef` and prefix your component name with an "H", like so:
-~~~~~~~~~~~~~{.cpp}
-class MyComponent : public Component
-{
- ...
-};
-
-typedef GameObjectHandle<MyComponent> HMyComponent;
-~~~~~~~~~~~~~
-
-# Prefabs {#gameObjects_d}
-@ref bs::Prefab "Prefabs" allow you to store groups of scene objects (and their components) and then re-use them. A prefab can be an entire scene or just a small subset of scene objects.
-
-To create one call @ref bs::Prefab::create "Prefab::create" with a @ref bs::SceneObject "SceneObject" you want to create a prefab of. The object, all of its children and all of the components will be stored in the prefab. You can then save that prefab to disk like any other @ref bs::Resource "Resource" (see the [resources](@ref resources) manual), and load it later.
-
-@ref bs::Prefab "Prefabs" can be instantiated back into @ref bs::SceneObject "SceneObjects" by calling @ref bs::Prefab::instantiate "Prefab::instantiate".
-
-For example:
-~~~~~~~~~~~~~{.cpp}
-HSceneObject mySO = SceneObject::create("MySceneObject");
-... create a more complex hierarchy with components here ...
-HPrefab myPrefab = Prefab::create(mySO);
-... potentially save the prefab for later use ...
-// Or use it right away
-HSceneObject clonedSO = myPrefab->instantiate();
-~~~~~~~~~~~~~
-
-Prefabs are used for more than just cloning. Any scene objects that are instantiated from a @ref bs::Prefab "Prefabs" (including the original scene object that the prefab was created from) become permanently linked to that scene object hierarchy. We call such scene objects "prefab instances". You can use @ref bs::SceneObject::getPrefabParent "SceneObject::getPrefabParent" to find a @ref bs::Prefab "Prefab" that a scene object might be an instance of.
-
-This can be useful if you have many prefab instances of a particular prefab (e.g. buildings or trees in a level). You can quickly apply changes to all scene objects linked to a particular prefab. Simply make your modifications on an existing prefab instance, or create a new scene object hierarchy. Then call @ref bs::Prefab::update "Prefab::update" with the new data. This will replace contents of the prefab with the new hierarchy. After that you can use @ref bs::PrefabUtility::updateFromPrefab "PrefabUtility::updateFromPrefab" on all prefab instances and they will replace their contents with the new contents of the prefab.
-
-You are also allowed to make changes to prefab instances. @ref bs::PrefabUtility::updateFromPrefab "PrefabUtility::updateFromPrefab" will try its best to keep the changes made, while also updating the underlying hierarchy. Obviously this is not possible if the hierarchy fully changes, but in most cases there will only be minor changes.
-
-In case you made some changes to a prefab instance you can revert back to original prefab state by calling @ref bs::PrefabUtility::revertToPrefab "PrefabUtility::revertToPrefab". If you wish to break a link of a scene object with a prefab, call @ref bs::SceneObject::breakPrefabLink "PrefabUtility::breakPrefabLink".

Documentation/Manuals/Native/geometry.md

@@ -0,0 +1,116 @@
+Geometry									{#geometry}
+===============
+[TOC]
+
+In this chapter we'll show how is geometry of an object represented, and how to bind that geometry to be rendered. The geometry is represented using three object types:
+ - @ref bs::ct::VertexBuffer "ct::VertexBuffer" - Contains per-vertex information
+ - @ref bs::ct::VertexDeclaration "ct::VertexDeclaration" - Contains meta-data about which properties each entry in the vertex buffer contains
+ - @ref bs::ct::IndexBuffer "ct::IndexBuffer" - Contains a list of indices that map into the vertex buffer and determine in what order are vertices assembled into primitives (triangles, lines or points)
+
+# Vertex buffer {#geometry_a}
+**ct::VertexBuffer** is a buffer that contains all vertices of the object we wish to render. When drawing the vertices will be interpreted as primitives (either points, lines or triangles) and rendered. Each vertex can have one or multiple properties associated with it.
+
+To create a vertex buffer call @ref bs::ct::VertexBuffer::create "ct::VertexBuffer::create()" with a populated @ref bs::VERTEX_BUFFER_DESC "VERTEX_BUFFER_DESC" structure. You need to know the size of an individual vertex (determined by the properties each vertex requires) and the number of vertices. 
+
+~~~~~~~~~~~~~{.cpp}
+// Create a vertex buffer containing 8 vertices with just a vertex position (3D float)
+VERTEX_BUFFER_DESC desc;
+desc.vertexSize = sizeof(Vector3);
+desc.numVerts = 8;
+
+SPtr<VertexBuffer> vb = VertexBuffer::create(desc);
+~~~~~~~~~~~~~
+
+Once the vertex buffer is created you will want to populate it with some data. For this you can use any of the following methods:
+ - @ref bs::ct::VertexBuffer::lock "ct::VertexBuffer::lock()" - Locks a specific region of the vertex buffer and returns a pointer you can then use for reading and writing. Make sure to specify valid a @ref bs::GpuLockOptions "GpuLockOptions" signaling whether you are planning on reading or writing from the buffer. Once done call @ref bs::ct::VertexBuffer::unlock "ct::VertexBuffer::unlock()" to make the locked region accessible to the GPU again.
+ - @ref bs::ct::VertexBuffer::writeData "ct::VertexBuffer::writeData()" - Writes an entire block of memory at once.
+ 
+~~~~~~~~~~~~~{.cpp}
+// Fill out a vertex buffer using lock/unlock approach
+Vector3* positions = (Vector3*)vb->lock(0, sizeof(Vector3) * 8, GBL_WRITE_ONLY_DISCARD);
+positions[0] = Vector3(0, 0, 0);
+positions[1] = Vector3(10, 0, 0);
+// ... assign other 6 positions
+vb->unlock();
+~~~~~~~~~~~~~  
+ 
+Once a vertex buffer is created and populated with data, you can bind it to the pipeline by calling @ref bs::ct::RenderAPI::setVertexBuffers "ct::RenderAPI::setVertexBuffers()". You can bind one or multiple vertex buffers at once. If binding multiple vertex buffers they must all share the same vertex count, but each may contain different vertex properties (e.g. one might contain just positions and UV, while another might contain tangents and normals).
+
+~~~~~~~~~~~~~{.cpp}
+// Bind a single vertex buffer
+RenderAPI& rapi = RenderAPI::instance();
+rapi.setVertexBuffers(0, { vb });
+~~~~~~~~~~~~~
+
+# Vertex declaration {#geometry_b}
+Before vertex buffer(s) can be used for rendering, you need to tell the pipeline what kind of information does each vertex in the vertex buffer(s) contain. This information lets the GPU know how to map per-vertex properties like position & UV coordinates, to vertex GPU program inputs. This is done by creating a @ref bs::ct::VertexDeclaration "ct::VertexDeclaration" object.
+
+In order to create one you call @ref bs::ct::VertexDeclaration::create "ct::VertexDeclaration::create()" which accepts a **VertexDataDesc** as its parameter. We already explained to how create a **VertexDataDesc** in the @ref creatingMeshes manual.
+
+~~~~~~~~~~~~~{.cpp}
+// Create a vertex descriptor with a position, normal and UV coordinates
+SPtr<VertexDataDesc> vertexDesc = VertexDataDesc::create();
+vertexDesc->addVertElem(VET_FLOAT3, VES_POSITION);
+vertexDesc->addVertElem(VET_FLOAT3, VES_NORMAL);
+vertexDesc->addVertElem(VET_FLOAT2, VES_TEXCOORD);
+
+// Create a vertex declaration
+SPtr<VertexDeclaration> vertexDecl = VertexDeclaration::create(vertexDesc);
+~~~~~~~~~~~~~
+
+If you are binding multiple vertex buffers, then make use of the @p streamIdx parameter when registering elements in **VertexDataDesc**. This index will let the pipeline know in which vertex buffer to find the provided element.
+
+Once created you can bind the declaration to the pipeline by calling @ref bs::ct::RenderAPI::setVertexDeclaration "ct::RenderAPI::setVertexDeclaration()".
+
+~~~~~~~~~~~~~{.cpp}
+RenderAPI& rapi = RenderAPI::instance();
+rapi.setVertexDeclaration(vertexDecl);
+~~~~~~~~~~~~~
+
+**ct::VertexDeclaration** can also be used for querying information about vertex size and offsets, which can be useful for creating the vertex buffer. First retrieve the @ref bs::VertexDeclarationProperties "VertexDeclarationProperties" object by calling @ref bs::ct::VertexDeclaration::getProperties() "ct::VertexDeclaration::getProperties()". Then you can query for information like vertex size by calling @ref bs::VertexDeclarationProperties::getVertexSize "VertexDeclarationProperties::getVertexSize()".
+
+~~~~~~~~~~~~~{.cpp}
+auto& props = vertexDecl->getProperties();
+
+// Gets the size of an individual vertex in the 0th stream (stream index maps to bound vertex buffer at the same index)
+UINT32 vertexSize = props.getVertexSize(0);
+~~~~~~~~~~~~~
+
+# Index buffer {#geometry_c}
+Finally, before drawing you want to also bind an index buffer. Index buffers are optional, but you will usually want to use them. Each entry in an index buffer points to a vertex in the vertex buffer, and sequential indexes are used for form primitives for rendering (e.g. every three indices will form a triangle). This ensures you can re-use same vertex in multiple primitives, saving on memory and bandwidth, as well as create more optimal vertex order for GPU processing. Without an index buffer the vertices are instead read sequentially in the order they are defined in the vertex buffer.
+
+To create an index buffer call @ref bs::ct::IndexBuffer::create "ct::IndexBuffer::create()" with a populated @ref bs::INDEX_BUFFER_DESC "INDEX_BUFFER_DESC" structure. The call requires a number of indices and their type. Indices can be either 16- or 32-bit. 
+
+~~~~~~~~~~~~~{.cpp}
+// Create an index buffer containing 36 16-bit indices
+INDEX_BUFFER_DESC desc;
+desc.indexType = IT_16BIT;
+desc.numIndices = 36;
+
+SPtr<IndexBuffer> ib = IndexBuffer::create(desc);
+~~~~~~~~~~~~~
+
+Reading and writing from/to the index buffer has the identical interface to the vertex buffer, so we won't show it again.
+
+To bind an index buffer to the pipeline call @ref bs::ct::RenderAPI::setIndexBuffer "ct::RenderAPI::setIndexBuffer()".
+
+~~~~~~~~~~~~~{.cpp}
+// Bind an index buffer
+RenderAPI& rapi = RenderAPI::instance();
+rapi.setIndexBuffer(ib);
+~~~~~~~~~~~~~
+
+# Geometry from meshes {#geometry_d}
+All the objects we described so far can be retrieved directly from a **ct::Mesh**. This allows you to manually bind imported mesh geometry to the pipeline. 
+
+This fact can also be exploited for easier vertex/index buffer and declaration creation, as creating a **ct::Mesh** is usually simpler than creating these objects individually.
+
+To retrieve an index buffer from a **ct::Mesh** call @ref bs::ct::Mesh::getIndexBuffer() "ct::Mesh::getIndexBuffer()". Vertex buffer(s) and vertex declaration can be retrieved from a @ref bs::ct::VertexData "ct::VertexData" structure returned by @ref bs::ct::Mesh::getVertexData() "ct::Mesh::getVertexData()". **ct::VertexDeclaration** can then be retrieved from @ref bs::ct::VertexData::vertexDeclaration "ct::VertexData::vertexDeclaration", and vertex buffers from @ref bs::ct::VertexData::getBuffer "ct::VertexData::getBuffer()"
+
+~~~~~~~~~~~~~{.cpp}
+SPtr<Mesh> mesh = ...;
+SPtr<IndexBuffer> meshIB = mesh->getIndexBuffer();
+SPtr<VertexData> vertexData = mesh->getVertexData();
+SPtr<VertexDeclaration> = vertexData->vertexDeclaration;
+SPtr<VertexBuffer> meshVB = vertexData->getBuffer(0);
+~~~~~~~~~~~~~

Documentation/Manuals/Native/manuals.md

@@ -2,7 +2,7 @@ Manuals									{#manuals}
 ===============
 
 # 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.
+TODO - [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.
@@ -77,10 +77,11 @@ A set of manuals covering advanced functionality intented for those wanting to e
  - [Core thread](@ref coreThread)
  - [GPU programs](@ref gpuPrograms)
  - [Non-programmable states](@ref nonProgrammableStates)
+ - [Geometry](@ref geometry)
+ - [Render targets](@ref renderTargets)
+ - [Drawing](@ref drawing) 
  - [Load-store textures](@ref loadStoreTextures)
- - [Vertex & index buffer](@ref vertexIndexBuffers)
  - [Generic buffers](@ref genericBuffers)
- - [Drawing](@ref drawing)
  - [Compute](@ref compute)
  - [Command buffers](@ref commandBuffers)
 
@@ -89,7 +90,6 @@ Name                                      | Description
 ------------------------------------------|-------------
 [Utilities](@ref utilities)               | Provides an overview of a variety of utility systems used throughout Banshee.
 [Resources](@ref resources)  			  | Explains how resources work, including saving, loading and creating brand new resource types.
-[Game objects](@ref gameObjects)          | Explains what are scene objects and components and how can you use them to create your scene.
 [Scripting](@ref scripting)               | Shows you how to interact with the scripting system, and how to expose C++ objects to the scripting API.
 [Renderer](@ref renderer)    	  		  | Explains how the renderer works on the low level, and how to create a custom renderer so you may fully customize the look of your application.
 [BSLFX](@ref bslfx)    	  		  		  | Provides a reference for the Banshee Shading Language FX syntax.
@@ -106,5 +106,5 @@ Name                                      | Description
 ------------------------------------------|-------------
 [Textures](@ref textures)                 | Shows you how to create, use and manipulate textures.
 [Meshes](@ref meshes)                     | Shows you how to create, use and manipulate meshes.
-[Render targets](@ref renderTargets)	  | Shows you how to create and use render textures and windows.
-[Materials](@ref materials)				  | Shows you how to create and use materials and shaders.
+[Materials](@ref materials)				  | Shows you how to create and use materials and shaders.
+[Render API](@ref renderAPI)

Documentation/Manuals/Native/renderTargets.md

@@ -2,150 +2,62 @@ Render targets				{#renderTargets}
 ===============
 [TOC]
 
-Render targets represent destination surfaces onto which objects are rendered. They can be textures or windows.
+Before we can actually render an object, we must also specify a render target which will serve as a surface to render the output to. We already covered render target creation in @ref windows and @ref offscreenRendering manuals. The only difference is that in those manuals we used a **Camera** component to set the target, and relied on the renderer to make use of it. 
 
-In Banshee render targets are represented with:
- - Windows - @ref bs::RenderWindow "RenderWindow" and @ref bs::ct::RenderWindow "ct::RenderWindow"
- - Textures - @ref bs::RenderTexture "RenderTexture" and @ref bs::ct::RenderTexture "ct::RenderTexture"
- 
-Each type comes in two variants, both of which provide almost equivalent functionality, but the former is for use on the simulation thread, and the latter is for use on the core thread. If you are confused by the dual nature of the objects, read the [core thread](@ref coreThread) manual. 
-
-We're going to focus on the simulation thread implementation in this manual, and then note the differences in the core thread version at the end.
-
-# Render windows {#renderTargets_a}
-Render windows are render targets that are backed up by OS-specific windows. Each application must have at least one render window in order to display its contents to the user. All created windows are double or triple buffered, meaning they internally have multiple render surfaces that are swapped between during rendering (see the section about rendering later). This makes them useful for displaying final rendering results in the screen, while render textures are used for intermediary processing.
-
-Creating a @ref bs::RenderWindow "RenderWindow" involves filling out the @ref bs::RENDER_WINDOW_DESC "RENDER_WINDOW_DESC" and calling @ref bs::RenderWindow::create "RenderWindow::create". This method also accepts a parent render window, in case your window is meant to be a child of another window. @ref bs::RENDER_WINDOW_DESC "RENDER_WINDOW_DESC" contains many properties, and you should read its reference for information about what all of them do. In this manual we'll just cover the most important settings:
-
-@ref bs::RENDER_WINDOW_DESC::videoMode "RENDER_WINDOW_DESC::videoMode"
- - This is the only field that is required, all others are optional. It controls the resolution of the render target, and output monitor and its refresh rate. 
-
-You can create a @ref bs::VideoMode "VideoMode" manually by providing a custom resolution and a refresh rate, or you can query @ref bs::RenderAPI::getVideoModeInfo "RenderAPI::getVideoModeInfo" to retrieve all available video modes for all available monitors. The latter is the suggested method as it guarantees the video mode will be compatible with the hardware.
-
-@ref bs::RENDER_WINDOW_DESC::fullscreen "RENDER_WINDOW_DESC::fullscreen"
- - Controlls whether or not to create the window in fullscreen mode. Fullscreen mode gives your application the exclusive access for rendering device. Without it refresh rate and vsync options are ignored.
+In this chapter we'll show how to manually bind a render target for rendering, as well as some other render target related operations.
 
-@ref bs::RENDER_WINDOW_DESC::vsync "RENDER_WINDOW_DESC::vsync"
- - Controls whether the GPU should wait for the vertical sync before presenting the rendered image. This prevents screen tearing. 
+# Binding {#renderTargets_a}
+Use @ref bs::ct::RenderAPI::setRenderTarget "ct::RenderAPI::setRenderTarget()" to bind a render target for rendering.
 
-@ref bs::RENDER_WINDOW_DESC::multisampleCount "RENDER_WINDOW_DESC::multisampleCount"
- - Controls whether you want the render window target to be a multisampled surface. This allows you to perform MSAA antialiasing and similar effects. Most applications will set this to false and instead use multi-sampled render textures, and use the render window for displaying the final resolved (antialiased) image.
-
-@ref bs::RENDER_WINDOW_DESC::depthBuffer "RENDER_WINDOW_DESC::depthBuffer"
- - Controls whether the render window should also contain a depth/stencil buffer. This is useful if you are not using intermediary render textures and are rendering directly to the render window. Most applications will set this to false and create the depth/stencil buffer manually as a render texture (see below).
-
-@ref bs::RENDER_WINDOW_DESC::gamma "RENDER_WINDOW_DESC::gamma"
- - Controls whether or not should pixels written to be render target be automatically gamma corrected (multiplied by inverse sRGB gamma). If your rendering calculations are in linear space and you aren't performing gamma correction manually you should set this to true.
-
-An example that creates a 1280x720 window:
 ~~~~~~~~~~~~~{.cpp}
-RENDER_WINDOW_DESC desc;
-desc.videoMode = VideoMode(1280, 720);
-desc.fullscreen = false;
+SPtr<RenderTarget> target = ...; // Create a RenderTexture or RenderWindow as described in earlier chapters
 
-SPtr<RenderWindow> window = RenderWindow::create(desc);
+RenderAPI& rapi = RenderAPI::instance();
+rapi.setRenderTarget(target);
 ~~~~~~~~~~~~~
 
-## Manipulating the window {#renderTargets_a_a}
-Once the window is created you can perform the following actions:
- - @ref bs::RenderWindow::resize "RenderWindow::resize"
- - @ref bs::RenderWindow::move "RenderWindow::move"
- - @ref bs::RenderWindow::setFullscreen "RenderWindow::setFullscreen"
- - @ref bs::RenderWindow::setWindowed "RenderWindow::setWindowed"
- 
-And more. Read the @ref bs::RenderWindow "RenderWindow" reference for the rest.
-
-You can also use the window to convert between screen and window coordinates by calling:
- - @ref bs::RenderWindow::screenToWindowPos "RenderWindow::screenToWindowPos"
- - @ref bs::RenderWindow::windowToScreenPos "RenderWindow::windowToScreenPos"
- 
-# Render textures {#renderTargets_b}
-Render textures are simpler than windows, but you are given more control over their format. Internally a render texture is just a @ref bs::Texture "Texture" created with the @ref bs::TU_RENDERTARGET "TU_RENDERTARGET" flag. Read the [texture](@ref textures) manual to learn how to create such textures.
-
-Render texture must contain at least one texture (color surface), but may optionally also contain a depth-stencil surface. Depth-stencil surface is also a @ref bs::Texture "Texture", but one created with the @ref bs::TU_DEPTHSTENCIL "TU_DEPTHSTENCIL" flag. Depth stencil surfaces only accept specific pixel formats starting with "D" prefix in @ref bs::PixelFormat "PixelFormat". Dimensions of the depth stencil surface must match the color surface.
-
-To create a render texture call @ref bs::RenderTexture::create(const RENDER_TEXTURE_DESC&) "RenderTexture::create" with a populated @ref bs::RENDER_TEXTURE_DESC "RENDER_TEXTURE_DESC" structure. This structure expects a reference to one or more color surface textures, and an optional depth-stencil surface texture. For each of those you must also specify the face and mip level onto which to render, in case your texture has multiple.
+This will bind the entirety of the render target surface for rendering. If you just want to render to a portion of the target you can also call @ref bs::ct::RenderAPI::setViewport "ct::RenderAPI::setViewport()". It accepts a 2D rectangle whose coordinates should be in [0, 1] range and it specifies in which portion of the render target should rendering occurr.
 
-For example:
 ~~~~~~~~~~~~~{.cpp}
-// Create a 1280x720 texture with 32-bit RGBA format
-TEXTURE_DESC colorDesc;
-colorDesc.type = TEX_TYPE_2D;
-colorDesc.width = 1280;
-colorDesc.heigth = 720;
-colorDesc.format = PF_R8G8B8A8;
-colorDesc.usage = TU_RENDERTARGET;
-
-HTexture color = Texture::create(colorDesc);
-
-// Create a 1280x720 texture with a 32-bit depth-stencil format
-TEXTURE_DESC depthDesc;
-depthDesc.type = TEX_TYPE_2D;
-depthDesc.width = 1280;
-depthDesc.heigth = 720;
-depthDesc.format = PF_R8G8B8A8;
-depthDesc.usage = TU_DEPTHSTENCIL;
-
-HTexture depthStencil = Texture::create(depthDesc);
-
-RENDER_TEXTURE_DESC desc;
-desc.colorSurfaces[0].texture = color;
-desc.colorSurfaces[0].face = 0;
-desc.colorSurfaces[0].mipLevel = 0;
-
-desc.depthStencilSurface.texture = depthStencil;
-desc.depthStencilSurface.face = 0;
-desc.depthStencilSurface.mipLevel = 0;
-
-SPtr<RenderTexture> renderTexture = RenderTexture::create(desc);
+// Render to the center of the render target, at 50% of its size
+RenderAPI& rapi = RenderAPI::instance();
+rapi.setViewport(Rect2(0.25f, 0.25f, 0.5f, 0.5f));
 ~~~~~~~~~~~~~
 
-Optionally you can also use the overloaded @ref bs::RenderTexture::create(const TEXTURE_DESC&, bool, PixelFormat) "RenderTexture::create" to create the texture surfaces and the render texture in one go:
+## Advanced binding {#renderTargets_a_a}
+**ct::RenderAPI::setRenderTarget()** also has a couple of parameters to control more advanced behaviour:
+ - @p readOnlyDepthStencil - Guarantees that the depth/stencil portion of the render target will not be written to. This allows the depth/stencil texture to be bound both as a render target, as well as a normal GPU program input.
+ - @p loadMask - Mask described by @ref bs::RenderSurfaceMaskBits "RenderSurfaceMaskBits" which controls if current contents of any of the render target surfaces should be preserved. By default the system doesn't guarantee the contents will be preserved and data is instead undefined. In certain cases (like blending operations) you want to preserve the contents, in which case specify the necessary flags to tell the system which surfaces need their contents preserved.
+
 ~~~~~~~~~~~~~{.cpp}
-// Has the same result as above:
-TEXTURE_DESC colorDesc;
-colorDesc.type = TEX_TYPE_2D;
-colorDesc.width = 1280;
-colorDesc.heigth = 720;
-colorDesc.format = PF_R8G8B8A8;
-
-SPtr<RenderTexture> renderTexture = RenderTexture::create(colorDesc, true, PF_D24S8);
+// Bind a render target with read-only depth/stencil, and preserve the existing contents of depth-stencil buffer on bind
+RenderAPI& rapi = RenderAPI::instance();
+rapi.setRenderTarget(target, true, RT_DEPTH);
 ~~~~~~~~~~~~~
+ 
+# Clearing {#renderTargets_b}
+Usually a render target will be re-used many times. Unless you are sure that every use will completely overwrite the render target contents, it can be beneficial (and in some cases necessary) to clear the render target to some value. Call @ref bs::ct::RenderAPI::clearRenderTarget "ct::RenderAPI::clearRenderTarget()" to clear the currently bound render target. 
 
-## Multiple surfaces {#renderTargets_b_a}
-Render textures can also contain multiple color surfaces (up to 8). Such targets simply allow you to write more data at once, improving performance as you do not need to execute multiple draw calls. To create a texture with multiple color surfaces simply fill out other entries of @ref bs::RENDER_TEXTURE_DESC "RENDER_TEXTURE_DESC::colorSurfaces" array and proceed the same as in the above example.
-
-Use `BS_MAX_MULTIPLE_RENDER_TARGETS` to learn what is the maximum supported number of color surfaces per target (usually 8). All color surfaces (and the depth/stencil surface) must have the same dimensions and sample count.
-
-## Multi-sampled surfaces {#renderTargets_b_c}
-Same as windows, render textures can be created with support for multiple samples per pixel. This allows affects such as multi-sampled antialiasing and similar. To create a multi-sampled render texture simply create a @ref bs::Texture "Texture" with its `multisampleCount` parameter larger than one, which you then use to initialize a render texture. Make sure that all surfaces (including depth-stencil) in a render texture have the same number of samples.
-
-In order to display a multi-sampled render texture on the screen you need to resolve the texture into a non-multi-sampled one. For windows this is done automatically for you, but for textures you must do it manually. You can do it from the GPU program (render API dependant), or by calling @ref bs::ct::Texture::copy "ct::Texture::copy". 
-
-@ref bs::ct::Texture::copy "ct::Texture::copy" works only on the core thread, and it will copy contents of one texture to another texture. If you ensure that the source texture is multi-sampled but the destination is not, it will automatically resolve the multi-sampled texture.
-
-# Priority {#renderTargets_c}
-All render targets have a priority that can be set by calling @ref bs::RenderTarget::setPriority "RenderTarget::setPriority". This priority can be used as a hint to the renderer in which order should the targets be rendered to. Targets with higher priority will be rendered to before targets with lower priority. If you are rendering manually using the @ref bs::RenderAPI "RenderAPI" then this value is not used.
+The first parameter represents a @ref bs::FrameBufferType "FrameBufferType" of which portions of the target to clear. Second, third and fourth parameters represent the clear values for the color, depth and stencil surfaces, respectively. In case you want to clear only a specific color surface (in case they are multiple), you can use the fifth parameter as a bitmask of which color surfaces to clear.
 
-# Using render targets {#renderTargets_d}
-Now that we know how to create a render target we can use it in one of various ways: render to it, read from it, clear it, or use its contents to render something else.
+~~~~~~~~~~~~~{.cpp}
+// Clear color and depth surfaces. All color surfaces are cleared to blue color, while depth is cleared to the value of 1
+RenderAPI& rapi = RenderAPI::instance();
+rapi.clearRenderTarget(FBT_COLOR | FBT_DEPTH, Color::Blue, 1, 0, 0xFF);
+~~~~~~~~~~~~~
 
-## Rendering to targets {#renderTargets_d_a}
-Use @ref bs::RenderAPI::setRenderTarget "RenderAPI::setRenderTarget" to bind a render target for rendering. After binding you may issue draw calls, after which you should follow it with a call to @ref bs::RenderAPI::swapBuffers "RenderAPI::swapBuffers" if the target has multiple buffers (like a window). Read the [render API](@ref renderAPI) manual for more information.
+You can also call @ref bs::ct::RenderAPI::clearViewport "ct::RenderAPI::clearViewport()" to clear only the viewport portion of the render target. The parameters are identical to **ct::RenderAPI::clearRenderTarget()**.
 
-## Clearing targets {#renderTargets_d_b}
-Call @ref bs::RenderAPI::clearRenderTarget "RenderAPI::clearRenderTarget" to clear all or portions of a render target to a specific color/value. Read the [render API](@ref renderAPI) manual for more information.
+Clearing the depth buffer is especially important as the GPU will read its contents during rendering, and having old data in the depth buffer pretty much guarantees your rendering will not be valid.
 
-## Reading from targets {#renderTargets_d_c}
-If you wish to read render target pixels from the CPU, you can use the normal @ref bs::Texture "Texture" read functionality as described in the [texture](@ref textures) manual. To retrieve a @ref bs::Texture "Texture" from a @ref bs::RenderTexture "RenderTexture" call the following methods:
- - @ref bs::RenderTexture::getColorTexture "RenderTexture::getColorTexture"
- - @ref bs::RenderTexture::getDepthStencilTexture "RenderTexture::getDepthStencilTexture"
- 
-Before reading you must make sure the render target is not currently bound for rendering otherwise this will fail. You cannot read from a @ref bs::RenderWindow "RenderWindow".
+# Swapping {#renderTargets_c}
+If a render target is a **RenderWindow** you must call @ref bs::ct::RenderAPI::swapBuffers "ct::RenderAPI::swapBuffers()" after rendering. This is because windows are usually double or triple buffered, meaning the rendering happens to a hidden buffer invisible to the user. When **ct::RenderAPI::swapBuffers()** is called this hidden buffer is presented to the user.
 
-## Rendering using the targets {#renderTargets_c_d}
-Sometimes you render to a render texture only to use it as input in another rendering operation. In such case the render texture is first used for writing, and then for reading. This case is similar to above, first you make sure that the render texture is not currently bound for writing, and then you call one of the above listed methods to retrieve the required @ref bs::Texture "Texture".
+~~~~~~~~~~~~~{.cpp}
+SPtr<RenderWindow> window;
+rapi.setRenderTarget(window);
 
-Then you can bind the texture for rendering as normal (described in the [render API](@ref renderAPI) manual).
+// ... draw something ...
 
-For depth/stencil surfaces there is a special case where you might need to leave them bound as a render target to be used for depth/stencil testing (not writing), but also for reading within a GPU program. In such a case you can call @ref bs::RenderAPI::setRenderTarget "RenderAPI::setRenderTarget" with `readOnlyDepthStencil` parameter set to true.
+rapi.swapBuffers(window);
+~~~~~~~~~~~~~