More work on manuals

Documentation/Manuals/Native/architecture.md

@@ -6,7 +6,7 @@ Banshee is implemented throughout many separate libraries. Spreading the engine
  - Portions of the engine can be easily modified or replaced
  - User can choose which portions of the engine are needed
  - Internals are easier to understand as libraries form a clear architecture between themselves, while ensuring source code isn't all bulked into one big package
- - It insures quality design by decoupling code and forcing an order of dependencies.
+ - It ensures quality design by decoupling code and forcing an order of dependencies.
  
 All the libraries can be separated into four main categories:
  - Layers - These are the core libraries of the engine. Each layer is built on top of the previous layer and provides higher level and more specific functionality than the other.

Documentation/Manuals/Native/meshes.md

@@ -0,0 +1,159 @@
+Meshes									{#meshes}
+===============
+[TOC]
+
+Mesh is an object represented by a set of points, their properties and a set of primitives formed by those points. In Banshee mesh is represented with the @ref BansheeEngine::Mesh "Mesh" and @ref BansheeEngine::MeshCore "MeshCore" classes. Both of these 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.
+
+# Creating a mesh {#meshes_a}
+To create a mesh call @ref BansheeEngine::Mesh::create "Mesh::create" or one if its overloads. At minimum you need to provide a @ref BansheeEngine::VertexDataDesc "vertex description" that describes in what format are the vertices stored in the vertex buffer and the number of vertices and indices. 
+
+Optionally you can also provide the type of indices, type of primitives, and a set of sub-meshes:
+ - Indices can be 32- or 16-bit. This is controlled by the `indexType` parameter. Smaller indices can be used to save bandwidth if your mesh has a small enough number of primitives.
+ - `drawOp` parameter determines how are the indices interpreted. By default they're interpreted as a list of triangles (every three indices forming a triangle, one after another) but different @ref BansheeEngine::DrawOperationType "types" are supported.
+ - A mesh can have multiple sub-meshes. Each sub-mesh is described by an offset and a range of indices that belong to it. Sub-meshes can be used for rendering sections of a mesh, instead of all of it (for example if a single mesh uses different materials).
+ 
+For example to create a simple mesh:
+~~~~~~~~~~~~~{.cpp}
+SPtr<VertexDataDesc> vertexDesc = ...; // Vertex description creation is explained later
+
+// Creates an empty mesh with 36 indices and 8 vertices
+HMesh mesh = Mesh::create(8, 32, vertexDesc);
+~~~~~~~~~~~~~ 
+ 
+You can also create a non-empty mesh by creating it with a populated @ref BansheeEngine::MeshData "MeshData" object. More about @ref BansheeEngine::MeshData "MeshData" later. 
+ 
+# Accessing properties {#meshes_b} 
+You can access various mesh properties by calling @ref BansheeEngine::Mesh::getProperties() "Mesh::getProperties()" which will return an instance of @ref BansheeEngine::MeshProperties "MeshProperties" which contains information such as mesh bounds, number of indices/vertices and sub-meshes. 
+ 
+# Reading/writing {#meshes_c}
+To read and write from/to the mesh use the @ref BansheeEngine::Mesh::readSubresource "Mesh::readSubresource" and @ref BansheeEngine::Mesh::writeSubresource "Mesh::writeSubresource" methods. These expect an index of a sub-resource to read/write to, and a @ref BansheeEngine::MeshData "MeshData" object.
+
+The sub-resource index for a mesh is currently ignored and should be always left as zero.
+
+@ref BansheeEngine::MeshData "MeshData" object is just a container for a set of vertices and indices. You can create one manually or use @ref BansheeEngine::Mesh::allocateSubresourceBuffer "Mesh::allocateSubresourceBuffer" to create the object of valid size and format for the specified mesh. When reading from the mesh the buffer will be filled with vertices/indices from the mesh, and when writing you are expected to populate the object.
+
+## MeshData {#meshes_c_a}
+You can create @ref BansheeEngine::MeshData "MeshData" manually by calling @ref BansheeEngine::MeshData::create "MeshData::create" and providing it with vertex description, index type and number of vertices and indices. You must ensure that the formats and sizes matches the mesh this will be used on.
+
+### Vertex description {#meshes_c_a_a}
+Creating a vertex description is simple, it requires you to specify a list of vertex properties, each identified by a type and a semantic. The semantic determines to which GPU program input field does the property map to. See the [gpu program](@ref gpuPrograms) manual for more information about semantics. For example:
+~~~~~~~~~~~~~{.cpp}
+// Create a vertex 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);
+~~~~~~~~~~~~~ 
+
+See @ref BansheeEngine::VertexElementType "VertexElementType" for valid types, and @ref BansheeEngine::VertexElementSemantic "VertexElementSemantic" for a list of valid semantics. Each semantic can also optionally have an index in case multiple values of the same semantic are needed.
+
+Each vertex element can also be placed in a "stream". In the example above all the elements are in the 0th stream, but you can place different elements in different streams by providing a stream index to @ref BansheeEngine::VertexDataDesc::addVertElem "VertexDataDesc::addVertElem". Different streams will result in multiple vertex buffers created within the mesh. This can be useful if you are rendering the mesh with multiple GPU programs and not every GPU program requires all vertex elements, in which case you could only bind a subset of the vertex buffers and reduce the bandwidth costs by not sending the unnecessary data.
+
+Once the @ref BansheeEngine::VertexDataDesc "VertexDataDesc" structure has been filled, you can use it for initializing a @ref BansheeEngine::Mesh "Mesh" or @ref BansheeEngine::MeshData "MeshData". You can also use it to manually create a vertex declaration by calling @ref BansheeEngine::VertexDeclaration::create "VertexDeclaration::create". @ref BansheeEngine::VertexDeclaration "VertexDeclaration" can be manually bound to the @ref BansheeEngine::RenderAPI "RenderAPI", which can be useful in the case you're manually creating vertex or index buffers.
+
+### Reading/writing MeshData {#meshes_c_a_b}
+@ref BansheeEngine::MeshData "MeshData" provides multiple methods of reading/writing vertex data. The most trivial is setting the data in-bulk by using @ref BansheeEngine::MeshData::setVertexData "MeshData::setVertexData" and @ref BansheeEngine::MeshData::getVertexData "MeshData::getVertexData" which set vertex data for a single vertex element all at once. 
+
+~~~~~~~~~~~~~{.cpp}
+SPtr<MeshData> meshData = ...; // Assume we have 4 vertices, with only a position element
+
+Vector3 myVertices[4];
+// ... Set vertex positions ...
+
+// Write the vertices
+meshData->setVertexData(VES_POSITION, myVertices, sizeof(myVertices));
+~~~~~~~~~~~~~
+
+You can also use @ref BansheeEngine::MeshData::getElementData "MeshData::getElementData" which will return a pointer to the starting point of the vertex data for a specific element. You can then iterate over the pointer to read/write values. Make sure to use @ref BansheeEngine::VertexDataDesc::getVertexStride "VertexDataDesc::getVertexStride" to know how many bytes to advance between elements.
+
+~~~~~~~~~~~~~{.cpp}
+SPtr<MeshData> meshData = ...; // Assume we have 4 vertices, with only a position element
+
+UINT8* vertices = meshData->getElementData(VES_POSITION);
+UINT32 stride = meshData->getVertexDesc()->getVertexStride();
+
+for(UINT32 i = 0; i < 4; i++)
+{
+	Vector3 myVertex(i, i, 0);
+	memcpy(vertices, &myVertex, sizeof(myVertex));
+	
+	vertices += stride;
+}
+~~~~~~~~~~~~~
+
+And finally you can use iterators: @ref BansheeEngine::MeshData::getVec2DataIter "MeshData::getVec2DataIter", @ref BansheeEngine::MeshData::getVec3DataIter "MeshData::getVec3DataIter", @ref BansheeEngine::MeshData::getVec4DataIter "MeshData::getVec4DataIter", @ref BansheeEngine::MeshData::getDWORDDataIter "MeshData::getDWORDDataIter". They are similar to the previous example but you don't need to manually worry about the vertex stride, or going outside of valid bounds.
+
+~~~~~~~~~~~~~{.cpp}
+SPtr<MeshData> meshData = ...; // Assume we have 4 vertices, with only a position element
+
+auto iter = meshData->getVec3DataIter(VES_POSITION);
+
+int i = 0;
+do {
+	vecIter.addValue(myVertex(i, i, 0)); // Automatically advances the iterator
+	i++;
+} while(vecIter.moveNext()); // Iterate until we reach the end
+~~~~~~~~~~~~~
+
+Accessing indices is simpler and is done through @ref BansheeEngine::MeshData::getIndices32 "MeshData::getIndices32" or @ref BansheeEngine::MeshData::getIndices16 "MeshData::getIndices16" depending if the indices are 32- or 16-bit. The returned value is a pointer to the index buffer you can use to read/write the indices directly.
+
+~~~~~~~~~~~~~{.cpp}
+SPtr<MeshData> meshData = ...; // Assume we have 6 32-bit indices
+
+UINT32* indices = meshData->getIndices32();
+indices[0] = 0;
+indices[1] = 1;
+indices[2] = 2;
+
+indices[3] = 2;
+indices[4] = 1;
+indices[5] = 3;
+~~~~~~~~~~~~~
+
+## Cached CPU data {#meshes_c_b}
+When you read from a mesh using the @ref BansheeEngine::Mesh::readSubresource "Mesh::readSubresource" method the read will be performed from the GPU. This is useful if the GPU has in some way modified the mesh, but will also incur a potentially large performance penalty because it will introduce a CPU-GPU synchronization point. In a lot of cases you might just want to read mesh data from a mesh that was imported or created on the CPU in some other way.
+
+For this reason @ref BansheeEngine::Mesh::readData "Mesh::readData" exists. It will read data quickly with little performance impact. However you must create the mesh using the @ref BansheeEngine::MU_CPUCACHED "MU_CPUCACHED" usage. This also means that the mesh will keep a copy of its data in system memory, so use it sparingly. If the mesh is modified from the GPU this method will not reflect such changes.
+
+# Rendering using the mesh {#meshes_d}
+To use a mesh for rendering you need to bind its vertex buffer(s), index buffer, vertex declaration and draw operation using the @ref BansheeEngine::RenderAPI "RenderAPI". Relevant methods are @ref BansheeEngine::RenderAPI::setVertexBuffers "RenderAPI::setVertexBuffers", @ref BansheeEngine::RenderAPI::setIndexBuffer "RenderAPI::setIndexBuffer", @ref BansheeEngine::RenderAPI::setVertexDeclaration "RenderAPI::setVertexDeclaration" and @ref BansheeEngine::RenderAPI::setDrawOperation "RenderAPI::setDrawOperation". See below for information about how to retrieve this information from a mesh.
+
+See the [render API](@ref renderAPI) manual for more information on how to manually execute rendering commands.
+
+If working on the core thread you can use the helper @ref BansheeEngine::RendererUtility::draw "RendererUtility::draw" method that performs these operations for you.
+
+# Saving/loading {#meshes_e}
+A mesh is a @ref BansheeEngine::Resource "Resource" and can be saved/loaded like any other. See the [resource](@ref resources) manual.
+
+# Core thread meshes {#meshes_f}
+So far we have only talked about the simulation thread @ref BansheeEngine::Mesh "Mesh" but have ignored the core thread @ref BansheeEngine::MeshCore "MeshCore". The functionality between the two is mostly the same, with the major difference being that the core thread version doesn't require a @ref BansheeEngine::CoreThreadAccessor "CoreAccessor" for access, and you can instead perform operations on it directly.
+
+You can also use the core thread version to access and manipulate vertex and index buffers directly (including binding them to the pipeline as described earlier). Use @ref BansheeEngine::MeshCore::getVertexData "MeshCore::getVertexData" to retrieve information about all @ref BansheeEngine::VertexBufferCore "vertex buffers", @ref BansheeEngine::MeshCore::getIndexBuffer "MeshCore::getIndexBuffer" to retrieve the @ref BansheeEngine::IndexBufferCore "index buffer" and @ref BansheeEngine::MeshCore::getVertexDesc "MeshCore::getVertexDesc" to retrieve the @ref BansheeEngine::VertexDataDesc "vertex description".
+
+# Advanced meshes {#meshes_g}
+So far we have described the use of standard meshes. And while the described meshes can be used for all purposes, when we have a mesh that is updated often (every frame or every few frames) it can be beneficial for performance to use a different mesh type. This is because updates to a normal mesh can introduce GPU-CPU synchronization points if that mesh is still being used by the GPU while we are updating it (which can happen often).
+
+So instead we use a concept of a @ref BansheeEngine::MeshHeap "MeshHeap", which allows us to quickly create and allocate new meshes, without having to worry about introducing GPU-CPU synchronization points. This is perfect for systems like GUI or grass rendering, which might have their meshes rebuilt nearly every frame. The only downside is that the heap will allocate more memory than actually required for a mesh, as it keeps the memory for both the newly updated mesh and the one currently being used.
+
+Creation of a @ref BansheeEngine::MeshHeap::create "MeshHeap::create" is nearly identical to creation of a @ref BansheeEngine::Mesh "Mesh". It requires a vertex description and an index type, while the index/vertex counts are mostly arbitrary (the heap will grow as needed).
+
+You can allocate meshes from the heap by calling @ref BansheeEngine::MeshHeap::alloc "MeshHeap::alloc" and providing it with a @ref BansheeEngine::MeshData "MeshData". When done with the mesh call @ref BansheeEngine::MeshHeap::dealloc "MeshHeap::dealloc". @ref BansheeEngine::MeshHeap::alloc "MeshHeap::alloc" returns a @ref BansheeEngine::TransientMesh "TransientMesh" which shares mostly the same interface as a normal @ref BansheeEngine::Mesh "Mesh", with a few restrictions. You are not allowed to read/write to it (aside from the initial value), and it doesn't support sub-meshes.
+
+A simple example of a mesh heap:
+~~~~~~~~~~~~~{.cpp}
+SPtr<VertexDataDesc> vertexDesc = VertexDataDesc::create();
+vertexDesc->addVertElem(VET_FLOAT3, VES_POSITION);
+
+// Create the mesh heap (normally you you create this once and use it throughout the application)
+SPtr<MeshHeap> meshHeap = MeshHeap::create(100, 100, vertexDesc);
+
+SPtr<MeshData> meshData = ...; // Assume we create mesh data like in one of the previous sections
+SPtr<TransientMesh> mesh = meshHeap->alloc(meshData);
+// Draw using the mesh
+meshHeap->dealloc(mesh);
+
+~~~~~~~~~~~~~
+
+See @ref BansheeEngine::GUIManager "GUIManager" implementation in "BsGUIManager.cpp" for a functional example.

Documentation/Manuals/Native/porting.md

@@ -0,0 +1,70 @@
+Porting									{#porting}
+===============
+[TOC]
+
+This guide will try to offer you a solid set of guidelines how to go about porting Banshee to a different operating system.
+
+# Compilation {#porting_a}
+Banshee currently compiles using MSVC and Clang on Windows. There should be little issues compiling using Clang on other platforms. GCC was not tested but considering compilation works with two separate compilers there should be no major issues. Banshee also supports the CMake build system, which can generate make files and project files for various popular compilers and IDEs. 
+
+This means that as far as the compilation goes most of the work should be done for you.
+
+# Platform specific functionality {#porting_b}
+Most of the porting work remains in adding platform specific functionality like file-system, windows and similar. Banshee comes with a fully working implementation of OpenGL, which means the rendering API is already cross-platform (for the most part), and the platform functionality mostly lies in various utility functionality.
+
+Banshee was built with multi-platform in mind from day one, and it tries to minimize the amount of platform specific functionality as much as possible. The functionality that is platform specific is encapsulated so external code never needs to access it directly, making the porting process transparent to higher level systems. All of the platform specific functionality is cleanly marked either in an \#ifdef block or is in a separate source file with a special prefix.
+
+Banshee is built in layers, higher layers referencing lower layers. This should make porting easier as you can start with the lowest layer and work your way up. This way you can compile and test layer by layer instead of needing to fully port the entire engine to properly compile it. Additionally a lot of functionality is in plugins and those generally don't have any platform specific code (except the OpenGL plugin), which should also help with dividing the work into manageable chunks. These aspects of Banshee should significantly help with the porting effort, so keep the layers/plugins in mind.
+
+Aside from dividing the work by layers/plugins you should most definitely also divide it by functionality needed: editor requires significantly more platform specific code than a standalone game. You should first strive to port all the features used by the standalone game, then after everything is working should you proceed with working on editor features. You can use the `ExampleProject` as a test-bed for the standalone features. 
+
+All the features that need porting are wrapped in a BS_PLATFORM \#ifdef block, or in files prefixed with "Win32". In a very limited set of cases there are also BS_COMPILER defines for functionality specific to a compiler. For every such block and file you will need to write equivalent code for the destination platform. 
+
+Below you will find a fairly complete list of all such blocks/files that need to be modified, to give you a good idea of the scope. Each listed feature has an indication whether this is a engine or editor-only feature.
+Additionally, not all features are critical, meaning you can get the engine to run without them (e.g. platform cursors or clipboard), which are also specially marked. For them it is suggested you implement a dummy version first, and only proceed with actual implementation once the critical features are done.
+
+## Critical features {#porting_b_a}
+A list of all critical features that require the engine to be ran standalone (no editor), in the rough order they should be implemented.
+
+Feature                                         | Editor only 	| Library                       | Dummy implementation  | Relevant files										 | Description
+------------------------------------------------|---------------|-------------------------------|-----------------------|--------------------------------------------------------|-----------------
+File system*								   	| No			| BansheeUtility				| No					| BsFileSystem.h/BsWin32FileSystem.cpp 					 | Opening/creating files, iterating over directories
+Dynamic library loading							| No			| BansheeUtility				| No					| BsDynLib.h/BsDynLib.cpp 							     | Loading dynamic libraries (.dll, .so)
+OpenGL initialization*							| No			| BansheeGLRenderAPI			| No					| BsGLUtil.h, BsGLSupport.h/BsWin32GLSupport.cpp, BsWin32Context.h/BsWin32Context.cpp, BsWin32VideoModeInfo.cpp | Initializing the OpenGL context (or other context if non-OpenGL API is used for the port)
+Window creation*								| No			| BansheeUtility, BansheeGLRenderAPI | No				| BsWin32Window.h/BsWin32Window.cpp, BsWin32Platform.h/BsWin32Platform.cpp, BsWin32RenderWindow.h/BsWin32RenderWindow.cpp | Creating and interacting with the window
+OS message loop*								| No			| BansheeCore					| No					| BsWin32Platform.h/BsWin32Platform.cpp 				 | Running the main message loop, responding to its events
+Timer											| No			| BansheeUtility				| No					| BsTimer.h/BsWin32Timer.cpp 							 | Measuring time
+Input*											| No			| BansheeCore					| Maybe					| BsPlatform.h/BsWin32Platform.cpp 						 | Receive input from OS (mouse, keyboard)
+UUID generation									| No			| BansheeUtility				| No					| BsPlatformUtility.h/BsWin32PlatformUtility.cpp 		 | Generate UUID/GUID
+Performance timers								| No			| BansheeUtility				| No					| BsPlatformUtility.h/BsWin32PlatformUtility.cpp 		 | Measure time precisely for profiling
+
+## Non-critical features {#porting_b_b} 
+A list of non-critical features, and editor-only features, in the rough order they should be implemented. You should be able to get the engine running without these, or with just dummy implementations (that do nothing).
+
+Feature                                         | Editor only 	| Library                       | Dummy implementation  | Relevant files											| Description
+------------------------------------------------|---------------|-------------------------------|-----------------------|-----------------------------------------------------------|-------------------
+Crash handler									| No			| BansheeUtility				| Yes					| BsCrashHandler.h, ThreadPool.cpp, BansheeEditorExec.cpp, Main.cpp (in Game project) | Save a log with a callstack when a crash occurs
+Process termination								| No			| BansheeUtility				| Yes					| BsPlatformUtility.h/BsWin32PlatformUtility.cpp | Terminate the application on user request
+Cursor											| No			| BansheeCore					| Yes					| BsPlatform.h/BsWin32Platform.cpp | Get/set cursor position, clip cursor, change cursor look
+Window non-client areas 						| Yes			| BansheeCore					| Yes					| BsPlatform.h/BsWin32Platform.cpp | Set up OS window borders used for resize/move operations
+Changing executable icon*						| Yes			| BansheeCore					| Yes					| BsPlatform.h/BsWin32Platform.cpp | Ability to inject an icon into an executable, used by the build process
+Clipboard										| No			| BansheeUtility				| Yes					| BsPlatformUtility.h/BsWin32PlatformUtility.cpp | Ability to copy/paste text from the editor and the OS
+Converting keyboard code to character			| Yes			| BansheeUtility				| Yes					| BsPlatformUtility.h/BsWin32PlatformUtility.cpp | Converting keyboard codes into a character symbol
+Retrieving MAC address							| Yes			| BansheeUtility				| Yes					| BsPlatformUtility.h/BsWin32PlatformUtility.cpp | Retrieving a MAC address of the computer
+Browse file/folder dialogs						| Yes			| BansheeUtility				| Yes					| BsPlatformUtility.h/BsWin32BrowseDialogs.cpp, BsPlatformUtility.h/BsWin32PlatformUtility.cpp | OS built-in dialogs for browsing/creating files/folders
+Folder monitor*									| Yes			| BansheeCore					| Yes					| BsFolderMonitor.h, BsWin32FolderMonitor.h/BsWin32FolderMonitor.cpp | Monitor that can track and report  file changes/additions/deletions in a folder
+Drop target*									| Yes			| BansheeCore					| Yes					| BsWin32DropTarget.h/BsWin32Platform.cpp | Target that can be used for drag and drop operations initiated by the OS
+Script compilation								| Yes			| BansheeMono					| Yes					| BsMonoManager.cpp | Starting of the external compiler tool, and copying its output files into proper location.
+Game build										| Yes			| Game, BansheeEditor, MBansheeEditor | Yes				| Main.cpp in Game, BuildManager.cpp in BansheeEditor, BuildManager.cs in MBansheeEditor | Copying the right libraries, and assemblies during build. Platform-specific options in the build manager.
+Splash Screen									| Yes			| BansheeEngine					| Yes					| BsSplashScreen.cpp | Displaying a splash screen with the Banshee logo
+MonoDevelop integration*						| Yes			|BansheeEditor					| Yes					| BsCodeEditor.cpp | Ability to open/edit script files with MonoDevelop, similar to how VS integration works
+
+(*) - This is a larger and/or non-trivial task. Most listed tasks are just a few dozen up to a couple of hundred lines of code, or if larger they're trivially simple. Larger tasks are a few hundred lines of code (less than a 1000) and/or might be more difficult to implement than others. This is noted here to give you a better idea of the scope.
+
+# Compiling third party dependencies {#porting_c} 
+In order to run Banshee on different platforms you will also need to compile all of Banshee's dependencies. Most of Banshee's dependencies are only used in plugins, which should make it easier to compile and test them individually.
+
+All used dependencies are already multi-platform and you should have little trouble compiling them for major platforms. See "CompilingDependenciesManually.txt" (distributed with the source code) for information which dependencies are needed.
+
+# Mobile platforms {#porting_d} 
+If building for mobile platforms you will also need to provide a compatible render API plugin. It is suggested you use the BansheeOpenGL plugin as an example of creating such an API (for example OpenGL ES). API's like Metal or Vulkan for mobiles will require more work but you can still use the existing render API plugins for a good basis of what needs to be implemented.

Documentation/Manuals/Native/textures.md

@@ -7,7 +7,7 @@ Textures in Banshee are represented with the @ref BansheeEngine::Texture "Textur
 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.
 
 # Creating a texture {#textures_a}
-To create a texture call @ref BansheeEngine::Texture::create "create" or one if its overloads. At minimum you need to provide a @ref BansheeEngine::TextureType "texture type", dimensions and @ref BansheeEngine::PixelFormat "pixel format". The dimensions range from one to three dimensional depending on the texture type.
+To create a texture call @ref BansheeEngine::Texture::create "Texture::create" or one if its overloads. At minimum you need to provide a @ref BansheeEngine::TextureType "texture type", dimensions and @ref BansheeEngine::PixelFormat "pixel format". The dimensions range from one to three dimensional depending on the texture type.
 
 Optionally you can also provide the number of mipmaps, number of samples, usage flags and a gamma correction flag:
  - A texture with mip-maps will contain a set of scaled down versions of itself that are used by the GPU for special filtering. 
@@ -20,12 +20,14 @@ For example:
 // Creates a 2D texture, 128x128 with an 8-bit RGBA format
 HTexture texture = Texture::create(TEX_TYPE_2D, 128, 128, 0, PF_R8G8B8A8);
 ~~~~~~~~~~~~~ 
+
+You can also create a non-empty texture by creating it with a populated @ref BansheeEngine::PixelData "PixelData" object. More about @ref BansheeEngine::PixelData "PixelData" later.
  
 # Accessing properties {#textures_b} 
 You can access all relevant texture properties by calling @ref BansheeEngine::Texture::getProperties() "Texture::getProperties()" which will return an instance of @ref BansheeEngine::TextureProperties "TextureProperties" which contains all the information about the texture, as well as some useful methods (as we'll see in the next section).
  
 # Reading/writing {#textures_c}
-To read and write to the texture use the @ref BansheeEngine::Texture::readSubresource "Texture::readSubresource" and @ref BansheeEngine::Texture::writeSubresource "Texture::writeSubresource" methods. These expect an index of a sub-resource to read/write to, and a @ref BansheeEngine::PixelData "PixelData" object.
+To read and write from/to the texture use the @ref BansheeEngine::Texture::readSubresource "Texture::readSubresource" and @ref BansheeEngine::Texture::writeSubresource "Texture::writeSubresource" methods. These expect an index of a sub-resource to read/write to, and a @ref BansheeEngine::PixelData "PixelData" object.
 
 The sub-resource index is simply a sequential index of the surface you want to access. If the texture has only one surface this will always be zero. But if the texture has multiple mipmaps or multiple faces (like for cube textures or texture arrays) you can use @ref BansheeEngine::TextureProperties::mapToSubresourceIdx "TextureProperties::mapToSubresourceIdx" to convert mip/face combination into an subresource index, and @ref BansheeEngine::TextureProperties::mapFromSubresourceIdx "TextureProperties::mapFromSubresourceIdx" for the other way around.
 
@@ -41,7 +43,7 @@ You can also use @ref BansheeEngine::PixelUtil "PixelUtil" to perform various op
 ## Cached CPU data {#textures_c_b}
 When you read from a texture using the @ref BansheeEngine::Texture::readSubresource "Texture::readSubresource" method the read will be performed from the GPU. This is useful if the GPU has in some way modified the texture, but will also incur a potentially large performance penalty because it will introduce a CPU-GPU synchronization point. In a lot of cases you might just want to read pixels from a texture that was imported or created on the CPU in some other way.
 
-For this reason @ref BansheeEngine::Texture::readData "Texture::readData" exists. It will read data quickly with little performance impact. However you must create the texture using the @ref BansheeEngine::TU_CPUCACHED usage. This also means that the texture will keep a copy of its pixels in system memory, so use it sparingly. If the texture is modified from the GPU this method will not reflect such changes.
+For this reason @ref BansheeEngine::Texture::readData "Texture::readData" exists. It will read data quickly with little performance impact. However you must create the texture using the @ref BansheeEngine::TU_CPUCACHED "TU_CPUCACHED" usage. This also means that the texture will keep a copy of its pixels in system memory, so use it sparingly. If the texture is modified from the GPU this method will not reflect such changes.
 
 # Rendering using the texture {#textures_d}
 To use a texture for rendering you can either bind it to the @ref BansheeEngine::RenderAPI::setTexture "RenderAPI::setTexture" directly, or assign it to a @ref BansheeEngine::Material "Material" which will then be used on a @ref BansheeEngine::Renderable "Renderable" or a similar object. To learn more about this check out the [render API](@ref renderAPI) and [material](@ref materials) manuals.

Source/BansheeCore/Include/BsDrawOps.h

@@ -13,12 +13,12 @@ namespace BansheeEngine
 	/** Describes operation that will be used for rendering a certain set of vertices. */
 	enum DrawOperationType 
 	{
-		DOT_POINT_LIST = 1,
-		DOT_LINE_LIST = 2,
-		DOT_LINE_STRIP = 3,
-		DOT_TRIANGLE_LIST = 4,
-		DOT_TRIANGLE_STRIP = 5,
-		DOT_TRIANGLE_FAN = 6
+		DOT_POINT_LIST = 1, /**< Each vertex represents a point. */
+		DOT_LINE_LIST = 2, /**< Each sequential pair of vertices represent a line. */
+		DOT_LINE_STRIP = 3, /**< Each vertex (except the first) forms a line with the previous vertex. */
+		DOT_TRIANGLE_LIST = 4, /**< Each sequential 3-tuple of vertices represent a triangle. */
+		DOT_TRIANGLE_STRIP = 5, /**< Each vertex (except the first two) form a triangle with the previous two vertices. */
+		DOT_TRIANGLE_FAN = 6 /**< Each vertex (except the first two) form a triangle with the first vertex and previous vertex. */
 	};
 
 	/** Converts the number of vertices to number of primitives based on the specified draw operation. */

Source/BansheeCore/Include/BsIndexBuffer.h

@@ -15,8 +15,8 @@ namespace BansheeEngine
 	/**	Type of the indices used, used for determining size. */
 	enum IndexType 
 	{
-		IT_16BIT,
-		IT_32BIT
+		IT_16BIT, /**< 16-bit indices. */
+		IT_32BIT /**< 32-bit indices. */
 	};
 
 	/**	Contains information about an index buffer. */

Source/BansheeCore/Include/BsVertexDeclaration.h

@@ -15,35 +15,35 @@ namespace BansheeEngine
 	/** Semantics that are used for identifying the meaning of vertex buffer elements. */
 	enum VertexElementSemantic 
 	{
-		VES_POSITION = 1,
-		VES_BLEND_WEIGHTS = 2,
-        VES_BLEND_INDICES = 3,
-		VES_NORMAL = 4,
-		VES_COLOR = 5,
-		VES_TEXCOORD = 6,
-        VES_BITANGENT = 7,
-        VES_TANGENT = 8,
-		VES_POSITIONT = 9,
-		VES_PSIZE = 10
+		VES_POSITION = 1, /**< Position */
+		VES_BLEND_WEIGHTS = 2, /**< Blend weights */
+        VES_BLEND_INDICES = 3, /**< Blend indices */
+		VES_NORMAL = 4, /**< Normal */
+		VES_COLOR = 5, /**< Color */
+		VES_TEXCOORD = 6, /**< UV coordinate */
+        VES_BITANGENT = 7, /**< Bitangent */
+        VES_TANGENT = 8, /**< Tangent */
+		VES_POSITIONT = 9, /**< Transformed position */
+		VES_PSIZE = 10 /**< Point size */
 	};
 
 	/**	Types used to identify base types of vertex element contents. */
     enum VertexElementType
     {
-        VET_FLOAT1 = 0,
-        VET_FLOAT2 = 1,
-        VET_FLOAT3 = 2,
-        VET_FLOAT4 = 3,
-		VET_COLOR = 4,
-		VET_SHORT1 = 5,
-		VET_SHORT2 = 6,
-		VET_SHORT3 = 7,
-		VET_SHORT4 = 8,
-        VET_UBYTE4 = 9,
-        VET_COLOR_ARGB = 10,
-        VET_COLOR_ABGR = 11,
-		VET_UINT4 = 12,
-		VET_SINT4 = 13
+        VET_FLOAT1 = 0, /**< 1D floating point value */
+        VET_FLOAT2 = 1, /**< 2D floating point value */
+        VET_FLOAT3 = 2, /**< 3D floating point value */
+        VET_FLOAT4 = 3, /**< 4D floating point value */
+		VET_COLOR = 4, /**< 4D floating point value */
+		VET_SHORT1 = 5, /**< 1D 16-bit signed integer value */
+		VET_SHORT2 = 6, /**< 2D 16-bit signed integer value */
+		VET_SHORT3 = 7, /**< 3D 16-bit signed integer value */
+		VET_SHORT4 = 8, /**< 4D 16-bit signed integer value */
+        VET_UBYTE4 = 9, /**< 4D 8-bit unsigned integer value */
+        VET_COLOR_ARGB = 10, /**< Color encoded in 32-bits (8-bits per channel) in ARGB order) */
+        VET_COLOR_ABGR = 11, /**< Color encoded in 32-bits (8-bits per channel) in ABGR order) */
+		VET_UINT4 = 12, /**< 4D 32-bit unsigned integer value */
+		VET_SINT4 = 13  /**< 4D 32-bit signed integer value */
     };
 
 	/**	Describes a single vertex element in a vertex declaration. */
@@ -155,7 +155,7 @@ namespace BansheeEngine
 		SPtr<VertexDeclarationCore> getCore() const;
 
 		/** @copydoc HardwareBufferManager::createVertexDeclaration */
-		static VertexDeclarationPtr createVertexDeclaration(const List<VertexElement>& elements);
+		static VertexDeclarationPtr create(const List<VertexElement>& elements);
 
     protected:
 		friend class HardwareBufferManager;

Source/BansheeCore/Source/BsVertexDeclaration.cpp

@@ -286,7 +286,7 @@ namespace BansheeEngine
 		return HardwareBufferCoreManager::instance().createVertexDeclarationInternal(mProperties.mElementList);
 	}
 
-	VertexDeclarationPtr VertexDeclaration::createVertexDeclaration(const List<VertexElement>& elements)
+	VertexDeclarationPtr VertexDeclaration::create(const List<VertexElement>& elements)
 	{
 		return HardwareBufferManager::instance().createVertexDeclaration(elements);
 	}