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