1 /*
  2   Copyright (c) 2008 Seneca College
  3   Licenced under the MIT License (http://www.c3dl.org/index.php/mit-license/)
  4 */
  5 
  6 /**
  7   @class used to output error, warning and information to either the page or firebug.
  8   If firebug is enabled, the message will appear in both firebug and the page.
  9 */
 10 c3dl.debug = 
 11 {
 12   //
 13   BENCHMARK: false,
 14   DUMMY: false,
 15   DUMP: false,
 16   SHARK: false,
 17   
 18   // will the messages be visible to the user which the script is running?
 19   isVisible: true,
 20   
 21   // keep track of the total number of lines logged and prevent logging
 22   // too many, which may slow down the browser.
 23   numLinesLogged: 0,
 24   
 25   // once this many lines have been logged, logging will stop to prevent the
 26   // browser from slowing down.
 27   maxLinesToLog: 100,
 28 
 29   isSetUp : false,
 30   
 31   // this will contain a div element which will be populated with <p> tags which 
 32   // are warning, errors, etc.
 33   logDiv: null,
 34   
 35   // make sure the user has firebug before writing to the firebug console.
 36   isFirebugEnabled: false,
 37   
 38   /**
 39     Is the debugger visible?
 40     
 41     @returns {boolean} true if logs will be displayed for the user, false otherwise.
 42   */
 43   getVisible: function()
 44   {
 45     return c3dl.debug.isVisible;
 46   },
 47   
 48   /**
 49     @private
 50     Setup creates a div element and adds it to the DOM. This div will be populated with any warnings, 
 51     errors, etc. which happen to occur during the execution of the script.
 52   */
 53   setup: function()
 54   {
 55     windowWidth = document.body.clientWidth - 50;
 56     windowHeight = document.body.clientHeight;
 57     logWindowWidth = windowWidth;
 58     logWindowHeight = 200;  
 59 
 60     c3dl.debug.logDiv = document.createElement("div");
 61     c3dl.debug.logDiv.style.width = logWindowWidth + "px"; 
 62     c3dl.debug.logDiv.style.position = 'absolute';
 63     c3dl.debug.logDiv.style.top = windowHeight - logWindowHeight;
 64     c3dl.debug.logDiv.style.left = 5;
 65     c3dl.debug.logDiv.style.padding = 5;
 66     c3dl.debug.logDiv.style.opacity = .8;
 67     c3dl.debug.logDiv.style.border = '1px solid #000';
 68     c3dl.debug.logDiv.id = 'logdiv';
 69     c3dl.debug.logDiv.name = 'logdiv';
 70     document.body.appendChild(c3dl.debug.logDiv);
 71 
 72     // find out if the user is using firebug. If they are, we can add the messages to the
 73     // firebug console as well as the DOM.
 74     try{
 75       if (console) {
 76         c3dl.debug.isFirebugEnabled = true;
 77       }
 78     } catch (err){
 79       c3dl.debug.isFirebugEnabled = false;
 80     }
 81 
 82     c3dl.debug.isSetUp = true;
 83   },
 84 
 85   /**
 86     
 87     @private
 88     @author Jeremy Giberson
 89     This gem will wrap any function call with an inspector that will log parameters and return values.
 90 
 91     param {String} functionName function calls you want to inspect
 92     param {Object} object
 93   */
 94   inspect: function(functionName, object) {
 95     var f;
 96     f = (object) ? object.functionName : window.funcName;
 97     object.functionName = function() {
 98       // log args
 99       // c3dl.debug.log (arguments);
100       var r = f.call(args);
101       // log r
102       // c3dl.debug.log (r);
103       return r;
104     }
105   },
106   
107   /**
108     Set the visibility of the logs.
109     
110     @param {boolean} isVisible true if the logs should be displayed, false if the logs should not
111     be displayed.
112   */
113   setVisible: function(isVisible)
114   {
115     c3dl.debug.isVisible = isVisible;
116   },
117   
118     
119   /**
120     @private
121     If the user has firebug, the warning will
122     be placed in the console.  The warning will also appear on the HTML page itself.
123     
124     @param {String} str The string which will be displayed on the HTML page.
125     @param {String} type The type of log, either 'Info', 'Warning' or 'Error'.
126     @param {String} colour A string which contains an HTML colour encoded 
127     value, such as '#FF6666', 'yellow', etc.
128   */
129   doLog: function(str, type, color)
130   {
131   
132     if(c3dl.debug.getVisible())
133     {
134       // if we reached the max number of lines to log, we will overwrite the parameters passed in
135       // and print out our our warning specifying no more lines will be logged.
136       if (c3dl.debug.numLinesLogged == c3dl.debug.maxLinesToLog)
137       {        
138         // Too many lines logged may overload/slow down the browser.
139         str =  "Too many lines to log (" + c3dl.debug.numLinesLogged + "). Logging stopped.";
140         type = c3dl.DEBUG_WARNING;
141         colour = "yellow";
142       }
143       
144       // don't log anything if we have too many lines, just return from this function.
145       if (c3dl.debug.numLinesLogged > c3dl.debug.maxLinesToLog)
146       {
147         return;
148       }
149       
150       if(!c3dl.debug.isSetUp)
151       {
152         c3dl.debug.setup();
153       }
154       
155       // Output a log line to the HTML page
156       var currentTime = new Date();
157       
158       // this should probably be lowercase
159       var node = document.createElement('p');
160       node.innerHTML = currentTime.getHours() + ':' + 
161                currentTime.getMinutes() + ':' + 
162                currentTime.getSeconds() + ' ' +
163                type + ': ' + str;
164       node.style.background = color;
165       c3dl.debug.logDiv.insertBefore(node, c3dl.debug.logDiv.firstChild);
166       
167       // output an appropriate log to the firebug console if it is enabled. If 
168       // the user has firebug installed, but the console is enabled and we don't
169       // check for this, our script could break.
170       if(c3dl.debug.isFirebugEnabled)
171       {
172         switch(type)
173         {
174           case c3dl.DEBUG_WARNING: console.warn(str);break;
175           case c3dl.DEBUG_ERROR:   console.error(str);break;
176           case c3dl.DEBUG_INFO:    console.info(str);break;
177           default:break;
178         }
179       }
180       
181       c3dl.debug.numLinesLogged++;
182     }
183   },
184   
185   /**
186     @private
187     Provide some sort of information the user should know about.
188 
189     @param {String} infoMsg the message containing some information which may be useful
190     to the user.
191   */
192   logInfo: function(infoMsg)
193   {
194     c3dl.debug.doLog(infoMsg, c3dl.DEBUG_INFO,  '#CCFFFF');
195   },
196   
197   /**
198     @private
199     Inform the user of a warning. A warning indicates the script can still run, 
200     but whatever caused the warning should be fixed. One example of a warning is trying to
201     add an object to a scene which is not a valid object.
202 
203     @param {String} warningMsg the message containing information about the warning.
204   */
205   logWarning: function(warningMsg)
206   {  
207     c3dl.debug.doLog(warningMsg, c3dl.DEBUG_WARNING, '#FFFF00');  
208   },
209   
210   /**
211     @private
212     Inform the user an exception has been caught. An exception can be something like trying to 
213     access an array with an out of bounds index or trying to enable an unsupported capability.
214     The script may still be able to run even after an exception has occured.
215 
216     @param {String} exceptionMsg the message containing information about the exception.
217   */
218   logException: function(exceptionMsg)
219   {
220     c3dl.debug.doLog(exceptionMsg, c3dl.DEBUG_EXCEPTION, '#FF6600');
221   },
222   
223   /**
224     @private
225     Inform the user an error has occured.  An error prevents the script from running properly.
226     An example of an error is the renderer failing to initialize because of an invalid value 
227     passed to the renderer's initialize method.
228     
229     @param {String} errorMsg A string which indicates why the script failed to run.
230   */
231   logError: function(errorMsg)
232   {
233     c3dl.debug.doLog(errorMsg, c3dl.DEBUG_ERROR, '#FF2222');
234   }
235 }
236