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