GL Studio C++ Runtime API
display_frame.h
Go to the documentation of this file.
1/// \file display_frame.h
2/// \brief The disti::DisplayFrame class.
3///
4/// \par Copyright Information
5///
6/// Copyright (c) 2017 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 INCLUDED_DISTI_DISPLAY_FRAME_H
40#define INCLUDED_DISTI_DISPLAY_FRAME_H
41
42#include "display.h"
43#include "gls_include.h"
44#include "gls_painter.h"
45#include "image.h"
46#include "texture_palette.h"
47#include "util.h"
48#include "vertex.h"
49#include <string.h>
50#ifndef GLS_EDITOR_CODE
51# include "message.h"
52#endif
53
54#include "disti_metadata.h"
55#include "dynamic_array.h"
56#include "input_handler.h"
57#include "material.h"
58#include "scoped_ptr.h"
59#include "sound.h"
61
62struct DragObjectMap;
63
64namespace disti
65{
66static const int MAX_PLAYABLE = 20; /**< Max. Number of sound files that can be played */
67
68const char META_COMPONENT_HEADER_FILE_NAME[] = "ComponentHeaderFile"; ///< Attribute name for ComponentHeaderFile.
69
70typedef DynamicArray<Material> DynamicMaterialArray; /**< Typedef for dynamic array of materials */
71
72class Group;
74
75template<class>
76class EventCompressor;
77
78/** The base class for associating a display device with an object list.
79 *
80 * DisplayFrame contains all of the display objects, texture, and fonts for
81 * an application.
82 *
83 */
85 , virtual public WeakReferenceableMixin
86{
87private:
88 DistiAttribDict* _frameAttribDict; /**< Stores all of the attributes specific to the DisplayFrame */
89 ScopedPtr<InputHandler> _inputHandler;
90
91protected:
92 bool _cullingEnabled; /**< True if culling is enabled for this DisplayFrame */
93 int _width; /**< The width of the window for this display frame */
94 int _height; /**< The height of the window for this display frame */
95 float _lastPickedDepth; /**< Keeps previous picks depth for use when no pick is performed (dragging) */
96 DynamicMaterialArray _materialPalette; /**< A Dynamic array for keeping the materials for this frame */
97 ComponentLightMgr* _lightMgr; /**< The _lightMgr is used to setup lighting for the DisplayFrame */
98 GLbitfield _clearBitfield; /**< The OpenGL bitfield to use when clearing. /see glClear */
99
100 std::string _componentHeaderFileName; /**< backing store for META_COMPONENT_HEADER_FILE_NAME attribute */
101
102 DragObjectMap* _dragObjectMap; ///< Holds a focus object for each cursor.
103 unsigned int _currentCursor; /**< the current cursor being processed */
104 bool _multitouchEnabled; /**< whether or not multitouch is enabled */
105 unsigned int _cursorsDown; /**< The number of cursors (touches) that are currently down */
106
107 /** Changes the current cursor to the specified cursor id. Needed by multitouch, so that DragObject and FocusObject will return
108 * the correct objects for the current cursor.
109 * \param cursor_id the cursor id
110 */
111 virtual GLS_EXPORT void CurrentCursor( unsigned int cursor_id );
112
113 /** Cleanup unused entries from the drag map */
115
116 /** Get the drag object that corresponds to the curosr
117 * \param cursorID the cursor
118 * \return the drag object or null if none exists
119 */
120 DisplayObject* GetDragObjectForCursor( unsigned int cursorID );
121
122 /** Find a non-null drag object from the _dragObjectMap if on exists
123 * \return a drag object, or null if there aren't any in the map
124 */
126
127 /// Get the event compressor for this display frame, if it exists
128 /// \return The event compressor.
130
131 /** \return The current scale for the display frame
132 */
133 virtual float Scale() { return 1.0f; }
134
135public:
136 TexturePalette* texturePalette; /**< An array of textures allocated for display on objects */
137 SoundSystem* _sound_player; /**< Sound file player for this DisplayFrame */
138 Group* objects; /**< The object hierarchy for this display frame */
139
140 /** Creates a new display frame
141 * \param width The width of this display frame in pixels
142 * \param height The height of this display frame in pixels
143 * \param allocateObjects
144 */
145 GLS_EXPORT DisplayFrame( int width, int height, bool allocateObjects = true );
146
147 virtual GLS_EXPORT ~DisplayFrame();
148
149 /** Sets the OpenGL clear bitmask that will be used when the window is cleared
150 * \param bitField The OpenGL bitfield to use when clearing. /see glClear
151 */
152 void ClearBitfield( GLbitfield bitField ) { _clearBitfield = bitField; }
153
154 /** Gets the OpenGL clear bitmask that will be used when the window is cleared
155 * \return The OpenGL bitfield to use when clearing. /see glClear
156 */
157 GLbitfield ClearBitfield() { return _clearBitfield; }
158
159 /** Sets the current "Drag" object for the current cursor
160 * \param obj The new DragObject
161 */
162 virtual GLS_EXPORT void DragObject( DisplayObject* obj );
163
164 /** Gets the current "Drag" object for the current cursor
165 * \return The current DragObject
166 */
168
169 /** Clears the drag objects for all cursors.*/
170 virtual GLS_EXPORT void ClearDrag();
171
172 /// Sets the current focus object for the current cursor.
173 /// \param obj The new focus object to set.
175
176 /** Gets the current "Focus" object for the current cursor
177 * \return The current FocusObject
178 */
180
181 /** Clears the focus objects for all cursors.*/
182 virtual GLS_EXPORT void ClearFocus();
183
184 /// Enables/Disables multitouch on the display frame. Multitouch is enabled by default.
185 /// This function has no effect on platforms that do not support multitouch.
186 /// \param enabled The new multitouch state to set.
187 virtual GLS_EXPORT void MultitouchEnabled( bool enabled );
188
189 /// \return Whether or not multitouch is enabled on the display frame.
191
192 /// \return The input handler for this component.
194
195 /// Sets the input handler for this frame.
196 /// Takes ownership of the handler pointer.
197 /// \param handler Pointer to the input handler to set (ownership transferred).
198 virtual GLS_EXPORT void SetInputHandler( InputHandler* handler );
199
200 /// Handles a display event.Picks an object and also tracks focus.
201 /// \param ev The display event to be handled.
202 /// \return A pointer to the object that received the event, otherwise NULL.
204
205 /** Write the resources (attributes) of the objects in this display frame to the specified file
206 * \param filename Name of the file to write to
207 * \param filter A filter to specify which attributes to write
208 */
209 virtual GLS_EXPORT void WriteResources( const char* filename, GlsResourceFilter* filter = NULL );
210
211 /** Read the resources (attributes) of the objects in this display frame from the specified file
212 * \param filename Name of the file to read from
213 */
214 virtual GLS_EXPORT void ReadResources( const char* filename );
215
216 /// Gets a reference to the specified attribute for reading and writing.
217 /// This reference can be streamed into and out of variables.
218 /// This can access different levels of objects.
219 /// For example:
220 /// The DisplayFrame:
221 /// Resource("ComponentHeaderFile") >> someStdString;
222 /// An object in the DisplayFrame:
223 /// Resource("SomeObject.Visible") << someBool;
224 /// An object in a Component in this DisplayFrame:
225 /// Resource("SomeComponentObject.SomeObject.Visible") >> someBool;
226 /// \param name The name of the attribute to get.
227 /// \return A reference to the requested attribute if available, otherwise DistiEmptyAttribute.
228 virtual GLS_EXPORT DistiAttributeBase& Resource( const char* name );
229
230 /** Get the resources for this display frame and all it's children acording to the filter
231 * \param outstr The stream to write to
232 * \param filter The filter to control what gets written.
233 */
234 virtual GLS_EXPORT void GetResources( std::ostream& outstr, GlsResourceFilter* filter = NULL );
235
236 /** Parse a stream of resource value pairs.
237 * \param instr Stream containing the resource data
238 */
239 virtual GLS_EXPORT void SetResources( std::istream& instr );
240
241 /** Sets a DisplayFrame resource value.
242 * \param resourceName Name of the resource to set.
243 * \param resourceVal Value of the resource to set
244 */
245 void SetResource( const std::string& resourceName, const std::string& resourceVal )
246 {
247 SetResource_CRTClean( resourceName.c_str(), resourceVal.c_str() );
248 }
249
250 /// Sets a DisplayFrame resource value.
251 /// \param resourceName Name of the resource to set.
252 /// \param resourceVal Value of the resource to set.
253 void SetResource( const char* resourceName, const char* resourceVal )
254 {
255 SetResource_CRTClean( resourceName, resourceVal );
256 }
257
258 /// Gets a DisplayFrame resource value.
259 /// \param resourceName Name of the resource to set.
260 /// \return The string value of the requested resource, empty string if not available.
261 std::string GetResource( const std::string& resourceName )
262 {
263 char* value = GetResource_CRTClean( resourceName.c_str() );
264 std::string stringVal = value;
266 return stringVal;
268
269 /// Gets a DisplayFrame resource value.
270 /// \param resourceName Name of the resource to set.
271 /// \return The string value of the requested resource, empty string if not available.
272 std::string GetResource( const char* resourceName )
273 {
274 char* value = GetResource_CRTClean( resourceName );
275 std::string stringVal = value;
277 return stringVal;
278 }
279
280 /** CRT Insensitive version of GetResource()
281 * Version with streams can not be called from differently compiled code.
282 * \param name name of resource
283 * \return The requested value allocated as a char array.
284 * The user MUST call GetResourceFree() when finished using returned value.
285 */
286 virtual GLS_EXPORT char* GetResource_CRTClean( const char* name );
287
288 /** Frees the memory allocated by a previous GetResource_CRTClean call
289 * \param memoryToFree Pointer to memory allocated by GetResource_CRTClean
290 */
291 virtual GLS_EXPORT void GetResourceFree_CRTClean( char* memoryToFree );
292
293 /** CRT Insensitive version of GetResources()
294 * \param filter The filter to control what gets written
295 * \return A null terminated char* containing the requested resources
296 * The user MUST call GetResourcesFree() on the returned value.
297 */
299
300 /** Frees the memory allocated by a previous GetResources_CRTClean call
301 * \param memoryToFree Pointer to memory allocated by GetResource_CRTClean
302 */
303 virtual GLS_EXPORT void GetResourcesFree_CRTClean( char* memoryToFree );
304
305 /** CRT Insensitive version of SetResource()
306 * Version with streams can not be called from differently compiled code.
307 * \param name name of resource
308 * \param value new value for resource
309 */
310 virtual GLS_EXPORT void SetResource_CRTClean( const char* name, const char* value );
311
312 /** CRT Insensitive version of SetResources()
313 * Parse a buffer of resource value pairs.
314 * \param buf String containing resource data
315 */
316 virtual GLS_EXPORT void SetResources_CRTClean( const char* buf );
317
318 /** Implements AttributeChangedNotifier::NotifyAttributeChanged.
319 * Notify the class that the attribute has changed. Observers of the attribute will have their callbacks called
320 * \param name the name of the attribute
321 */
323
324#ifndef GLES
325 /** Get the details of the Cpp Interface
326 * The actual interface is exposed in compiled code.
327 * \param addToThisList A list to add to and then return. Creates a new one if NULL.
328 * \return A templated list.
329 * The caller must call the corresponding free method to
330 * safely free the memory.
331 */
333
334 /** Frees the memory allocated by a previous GetCppInterfaceDescription call
335 * \param array Pointer to memory allocated by GetCppInterfaceDescription
336 */
338#endif
339
340 /** Sets the texture palette size for this display frame
341 * \param cnt The number of entries to have in the display frame
342 */
344
345 /** Draw the objects contained in this display frame */
347
348 /** Adds the specified object into the group, at the end of the list
349 * \param obj A pointer to the object to add
350 * \param reparent Whether or not the object parent should be set to this group
351 * \param recalculateBoundingbox Whether or not to recalculate the bounding box
352 * \param loc Where to insert it (defaults to -1 which means at the end of the list)
353 */
354 GLS_EXPORT void InsertObject( DisplayObject* obj, bool reparent = true, bool recalculateBoundingbox = true, int loc = -1 );
355
356 /** Inserts a display object into this display frame at the specified
357 * index in the object list.
358 * \param obj The object to insert
359 * \param loc Where to insert the object
360 */
361 GLS_EXPORT void InsertObject( DisplayObject* obj, int loc );
362
363 /** Inserts a display object into this display frame at the end
364 * of the object list.
365 * \param obj The object to insert
366 */
368
369 /** Gets the width in pixels of this display frame
370 * \return The width in pixels of this display frame
371 */
373
374 /** Gets the height in pixels of this display frame
375 * \return The height in pixels of this display frame
376 */
378
379 /** Sets the width in pixels of this display frame
380 * \param w The new width in pixels of this display frame
381 */
382 GLS_EXPORT void SetWidth( int w );
383
384 /** Sets the height in pixels of this display frame
385 * \param h The new height in pixels of this display frame
386 */
387 GLS_EXPORT void SetHeight( int h );
388
389 /** Does nothing here in the base class. Allows other display
390 * frames to add functionality.
391 * \deprecated Should not be called by new code.
392 */
393 virtual void SetRedraw() {}
394
395 /** Gets the whether or not culling is enabled for this display frame
396 * \return whether or not culling is enabled for this display frame
397 */
399
400 /** Sets the whether or not culling is enabled for this display frame
401 * \param enabled whether or not culling is enabled for this display frame
402 */
403 GLS_EXPORT void CullingEnabled( const bool enabled );
404
405 /** Sets up the OpenGL Pipeline to the state expected by GL Studio drawing.
406 * resetTemplate is used to not reset certain catagories. For example, it may
407 * be desirable for a GL Studio object to receive lighting from it's VegaPrime scene.
408 * \param saveVal Whether or not to save values. If true, this will call
409 * glPushClientAttrib(GL_CLIENT_ALL_ATTRIB_BITS) and glPushAttrib(GL_ALL_ATTRIB_BITS). You should call
410 * RestoreOpenGLState() after drawing to pop the attributes.
411 */
412 static GLS_EXPORT void SetOpenGLDefaultState( bool saveVal );
413
414 /** Call this after calling SetOpenGLDefaultState with saveVal == true.
415 * DO NOT call this after calling SetOpenGLDefaultState with saveVal == false
416 * because this will pop the attribute stack.
417 */
419
420 /** \return A reference to the Attribute dictionary for this display frame */
421 DistiAttribDict& FrameAttribDict() { return *_frameAttribDict; }
422
423 /** \return A const reference to the Attribute dictionary for this display frame */
424 const DistiAttribDict& FrameAttribDict() const { return *_frameAttribDict; }
425
426 /** \return A reference to the material palette for this display frame */
428
429 /** \return A pointer to the light manager for this display frame */
431
432 /** Sets the light manager for this display frame.
433 * This is used only for very special cases.
434 * The current LightMgr is NOT deleted when the new one is set.
435 * If this is used, it is recommended to restore the value to
436 * the original value.
437 * \param val The pointer to the new light manger.
438 */
439 void LightMgr( ComponentLightMgr* val ) { _lightMgr = val; }
440
441 /** Call this before deleting objects which may be being kept
442 * by the drag or focus objects.
443 * If an object is to be deleted. The user must ensure that it is not
444 * being used as the drag or focus object. If it is, a leave event may
445 * be sent to it after it has been deleted, causing a crash.
446 * To avoid this the user can either ensure that the object never handles mouse events,
447 * or call ClearDragAndFocus() imediatly before deleting them */
449};
450
451} // namespace disti
452
453#endif
Definition: disti_metadata.h:521
Definition: disti_metadata.h:87
Definition: component_light_mgr.h:55
Definition: events.h:111
Definition: display_frame.h:86
TexturePalette * texturePalette
Definition: display_frame.h:136
virtual DisplayObject * DragObject()
unsigned int _currentCursor
Definition: display_frame.h:103
void PushObject(DisplayObject *obj)
virtual bool MultitouchEnabled()
virtual void FocusObject(DisplayObject *obj)
virtual void GetCppInterfaceDescriptionFree(InterfaceListType *array)
DisplayFrame(int width, int height, bool allocateObjects=true)
virtual void ClearDragAndFocus()
DragObjectMap * _dragObjectMap
Holds a focus object for each cursor.
Definition: display_frame.h:102
void SetWidth(int w)
static void RestoreOpenGLState()
ComponentLightMgr * LightMgr()
Definition: display_frame.h:430
GLbitfield _clearBitfield
Definition: display_frame.h:98
DynamicMaterialArray _materialPalette
Definition: display_frame.h:96
static void SetOpenGLDefaultState(bool saveVal)
DisplayObject * GetDragObjectForCursor(unsigned int cursorID)
bool _cullingEnabled
Definition: display_frame.h:92
virtual void SetResource_CRTClean(const char *name, const char *value)
void SetHeight(int h)
Group * objects
Definition: display_frame.h:138
void LightMgr(ComponentLightMgr *val)
Definition: display_frame.h:439
virtual void DragObject(DisplayObject *obj)
const DistiAttribDict & FrameAttribDict() const
Definition: display_frame.h:424
void InsertObject(DisplayObject *obj, int loc)
virtual void GetResources(std::ostream &outstr, GlsResourceFilter *filter=NULL)
ComponentLightMgr * _lightMgr
Definition: display_frame.h:97
std::string GetResource(const char *resourceName)
Definition: display_frame.h:272
virtual void SetResources_CRTClean(const char *buf)
virtual void GetResourceFree_CRTClean(char *memoryToFree)
virtual EventCompressor< DisplayFrame > * GetEventCompressor()
Definition: display_frame.h:129
virtual void SetRedraw()
Definition: display_frame.h:393
std::string GetResource(const std::string &resourceName)
Definition: display_frame.h:261
virtual void SetResources(std::istream &instr)
virtual char * GetResource_CRTClean(const char *name)
virtual void WriteResources(const char *filename, GlsResourceFilter *filter=NULL)
virtual void GetResourcesFree_CRTClean(char *memoryToFree)
GLbitfield ClearBitfield()
Definition: display_frame.h:157
DisplayObject * FindDragObject()
DynamicMaterialArray & MaterialPalette()
Definition: display_frame.h:427
void SetResource(const std::string &resourceName, const std::string &resourceVal)
Definition: display_frame.h:245
void ClearBitfield(GLbitfield bitField)
Definition: display_frame.h:152
virtual void CurrentCursor(unsigned int cursor_id)
virtual float Scale()
Definition: display_frame.h:133
void NotifyAttributeChanged(const AttributeName &name) override
void CullingEnabled(const bool enabled)
virtual void ClearFocus()
DistiAttribDict & FrameAttribDict()
Definition: display_frame.h:421
void InsertObject(DisplayObject *obj, bool reparent=true, bool recalculateBoundingbox=true, int loc=-1)
virtual void ClearDrag()
bool _multitouchEnabled
Definition: display_frame.h:104
SoundSystem * _sound_player
Definition: display_frame.h:137
void SetTexturePaletteSize(int cnt)
virtual DistiAttributeBase & Resource(const char *name)
std::string _componentHeaderFileName
Definition: display_frame.h:100
int _height
Definition: display_frame.h:94
virtual DisplayObject * FocusObject()
virtual void ReadResources(const char *filename)
virtual void MultitouchEnabled(bool enabled)
virtual InputHandler * GetInputHandler()
virtual InterfaceListType * GetCppInterfaceDescription(InterfaceListType *addToThisList=NULL)
virtual void SetInputHandler(InputHandler *handler)
virtual DisplayObject * HandleDisplayEvent(DisplayEvent *ev)
int _width
Definition: display_frame.h:93
float _lastPickedDepth
Definition: display_frame.h:95
unsigned int _cursorsDown
Definition: display_frame.h:105
void SetResource(const char *resourceName, const char *resourceVal)
Definition: display_frame.h:253
virtual char * GetResources_CRTClean(GlsResourceFilter *filter)
Definition: display.h:95
Definition: disti_metadata.h:750
Definition: disti_metadata.h:220
Definition: events.h:660
Definition: gls_resources.h:49
Definition: group.h:52
Definition: input_handler.h:185
Definition: scoped_ptr.h:53
Definition: sound.h:49
Definition: texture_palette.h:185
Definition: weak_referenceable_mixin.h:52
The disti::DisplayObject class and global enumerations.
The disti metadata.
The disti::DynamicArray class. A templated array of objects capable of dynamically growing.
#define DISTI_METHOD_OVERRIDE
Macro to wrap the override keyword, removed on compilers that don't support it.
Definition: gls_cpp_lang_support.h:221
A file for all GL Studio files to include.
#define GLS_EXPORT
Macro denoting which functions should be visible from the runtime library.
Definition: gls_include.h:50
The GlsPainter interface.
The Image class. All textures are converted internally into Images.
The input handler interface.
The disti::Material class.
The Message functions. Implements Messages to the user in the form of pop-up dialog boxes,...
Definition: bmpimage.h:46
DynamicArray< Material > DynamicMaterialArray
Definition: display_frame.h:70
const char META_COMPONENT_HEADER_FILE_NAME[]
Attribute name for ComponentHeaderFile.
Definition: display_frame.h:68
A smart pointer with unique ownership – poor man's std::unique_ptr.
The SoundSystem class for playback of audio files.
The disti::TexturePalette class.
Generally useful defines, macros, enumerations and function prototypes.
The disti::Vertex class. A class for manipulating 3D vertices.
Weak reference and related classes.