diff --git a/Doc/DesignCodeExamples/Assets/BasicAssetUsage.bf b/Doc/DesignCodeExamples/Assets/BasicAssetUsage.bf new file mode 100644 index 0000000..3787ca7 --- /dev/null +++ b/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(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(_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(); + + // ... + // 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(handle); // Alternative: _lineEffect = handle.Get(); + // 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(); +} diff --git a/Doc/DesignCodeExamples/Assets/SmartAssetHandle.bf b/Doc/DesignCodeExamples/Assets/SmartAssetHandle.bf new file mode 100644 index 0000000..b0c0340 --- /dev/null +++ b/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 _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. +// diff --git a/Doc/DesignCodeExamples/readme.md b/Doc/DesignCodeExamples/readme.md new file mode 100644 index 0000000..69326ab --- /dev/null +++ b/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. \ No newline at end of file