Finished resources manual, improvde renderAPI, coreThread, gui manuals

Documentation/Manuals/Native/coreThread.md

@@ -137,11 +137,18 @@ Core objects might be dependant on other core objects. For example a @ref Banshe
 
 To add dependencies implement the @ref BansheeEngine::CoreObject::getCoreDependencies "CoreObject::getCoreDependencies" method, which returns all currently valid dependencies. Whenever the dependencies change call @ref BansheeEngine::CoreObject::markDependenciesDirty "CoreObject::markDependenciesDirty" so the system can refresh its dependency list.
 
-## Other features {#coreThread_b_b}
+## Deserialization {#coreThread_b_b}
+When creating RTTI for a @ref BansheeEngine::CoreObject "CoreObject", as described in the [RTTI](@ref rtti) manual, you must take care not to fully initialize the object until deserialization of the object's fields is done.
+
+Essentially this means that @ref BansheeEngine::RTTITypeBase::newRTTIObject "RTTIType::newRTTIObject" must return a pointer to the core object on which @ref BansheeEngine::CoreObject::initialize "CoreObject::initialize" hasn't called yet. You must then call @ref BansheeEngine::CoreObject::initialize "CoreObject::initialize" manually in @ref BansheeEngine::RTTITypeBase::onDeserializationEnded "RTTIType::onDeserializationEnded".
+
+This ensures that @ref BansheeEngine::CoreObject::initialize "CoreObject::initialize" has all the relevant information when it is ran.
+
+## Other features {#coreThread_b_c}
 Core objects also have some other potentially useful features:
  - @ref BansheeEngine::CoreObject::getInternalID "CoreObject::getInternalID" will return a globally unique ID for the core object
  - @ref BansheeEngine::CoreObject::destroy "CoreObject::destroy" will destroy the core object and its core thread counterpart. You do not need to call this manually as it will be automatically called when the object goes out of scope (is no longer referenced). The core thread counterpart (@ref BansheeEngine::CoreObjectCore "CoreObjectCore") will not be destroyed if something on the core thread is still holding a reference to it.
- - Override @ref BansheeEngine::CoreObject::initialize "CoreObject::initialize" or @ref BansheeEngine::CoreObject::destroy "CoreObject::destroy" methods if you need to perform some initialization/destruction operations not suitable for the constructor/destructor (e.g. calling virtual methods).
+ - Override @ref BansheeEngine::CoreObject::initialize "CoreObject::initialize" or @ref BansheeEngine::CoreObject::destroy "CoreObject::destroy" methods instead of using the constructor/destructor. This ensures that your initialization code runs after things like serialization, and also allows you to call virtual methods.
  - You can construct a core object without a core thread counterpart. Simply don't override @ref BansheeEngine::CoreObject::createCore "CoreObject::createCore".
  - You can construct a core object with a @ref BansheeEngine::CoreObjectCore "CoreObjectCore" that isn't initialized on the core thread by setting the @ref BansheeEngine::CoreObject "CoreObject" constructor parameter `requiresCoreInit` to false.
  - Core objects always hold a shared pointer to themselves. Use @ref BansheeEngine::CoreObject::getThisPtr "CoreObject::getThisPtr" to access it.

Documentation/Manuals/Native/gui.md

@@ -84,6 +84,6 @@ If you ever require to render text completely manually (perhaps even outside of
 
 Once you have a custom GUI element you might want to expose it to the scripting API. Take a look at the [scripting interop guide](@ref scripting) to learn how to create scripting API objects. 
 
-Every GUI scripting interop object must implement @ref BansheeEngine::TScriptGUIElement "TScriptGUIElement", but other than that creating GUI interop objects is the same as the general case described in the guide above. See @ref BansheeEngine::ScriptGUITexture "ScriptGUITexture" for an example.
+Every GUI scripting interop object must implement @ref BansheeEngine::TScriptGUIElement "TScriptGUIElement", but other than that creating GUI interop objects is the same as the general case described in the guide above. See @ref BansheeEngine::ScriptGUITexture "ScriptGUITexture" in `BsScriptGUITexture.cpp` for an example.
 
-Creating managed GUI objects is again the same as the general case. Take a look at the managed GUITexture implementation for an example.
+Creating managed GUI objects is again the same as the general case. Take a look at the managed GUITexture implementation in `GUITexture.cs` for an example.

Documentation/Manuals/Native/renderAPI.md

@@ -243,4 +243,11 @@ rapi.dispatchCompute(512, 512);
 ... read from our texture to get the result ...
 ~~~~~~~~~~~~~
 
-We won't go any deeper about the details of the compute pipeline as this information can be found by learning about the GPU pipeline in general from other sources.
+We won't go any deeper about the details of the compute pipeline as this information can be found by learning about the GPU pipeline in general from other sources.
+
+# API specifics {#renderAPI_h}
+@ref BansheeEngine::RenderAPI "RenderAPI" can be internally implemented by a variety of actual rendering API's like DirectX or OpenGL. Most of the functionality is shared, but there are always some differences between them to be noted (for example DirectX uses a depth range of [0, 1] while OpenGL uses [-1, 1]). Often those differences can be important for various rendering algorithms.
+
+Use @ref BansheeEngine::RenderAPI::getAPIInfo "RenderAPI::getAPIInfo" to receive the @ref BansheeEngine::RenderAPIInfo "RenderAPIInfo" containing such information, so you may modify your rendering accordingly. 
+
+For convenience a specialized @ref BansheeEngine::RenderAPI::convertProjectionMatrix "RenderAPI::convertProjectionMatrix" method is also provided, which converts a generic engine projection matrix, into a render API specific one.

Documentation/Manuals/Native/resources.md

@@ -72,17 +72,68 @@ HTexture texture = Texture::create(TEX_TYPE_2D, 1280, 720, 0, PF_R8G8B8A8);
 gResources().save(texture, "myTexture.asset");
 ~~~~~~~~~~~~~
 
-# Creating your own resource
+# Creating your own resource {#resources_c}
+To create your own resource, derive a class from @ref BansheeEngine::Resource "Resource" and:
+ - Implement the @ref BansheeEngine::CoreObject "CoreObject" interface as described in the [core thread](@ref coreThread) manual
+ - Implement a RTTI object as described in the [RTTI](@ref rtti) manual
+ 
+Every resource is also a @ref BansheeEngine::CoreObject "CoreObject", but not every resource actually needs a core thread representation (for example a @ref BansheeEngine::Font "Font" is not relevant on the core thread). In such a case you can provide false to the `requiresGpuInitialization` parameter of the @ref BansheeEngine::CoreObject "CoreObject" constructor. This also means you can ignore implementing most of the @ref BansheeEngine::CoreObject "CoreObject" interface.
+
+When creating resources, aside from the normal @ref BansheeEngine::CoreObject "CoreObject" creation requirements, you must also call @ref BansheeEngine::Resources::_createResourceHandle "Resources::_createResourceHandle". This method accepts a resource pointer and returns a resource handle. Similar to @ref BansheeEngine::CoreObject "CoreObject" initialization, this should probably be wrapped as a part of a static `create` method and hidden from the user.
+
+See @ref BansheeEngine::Font "Font" implementation in `BsFont.cpp` for an example of a simple resource implementation.
+
+## Exposing resources to scripting {#resources_c_a}
+Once you have a custom resource you might want to expose it to the scripting API. Take a look at the [scripting interop guide](@ref scripting) to learn how to create scripting API objects. 
+
+Every resource scripting interop object must implement @ref BansheeEngine::TScriptResource "TScriptResource", but other than that creating GUI interop objects is the same as the general case described in the guide above. See @ref BansheeEngine::ScriptFont "ScriptFont" in `BsScriptFont.cpp` for an example.
+
+Creating managed GUI objects is again the same as the general case. Take a look at the managed `Font` implementation in `Font.cs` for an example.
+
+Resources are unlike most other scripting objects because they can be created in the native code and then used in the managed code, or vice versa. Resources are also serialized by reference, which requires some specialized code for managed serialization to properly recognize the resource. 
+
+### Native <-> managed resource conversion {#resources_c_a_a}
+When a resource is created in native code, but needs to be passed to scripting code, the system creates a script interop object and a managed object, which wrap the native resource. The system also needs to be aware if such managed representation of an object already exists, and return an existing one if so. This is the job of the @ref BansheeEngine::ScriptResourceManager "ScriptResourceManager".
+
+You will need to update this manager with your custom resource type. Relevant methods are:
+ - @ref BansheeEngine::ScriptResourceManager::createScriptResource "ScriptResourceManager::createScriptResource" - Creates a new managed object instance from a native resource (only valid if one doesn't already exist). This method has two overloads, and is specialized for specific resource types. Make sure to add a specialization for both overloads, with your custom resource type. And also update the specialization that accepts a generic @ref BansheeEngine::ResourceHandleBase "HResource" with an entry of your own resource. You can use existing resources as an example of how it should be done, only the type names need changing.
+ - @ref BansheeEngine::ScriptResourceManager::getScriptResource<RetType, InType> "ScriptResourceManager::getScriptResource" - Retrieves an existing managed object instance from a native resource handle. Optionally creates the managed object if one doesn't already exist. Add a specialization for your own resource type similar to methods above.
 
-// General info, registering with Resources
-// Custom resource handle
-// RTTI - Link to manual
-// Exposing resource to scripting
+### Managed resource serialization {#resources_c_a_b}
+In order for your new resource type to be properly referenced by serialized managed objects you need to make a few more additions:
+ - First of append a new resource type to the @ref BansheeEngine::ScriptReferenceType "ScriptReferenceType" enum.
+ - Append a new entry to @ref BansheeEngine::ManagedSerializableTypeInfoRef::getMonoClass "ManagedSerializableTypeInfoRef::getMonoClass" which maps the enum entry above to your resource script interop object type
+ - Append a new entry to @ref BansheeEngine::ManagedSerializableTypeInfoRef::isTypeLoaded "ManagedSerializableTypeInfoRef::isTypeLoaded" so it always returns true if your resource is encountered (since it's built-in, it's always loaded)
+ - Append a new entry in the @ref BansheeEngine::ScriptAssemblyManager::getTypeInfo "ScriptAssemblyManager::getTypeInfo" which maps the managed resource object type to the enum above
+ - Append a new entry to the `getResourceFieldLookup` method in `BsManagedSerializableField.cpp` which uses the native <-> managed conversion methods to map between a native and a managed instance of a resource during serialization/deserialization
+ 
+For all of these you can use examples of existing resources which already exist within the mentioned methods, it is just a matter of changing the type/enum names for your own resource. 
+ 
+### Other {#resources_c_a_c}
+In order for your resources to be properly recognized by GUI drop fields, as well as the project library append new entries to @ref BansheeEngine::ScriptResource::getClassFromTypeId "ScriptResource::getClassFromTypeId" and @ref BansheeEngine::ScriptResource::getTypeFromTypeId "ScriptResource::getTypeFromTypeId" which map between the enum above and the RTTI type ID of the resource.
+
+# Advanced {#resources_d}
+This section lists some more advanced (and optional) features when dealing with resources.
+
+## Dependencies {#resources_d_a}
+When creating a custom resource that is dependant on some other resource(s), make sure to implement @ref BansheeEngine::Resource::getResourceDependencies "Resource::getResourceDependencies" which returns a list of all resources it is dependant upon. These resources will be checked when @ref BansheeEngine::ResourceHandleBase::isLoaded "HResource::isLoaded" or @ref BansheeEngine::ResourceHandleBase::blockUntilLoaded "HResource::blockUntilLoaded" is called with `checkDependencies` parameter enabled.
+
+This does not impact the dependencies that are loaded with @ref BansheeEngine::Resources::load "Resources::load". ALL referenced non-weak resource handles will be loaded regardless of @ref BansheeEngine::Resource::getResourceDependencies "Resource::getResourceDependencies" implementation.
+
+## Resource listener {#resources_d_b}
+If an object is interested in learning when a certain resource has been loaded, or updated you can implement the @ref BansheeEngine::IResourceListener "IResourceListener" interface. For example this can be used for refreshing a @ref BansheeEngine::Material "Material" if the @ref BansheeEngine::Shader "Shader" it is dependant upon changes. This also allows you to wait when initializing an object dependant on other resources, in case those resources are being loaded asynchronously.
+
+To implement it you must return a list of resource handles you are interested in tracking by implementing the @ref BansheeEngine::IResourceListener::getListenerResources "IResourceListener::getListenerResources" method. Whenever the dependant resource list changes you should call @ref BansheeEngine::IResourceListener::markListenerResourcesDirty "IResourceListener::markListenerResourcesDirty".
+
+After you have set up the listener resources, whenever such a resource is loaded @ref BansheeEngine::IResourceListener::notifyResourceLoaded "IResourceListener::notifyResourceLoaded" will be called, and when it is updated (via @ref BansheeEngine::Resources::update "Resources::update") @ref BansheeEngine::IResourceListener::notifyResourceChanged "IResourceListener::notifyResourceChanged" will be called.
+ 
+@ref BansheeEngine::Resources "Resources" also provides @ref BansheeEngine::Resources::onResourceLoaded "Resources::onResourceLoaded", @ref BansheeEngine::Resources::onResourceDestroyed "Resources::onResourceDestroyed" and @ref BansheeEngine::Resources::onResourceModified "Resources::onResourceModified" events which may be used for similar purpose, but @ref BansheeEngine::IResourceListener "IResourceListener" is more efficient since it only tracks specific resources.
 
-# Advanced
+## Resource manifest {#resources_d_c}
+Every time a resource is saved via @ref BansheeEngine::Resources::save "Resources::save", its UUID and file path is stored in a @ref BansheeEngine::ResourceManifest "ResourceManifest". This manifest is used primarily by the deserialization process, so it knows to find resource file paths from the resource handle UUIDs that were serialized.
 
-// Resource dependencies
-// Resource listener
+Without this manifest every time a user saved an object referencing a resource (like a scene), then restarted the application the system would no longer know where to locate the referenced resources. When using the editor or the scripting API the manifest is managed for you, but if you are building an application on a lower level, you must manage it yourself.
 
+Use @ref BansheeEngine::Resources::getResourceManifest "Resources::getResourceManifest" to retrieve a manifest. By default only one manifest with the name "Default" is registered. You will need to save this manifest before application shut-down and restore it upon application start-up. To restore a manifest call @ref BansheeEngine::Resources::registerResourceManifest "Resources::registerResourceManifest".
 
-// TODO - Resource manifest
+You can register multiple manifests and the system will scan all of them to find resource paths. If a resource exists in multiple ones, then the latest registered one takes priority. You can unregister a manifest by calling @ref BansheeEngine::Resources::unregisterResourceManifest "Resources::unregisterResourceManifest"

Source/SBansheeEngine/Include/BsScriptResource.h

@@ -126,7 +126,7 @@ namespace BansheeEngine
 		static UINT32 getTypeIdFromType(ScriptResourceType type);
 
 		/**	Converts a RTTI id belonging to a resource type into a managed class representing that type. */
-		static MonoClass* ScriptResource::getClassFromTypeId(UINT32 typeId);
+		static MonoClass* getClassFromTypeId(UINT32 typeId);
 	private:
 		ScriptResource(MonoObject* instance)
 			:ScriptObject(instance)