More user manuals and minor usability tweaks

Documentation/Manuals/Native/User/resourceBasicsAndImport.md

@@ -0,0 +1,39 @@
+Resource basics and import					{#resourceBasicsAndImport}
+===============
+
+Resources represent data that you can load from disk and use in your application. These may be images, meshes, fonts, and others. Normally these resources originate from other content creation programs like Photoshop or Maya. 
+
+# Import
+Before you can use such resources in the engine, you must first import them, converting them from their original format (e.g. ".jpg") into an engine object (e.g. a **Texture**).
+
+You can import resources from its source format (e.g. ".jpg") into engine by using the @ref bs::Importer "Importer" module, accessible globally through @ref bs::gImporter() "gImporter()". Lets see an example of importing a **Texture** resource:
+
+~~~~~~~~~~~~~{.cpp}
+// Import a texture named "myTexture.jpg" from the disk
+HTexture texture = gImporter().import<Texture>("myTexture.jpg");
+~~~~~~~~~~~~~
+
+We will touch upon different resource types like meshes and textures in later chapters. For now don't worry about what **Texture** is or how it works, nor what other resources types exist, and focus instead on the more general resource logic.
+
+# Handles
+Similar to scene objects and components, resources are also represented using handles. Resource handles are prefixed with an "H", followed by the resource class name (e.g. **HTexture** for the **Texture** resource, as seen above).
+
+You may treat the handles as pointers, using "->" to access their members, comparing them for equality or with *nullptr* to check their validity. 
+
+# Customizing import
+Sometimes you need more control over import. In which case you can provide an additional **ImportOptions** object to the @ref bs::Importer::import<T> "Importer::import<T>" method. See the example below on how we change the texture format on import, using **TextureImportOptions**.
+
+~~~~~~~~~~~~~{.cpp}
+// Create an import options object specific to textures
+auto importOptions = TextureImportOptions::create();
+
+// Specify we wish to import the texture as an uncompressed 32-bit RGBA format
+importOptions->setFormat(PF_R8G8B8A8); 
+
+// Import a texture using the specified import options
+HTexture texture = gImporter().import<Texture>("myTexture.jpg", importOptions);
+~~~~~~~~~~~~~
+
+We'll touch more on import options as we talk about specific resource types in later chapters.
+
+> Import option class names always start with the name of their resource, followed by "ImportOptions". e.g. **TextureImportOptions** for the **Texture** resource. However not all resource types have an import options object, in which case you have no choice but to import them in the default way.

Documentation/Manuals/Native/User/resourceSavingAndLoading.md

@@ -0,0 +1,42 @@
+Resource saving and loading					{#resourceSavingAndLoading}
+===============
+
+All resource save and load operations are managed through the @ref bs::Resources "Resources" module, accessible through @ref bs::gResources() "gResources"().
+
+# Saving
+Once a resource has been imported you can save it for later use. The advantage of saving a resource (instead of importing it every time) is performance - resource import is usually a costly operation. Saved resources remain in engine-friendly format and can be easily loaded later. 
+
+To save a resource call @ref bs::Resources::save "Resources::save". Lets see an example where we import a texture and then save it for later use:
+
+~~~~~~~~~~~~~{.cpp}
+// Import a texture named "myTexture.jpg" from the disk
+HTexture texture = gImporter().import<Texture>("myTexture.jpg");
+
+// Save the texture for later use
+gResources().save(texture, "myTexture.asset");
+~~~~~~~~~~~~~
+
+Note that resources can also be created within the engine, and don't necessarily have to be imported. e.g. you can populate texture pixels or mesh vertices manually, and then save the resource in this same manner. We will show later how to manually create resources.
+
+# Loading
+Once a resource has been saved you can load it at any time using @ref bs::Resources::load "Resources::load". Lets load the texture we just saved:
+
+~~~~~~~~~~~~~{.cpp}
+HTexture loadedTexture = gResources().load<Texture>("myTexture.asset");
+~~~~~~~~~~~~~
+
+> Extra: If you attempt to load a resource that has already been loaded, the system will return the existing resource.
+
+> Extra: You can load resources asynchronously (in the background) by calling @ref bs::Resources::loadAsync "Resources::loadAsync"
+
+# Unloading
+Note that the resource system by default never unloads a loaded resource, unless told explicitly. To unload a resource call @ref bs::Resources::release "Resources::release".
+
+To unload the texture we loaded previously:
+~~~~~~~~~~~~~{.cpp}
+gResources().release(loadedTexture);
+~~~~~~~~~~~~~
+
+> Note that if you called **Resources::load** multiple times, you must also call **Resources::release** the same amount of times.
+
+> Extra: You can also force the system to automatically unload a resource when it is no longer being referenced. Just make sure you don't set the @ref bs::ResourceLoadFlag::KeepInternalRef "ResourceLoadFlag::KeepInternalRef" flag as the second parameter of @ref bs::Resources::load "Resources::load" (set by default).

Documentation/Manuals/Native/manuals.md

@@ -7,7 +7,8 @@ Manuals									{#manuals}
 - [Startup and main loop](@ref startup)
 - [Scene objects and components](@ref scenesAndComponents)
 - Resources
- - [Importing](@ref importing)
+ - [Basics and import](@ref resourceBasicsAndImport)
+ - [Saving and loading](@ref resourceSavingAndLoading)
  
 # Developer guides
 

Source/BansheeCore/Include/BsAudioClipImportOptions.h

@@ -47,6 +47,9 @@ namespace bs
 
 		// Note: Add options to resample to a different frequency
 
+		/** Creates a new import options object that allows you to customize how are audio clips imported. */
+		static SPtr<AudioClipImportOptions> create();
+
 	private:
 		AudioFormat mFormat;
 		AudioReadMode mReadMode;

Source/BansheeCore/Include/BsFontImportOptions.h

@@ -66,6 +66,9 @@ namespace bs
 		/**	Sets whether the italic font style should be used when rendering. */
 		bool getItalic() const { return mItalic; }
 
+		/** Creates a new import options object that allows you to customize how are fonts imported. */
+		static SPtr<FontImportOptions> create();
+
 	private:
 		Vector<UINT32> mFontSizes;
 		Vector<std::pair<UINT32, UINT32>> mCharIndexRanges;

Source/BansheeCore/Include/BsMeshImportOptions.h

@@ -168,6 +168,9 @@ namespace bs
 		 */
 		bool getImportRootMotion() const { return mImportRootMotion; }
 
+		/** Creates a new import options object that allows you to customize how are meshes imported. */
+		static SPtr<MeshImportOptions> create();
+
 	private:
 		bool mCPUCached;
 		bool mImportNormals;

Source/BansheeCore/Include/BsResources.h

@@ -19,7 +19,7 @@ namespace bs
 		/** If enabled all resources referenced by the root resource will be loaded as well. */
 		LoadDependencies = 1 << 0, 
 		/**
-		 * If enabled the resource system will keep an internal reference to the resource so it doesn't get destroyed with
+		 * If enabled the resource system will keep an internal reference to the resource so it doesn't get destroyed when
 		 * it goes out of scope. You can call Resources::release() to release the internal reference. Each call to load will
 		 * create a new internal reference and therefore must be followed by the same number of release calls. If
 		 * dependencies are being loaded, they will not have internal references created regardless of this parameter.
@@ -83,9 +83,6 @@ namespace bs
 		 * Loads the resource from a given path. Returns an empty handle if resource can't be loaded. Resource is loaded 
 		 * synchronously.
 		 *			
-		 * All loaded resources are reference counted and will be automatically unloaded when all of their references go out
-		 * of scope. 
-		 *			
 		 * @param[in]	filePath	File path to the resource to load. This can be absolute or relative to the working 
 		 *							folder.
 		 * @param[in]	loadFlags	Flags used to control the load process.
@@ -117,14 +114,11 @@ namespace bs
 
 		/**
 		 * Loads the resource asynchronously. Initially returned resource handle will be invalid until resource loading is 
-		 * done.
+		 * done. Use ResourceHandle<T>::isLoaded to check if resource has been loaded, or 
+		 * ResourceHandle<T>::blockUntilLoaded to wait until load completes.
 		 *
 		 * @param[in]	filePath	Full pathname of the file.
 		 * @param[in]	loadFlags	Flags used to control the load process.
-		 *
-		 * @note	
-		 * You can use returned invalid handle in many engine systems as the engine will check for handle validity before 
-		 * using it.
 		 *			
 		 * @see		load(const Path&, ResourceLoadFlags)
 		 */

Source/BansheeCore/Include/BsTextureImportOptions.h

@@ -66,6 +66,9 @@ namespace bs
 		 */
 		bool getSRGB() const { return mSRGB; }
 
+		/** Creates a new import options object that allows you to customize how are textures imported. */
+		static SPtr<TextureImportOptions> create();
+
 		/************************************************************************/
 		/* 								SERIALIZATION                      		*/
 		/************************************************************************/

Source/BansheeCore/Source/BsAudioClipImportOptions.cpp

@@ -11,6 +11,11 @@ namespace bs
 		
 	}
 
+	SPtr<AudioClipImportOptions> AudioClipImportOptions::create()
+	{
+		return bs_shared_ptr_new<AudioClipImportOptions>();
+	}
+
 	/************************************************************************/
 	/* 								SERIALIZATION                      		*/
 	/************************************************************************/

Source/BansheeCore/Source/BsFontImportOptions.cpp

@@ -22,6 +22,11 @@ namespace bs
 		mCharIndexRanges.clear();
 	}
 
+	SPtr<FontImportOptions> FontImportOptions::create()
+	{
+		return bs_shared_ptr_new<FontImportOptions>();
+	}
+
 	/************************************************************************/
 	/* 								SERIALIZATION                      		*/
 	/************************************************************************/

Source/BansheeCore/Source/BsMeshImportOptions.cpp

@@ -31,6 +31,11 @@ namespace bs
 		, mCollisionMeshType(CollisionMeshType::None)
 	{ }
 
+	SPtr<MeshImportOptions> MeshImportOptions::create()
+	{
+		return bs_shared_ptr_new<MeshImportOptions>();
+	}
+
 	RTTITypeBase* MeshImportOptions::getRTTIStatic()
 	{
 		return MeshImportOptionsRTTI::instance();

Source/BansheeCore/Source/BsTextureImportOptions.cpp

@@ -9,6 +9,11 @@ namespace bs
 		: mFormat(PF_R8G8B8A8), mGenerateMips(false), mMaxMip(0), mCPUReadable(false), mCPUCached(false), mSRGB(false)
 	{ }
 
+	SPtr<TextureImportOptions> TextureImportOptions::create()
+	{
+		return bs_shared_ptr_new<TextureImportOptions>();
+	}
+
 	/************************************************************************/
 	/* 								SERIALIZATION                      		*/
 	/************************************************************************/

Source/BansheeEngine/Include/BsScriptCodeImportOptions.h

@@ -24,6 +24,9 @@ namespace bs
 		/**	Checks whether the script is editor-only or a normal game script. */
 		bool isEditorScript() const { return mEditorScript; }
 
+		/** Creates a new import options object that allows you to customize how is script code imported. */
+		static SPtr<ScriptCodeImportOptions> create();
+
 		/************************************************************************/
 		/* 								SERIALIZATION                      		*/
 		/************************************************************************/

Source/BansheeEngine/Include/BsScriptCodeImporter.h

@@ -19,16 +19,16 @@ namespace bs
 		virtual ~ScriptCodeImporter();
 
 		/** @copydoc SpecificImporter::isExtensionSupported */
-		virtual bool isExtensionSupported(const WString& ext) const override;
+		bool isExtensionSupported(const WString& ext) const override;
 
 		/** @copydoc SpecificImporter::isMagicNumberSupported */
-		virtual bool isMagicNumberSupported(const UINT8* magicNumPtr, UINT32 numBytes) const override;
+		bool isMagicNumberSupported(const UINT8* magicNumPtr, UINT32 numBytes) const override;
 
 		/** @copydoc SpecificImporter::import */
-		virtual SPtr<Resource> import(const Path& filePath, SPtr<const ImportOptions> importOptions) override;
+		SPtr<Resource> import(const Path& filePath, SPtr<const ImportOptions> importOptions) override;
 
 		/** @copydoc SpecificImporter::createImportOptions */
-		virtual SPtr<ImportOptions> createImportOptions() const override;
+		SPtr<ImportOptions> createImportOptions() const override;
 
 		static const WString DEFAULT_EXTENSION;
 	};

Source/BansheeEngine/Source/BsScriptCodeImportOptions.cpp

@@ -11,6 +11,11 @@ namespace bs
 
 	}
 
+	SPtr<ScriptCodeImportOptions> ScriptCodeImportOptions::create()
+	{
+		return bs_shared_ptr_new<ScriptCodeImportOptions>();
+	}
+
 	/************************************************************************/
 	/* 								SERIALIZATION                      		*/
 	/************************************************************************/