GL Studio C++ Runtime API
gls_resource_file_mgr.h
Go to the documentation of this file.
1/// \file gls_resource_file_mgr.h
2/// \brief Resource file manager interface.
3///
4/// \par Copyright Information
5///
6/// Copyright (c) 2026 by The DiSTI Corporation.<br>
7/// 12249 Science Drive; Suite 300<br>
8/// Orlando, Florida 32826<br>
9/// USA<br>
10/// <br>
11/// All rights reserved.<br>
12///
13/// This Software contains proprietary trade secrets of DiSTI and may not be
14/// reproduced, in whole or part, in any form, or by any means of electronic,
15/// mechanical, or otherwise, without the written permission of DiSTI. Said
16/// permission may be derived through the purchase of applicable DiSTI product
17/// licenses which detail the distribution rights of this content and any
18/// Derivative Works based on this or other copyrighted DiSTI Software.
19///
20/// NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
21/// AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
22/// PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
23/// AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
24/// IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
25/// PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.
26///
27/// LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
28/// IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
29/// INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
30/// DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
31/// INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
32/// INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
33/// OF SUCH DAMAGES. DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
34/// EXCEED FIVE DOLLARS (US$5.00).
35///
36/// The aforementioned terms and restrictions are governed by the laws of the
37/// State of Florida and the United States of America.
38
39#ifndef GLS_RESOURCE_FILE_MGR_H_INCLUDED
40#define GLS_RESOURCE_FILE_MGR_H_INCLUDED
41
42/// Provides support for creating DLLs.
43#if( defined( GLSGEN_EXPORT_GLSGEOMETRYRESOURCE ) || defined( GLSGEN_IMPORT_GLSGEOMETRYRESOURCE ) || defined( GLS_EXPORT_GENERATED ) || defined( GLS_IMPORT_GENERATED ) ) \
44 && defined( _MSC_VER )
45# if defined( GLSGEN_EXPORT_GLSGEOMETRYRESOURCE ) || defined( GLS_EXPORT_GENERATED )
46# define GLSGEN_GlsGeometryResource_EXPORT __declspec( dllexport )
47# else
48# define GLSGEN_GlsGeometryResource_EXPORT __declspec( dllimport )
49# endif
50#else
51# define GLSGEN_GlsGeometryResource_EXPORT
52#endif
53///////////////////////////////////////////////////////////////////////////////
54
55namespace disti
56{
57/// \details class GlsResourceFileMgr
58/// This class manages all known resource files and provides an
59/// API for objects to access the data for a named resource.
60/// This allows the runtime code to access required resources without
61/// knowing their location. Resources may be stored in individual files,
62/// in an archive file, inline data in the source code, RCDATA, etc.
64{
65protected:
68
69public:
70 /** Reference counted handle to binary resource data
71 */
73 {
74 protected:
76 virtual ~BinaryResource();
77
78 public:
79 /// Should be called to release this BinaryResource when it is longer needed
80 virtual void Release() = 0;
81
82 /// \returns the resource string name
83 virtual const char* GetName() = 0;
84
85 /// \returns size of the data in bytes
86 virtual unsigned int GetDataSize() = 0;
87
88 /// \returns raw pointer to the binary resource data (Read-only)
89 virtual const char* GetDataPtr() = 0;
90 };
91
92 /** Lightweight reference to a resource
93 */
95 {
96 protected:
97 // Need virtual destructor
98 virtual ~ResourceRef() {}
99
100 public:
101 /// Increment the ResourceRef reference count
102 virtual void AddRef() = 0;
103
104 /// Should be called to release this ResourceRef when it is longer needed
105 virtual void Release() = 0;
106
107 /// \return The resource string name.
108 virtual const char* GetName() = 0;
109
110 /// \return A pointer to the resource data.
111 /// Make sure to Release() the BinaryResource when you are done with it (a SmartPtr can be used for this purpose).
113 };
114
115 /// \details Used to hold a resource file open for loading time performance.
116 /// \see CacheResourceFile
118 {
119 public:
120 virtual ~ResourceCache() {}
121 /// Increment the reference count
122 virtual void AddRef() = 0;
123 /// Decrement the reference count
124 virtual void Release() = 0;
125 };
126
127 /// \details Automatically release a resource when no more AutoRelease instances reference it.
128 /// \see CacheResourceFile
129 template<class T>
131 {
132 protected:
133 T* _ptr; ///< Pointer to an object with a refernce counting interface.
134
135 public:
136 /// Constructor
137 /// \param obj The object to wrap.
138 AutoRelease( T* obj ) { _ptr = obj; }
139
140 /// Copy constructor
141 /// \note Does not copy the underlying object, instead increments the underlying objects reference count.
142 /// \param other The object to copy.
143 AutoRelease( const AutoRelease& other )
144 {
145 _ptr = other._ptr;
146 if( _ptr )
147 {
148 _ptr->AddRef();
149 }
150 }
151
153 {
154 if( _ptr )
155 {
156 _ptr->Release();
157 }
158 }
159
160 /// \return A pointer to the underlying object with reference counting interface.
161 T* get() { return _ptr; }
162 };
163
164 /**
165 * \returns Reference to the GlsResourceFileMgr
166 */
168
169 /** Get a reference to a given resource
170 * \param resource_name The unique string name of the resource (relative path to the file if using resource folders)
171 * \returns reference to the resource or NULL if the resource was not found.
172 */
174
175 /** Tell the resource manager to load resources from the given location
176 * This method may be called multiple times to specify multiple locations
177 *
178 * \param url path to the resources. e.g. "./resources/". This may be a directory or zip file.
179 * \param silent if false, then a popup is displayed to the user if the location is not found
180 * \returns true if resources were successfully opened, false otherwise
181 */
182 GLSGEN_GlsGeometryResource_EXPORT bool AddResourceFolder( const char* url, bool silent = false );
183
184 /// Loads resources for a given component into RAM.
185 /// The resources remain cached until the ResourceCache is Released.
186 /// \param componentClassName The generated class name of the component.
187 /// \return A reference counted pointer to the resources.
189};
190
191} // end namespace disti
192
193#endif
Definition: gls_resource_file_mgr.h:131
T * get()
Definition: gls_resource_file_mgr.h:161
T * _ptr
Pointer to an object with a refernce counting interface.
Definition: gls_resource_file_mgr.h:133
AutoRelease(const AutoRelease &other)
Definition: gls_resource_file_mgr.h:143
AutoRelease(T *obj)
Definition: gls_resource_file_mgr.h:138
Definition: gls_resource_file_mgr.h:73
virtual void Release()=0
Should be called to release this BinaryResource when it is longer needed.
virtual unsigned int GetDataSize()=0
Definition: gls_resource_file_mgr.h:118
virtual void Release()=0
Decrement the reference count.
virtual void AddRef()=0
Increment the reference count.
Definition: gls_resource_file_mgr.h:95
virtual BinaryResource * LoadBinaryData()=0
virtual void Release()=0
Should be called to release this ResourceRef when it is longer needed.
virtual const char * GetName()=0
virtual void AddRef()=0
Increment the ResourceRef reference count.
Definition: gls_resource_file_mgr.h:64
ResourceRef * GetResourceRef(const char *resource_name)
static GlsResourceFileMgr & Instance()
AutoRelease< ResourceCache > CacheResourcesForComponent(const char *componentClassName)
bool AddResourceFolder(const char *url, bool silent=false)
#define GLSGEN_GlsGeometryResource_EXPORT
Provides support for creating DLLs.
Definition: gls_resource_file_mgr.h:51
Definition: bmpimage.h:46