AssetHandle Code snippets for design reference

Doc/DesignCodeExamples/Assets/BasicAssetUsage.bf

@@ -0,0 +1,92 @@
+///
+/// Loading and usage of an asset.
+///
+// Shows the usage of the Content Manager.
+// An asset is loaded with Content.LoadAsset(AssetName)
+// Loading an asset returns an AssetHandle.
+// Usually you want to hold on to the AssetHandle.
+// If you need the actual asset you can use Content.GetAsset<AssetType>(AssetHandle) to retrieve the actual asset.
+
+/*
+ * Only hold on to AssetHandle.
+ * Do NOT hold actual Assets! The Asset might get invalidated
+ * (e.g. reloading after the source-file changed).
+ */
+AssetHandle _lineEffect;
+
+void Start()
+{
+    /*
+     * Loading an asset returns a handle to that asset.
+     */
+    _lineEffect = Content.LoadAsset("Shaders\\LineEffect.hlsl");
+}
+
+void Update()
+{
+    // Use case 1:
+    {
+        // Retrieve the actual asset. Note that this Asset is only guaranteed to persist
+        // for the current frame.
+        Effect fx = Content.GetAsset<Effect>(_lineEffect);
+
+        // Note: Assets are ref counted, however since they are not inteded to be held GetAsset 
+        // does NOT increment the reference counter so you usually should NOT decrement it.
+        // The exception is when you manually hold on to an asset (see Example below)
+
+        // Use asset
+        fx.Variables["ViewProjection"].SetData(viewProjection * transform);
+        fx.Variables["Color"].SetData(color);
+        fx.ApplyChanges();
+        fx.Bind();
+    }
+
+    // Use case 2:
+    {
+        // Retrieve the actual asset.
+        Effect fx = _lineEffect.Get<Effect>();
+
+        // ...
+        // Same as case 1
+    }
+}
+
+
+///
+/// Holding on to an actual asset.
+///
+// Shows the usage of the Content Manager when you hold a reference to the actual Asset instead of the handle.
+// This should usually not be done. Eventhough it is technically fine, it has the implication, that if the
+// content manager decides to reload the asset the changes will not be reflected in the held reference
+// (which they would if you used GetAsset before every usage.)
+// Also the content manager can't unload the asset because the reference counter wouldn't be zero.
+// Though there currently is no way for the content manager to unload an asset unless it is specifically told to do so.
+
+/*
+ * Field to hold the asset.
+ */
+Effect _lineEffect;
+
+void Start()
+{
+    // Load the Asset.
+    AssetHandle handle = Content.LoadAsset("Shaders\\LineEffect.hlsl");
+    // Get the actual asset.
+    _lineEffect = Content.GetAsset<Effect>(handle); // Alternative: _lineEffect = handle.Get<Effect>();
+    // Increment the reference counter so that the asset doesn't get unloaded.
+    _lineEffect.AddRef();
+}
+
+void Destroy()
+{
+    // Make sure to release the asset once you don't need it anymore. Otherwise it will leak.
+    _lineEffect.Release();
+}
+
+void Update()
+{
+    _lineEffect.Variables["ViewProjection"].SetData(viewProjection * transform);
+    _lineEffect.Variables["Color"].SetData(color);
+    _lineEffect.ApplyChanges();
+    _lineEffect.Bind();
+}

Doc/DesignCodeExamples/Assets/SmartAssetHandle.bf

@@ -0,0 +1,44 @@
+///
+/// This shows the usage of a smart/typed Asset Handle.
+///
+// In the basic usage-patterns the user has two options:
+// Either he/she holds a handle and has to query for the actual asset every time
+// or he/she hold the actual asset and loses reloading capabilities.
+// The idea of the auto asset is to provide a way that can provide both.
+
+AssetHandle<Effect> _lineEffect;
+
+void Start()
+{
+    /*
+     * Loading an asset returns a handle to that asset.
+     * The asset handle is implicitly converted to a smart AssetHandle.
+     */
+    _lineEffect = Content.LoadAsset("Shaders\\LineEffect.hlsl");
+}
+
+void Update()
+{
+    // Use case 1 (Convenience)
+    {
+        _lineEffect.Variables["ViewProjection"].SetData(viewProjection * transform);
+        _lineEffect.Variables["Color"].SetData(color);
+        _lineEffect.ApplyChanges();
+        _lineEffect.Bind();
+    }
+
+    // Use case 2 (Technically more efficient)
+    {
+        Effect fx = _lineEffect.Get();
+        fx.Variables["ViewProjection"].SetData(viewProjection * transform);
+        fx.Variables["Color"].SetData(color);
+        fx.ApplyChanges();
+        fx.Bind();
+    }
+}
+
+//
+// Auto Assets use comp time to expose all the fields, Methods and properties of the actual asset.
+// They will automatically check if the asset for the handle changed and update accordingly.
+// This means it is more convenient to use than both basic patterns and has all benefits of both. 
+//

Doc/DesignCodeExamples/readme.md

@@ -0,0 +1,3 @@
+# Design Code Examples
+
+This directory (and its subdirectories) contains non functional code snippets showing the intended usage of certain systems of the engine.