Changes between Version 1 and Version 2 of Exposed_Misc_Functions

Timestamp:

Feb 23, 2008, 9:31:56 PM (16 years ago)

Author:

Jan Wassenberg

Comment:

remove old contents, replace by previous contents of ScriptGlue page

Exposed_Misc_Functions

@@ -1 @@
-<font color="red">'''DEPRECATED; will be replaced by contents of "jan's stomping ground"'''</font>
-
-= Miscellaneous Methods =
+
+= Events =
+
+== addGlobalHandler ==
+ * '''Overview:'''
+  * Register a global handler for the specified DOM event.
+ * '''Syntax:''' 
+  * success = addGlobalHandler(event_type_name, handler);
+ * '''Parameters:'''
+  * event type name [wstring], handler [fragment or function]
+ * '''Returns:'''
+  * whether it was actually newly registered [bool]
+ * '''Notes:'''
+  * 
+
+== removeGlobalHandler ==
+ * '''Overview:'''
+  * Remove a previously registered global handler for the specified DOM event.
+ * '''Syntax:''' 
+  * success = removeGlobalHandler(event_type_name, handler);
+ * '''Parameters:'''
+  * event type name [wstring], handler [fragment or function]
+ * '''Returns:'''
+  * whether it was successfully removed [bool]
+ * '''Notes:'''
+  * 
+
+= Timer =
+
+== setTimeout ==
+ * '''Overview:'''
+  * Request a callback be executed after the specified delay.
+ * '''Syntax:''' 
+  * setTimeout(delayed_func, 100);
+ * '''Parameters:'''
+  * callback [fragment or function], delay in milliseconds [int]
+ * '''Returns:'''
+  * 
+ * '''Notes:'''
+  * Scripts and functions registered this way are called on the first simulation frame after the specified period has elapsed. If this causes multiple segments of code to be executed in the same frame, relative timing is maintained. Delays of 0 milliseconds cause code to be executed on the following simulation frame. If more than one script or function is scheduled to execute in the same millisecond, the order of execution is undefined. Code is scheduled in simulation time, and is therefore suspended while the game is paused or frozen. Granularity of timing is also limited to 1/(Simulation frame rate); currently 100ms. The called function or script executes in the same scope as the code that called setTimeout (amongst other things, the 'this' reference is usually maintained)
+
+== setInterval ==
+ * '''Overview:'''
+  * Request a callback be executed periodically.
+ * '''Syntax:''' 
+  * setInterval(atlasUpdateInfoWindow, 500);
+ * '''Parameters:'''
+  * callback [fragment or function], initial delay in ms [int], period in ms [int] OR
+  * callback [fragment or function], period in ms [int] (initial delay = period)
+ * '''Returns:'''
+  * 
+ * '''Notes:'''
+  * setTimeout's notes apply here as well.
+
+== cancelInterval ==
+ * '''Overview:'''
+  * Cause all periodic functions registered via setInterval to no longer be called.
+
+ * '''Syntax:''' 
+  * cancelInterval();
+ * '''Parameters:'''
+  * 
+ * '''Returns:'''
+  * 
+ * '''Notes:'''
+  * Execution continues until the end of the triggered function or script fragment, but is not triggered again.
+
+= Debug =
+
+== crash ==
+ * '''Overview:'''
+  * Deliberately cause the game to crash.
+ * '''Syntax:''' 
+  * crash()
+ * '''Parameters:'''
+  * 
+ * '''Returns:'''
+  * 
+ * '''Notes:'''
+  * Currently implemented via access violation (read of address 0)
+  * Useful for testing the crashlog/stack trace code.
+
+== forceGC ==
+ * '''Overview:'''
+  * Force a JS GC (garbage collection) cycle to take place immediately.
+ * '''Syntax:''' 
+  * forceGC()
+ * '''Parameters:'''
+  * 
+ * '''Returns:'''
+  * 
+ * '''Notes:'''
+  * Writes an indication of how long this took to the console.
+
+= Misc. Script System =
+
+== getGlobal ==
+ * '''Overview:'''
+  * Returns the global object.
+ * '''Syntax:''' 
+  * global = getGlobal()
+ * '''Parameters:'''
+  * 
+ * '''Returns:'''
+  * global object
+ * '''Notes:'''
+  * Useful for accessing an object from another scope.
+
+= Misc. Engine Interface =
+
+== writeLog ==
+ * '''Overview:'''
+  * Write values to the log file.
+ * '''Syntax:''' 
+  * writeLog("string", 1234);
+ * '''Parameters:'''
+  * any number of any type.
+ * '''Returns:'''
+  * 
+ * '''Notes:'''
+  * Each argument is converted to a string and then written to the log.
+  * Output is in NORMAL style (see LOG).
+
+== setCursor ==
+ * '''Overview:'''
+  * Change the mouse cursor.
+ * '''Syntax:''' 
+  * setCursor("action-attack")
+ * '''Parameters:'''
+  * cursor name [string] (i.e. basename of definition file and texture)
+ * '''Returns:'''
+  * 
+ * '''Notes:'''
+  * Cursors are stored in "art\textures\cursors"
+
+== getFPS ==
+ * '''Overview:'''
+  * Return the global frames-per-second value.
+ * '''Syntax:''' 
+  * fps = getFPS()
+ * '''Parameters:'''
+  * 
+ * '''Returns:'''
+  * FPS [int]
+ * '''Notes:'''
+  * This value is recalculated once a frame. We take special care to filter it, so it is both accurate and free of jitter.
+
+== exit ==
+ * '''Overview:'''
+  * Cause the game to exit gracefully.
+ * '''Syntax:''' 
+  * exit();
+ * '''Parameters:'''
+  * 
+ * '''Returns:'''
+  * 
+ * '''Notes:'''
+  * Exit happens after the current main loop iteration ends (since this only sets a flag telling it to end)
+
+== vmem ==
+ * '''Overview:'''
+  * Write an indication of total/available video RAM to console.
+ * '''Syntax:''' 
+  * vmem()
+ * '''Parameters:'''
+  * 
+ * '''Returns:'''
+  * 
+ * '''Notes:'''
+  * Not supported on all platforms.
+  * Only a rough approximation; do not base low-level decisions ("should I allocate one more texture?") on this.
+
+== _rewriteMaps ==
+ * '''Overview:'''
+  * Trigger a rewrite of all maps.
+ * '''Syntax:''' 
+  * _rewriteMaps();
+ * '''Parameters:'''
+  * 
+ * '''Returns:'''
+  * 
+ * '''Notes:'''
+  * Usefulness is unclear. If you need it, consider renaming this and updating the docs.
+
+== _lodbias ==
+ * '''Overview:'''
+  * Change the LOD bias.
+ * '''Syntax:''' 
+  * _lodbias(bias)
+ * '''Parameters:'''
+  * LOD bias [float]
+ * '''Returns:'''
+  * 
+ * '''Notes:'''
+  * value is as required by GL_TEXTURE_LOD_BIAS.
+  * useful for adjusting image "sharpness" (since it affects which mipmap level is chosen)
+
+= Miscellany =
+
+== v3dist ==
+ * '''Overview:'''
+  * Return distance between 2 points.
+ * '''Syntax:''' 
+  * dist = v3dist(v1,v2);
+ * '''Parameters:'''
+  * 2 position vectors [CVector3D]
+ * '''Returns:'''
+  * Euclidean distance [float]
+ * '''Notes:'''
+  * 
 
 == buildTime ==
  * '''Overview:'''
-  * Returns a string value of the date when the project was last built.
- * '''Syntax:''' 
-  * !ReturnString = buildTime (flag)
- * '''Parameters:'''
-  * <font color="red">A flag set to 0 in the current example. Not sure what it does yet.</font>
- * '''Returns:'''
-  * Date string in the format <Mon dd yyyy> (eg Jun 24 2005).
- * '''Notes:'''
-  * 
-
-== crash ==
- * '''Overview:'''
-  * Crashes the engine.
-  * Caution, debug only.
- * '''Syntax:'''
-  * crash();
- * '''Parameters:'''
-  * None.
- * '''Returns:'''
-  * Nothing.
- * '''Notes:'''
-  * Passes invalid data to the !SpiderMonkey engine.
-
-== exit ==
- * '''Overview:'''
-  * Gracefully shuts down the engine, returning to the desktop.
- * '''Syntax:''' 
-  * exit()
- * '''Parameters:'''
-  * None.
- * '''Returns:'''
-  * None.
- * '''Notes:'''
-  * Call this function to quit the game.
-
-== getFPS ==
- * '''Overview:'''
-  * Return the current frames per second of the renderer.
- * '''Syntax:''' 
-  * FPS = getFPS()
- * '''Parameters:'''
-  * None.
- * '''Returns:'''
-  * FPS as a number (eg 30).
- * '''Notes:'''
-  * 
-
-== getGlobal ==
- * '''Overview:''' Access an object from another scope.
-
-== getGUIGlobal ==
- * '''Overview:''' Access a GUI object from another scope.
+  * Return the date/time at which the current executable was compiled.
+ * '''Syntax:''' 
+  * date = buildTime(0); // see below
+ * '''Parameters:'''
+  * none -> "$date $time"
+  * 0    -> "$date"
+  * 1    -> "$time"
+ * '''Returns:'''
+  * date and/or time [string]
+ * '''Notes:'''
+  * Displayed on main menu screen; tells non-programmers which auto-build they are running. Could also be determined via .EXE file properties, but that's a bit more trouble.
+  * To be exact, the date/time returned is when scriptglue.cpp was last compiled; since the auto-build does full rebuilds, that is moot.
+
 
 == getLanguageID ==
@@ -69 +237 @@
  * '''Notes:'''
   * 
-
-== setInterval ==
- * '''Overview:'''
-  * Schedules a function or script fragment to be called at a specified interval (the given JS function is continuously called each time a waiting period elapses).
- * '''Syntax:'''
-  * setInterval( fragment, interval );
-  * setInterval( function, interval );
-  * setInterval( fragment, delay, interval );
-  * setInterval( function, delay, interval );
-  * Example: setInterval(atlasUpdateInfoWindow, 500); // Call the function atlasUpdateInfoWindow() every 500ms.
- * '''Parameters:'''
-  * fragment: A text string containing executable !JavaScript.
-  * function: An expression evaluating to a !JavaScript function.
-  * interval: The interval between subsequent executions of the code. May not be negative.
-  * delay: The delay, in milliseconds, before the code is first executed. (If unspecified, defaults to 'interval'). May not be negative.
- * '''Returns:'''
-  * Nothing.
- * '''Notes:'''
-  * Functions and script are executed first at 'delay' milliseconds after the call and then every 'interval' milliseconds thereafter. If 'delay' is not present, the first call is 'interval' milliseconds following the setInterval call.
-  * All notes for setTimeout also apply to setInterval.
-
-== setTimeout ==
- * '''Overview:'''
-  * Schedules a specified fragment of script or a script function to execute some time in the future.
- * '''Syntax:'''
-  * setTimeout( fragment, delay );
-  * setTimeout( function, delay );
- * '''Parameters:'''
-  * delay: The desired delay, in milliseconds. May not be negative.
-  * fragment: A text string containing executable !JavaScript.
-  * function: An expression evaluating to a !JavaScript function.
- * '''Returns:'''
-  * Nothing.
- * '''Notes:'''
-  * Scripts and functions registered this way are called on the first simulation frame after the specified period has elapsed. If this causes multiple segments of code to be executed in the same frame, relative timing is maintained. Delays of 0 milliseconds cause code to be executed on the following simulation frame. If more than one script or function is scheduled to execute in the same millisecond, the order of execution is undefined. Code is scheduled in simulation time, and is therefore suspended while the game is paused or frozen. Granularity of timing is also limited to 1/(Simulation frame rate); currently 100ms. The called function or script executes in the same scope as the code that called setTimeout (amongst other things, the 'this' reference is usually maintained)
-
-== cancelInterval ==
- * '''Overview:'''
-  * Ceases triggering the currently executing interval.
- * '''Syntax:'''
-  * cancelInterval();
- * '''Parameters:'''
-  * None.
- * '''Returns:'''
-  * Nothing.
- * '''Notes:'''
-  * Execution continues until the end of the triggered function or script fragment, but is not triggered again.
-
-== writeLog ==
- * '''Overview:'''
-  * Writes an entry to the Prometheus log file.
- * '''Syntax:'''
-  * writeLog( ... );
- * '''Parameters:'''
-  * Any number of values of any type.
- * '''Returns:'''
-  * Nothing.
- * '''Notes:'''
-  * writeLog converts each of its arguments to a string, in turn. The message added to the logfile is all these strings concatenated together. The message is logged as 'NORMAL' style.