More work on user manuals

Documentation/Doxygen/Native.doxyconfig

@@ -2095,8 +2095,7 @@ PREDEFINED             = BS_SCRIPT_EXPORT()=
 # definition found in the source code.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_AS_DEFINED      = BS_SCRIPT_EXPORT() \
-                         BS_SCRIPT_EXPORT(Options)
+EXPAND_AS_DEFINED      = BS_SCRIPT_EXPORT()
 
 # If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
 # remove all references to function-like macros that are alone on a line, have

Documentation/Manuals/Native/User/advancedTextures.md

@@ -0,0 +1,211 @@
+Manipulating textures				{#advancedTextures}
+===============
+
+In this manual we'll learn how to create textures manually, modify their contents and even read-back texture data.
+
+# Creating textures
+To create a texture call @ref bs::Texture::create "Texture::create". You'll need to populate the @ref bs::TEXTURE_DESC "TEXTURE_DESC" structure and pass it as a parameter. The structure requires you to populate these properties at minimum:
+ - @ref bs::TEXTURE_DESC::type "TEXTURE_DESC::type" - Allows you to choose between 1D/2D/3D or cube-map textures using the @ref bs::TextureType "TextureType" enum
+ - @ref bs::TEXTURE_DESC::format "TEXTURE_DESC::format" - Allows you to choose a format for each individual pixel in the texture, using the @ref bs::PixelFormat "PixelFormat" enum
+ - @ref bs::TEXTURE_DESC::width "TEXTURE_DESC::width" - Width of the texture, in pixels
+ - @ref bs::TEXTURE_DESC::height "TEXTURE_DESC::height" - Height of the texture, in pixels. Not relevant for 1D textures.
+ - @ref bs::TEXTURE_DESC::depth "TEXTURE_DESC::depth" - Depth of the texture, in pixels. Only relevant for 3D textures.
+ 
+When it comes to texture types there four kinds of textures:
+ - @ref bs::TEX_TYPE_1D "TextureType::TEX_TYPE_1D" - A one-dimensional texture, containing just one row of pixels. Rarely used.
+ - @ref bs::TEX_TYPE_2D "TextureType::TEX_TYPE_2D" - A two-dimensional texture, most commonly used type.
+ - @ref bs::TEX_TYPE_3D "TextureType::TEX_TYPE_3D" - A three-dimensional texture, can be imagined as an array of 2D textures, but with support for interpolating between the texture slices. Used primarily when working with the low-level rendering API for special purposes.
+ - @ref bs::TEX_TYPE_CUBE_MAP "TextureType::TEX_TYPE_CUBE_MAP" - A cubemap texture that consists out of six 2D textures, each representing one face of the cube. Used primarily when working with the low-level rendering API for special purposes.
+ 
+You may also set these optional properties:
+ - @ref bs::TEXTURE_DESC::numMips "TEXTURE_DESC::numMips" - A texture with mip-maps will contain a set of scaled down versions of itself that are used by the GPU for anti-aliasing. Specify zero to use no mip maps. You can use the helper function @ref bs::PixelUtil::getMaxMipmaps "PixelUtil::getMaxMipmaps()" to return the maximum possible mip-map count for a specific set of dimensions. 
+ - @ref bs::TEXTURE_DESC::numArraySlices "TEXTURE_DESC::numArraySlices" - Specify number higher than 1 in order to create an array of textures. This is primarily used for low-level rendering purposes. Texture arrays are not supported for 3D textures.
+ - @ref bs::TEXTURE_DESC::hwGamma "TEXTURE_DESC::hwGamma" - When true, it specifies if the data in the texture is gamma corrected. When performing reads on such texture (e.g. in the shader) the GPU will transform the texture data back to linear space before returning the value. When a texture is used as a render target, the GPU will automatically convert from linear space into gamma space when rendering to the texture. Only relevant for 2D textures.
+ - @ref bs::TEXTURE_DESC::numSamples "TEXTURE_DESC::numSamples" - Specifies the number of samples per pixel. This is used primarily for multi-sample antialiasing. This is only relevant for 2D textures, and only for textures used as render targets. You cannot read or write from/to multi-sample textures manually.
+ - @ref bs::TEXTURE_DESC::usage "TEXTURE_DESC::usage" - Flags that control how is the texture allowed to be used, represented by the @ref bs::TextureUsage "TextureUsage" enum
+ 
+Supported textures usages are:
+ - @ref bs::TU_STATIC "TextureUsage::TU_STATIC" - Specify for normal textures that are created once (or updated very rarely) and used for normal rendering.
+ - @ref bs::TU_DYNAMIC "TextureUsage::TU_DYNAMIC" - Specify for textures that are updated often (e.g. every frame) and used for normal rendering.
+ - @ref bs::TU_RENDERTARGET "TextureUsage::TU_RENDERTARGET" - Specify for textures that will be used as color attachments for a render target.
+ - @ref bs::TU_DEPTHSTENCIL "TextureUsage::TU_DEPTHSTENCIL" - Specify for textures that will be used as a depth/stencil attachment for render target. Texture's pixel format must be one of the depth-stencil formats.
+ - @ref bs::TU_LOADSTORE "TextureUsage::TU_LOADSTORE" - Specify that the texture can be used for random read/write by shaders (e.g. for use in a compute shader).
+ - @ref bs::TU_CPUCACHED "TextureUsage::TU_CPUCACHED" - Specify that any data written to the texture (from the CPU) will be cached internally, allowing it to be accessed through **Texture::readCachedData()**. Uses extra memory as data needs to be stored in both normal and GPU memory.
+ - @ref bs::TU_CPUREADABLE "TextureUsage::TU_CPUREADABLE" - Specify that the CPU should be allowed to read texture data that was written by the GPU (e.g. resulting from rendering or a compute shader writes).
+ 
+Most of these options are only useful when using the low-level rendering API and your own shaders, in which case you might require advanced texture types and options. In majority of cases however you will be using 2D textures with mip-maps, potentially with gamma-corrected data, used for normal rendering (e.g. assigning them to materials).
+ 
+~~~~~~~~~~~~~{.cpp}
+// Creates a 2D texture, 128x128 with an 8-bit RGBA format
+TEXTURE_DESC desc;
+desc.type = TEX_TYPE_2D;
+desc.width = 128;
+desc.heigth = 128;
+desc.format = PF_R8G8B8A8;
+
+HTexture texture = Texture::create(desc);
+~~~~~~~~~~~~~
+
+# Writing data
+Once a texture has been created you might want to write some data to it. This is accomplished by calling @ref bs::Texture::writeData "Texture::writeData()". The method accepts a @ref bs::PixelData "PixelData" object, as well as a mip-map level and a face to write to.
+
+**PixelData** object is just a container for all the pixels of a single mip-level & face of a texture. It is created by calling @ref bs::PixelData::create "PixelData::create()" and providing dimensions as well as the pixel format.
+
+~~~~~~~~~~~~~{.cpp}
+// Create pixel data for a 128x128 texture with an 8-bit RGBA format
+SPtr<PixelData> pixelData = PixelData::create(128, 128, 1, PF_R8G8B8A8);
+~~~~~~~~~~~~~
+
+Once created you can set the color of each pixel by calling @ref bs::PixelData::setColorAt "PixelData::setColorAt()", or set all colors at once by calling @ref bs::PixelData::setColors "PixelData::setColors()".
+
+~~~~~~~~~~~~~{.cpp}
+// Generate some arbitrary colors
+Vector<Color> colors;
+for(UINT32 y = 0; y < 128; y++)
+	for(UINT32 x = 0; x < 128; x++)
+		colors.push_back(Color(x * 2.0f, y * 2.0f, 0.0f, 1.0f));
+
+pixelData->setColors(colors);		
+~~~~~~~~~~~~~
+
+Finally you can write the data the the texture.
+
+~~~~~~~~~~~~~{.cpp}
+texture->writeData(pixelData);
+~~~~~~~~~~~~~
+
+## Writing to sub-resources
+If a texture contains mip levels, or more than one face then we say it has multiple sub-resources. Each such sub-resource must be written to with a separate call to **Texture::writeData()**.
+
+A texture has multiple mip-levels if its **TEXTURE_DESC::numMips** property is larger than zero. 
+A texture has multiple faces if its **TEXTURE_DESC::numArraySlices** property is larger than one, or if texture type is **TextureType::TEX_TYPE_CUBE_MAP**. 
+
+If texture type is **TextureType::TEX_TYPE_CUBE_MAP** then the texture will have six faces by default. If such texture has multiple array slices the total number of faces is 6 * number of array slices. Each face has its own set of mip-map levels (if mip-maps count is larger than zero).
+
+To write to different sub-resources simply provide the mip-level and face index when calling **Texture::writeData()**. Note that when setting mip-levels your **PixelData** object must be of valid size for the mip-level. You can use the helper method @ref bs::PixelUtil::getSizeForMipLevel "PixelUtil::getSizeForMipLevel()" to calculate dimensions of a specific mip level.
+
+~~~~~~~~~~~~~{.cpp}
+// Creates a 2D texture, 128x128 with an 8-bit RGBA format, with maximum number of mipmaps, and 4 faces
+TEXTURE_DESC desc;
+desc.type = TEX_TYPE_2D;
+desc.width = 128;
+desc.heigth = 128;
+desc.numMips = PixelUtil::getMaxMipmaps(128, 128, 1, PF_R8G8B8A8);
+desc.format = PF_R8G8B8A8;
+desc.numArraySlices = 4;
+
+HTexture texture = Texture::create(desc);
+
+// For each face, and for each mip-level, write some data
+for(UINT32 face = 0; face < 4; face++)
+	for(UINT32 mip = 0; mip <= desc.numMips; mip++)
+	{
+		UINT32 mipWidth, mipHeight, mipDepth;
+		PixelUtil::getSizeForMipLevel(128, 128, 1, mip, mipWidth, mipHeight, mipDepth);
+		
+		SPtr<PixelData> pixelData = PixelData::create(mipWidth, mipHeight, 1, PF_R8G8B8A8);
+		
+		Vector<Color> colors;
+		for(UINT32 y = 0; y < mipHeight; y++)
+			for(UINT32 x = 0; x < mipWidth; x++)
+				colors.push_back(Color(x * 2.0f, y * 2.0f, 0.0f, 1.0f));
+
+		pixelData->setColors(colors);
+		texture->writeData(pixelData, face, mip);
+	}
+~~~~~~~~~~~~~
+
+> Note when writing we access a total of *desc.numMips + 1* mip-levels. This is because the 0th mip level is the main texture.
+
+As a shortcut, you can retrieve texture properties by calling **Texture::getProperties()** and then call the @ref bs::TextureProperties::allocBuffer "TextureProperties::allocBuffer()" to automatically create a **PixelData** object of a valid size and format, depending on provided face and mip level.
+
+~~~~~~~~~~~~~{.cpp}
+auto& texProps = texture->getProperties();
+
+// Get buffer with enough space and valid format for 0th face and 2nd mip-level
+SPtr<PixelData> pixelData = texProps.allocBuffer(0, 2);
+// ... populate the buffer and write
+~~~~~~~~~~~~~
+
+## Discard on write
+When you are sure you will overwrite all the contents of a texture, make sure to set the last parameter of **Texture::writeData()** to true. This ensures the system can more optimally execute the transfer, without requiring the GPU to finish its current action (which can be considerably slow if it is currently using that particular texture).
+
+## Generating mip-maps
+Mip-maps are generally created automatically from a source texture, rather than by manually setting their pixels. Therefore Banshee provides @ref bs::PixelUtil::genMipmaps "PixelUtil::genMipmaps()" method that accepts a **PixelData** object containing pixels to generate mip levels from. A maximum number of mip-maps levels is then generated and output. You can optionally customize mip-map generating by providing a @ref bs::MipMapGenOptions "MipMapGenOptions" object.
+
+~~~~~~~~~~~~~{.cpp}
+SPtr<PixelData> pixelData = "...";
+Vector<SPtr<PixelData>> mipMapPixelData = PixelUtil::genMipmaps(*pixelData, MipMapGenOptions());
+
+// Write mipmap data to texture...
+~~~~~~~~~~~~~
+
+## Writing compressed data
+If a **PixelFormat** chosen for your texture uses one of the compressed pixel formats, you will need to compress the data before writing it to the texture. For this purpose you can use the @ref bs::PixelUtil::compress "PixelUtil::compress()" method. The method accepts a source **PixelData** and a destination **PixelData**, as well as a @ref bs::CompressionOptions "CompressionOptions" object that contains the pixel format to compress to, among other options.
+
+~~~~~~~~~~~~~{.cpp}
+SPtr<PixelData> srcPixelData = PixelData::create(128, 128, 1, PF_R8G8B8A8);
+// ... fill up srcPixelData with some colors
+
+// Container for resulting data
+SPtr<PixelData> dstPixelData = PixelData::create(128, 128, 1, PF_BC3);
+
+// Compress into BC3 format
+CompressionOptions options;
+options.format = PF_BC3;
+PixelUtil::compress(srcPixelData, dstPixelData, options);
+
+// Write data to texture...
+~~~~~~~~~~~~~
+
+## Creating textures with data
+If you're creating a texture you wish to immediately populate with data, you can use the overload for @ref bs::Texture::create(const SPtr<PixelData>&, int, bool) "Texture::create()" that accepts a **PixelData** object directly, allowing you to skip the call to **Texture::writeData()**.
+
+~~~~~~~~~~~~~{.cpp}
+SPtr<PixelData> pixelData = PixelData::create(128, 128, 1, PF_R8G8B8A8);
+// ... fill up pixelData with some colors
+
+HTexture texture = Texture::create(pixelData);
+~~~~~~~~~~~~~
+
+# Reading texture data
+
+Reading data from a texture is done similarly to writing, using **PixelData** object as well. There are two ways to read texture data:
+ - Reading cached CPU data
+ - Reading GPU data
+
+## Reading cached CPU data
+Reading cached CPU data allows you to read-back any data you have written to the texture by calling **Texture::writeData()**. It is particularily useful when importing textures from external files and wish to access their pixels. Note that texture must be created with the **TextureUsage::TU_CPUCACHED** usage flag in order for CPU cached data to be available. When importing textures this flag will automatically be set if the relevant property is enabled in **TextureImportOptions**.
+
+Cached CPU data can be read by calling @ref bs::Texture::readCachedData "Texture::readCachedData()". It accepts a **PixelData** parameter to which to output the pixel colors, as well as indices to the face & mip-level to read.
+
+~~~~~~~~~~~~~{.cpp}
+SPtr<PixelData> pixelData = texProps.allocBuffer(0, 0);
+texture->readCachedData(*pixelData);
+~~~~~~~~~~~~~
+
+After reading the data you can access it through @ref bs::PixelData::getColorAt "PixelData::getColorAt()" or @ref bs::PixelData::getColors "PixelData::getColors()".
+
+~~~~~~~~~~~~~{.cpp}
+// Read pixel at 50x50
+Color color = pixelData->getColorAt(50, 50);
+~~~~~~~~~~~~~
+
+Note that cached data reads will not contain any data written by the GPU (e.g. in case the texture is used as a render target or written to by GPU in some other way).
+
+## Reading GPU data
+In case cached CPU reads are not enough, you can perform GPU reads, which always read the most recent data which includes both the data written by the CPU and the GPU. Unlike CPU caching this also does not require additional memory to be used to store texture data. Note that texture must be created with the **TextureUsage::TU_CPUREADABLE** usage flag in order for such reads to be available.
+
+To perform GPU reads call @ref bs::Texture::readData "Texture::readData()" which has the same interface as **Texture::readCachedData()**.
+
+~~~~~~~~~~~~~{.cpp}
+SPtr<PixelData> pixelData = texProps.allocBuffer(0, 0);
+texture->readData(*pixelData);
+~~~~~~~~~~~~~
+
+Note that performing GPU reads will almost certainly cause a GPU pipeline stall, requiring all GPU operations to finish before the read completes. Such stalls can severely impact performance and should generally be avoided.
+
+Also note that this operation is asynchronous. This means the function will return immediately, but the actual contents of the provided **PixelData** object will not be populated until the async operation finishes. Read the [mini-manual](@ref asyncMethod) for async operations for more information.
+
+# Other
+Take a look at @ref bs::PixelUtil "PixelUtil" class for a variety of helper methods for manipulating pixel data and colors.

Documentation/Manuals/Native/User/importingTextures.md

@@ -103,7 +103,7 @@ importOptions->setSRGB(true);
 ## Caching
 Sometimes you need to import a texture you don't want to only use for rendering, but rather for manually reading its contents. When that's the case you can enable the @ref bs::TextureImportOptions::setCPUCached "TextureImportOptions::setCPUCached" option.
 
-This will allow you to call @ref bs::Texture::readCachedData "Texture::readCachedData" and to manually read individual pixels of the texture.
+This will allow you to call @ref bs::Texture::readCachedData "Texture::readCachedData()" and to manually read individual pixels of the texture.
 
 Note that caching a texture means its data will be available in system memory, essentially doubling its memory usage.
 

Documentation/Manuals/Native/apiRefPages.md

@@ -32,4 +32,6 @@ Optionally, if the method returns an @ref bs::AsyncOp "AsyncOp" object, you can
 
 If the method provides a return value, you can use the provided **AsyncOp** object to retrieve it using @ref bs::AsyncOp::getReturnValue<T> "AsyncOp::getReturnValue<T>". Calling this is only valid if @ref bs::AsyncOp::hasCompleted "AsyncOp::hasCompleted" returns true. Return value is always available after you blocked using either of the ways mentioned above.
 
-Note that blocking is a very expensive operation and should not be done in performance critical code. If you need to wait until an async method completes, it is preferable to keep querying **AsyncOp::hasCompleted** and do something else until it returns true.
+Note that blocking is a very expensive operation and should not be done in performance critical code. If you need to wait until an async method completes, it is preferable to keep querying **AsyncOp::hasCompleted** and do something else until it returns true.
+
+If you wish to learn more about how core thread works, visit the [core thread manual](@ref coreThread).

Documentation/Manuals/Native/coreThread.md

@@ -24,7 +24,7 @@ As you can see the communication is one directional. Simulation thread calls int
 # Command queue {#coreThread_a}
 All the operations listed above happen with the help of a command queue. When simulation thread needs to notify the core thread about something it queues a command, which is then eventually received and processed by the core thread.
 
-@ref bs::CoreThread "CoreThread" managed the command queues. Use @ref bs::CoreThread::queueCommand "CoreThread::queueCommand" to queue a new command.
+@ref bs::CoreThread "CoreThread" manages the command queues. Use @ref bs::CoreThread::queueCommand "CoreThread::queueCommand" to queue a new command.
 
 Each thread has its own command queue, so calling this method from multiple threads will fill up different command queues.
 

Documentation/Manuals/Native/manuals.md

@@ -59,6 +59,7 @@ Manuals									{#manuals}
  - [Bones](@ref bones)
  - [Advanced animation](@ref advancedAnimation)
 - **Advanced**
+ - [Manipulating textures](@ref advancedTextures)
  - [Advanced RTTI](@ref advancedRtti) 
  
 # Developer guides

Source/BansheeCore/Include/BsComponent.h

@@ -92,7 +92,7 @@ namespace bs
 		virtual void _instantiate() {}
 
 		/** Sets new flags that determine when is onTransformChanged called. */
-		void _setNotifyFlags(TransformChangedFlags flags) { mNotifyFlags = flags; }
+		void setNotifyFlags(TransformChangedFlags flags) { mNotifyFlags = flags; }
 
 		/** Gets the currently assigned notify flags. See _setNotifyFlags(). */
 		TransformChangedFlags _getNotifyFlags() const { return mNotifyFlags; }

Source/SBansheeEngine/Source/BsScriptComponent.cpp

@@ -266,7 +266,7 @@ namespace bs
 		HComponent component = nativeInstance->getComponent();
 
 		if (!checkIfDestroyed(component))
-			component->_setNotifyFlags(flags);
+			component->setNotifyFlags(flags);
 	}
 	
 	void ScriptComponent::internal_destroy(ScriptComponentBase* nativeInstance, bool immediate)