245
edits
Difference between revisions of "SCI/Specifications/SCI virtual machine/Kernel functions"
Jump to navigation
Jump to search
SCI/Specifications/SCI virtual machine/Kernel functions (view source)
Revision as of 12:45, 11 January 2009
, 12:45, 11 January 2009Fixed formatting, converted math formulas to images
(Merging of the SCI documentation. Section "Kernel functions" done) |
(Fixed formatting, converted math formulas to images) |
||
| Line 48: | Line 48: | ||
word ResType, word ResNr;</syntax> | word ResType, word ResNr;</syntax> | ||
(word) <tt>ResType:</tt> The resource type number | | (word) <tt>ResType:</tt> The resource type number <nowiki>| 0x80</nowiki> (as in the patch files)<br> | ||
(word) <tt>ResNr:</tt> The resource number | (word) <tt>ResNr:</tt> The resource number<br> | ||
Returns: (&FarPtr): A HeapPtr pointing to an actual pointer on the heap. | Returns: (&FarPtr): A HeapPtr pointing to an actual pointer on the heap.<br> | ||
Loads a resource. The returned <tt>HeapPtr</tt> points to a special point on the heap where a pointer (32 bits) to the memory location of the specified resource is located. If the resource type equals sci_memory, the resource number is interpreted as a memory size instead; the specified number of bytes is allocated dynamically, and a handle returned. | Loads a resource. The returned <tt>HeapPtr</tt> points to a special point on the heap where a pointer (32 bits) to the memory location of the specified resource is located. If the resource type equals sci_memory, the resource number is interpreted as a memory size instead; the specified number of bytes is allocated dynamically, and a handle returned. | ||
| Line 59: | Line 59: | ||
word ResType, word ResNr;</syntax> | word ResType, word ResNr;</syntax> | ||
(word) <tt>ResType:</tt> The resource type number | | (word) <tt>ResType:</tt> The resource type number | 0x80<br> | ||
(word) <tt>ResNr:</tt> The resource number | (word) <tt>ResNr:</tt> The resource number<br> | ||
Returns: (void) | Returns: (void) | ||
| Line 70: | Line 70: | ||
word ScriptNr, word DispatchNr;</syntax> | word ScriptNr, word DispatchNr;</syntax> | ||
(word) <tt>ScriptNr:</tt> Number of the script to reference | (word) <tt>ScriptNr:</tt> Number of the script to reference<br> | ||
(word) <tt>DispatchNr:</tt> Number of the Dispatch entry inside the script to reference | (word) <tt>DispatchNr:</tt> Number of the Dispatch entry inside the script to reference<br> | ||
Returns: (HeapPtr): The address pointed to by the specified element of the dispatch/exports table (script block type #7). | Returns: (HeapPtr): The address pointed to by the specified element of the dispatch/exports table (script block type #7). | ||
| Line 81: | Line 81: | ||
word ScriptNumber;</syntax> | word ScriptNumber;</syntax> | ||
(word) <tt>ScriptNumber</tt> | (word) <tt>ScriptNumber</tt><br> | ||
Returns: (void) | Returns: (void)<br> | ||
Disposes a script. Unloads it, removes its entries from the class table, and frees the associated heap memory. | Disposes a script. Unloads it, removes its entries from the class table, and frees the associated heap memory. | ||
| Line 91: | Line 91: | ||
HeapPtr object;</syntax> | HeapPtr object;</syntax> | ||
(HeapPtr) <tt>object:</tt> The object to clone | (HeapPtr) <tt>object:</tt> The object to clone<br> | ||
Returns: (HeapPtr) The address of the clone | Returns: (HeapPtr) The address of the clone<br> | ||
This function clones a Class or Object by copying it as a whole and mofifying the -info- selector so that it contains 1. Objects with -info- set to 0x8000 (Classes) are stripped of their selector name area, and both Objects and Classes are stripped of the function selector area. | This function clones a Class or Object by copying it as a whole and mofifying the -info- selector so that it contains 1. Objects with -info- set to 0x8000 (Classes) are stripped of their selector name area, and both Objects and Classes are stripped of the function selector area. | ||
| Line 101: | Line 101: | ||
HeapPtr clone;</syntax> | HeapPtr clone;</syntax> | ||
(HeapPtr) <tt>clone:</tt> The clone to dispose | (HeapPtr) <tt>clone:</tt> The clone to dispose<br> | ||
Returns: (void) | Returns: (void)<br> | ||
Frees all memory associated with a cloned object (as produced by Clone()). | Frees all memory associated with a cloned object (as produced by Clone()). | ||
| Line 122: | Line 122: | ||
word PicNr[, word Animation, word Flags, word DefaultPalette]; | word PicNr[, word Animation, word Flags, word DefaultPalette]; | ||
(word) PicNr: The resource number of the picture to draw | (word) PicNr: The resource number of the picture to draw<br> | ||
(word) Animation: One of the following animation modes: | (word) Animation: One of the following animation modes: | ||
| Line 150: | Line 150: | ||
(word) Flags: | (word) Flags: | ||
Bit 0: Clear screen before drawing | * Bit 0: Clear screen before drawing | ||
Bit 1-f: unknown, probably unused | * Bit 1-f: unknown, probably unused | ||
If not specified, it defaults to 1. | If not specified, it defaults to 1. | ||
| Line 157: | Line 157: | ||
Some interpreter versions older than 0.000.502 interpret this parameter inversely, and have 0 as a default. | Some interpreter versions older than 0.000.502 interpret this parameter inversely, and have 0 as a default. | ||
(word) DefaultPalette: The default palette number to use for drawing | (word) DefaultPalette: The default palette number to use for drawing<br> | ||
Returns: (void) | Returns: (void)<br> | ||
The second parameter does not appear to affect anything. In QfG1, it appears to be set to <tt>0x64</tt> constantly. <tt>DefaultPalette</tt> is used to differentiate between day and night in QfG1. Palette 1 is used for "night" pictures, Palette 0 for "day" pictures there. The picture is drawn to the background image (which is used for restauration of everything with the exception of the mouse pointer). To bring it to the foreground, <tt>Animate()</tt> must be used. | The second parameter does not appear to affect anything. In QfG1, it appears to be set to <tt>0x64</tt> constantly. <tt>DefaultPalette</tt> is used to differentiate between day and night in QfG1. Palette 1 is used for "night" pictures, Palette 0 for "day" pictures there. The picture is drawn to the background image (which is used for restauration of everything with the exception of the mouse pointer). To bring it to the foreground, <tt>Animate()</tt> must be used. | ||
| Line 173: | Line 173: | ||
[(word) NewPicNotValid];</syntax> | [(word) NewPicNotValid];</syntax> | ||
[(word) <tt>NewPicNotValid</tt>]: The new value of the "PicNotValid" flag. | [(word) <tt>NewPicNotValid</tt>]: The new value of the "PicNotValid" flag.<br> | ||
Returns: (word): The previous value of the "PicNotValid" flag | Returns: (word): The previous value of the "PicNotValid" flag<br> | ||
This sets the <tt>PicNotValid</tt> flag that determines whether or not the current background picture should be considered "valid" by the other kernel functions. | This sets the <tt>PicNotValid</tt> flag that determines whether or not the current background picture should be considered "valid" by the other kernel functions. | ||
| Line 183: | Line 183: | ||
[DblList ViewList], [word cycle];</syntax> | [DblList ViewList], [word cycle];</syntax> | ||
[(DblList) <tt>ViewList</tt>]: List of views that are to be drawn on top of the background picture | [(DblList) <tt>ViewList</tt>]: List of views that are to be drawn on top of the background picture<br> | ||
(word) <unknown> | (word) <unknown><br> | ||
Returns: (void) | Returns: (void)<br> | ||
This function draws a background picture plus some views to the foreground. If the background picture had not been drawn previously, it is animated with the animation style set during kDrawPic (see section Kernel function 0x08). Drawing the views is a rather complex issue. Refer to Views and animation in SCI section for its description. | This function draws a background picture plus some views to the foreground. If the background picture had not been drawn previously, it is animated with the animation style set during kDrawPic (see section Kernel function 0x08). Drawing the views is a rather complex issue. Refer to Views and animation in SCI section for its description. | ||
| Line 194: | Line 194: | ||
DblList ViewList;</syntax> | DblList ViewList;</syntax> | ||
(DblList) <tt>ViewList</tt>: List of affected views | (DblList) <tt>ViewList</tt>: List of affected views<br> | ||
Returns: (void) | Returns: (void)<br> | ||
===Kernel function <tt>0x0d: NumLoops(HeapPtr)</tt>=== | ===Kernel function <tt>0x0d: NumLoops(HeapPtr)</tt>=== | ||
| Line 202: | Line 202: | ||
HeapPtr object;</syntax> | HeapPtr object;</syntax> | ||
(HeapPtr) <tt>object:</tt> The object which the view selector should be taken from | (HeapPtr) <tt>object:</tt> The object which the view selector should be taken from<br> | ||
Returns: (word) The number of loops in the view | Returns: (word) The number of loops in the view<br> | ||
This function looks up the view selector in the specified object, loads the view resource associated with it, and checks for the number of animation loops in the view. | This function looks up the view selector in the specified object, loads the view resource associated with it, and checks for the number of animation loops in the view. | ||
| Line 212: | Line 212: | ||
HeapPtr object;</syntax> | HeapPtr object;</syntax> | ||
HeapPtr <tt>object:</tt> The object which the selectors should be taken from | HeapPtr <tt>object:</tt> The object which the selectors should be taken from<br> | ||
Returns: (word) The number of cels in the loop | Returns: (word) The number of cels in the loop<br> | ||
This function looks up one specific loop in a specific view (both are taken from selectors with the same name from the object pointed to by the parameter) and returns the number of cels (animation frames) in it. | This function looks up one specific loop in a specific view (both are taken from selectors with the same name from the object pointed to by the parameter) and returns the number of cels (animation frames) in it. | ||
| Line 222: | Line 222: | ||
word view, word loop, word cel;</syntax> | word view, word loop, word cel;</syntax> | ||
(HeapPtr) <tt>view:</tt> The view we're searching in <tt>loop:</tt> The loop the cel is contained in <tt>cel:</tt> The cel we're interested in | (HeapPtr) <tt>view:</tt> The view we're searching in <tt>loop:</tt> The loop the cel is contained in <tt>cel:</tt> The cel we're interested in<br> | ||
Returns: (word) The width of the cel identified by the tuple (view, loop, cel). | Returns: (word) The width of the cel identified by the tuple (view, loop, cel).<br> | ||
===Kernel function 0x0f: CelWide(word view, word loop, word cel)=== | ===Kernel function 0x0f: CelWide(word view, word loop, word cel)=== | ||
| Line 230: | Line 230: | ||
word view, word loop, word cel;</syntax> | word view, word loop, word cel;</syntax> | ||
(HeapPtr) <tt>view:</tt> The view we're searching in <tt>loop:</tt> The loop the cel is contained in <tt>cel:</tt> The cel we're interested in | (HeapPtr) <tt>view:</tt> The view we're searching in <tt>loop:</tt> The loop the cel is contained in <tt>cel:</tt> The cel we're interested in<br> | ||
Returns: (word) The height of the cel identified by the tuple (view, loop, cel). | Returns: (word) The height of the cel identified by the tuple (view, loop, cel).<br> | ||
===Kernel function <tt>0x11: DrawCel(word, word, word, Point, word)</tt>=== | ===Kernel function <tt>0x11: DrawCel(word, word, word, Point, word)</tt>=== | ||
| Line 238: | Line 238: | ||
word view, word loop, word cel, Point pos, word priority;</syntax> | word view, word loop, word cel, Point pos, word priority;</syntax> | ||
(word) <tt>view:</tt> Number of the view resource to display | (word) <tt>view:</tt> Number of the view resource to display<br> | ||
(word) <tt>loop:</tt> Number of the loop in the view resource to display | (word) <tt>loop:</tt> Number of the loop in the view resource to display<br> | ||
(word) <tt>cel:</tt> Number of the cel inside the loop to display | (word) <tt>cel:</tt> Number of the cel inside the loop to display<br> | ||
(Point) <tt>pos:</tt> Position the cel should be drawn to | (Point) <tt>pos:</tt> Position the cel should be drawn to<br> | ||
(word) <tt>priority:</tt> Priority to draw the cel with | (word) <tt>priority:</tt> Priority to draw the cel with<br> | ||
Returns: (void) | Returns: (void)<br> | ||
Explicitly draws a cel, specified by the complete tuple (view, loop, cel), to a specified position. Invalid loop/cel values are assumed to be 0. | Explicitly draws a cel, specified by the complete tuple (view, loop, cel), to a specified position. Invalid loop/cel values are assumed to be 0. | ||
| Line 252: | Line 252: | ||
DblList picviews;</syntax> | DblList picviews;</syntax> | ||
(DblList) <tt>picviews:</tt> A doubly linked list of PicViews, i.e. objects that are drawn statically onto the background picture | (DblList) <tt>picviews:</tt> A doubly linked list of PicViews, i.e. objects that are drawn statically onto the background picture<br> | ||
Returns: (void) | Returns: (void)<br> | ||
This function stores the list of PicViews for later use by the Animate() syscall. See Kernel function 0x0b section for more details. | This function stores the list of PicViews for later use by the Animate() syscall. See Kernel function 0x0b section for more details. | ||
| Line 262: | Line 262: | ||
Rect Boundaries, HeapPtr Title, word Flags, word Priority, word FGColor, word BGColor;</syntax> | Rect Boundaries, HeapPtr Title, word Flags, word Priority, word FGColor, word BGColor;</syntax> | ||
(Rect) <tt>Boundaries:<tt> The bounding rectangle of the window | (Rect) <tt>Boundaries:<tt> The bounding rectangle of the window<br> | ||
(HeapPtr) <tt>Title:</tt> A pointer to the window title | (HeapPtr) <tt>Title:</tt> A pointer to the window title<br> | ||
(word) <tt>Flags:</tt> | (word) <tt>Flags:</tt><br> | ||
* bit 0 - transparency | * bit 0 - transparency | ||
| Line 272: | Line 272: | ||
* bit 7 - don't draw anything | * bit 7 - don't draw anything | ||
(word) <tt>Priority:</tt> The priority at which the window should be drawn, or -1 to force on-top drawing | (word) <tt>Priority:</tt> The priority at which the window should be drawn, or -1 to force on-top drawing<br> | ||
(word) <tt>FGColor:</tt> The foreground color for the window | (word) <tt>FGColor:</tt> The foreground color for the window<br> | ||
(word) <tt>BGColor:</tt> The background color | (word) <tt>BGColor:</tt> The background color<br> | ||
Returns: (HeapPtr): The position of the window structure on the heap | Returns: (HeapPtr): The position of the window structure on the heap<br> | ||
This function creates a window (see also Windows, Dialogs and Controls section), sets this window as the active port, draws the window (if neccessary), and returns with the window's heap address. | This function creates a window (see also Windows, Dialogs and Controls section), sets this window as the active port, draws the window (if neccessary), and returns with the window's heap address. | ||
| Line 290: | Line 290: | ||
HeapPtr NewPort;</syntax> | HeapPtr NewPort;</syntax> | ||
(HeapPtr) <tt>NewPort:</tt> The new port to set | (HeapPtr) <tt>NewPort:</tt> The new port to set<br> | ||
Returns: (void) | Returns: (void)<br> | ||
This selects the new port which many kernel functions will draw to. | This selects the new port which many kernel functions will draw to. | ||
| Line 302: | Line 302: | ||
HeapPtr Window;</syntax> | HeapPtr Window;</syntax> | ||
(HeapPtr) <tt>Window:</tt> The heap address of the window to destroy | (HeapPtr) <tt>Window:</tt> The heap address of the window to destroy<br> | ||
Returns: (void) | Returns: (void)<br> | ||
Destroys a window and frees the associated heap structure. | Destroys a window and frees the associated heap structure. | ||
| Line 312: | Line 312: | ||
HeapPtr Control;</syntax> | HeapPtr Control;</syntax> | ||
(HeapPtr) <tt>Control:</tt> The heap address of the Control to draw | (HeapPtr) <tt>Control:</tt> The heap address of the Control to draw<br> | ||
Returns: (void) | Returns: (void)<br> | ||
This function draws a Control (see Windows, Dialogs and Controls section for details). Please note that the correct port must be selected beforehand. | This function draws a Control (see Windows, Dialogs and Controls section for details). Please note that the correct port must be selected beforehand. | ||
| Line 322: | Line 322: | ||
HeapPtr Control;</syntax> | HeapPtr Control;</syntax> | ||
(HeapPtr) <tt>Control:</tt> The control to highlight | (HeapPtr) <tt>Control:</tt> The control to highlight<br> | ||
Returns: (void) | Returns: (void)<br> | ||
This function is used to highlight a control by drawing it with an inverted color scheme. It requires the correct port to be set beforehand. See Windows, Dialogs and Controls section for details on the windowing Control system. | This function is used to highlight a control by drawing it with an inverted color scheme. It requires the correct port to be set beforehand. See Windows, Dialogs and Controls section for details on the windowing Control system. | ||
| Line 332: | Line 332: | ||
HeapPtr Control, HeapPtr Event;</syntax> | HeapPtr Control, HeapPtr Event;</syntax> | ||
(HeapPtr) <tt>Control:</tt> A heap pointer to the Control to edit | (HeapPtr) <tt>Control:</tt> A heap pointer to the Control to edit<br> | ||
(HeapPtr) <tt>Event:</tt> The event to interpret | (HeapPtr) <tt>Event:</tt> The event to interpret<br> | ||
Returns: (void) | Returns: (void)<br> | ||
This function will apply the event provided to edit a type 3 (Edit window) Control (see Windows, Dialogs and Controls section for a description of the control system). Normal keypresses are added to the area pointed to by Control::text, unless the total string length would be greater than Control::max. Cursor keys, backspace and a few other keys may be used to manipulate the control. In FreeSCI, some of the libreadline control keys can be used to edit and move the cursor as well. If it is called to edit a Control which is not of type 3, it returns without error. Please note that the correct port (usually the window which the Control was drawn in) must be selected beforehand. | This function will apply the event provided to edit a type 3 (Edit window) Control (see Windows, Dialogs and Controls section for a description of the control system). Normal keypresses are added to the area pointed to by Control::text, unless the total string length would be greater than Control::max. Cursor keys, backspace and a few other keys may be used to manipulate the control. In FreeSCI, some of the libreadline control keys can be used to edit and move the cursor as well. If it is called to edit a Control which is not of type 3, it returns without error. Please note that the correct port (usually the window which the Control was drawn in) must be selected beforehand. | ||
| Line 343: | Line 343: | ||
HeapPtr dest, HeapPtr src, word font[, word maxwidth];</syntax> | HeapPtr dest, HeapPtr src, word font[, word maxwidth];</syntax> | ||
(HeapPtr) <tt>dest:</tt> The destination to write the rectangle to | (HeapPtr) <tt>dest:</tt> The destination to write the rectangle to<br> | ||
(HeapPtr) <tt>src:</tt> A pointer to the string to analyze | (HeapPtr) <tt>src:</tt> A pointer to the string to analyze<br> | ||
(word) <tt>font:</tt> The number of the font resource to use for this check | (word) <tt>font:</tt> The number of the font resource to use for this check<br> | ||
(word) <tt>maxwidth:</tt> The maximum width to allow for the text (defaults to 192) | (word) <tt>maxwidth:</tt> The maximum width to allow for the text (defaults to 192)<br> | ||
Returns: (void) | Returns: (void)<br> | ||
This function calculates the width and height the specified text will require to be displayed with the specified font and the specified maximum width. The result will be written to the (you guessed it) specified destination on the heap. The result is a rectangle structure: The first four bytes equal to zero, the next word is the height, and the last word is the width. | This function calculates the width and height the specified text will require to be displayed with the specified font and the specified maximum width. The result will be written to the (you guessed it) specified destination on the heap. The result is a rectangle structure: The first four bytes equal to zero, the next word is the height, and the last word is the width. | ||
| Line 356: | Line 356: | ||
String text, word commands...;</syntax> | String text, word commands...;</syntax> | ||
(String) <tt>text:</tt> The text to work with | (String) <tt>text:</tt> The text to work with<br> | ||
(word) <tt>commands...:</tt> A sequence of commands with parameters: | (word) <tt>commands...:</tt> A sequence of commands with parameters:<br> | ||
* 100: 2 params, (X,Y) coord of where to write on the port. | * 100: 2 params, (X,Y) coord of where to write on the port. | ||
* 101: 1 param, -1, 0 or 1 (align right (-1), left (0) or center (1). | * 101: 1 param, -1, 0 or 1 (align right (-1), left (0) or center (1). | ||
| Line 368: | Line 368: | ||
* 108: 1 param, (handle to stored pixels) restore under. With this command, the text and all other parameters are ignored. | * 108: 1 param, (handle to stored pixels) restore under. With this command, the text and all other parameters are ignored. | ||
Returns: (void) or (&FarPtr)(see above) | Returns: (void) or (&FarPtr)(see above)<br> | ||
This function executes the specified commands, then draws the supplied text to the active port (unless command 108 was executed). | This function executes the specified commands, then draws the supplied text to the active port (unless command 108 was executed). | ||
| Line 380: | Line 380: | ||
* bit 0 - 14: Bit mask for the events to be returned. | * bit 0 - 14: Bit mask for the events to be returned. | ||
* bit 15: Disable joystick polling | * bit 15: Disable joystick polling | ||
Returns: (word): 0 if a null event was created, 1 otherwise | (HeapPtr) <tt>Event:</tt> An Object on the stack which the results are written to<br> | ||
Returns: (word): 0 if a null event was created, 1 otherwise<br> | |||
This function fills an Event object with data from the event queue. The results are written to the "type", "message" and "modifiers" selectors. See Event handling in SCI section for details. | This function fills an Event object with data from the event queue. The results are written to the "type", "message" and "modifiers" selectors. See Event handling in SCI section for details. | ||
| Line 390: | Line 391: | ||
HeapPtr Event;</syntax> | HeapPtr Event;</syntax> | ||
(HeapPtr) <tt>Event:</tt> pointer to the Event object to convert | (HeapPtr) <tt>Event:</tt> pointer to the Event object to convert<br> | ||
Returns: (void) | Returns: (void)<br> | ||
This function converts a screen-relative event to a port-relative one, using the currently active port. | This function converts a screen-relative event to a port-relative one, using the currently active port. | ||
| Line 400: | Line 401: | ||
HeapPtr Event;</syntax> | HeapPtr Event;</syntax> | ||
(HeapPtr) <tt>Event:</tt> pointer to the Event object to convert | (HeapPtr) <tt>Event:</tt> pointer to the Event object to convert<br> | ||
Returns: (void) | Returns: (void)<br> | ||
This function converts a port-relative event to a screen-relative one, using the currently active port. | This function converts a port-relative event to a screen-relative one, using the currently active port. | ||
| Line 410: | Line 411: | ||
HeapPtr Event;</syntax> | HeapPtr Event;</syntax> | ||
(HeapPtr) <tt>Event:</tt> pointer to the Event object to convert | (HeapPtr) <tt>Event:</tt> pointer to the Event object to convert<br> | ||
Returns: (HeapPtr): A pointer to the converted object | Returns: (HeapPtr): A pointer to the converted object<br> | ||
This function converts a keyboard event to a movement event, if possible. Otherwise, the function returns without error. See Event handling in SCI section for details. | This function converts a keyboard event to a movement event, if possible. Otherwise, the function returns without error. See Event handling in SCI section for details. | ||
| Line 420: | Line 421: | ||
word mode;</syntax> | word mode;</syntax> | ||
(word) <tt>mode:</tt> 1 to draw, 0 to clear | (word) <tt>mode:</tt> 1 to draw, 0 to clear<br> | ||
Returns: (void) | Returns: (void)<br> | ||
Either draws or clears (overdraws with black) the menu bar. | Either draws or clears (overdraws with black) the menu bar. | ||
| Line 430: | Line 431: | ||
HeapPtr event[, word flag];</syntax> | HeapPtr event[, word flag];</syntax> | ||
(HeapPtr) <tt>event:</tt> The event to interpret | (HeapPtr) <tt>event:</tt> The event to interpret<br> | ||
(word) flag: (unknown) | (word) flag: (unknown)<br> | ||
Returns: (word) The menu index of a selected option, -1 if no menu option was selected, or 0 if the event passed through all of the menu system's filters. | Returns: (word) The menu index of a selected option, -1 if no menu option was selected, or 0 if the event passed through all of the menu system's filters. | ||
| Line 441: | Line 442: | ||
HeapPtr title, HeapPtr content;</syntax> | HeapPtr title, HeapPtr content;</syntax> | ||
(HeapPtr) <tt>title:</tt> The menu title | (HeapPtr) <tt>title:</tt> The menu title<br> | ||
(HeapPtr) <tt>content:</tt> The menu options | (HeapPtr) <tt>content:</tt> The menu options<br> | ||
Returns: (void) | Returns: (void)<br> | ||
This function adds a menu to the menu bar. The menu title is passed in the first parameter, the second parameter contains a heap pointer to the menu entries. They are contained in one single string; the following special characters/character combinations are used: | This function adds a menu to the menu bar. The menu title is passed in the first parameter, the second parameter contains a heap pointer to the menu entries. They are contained in one single string; the following special characters/character combinations are used: | ||
| Line 458: | Line 459: | ||
HeapPtr text;</syntax> | HeapPtr text;</syntax> | ||
(HeapPtr) <tt>text:</tt> The text to draw | (HeapPtr) <tt>text:</tt> The text to draw<br> | ||
Returns: (void) | Returns: (void)<br> | ||
Draws the specified text to the title bar. | Draws the specified text to the title bar. | ||
Kernel function 0x24: Parse(HeapPtr, HeapPtr) | ===Kernel function 0x24: Parse(HeapPtr, HeapPtr)=== | ||
kfunct 0x24: Parse(); | kfunct 0x24: Parse(); | ||
HeapPtr event, HeapPtr input; | HeapPtr event, HeapPtr input; | ||
(HeapPtr) event: The event to generate | (HeapPtr) event: The event to generate<br> | ||
(HeapPtr) input: The input line to parse | (HeapPtr) input: The input line to parse<br> | ||
Returns: (word) 1 on success, 0 otherwise | Returns: (word) 1 on success, 0 otherwise<br> | ||
This function parses the input line and generates a parse event (type 0x80). See The Parser and Event handling in SCI sections for details. | This function parses the input line and generates a parse event (type 0x80). See The Parser and Event handling in SCI sections for details. | ||
| Line 482: | Line 482: | ||
HeapPtr said_block;</syntax> | HeapPtr said_block;</syntax> | ||
(HeapPtr) <tt>said_block:</tt> Pointer to a Said block | (HeapPtr) <tt>said_block:</tt> Pointer to a Said block<br> | ||
Returns: (word) 1 if the line last parsed meets the criteria of the supplied said_block, 0 otherwise. | Returns: (word) 1 if the line last parsed meets the criteria of the supplied said_block, 0 otherwise. | ||
| Line 492: | Line 492: | ||
HeapPtr list;</syntax> | HeapPtr list;</syntax> | ||
(DblList) <tt>list:</tt> List of script objects to examine | (DblList) <tt>list:</tt> List of script objects to examine<br> | ||
Returns: (void) | Returns: (void)<br> | ||
This function sets the synonyms used by the parser. Synonyms are used to replace specified word groups with other word groups. The list contains a collection of script objects; all synonyms defined by the corresponding script (which can be identified by evaluating the 'number' selector of the script object) are added to the list of active synonyms. | This function sets the synonyms used by the parser. Synonyms are used to replace specified word groups with other word groups. The list contains a collection of script objects; all synonyms defined by the corresponding script (which can be identified by evaluating the 'number' selector of the script object) are added to the list of active synonyms. | ||
| Line 501: | Line 501: | ||
<syntax type="C">kfunct 0x27: HaveMouse();</syntax> | <syntax type="C">kfunct 0x27: HaveMouse();</syntax> | ||
Returns: (word) 1 if a mouse is available, 0 if not | Returns: (word) 1 if a mouse is available, 0 if not<br> | ||
This function simply returns a flag containing the availability of a pointing device. | This function simply returns a flag containing the availability of a pointing device. | ||
| Line 509: | Line 509: | ||
word resource, word visible[, Point coordinates];</syntax> | word resource, word visible[, Point coordinates];</syntax> | ||
(word) <tt>resource:</tt> The cursor resource to use for drawing the mouse pointer | (word) <tt>resource:</tt> The cursor resource to use for drawing the mouse pointer<br> | ||
(word) <tt>visible:</tt> 1 if the mouse pointer should be visible, 0 if not | (word) <tt>visible:</tt> 1 if the mouse pointer should be visible, 0 if not<br> | ||
(Point) <tt>coordinates:</tt> The coordinates (relative to the wm-port) to move the mouse pointer to | (Point) <tt>coordinates:</tt> The coordinates (relative to the wm-port) to move the mouse pointer to<br> | ||
Returns: (void) | Returns: (void)<br> | ||
This function can change the appearance and position of the mouse pointer. If no position is provided, the position remains unchanged. | This function can change the appearance and position of the mouse pointer. If no position is provided, the position remains unchanged. | ||
| Line 521: | Line 521: | ||
String fname, word mode;</syntax> | String fname, word mode;</syntax> | ||
(String) <tt>fname:</tt> The file name | (String) <tt>fname:</tt> The file name<br> | ||
(word) <tt>mode:</tt> The mode to open the file with | (word) <tt>mode:</tt> The mode to open the file with<br> | ||
Returns: (word) a file handle on success, 12#12 on error | Returns: (word) a file handle on success, 12#12 on error<br> | ||
Tries to open or create a file in the CWD with the specified file name. The following modes are valid: | Tries to open or create a file in the CWD with the specified file name. The following modes are valid: | ||
| Line 536: | Line 536: | ||
word filehandle, String data;</syntax> | word filehandle, String data;</syntax> | ||
(word) <tt>filehandle:</tt> Handle of the file to write to | (word) <tt>filehandle:</tt> Handle of the file to write to<br> | ||
(String) <tt>data:</tt> The string to write to the file | (String) <tt>data:</tt> The string to write to the file<br> | ||
Returns: (void) | Returns: (void)<br> | ||
Writes a zero-terminated string to a file. | Writes a zero-terminated string to a file. | ||
| Line 547: | Line 547: | ||
String dest, word maxsize, word handle;</syntax> | String dest, word maxsize, word handle;</syntax> | ||
(String) <tt>dest:</tt> Pointer to the destination buffer | (String) <tt>dest:</tt> Pointer to the destination buffer<br> | ||
(word) <tt>maxsize:</tt> Maximum number of bytes to read | (word) <tt>maxsize:</tt> Maximum number of bytes to read<br> | ||
(word) <tt>handle:</tt> Handle of the file to read from | (word) <tt>handle:</tt> Handle of the file to read from<br> | ||
Returns: (word) The number of bytes actually read | Returns: (word) The number of bytes actually read<br> | ||
===Kernel function 0x2c: FClose(word)=== | ===Kernel function 0x2c: FClose(word)=== | ||
| Line 557: | Line 557: | ||
word filehandle;</syntax> | word filehandle;</syntax> | ||
(word) <tt>filehandle:</tt> Handle of the file to close | (word) <tt>filehandle:</tt> Handle of the file to close<br> | ||
Returns: (void) | Returns: (void)<br> | ||
Closes a previously opened file. | Closes a previously opened file. | ||
| Line 567: | Line 567: | ||
String game_id, word save_nr, String save_description, String version;</syntax> | String game_id, word save_nr, String save_description, String version;</syntax> | ||
(String) <tt>game_id:</tt> The game object's ID string (e.g. "SQ3") | (String) <tt>game_id:</tt> The game object's ID string (e.g. "SQ3")<br> | ||
(word) <tt>save_nr:</tt> "slot" the game is to be saved to | (word) <tt>save_nr:</tt> "slot" the game is to be saved to<br> | ||
(String) <tt>save_description:</tt> String description of the game | (String) <tt>save_description:</tt> String description of the game<br> | ||
(String) <tt>version:</tt> Stringified game version number | (String) <tt>version:</tt> Stringified game version number<br> | ||
Returns: (word) 1 on success, 0 if an error occured while saving | Returns: (word) 1 on success, 0 if an error occured while saving<br> | ||
This function saves the game state (heap, windows, call stack, view list, sound state etc.) to the savegame with the numeric id save_nr and the description save_description. game_id and version are stored alongside, for verification when the game state is restored. | This function saves the game state (heap, windows, call stack, view list, sound state etc.) to the savegame with the numeric id save_nr and the description save_description. game_id and version are stored alongside, for verification when the game state is restored. | ||
| Line 580: | Line 580: | ||
String game_id, word save_nr, String version;</syntax> | String game_id, word save_nr, String version;</syntax> | ||
(String) <tt>game_id:</tt> The game object's ID string | (String) <tt>game_id:</tt> The game object's ID string<br> | ||
(word) <tt>save_nr:</tt> Number of the save game to restore | (word) <tt>save_nr:</tt> Number of the save game to restore<br> | ||
(String) <tt>version:</tt> The game object's version number | (String) <tt>version:</tt> The game object's version number<br> | ||
Returns: (void) | Returns: (void)<br> | ||
This function restores a previously saved game. It should only return if restoring failed. | This function restores a previously saved game. It should only return if restoring failed. | ||
| Line 590: | Line 590: | ||
===Kernel function 0x2f: RestartGame()=== | ===Kernel function 0x2f: RestartGame()=== | ||
<syntax type="C">kfunct 0x2f: RestartGame();</syntax> | <syntax type="C">kfunct 0x2f: RestartGame();</syntax> | ||
Returns: never | Returns: never<br> | ||
If this function is invoked, the following things happen: | If this function is invoked, the following things happen: | ||
| Line 605: | Line 605: | ||
<syntax type="C">kfunct 0x30: GameIsRestarting();</syntax> | <syntax type="C">kfunct 0x30: GameIsRestarting();</syntax> | ||
Returns: (word) 1 if the game is restarting, 0 if not | Returns: (word) 1 if the game is restarting, 0 if not<br> | ||
===Kernel function 0x31: DoSound(word, ...])=== | ===Kernel function 0x31: DoSound(word, ...])=== | ||
| Line 611: | Line 611: | ||
word action, ...;</syntax> | word action, ...;</syntax> | ||
(word) <tt>action:</tt> The sound command subfunction number | (word) <tt>action:</tt> The sound command subfunction number<br> | ||
Returns: (see below) | Returns: (see below)<br> | ||
'action' may be one of the following: | 'action' may be one of the following: | ||
| Line 637: | Line 637: | ||
word 0, Object sound_obj;</syntax> | word 0, Object sound_obj;</syntax> | ||
(word) <tt>0:</tt> subfunction identifier | (word) <tt>0:</tt> subfunction identifier<br> | ||
(Object) <tt>sound_obj:</tt> The sound object affected | (Object) <tt>sound_obj:</tt> The sound object affected<br> | ||
Returns: (void) | Returns: (void)<br> | ||
Initializes the specified sound object. This will set the 'status' selector of the object to 1 ('initialized'), and load the sound indicated by the 'number' selector into the sound driver. | Initializes the specified sound object. This will set the 'status' selector of the object to 1 ('initialized'), and load the sound indicated by the 'number' selector into the sound driver. | ||
| Line 648: | Line 648: | ||
word 1, Object sound_obj;</syntax> | word 1, Object sound_obj;</syntax> | ||
(word) <tt>1:</tt> The subfunction identifier | (word) <tt>1:</tt> The subfunction identifier<br> | ||
(Object) <tt>sound_obj:</tt> The sound object affected | (Object) <tt>sound_obj:</tt> The sound object affected<br> | ||
Returns: (void) | Returns: (void)<br> | ||
Starts to play the song represented by the specified sound object. This will also set the 'status' selector of the object to 2 ('playing'). | Starts to play the song represented by the specified sound object. This will also set the 'status' selector of the object to 2 ('playing'). | ||
| Line 659: | Line 659: | ||
word 2;</syntax> | word 2;</syntax> | ||
(word) <tt>2:</tt> The sound command subfunction number | (word) <tt>2:</tt> The sound command subfunction number<br> | ||
Returns: (void) | Returns: (void)<br> | ||
No action appears to be associated with this subfunction call. | No action appears to be associated with this subfunction call. | ||
| Line 669: | Line 669: | ||
word 3, Object sound_obj;</syntax> | word 3, Object sound_obj;</syntax> | ||
(word) <tt>3</tt>: The sound command subfunction number | (word) <tt>3</tt>: The sound command subfunction number<br> | ||
(Object) <tt>sound_obj:</tt> The sound object affected | (Object) <tt>sound_obj:</tt> The sound object affected<br> | ||
Returns: (void) | Returns: (void)<br> | ||
Removes the song indexed by a sound object from the sound server song list. | Removes the song indexed by a sound object from the sound server song list. | ||
| Line 680: | Line 680: | ||
word 4, word state;</syntax> | word 4, word state;</syntax> | ||
(word) <tt>4:</tt> The sound command subfunction number | (word) <tt>4:</tt> The sound command subfunction number<br> | ||
(word) <tt>state:</tt> 1 if sound should be active, 0 if it should be turned off | (word) <tt>state:</tt> 1 if sound should be active, 0 if it should be turned off<br> | ||
Returns: (word) 1 if currently active, 0 if currently muted. | Returns: (word) 1 if currently active, 0 if currently muted.<br> | ||
This function completely mutes or un-mutes the sound subsystem. If called with no parameters, it returns the current status. | This function completely mutes or un-mutes the sound subsystem. If called with no parameters, it returns the current status. | ||
| Line 691: | Line 691: | ||
word 5, Object sound_obj;</syntax> | word 5, Object sound_obj;</syntax> | ||
(word) <tt>5:</tt> The sound command subfunction number | (word) <tt>5:</tt> The sound command subfunction number<br> | ||
(Object) <tt>sound_obj:</tt> The sound object affected | (Object) <tt>sound_obj:</tt> The sound object affected<br> | ||
Returns: (void) | Returns: (void)<br> | ||
Stops playing the song represented by the specified sound object. This will set the object's 'state' selector to 0 ('stopped'). | Stops playing the song represented by the specified sound object. This will set the object's 'state' selector to 0 ('stopped'). | ||
| Line 702: | Line 702: | ||
word 6, Object sound_obj;</syntax> | word 6, Object sound_obj;</syntax> | ||
(word) <tt>6:</tt> The sound command subfunction number | (word) <tt>6:</tt> The sound command subfunction number<br> | ||
(Object) <tt>sound_obj:</tt> The sound object affected | (Object) <tt>sound_obj:</tt> The sound object affected<br> | ||
Returns: (void) | Returns: (void)<br> | ||
Suspends the song associated with the specified sound object. Its state is buffered, so that it can be resumed later on. The sound object's 'state' selector is set to 3 ('suspended'). | Suspends the song associated with the specified sound object. Its state is buffered, so that it can be resumed later on. The sound object's 'state' selector is set to 3 ('suspended'). | ||
| Line 713: | Line 713: | ||
word 7, Object sound_obj;</syntax> | word 7, Object sound_obj;</syntax> | ||
(word) <tt>7:</tt> The sound command subfunction number | (word) <tt>7:</tt> The sound command subfunction number<br> | ||
(Object) </tt>sound_obj:</tt> The sound object affected | (Object) </tt>sound_obj:</tt> The sound object affected<br> | ||
Returns: (void) | Returns: (void)<br> | ||
Resumes a previously suspended song. The 'state' selector is set to 2 ('playing'). | Resumes a previously suspended song. The 'state' selector is set to 2 ('playing'). | ||
| Line 724: | Line 724: | ||
word 8[, word volume];</syntax> | word 8[, word volume];</syntax> | ||
(word) <tt>8:</tt> The sound command subfunction number | (word) <tt>8:</tt> The sound command subfunction number<br> | ||
(word) <tt>volume:</tt> An optional volume parameter | (word) <tt>volume:</tt> An optional volume parameter<br> | ||
Returns: (word) The currently set sound volume (0 to 0xf) | Returns: (word) The currently set sound volume (0 to 0xf)<br> | ||
This subfunction retrieves and returns the current sound volume. If a second parameter is supplied the volume will be set to the value of this parameter. | This subfunction retrieves and returns the current sound volume. If a second parameter is supplied the volume will be set to the value of this parameter. | ||
| Line 735: | Line 735: | ||
word 9, Object sound_obj;</syntax> | word 9, Object sound_obj;</syntax> | ||
(word) <tt>9:</tt> The sound command subfunction number | (word) <tt>9:</tt> The sound command subfunction number<br> | ||
(Object) <tt>sound_obj:</tt> The sound object affected | (Object) <tt>sound_obj:</tt> The sound object affected<br> | ||
Returns: (void) | Returns: (void)<br> | ||
Notifies the sound server that a sound object was modified. The song priority and number of loops (stored in the 'priority' and 'loop' selectors, respectively) are re-evaulated by the sound system. | Notifies the sound server that a sound object was modified. The song priority and number of loops (stored in the 'priority' and 'loop' selectors, respectively) are re-evaulated by the sound system. | ||
| Line 746: | Line 746: | ||
word 0xa, Object sound_obj;</syntax> | word 0xa, Object sound_obj;</syntax> | ||
(word) <tt>0xa:</tt> The sound command subfunction number | (word) <tt>0xa:</tt> The sound command subfunction number<br> | ||
(Object) <tt>sound_obj:</tt> The sound object affected | (Object) <tt>sound_obj:</tt> The sound object affected<br> | ||
Returns: (void) | Returns: (void)<br> | ||
Fades the specified song. Fading takes approximately two seconds. The song status is set to 'stopped' (0) afterwards. | Fades the specified song. Fading takes approximately two seconds. The song status is set to 'stopped' (0) afterwards. | ||
| Line 757: | Line 757: | ||
word 0xb;</syntax> | word 0xb;</syntax> | ||
(word) <tt>0xb:</tt> The sound command subfunction number | (word) <tt>0xb:</tt> The sound command subfunction number<br> | ||
Returns: (word) 1 if the sound driver was installed successfully, 0 if not | Returns: (word) 1 if the sound driver was installed successfully, 0 if not<br> | ||
===Kernel function 0x31: DoSound(ALL_STOP)=== | ===Kernel function 0x31: DoSound(ALL_STOP)=== | ||
| Line 765: | Line 765: | ||
word 0xc;</syntax> | word 0xc;</syntax> | ||
(word) <tt>0xc:</tt> The sound command subfunction number | (word) <tt>0xc:</tt> The sound command subfunction number<br> | ||
Returns: (void) | Returns: (void)<br> | ||
Stops all music and sound effects. | Stops all music and sound effects.<br> | ||
==Kernel function 0x32: NewList()=== | ==Kernel function 0x32: NewList()=== | ||
<syntax type="C">kfunct 0x32: NewList();</syntax> | <syntax type="C">kfunct 0x32: NewList();</syntax> | ||
Returns: (DblList) The address of a new node list on the heap | Returns: (DblList) The address of a new node list on the heap<br> | ||
This function allocates and initializes a node list containing no elements. | This function allocates and initializes a node list containing no elements. | ||
| Line 782: | Line 782: | ||
NodeList list;</syntax> | NodeList list;</syntax> | ||
(NodeList) <tt>list:</tt> The list to dispose | (NodeList) <tt>list:</tt> The list to dispose<br> | ||
Returns: (void) | Returns: (void)<br> | ||
Frees all memory associated to a list. | Frees all memory associated to a list. | ||
| Line 792: | Line 792: | ||
word value, word key;</syntax> | word value, word key;</syntax> | ||
(word) <tt>value:</tt> The node value | (word) <tt>value:</tt> The node value<br> | ||
(word) <tt>key:</tt> The node key (used for searching the list) | (word) <tt>key:</tt> The node key (used for searching the list)<br> | ||
Returns: (Node) A new node | Returns: (Node) A new node<br> | ||
This function allocates a new node and initializes it with the key and value passed as parameters. | This function allocates a new node and initializes it with the key and value passed as parameters. | ||
| Line 803: | Line 803: | ||
DblList list;</syntax> | DblList list;</syntax> | ||
(DblList) <tt>list:</tt> The list to examine | (DblList) <tt>list:</tt> The list to examine<br> | ||
Returns: (Node) The first node of the list, or 0 if the list is empty | Returns: (Node) The first node of the list, or 0 if the list is empty<br> | ||
===Kernel function 0x36: LastNode(DblList)=== | ===Kernel function 0x36: LastNode(DblList)=== | ||
| Line 811: | Line 811: | ||
DblList list;</syntax> | DblList list;</syntax> | ||
(DblList) <tt>list:</tt> The list to examine | (DblList) <tt>list:</tt> The list to examine<br> | ||
Returns: (Node) The last node of the list, or 0 if the list is empty | Returns: (Node) The last node of the list, or 0 if the list is empty<br> | ||
===Kernel function 0x37: EmptyList(DblList)=== | ===Kernel function 0x37: EmptyList(DblList)=== | ||
| Line 819: | Line 819: | ||
DblList list;</syntax> | DblList list;</syntax> | ||
(DblList) <tt>list:</tt> The list to check | (DblList) <tt>list:</tt> The list to check<br> | ||
Returns: (int) 1 if list is an empty list, 0 if it isn' | Returns: (int) 1 if list is an empty list, 0 if it isn'tv | ||
===Kernel function 0x38: NextNode(Node)=== | ===Kernel function 0x38: NextNode(Node)=== | ||
| Line 827: | Line 827: | ||
Node node;</syntax> | Node node;</syntax> | ||
(Node) <tt>node:</tt> The node whose succcessor is to be found | (Node) <tt>node:</tt> The node whose succcessor is to be found<br> | ||
Returns: (Node) The node following the supplied node, or 0 if none is available. | Returns: (Node) The node following the supplied node, or 0 if none is available.<br> | ||
===Kernel function 0x39: PrevNode(Node)=== | ===Kernel function 0x39: PrevNode(Node)=== | ||
| Line 835: | Line 835: | ||
Node node;</syntax> | Node node;</syntax> | ||
(Node) <tt>node:</tt> The node whose predecessor is to be determined | (Node) <tt>node:</tt> The node whose predecessor is to be determined<br> | ||
Returns: (Node) The supplied node's predecessor, or 0 if the node has no predecessor | Returns: (Node) The supplied node's predecessor, or 0 if the node has no predecessor<br> | ||
===Kernel function 0x3a: NodeValue(Node)=== | ===Kernel function 0x3a: NodeValue(Node)=== | ||
| Line 843: | Line 843: | ||
Node node;</syntax> | Node node;</syntax> | ||
(Node) <tt>node:</tt> The node whose value is to be determined | (Node) <tt>node:</tt> The node whose value is to be determined<br> | ||
Returns: (word) The value associated with the specified node | Returns: (word) The value associated with the specified node<br> | ||
===Kernel function 0x3b: AddAfter(DblList, Node, Node)=== | ===Kernel function 0x3b: AddAfter(DblList, Node, Node)=== | ||
| Line 851: | Line 851: | ||
DblList list, Node ref_node, Node new_node;</syntax> | DblList list, Node ref_node, Node new_node;</syntax> | ||
(DblList) <tt>list:</tt> The list to insert into | (DblList) <tt>list:</tt> The list to insert into<br> | ||
(Node) ref_node: The node in list to insert after | (Node) ref_node: The node in list to insert after<br> | ||
(Node) new_node: The node to insert | (Node) new_node: The node to insert<br> | ||
Returns: (void) | Returns: (void)<br> | ||
This function inserts <tt>new_node</tt> into <tt>list</tt> as the immediate successor of <tt>ref_node</tt>. | This function inserts <tt>new_node</tt> into <tt>list</tt> as the immediate successor of <tt>ref_node</tt>. | ||
| Line 863: | Line 863: | ||
DblList list, Node node;</syntax> | DblList list, Node node;</syntax> | ||
(DblList) <tt>list:</tt> The list the node is to be added to | (DblList) <tt>list:</tt> The list the node is to be added to<br> | ||
(Node) node: The node to add | (Node) node: The node to add<br> | ||
Returns: (void) | Returns: (void)<br> | ||
This function adds a node to the beginning of a doubly linked list. | This function adds a node to the beginning of a doubly linked list. | ||
| Line 875: | Line 875: | ||
DblList list, Node node;</syntax> | DblList list, Node node;</syntax> | ||
(DblList) <tt>list:</tt> The list to add the node to | (DblList) <tt>list:</tt> The list to add the node to<br> | ||
(Node) <tt>node:</tt> The node to add to the list | (Node) <tt>node:</tt> The node to add to the list<br> | ||
Returns: (void) | Returns: (void)<br> | ||
This function adds the specified node to the end of the specified list. | This function adds the specified node to the end of the specified list. | ||
| Line 886: | Line 886: | ||
DblList list, word key;</syntax> | DblList list, word key;</syntax> | ||
(DblList) <tt>list:</tt> The list in which the key is to be sought | (DblList) <tt>list:</tt> The list in which the key is to be sought<br> | ||
(word) <tt>key:</tt> The key to seek | (word) <tt>key:</tt> The key to seek<br> | ||
Returns: (Node) The node containing the key, or 0 if no node contains it | Returns: (Node) The node containing the key, or 0 if no node contains it<br> | ||
This function searches for a specific key in the nodes of a doubly linked list. | This function searches for a specific key in the nodes of a doubly linked list. | ||
| Line 897: | Line 897: | ||
DblList list, word key;</syntax> | DblList list, word key;</syntax> | ||
(DblList) <tt>list:</tt> The list to examine | (DblList) <tt>list:</tt> The list to examine<br> | ||
(word) <tt>key:</tt> The key to find | (word) <tt>key:</tt> The key to find<br> | ||
Returns: (void) | Returns: (void)<br> | ||
This function searches in the supplied list for the specified key and removes the node containing it, if any can be found. | This function searches in the supplied list for the specified key and removes the node containing it, if any can be found. | ||
===Kernel function 0x40: Random(word, word)=== | ===Kernel function 0x40: Random(word, word)=== | ||
<syntax type="C">kfunct 0x40: Random(); | <syntax type="C">kfunct 0x40: Random(); | ||
word min, word max;</syntax> | word min, word max;</syntax> | ||
(word) <tt>min:</tt> The minimum result | (word) <tt>min:</tt> The minimum result<br> | ||
(word) <tt>max:</tt> The maximum result | (word) <tt>max:</tt> The maximum result<br> | ||
Returns: (word) A random number between min and max (inclusive) | Returns: (word) A random number between min and max (inclusive)<br> | ||
Kernel function 0x41: Abs(word) | ===Kernel function 0x41: Abs(word)=== | ||
<syntax type="C">kfunct 0x41: Abs(); | |||
word value;</syntax> | |||
<syntax type="C">word value;</syntax> | |||
(word) <tt>value | (word) <tt>value</tt>: The value to absolutize<br> | ||
Returns: (word) The absolute value of the specified parameter | Returns: (word) The absolute value of the specified parameter<br> | ||
This function interprets the supplied value as a signed value and returns its absolute value. | This function interprets the supplied value as a signed value and returns its absolute value. | ||
===Kernel function 0x42: Sqrt(word)=== | ===Kernel function 0x42: Sqrt(word)=== | ||
<syntax type="C">kfunct 0x42: Sqrt(); | <syntax type="C">kfunct 0x42: Sqrt(); | ||
word value;</syntax> | word value;</syntax> | ||
(word) <tt>value:</tt> The value to draw the square root out of | (word) <tt>value:</tt> The value to draw the square root out of<br> | ||
Returns: (word) The square root of the supplied value | Returns: (word) The square root of the supplied value<br> | ||
===Kernel function 0x43: GetAngle(Point, Point)=== | ===Kernel function 0x43: GetAngle(Point, Point)=== | ||
| Line 939: | Line 935: | ||
Point origin, Point destination;</syntax> | Point origin, Point destination;</syntax> | ||
(Point) <tt>origin:</tt> The point to look from | (Point) <tt>origin:</tt> The point to look from<br> | ||
(Point) <tt>destination:</tt> The point to look to | (Point) <tt>destination:</tt> The point to look to<br> | ||
Returns: (word) A positive angle between the two points, relative to the screen coordinate axis. | Returns: (word) A positive angle between the two points, relative to the screen coordinate axis. | ||
| Line 950: | Line 946: | ||
Point foo, Point bar;</syntax> | Point foo, Point bar;</syntax> | ||
(Point) <tt>foo:</tt> A point in two-dimensional integer space | (Point) <tt>foo:</tt> A point in two-dimensional integer space<br> | ||
(Point) <tt>bar:</tt> Another two-dimensional integer point | (Point) <tt>bar:</tt> Another two-dimensional integer point<br> | ||
Returns: (int) The euklidian distance between the points foo and bar | Returns: (int) The euklidian distance between the points foo and bar<br> | ||
===Kernel function 0x45: Wait(word)=== | ===Kernel function 0x45: Wait(word)=== | ||
| Line 960: | Line 956: | ||
word ticks;</syntax> | word ticks;</syntax> | ||
(word) <tt>ticks:</tt> The number of game ticks (60 Hz beats) to wait | (word) <tt>ticks:</tt> The number of game ticks (60 Hz beats) to wait<br> | ||
Returns: (word) The time passed in between the finish of the last Wait() syscall | Returns: (word) The time passed in between the finish of the last Wait() syscall<br> | ||
Kernel function 0x46: GetTime([word]) | ===Kernel function 0x46: GetTime([word])=== | ||
<syntax type="C">kfunct 0x46: GetTime(); | |||
word mode;</syntax> | |||
<syntax type="C">word mode;</syntax> | |||
(wrod) <tt>mode:</tt> If this parameter is supplied, the time of day is returned. | (wrod) <tt>mode:</tt> If this parameter is supplied, the time of day is returned. | ||
Returns: (word) Either the time of day in seconds, or the elapsed number of ticks since the interpreter started. | Returns: (word) Either the time of day in seconds, or the elapsed number of ticks since the interpreter started.<br> | ||
This function is somewhat strange, because it determines its behaviour not by the value of a parameter passed, but by its presence instead. Please note that the time of day in this case does not distinguish between am and pm. | This function is somewhat strange, because it determines its behaviour not by the value of a parameter passed, but by its presence instead. Please note that the time of day in this case does not distinguish between am and pm. | ||
| Line 980: | Line 974: | ||
HeapPtr string;</syntax> | HeapPtr string;</syntax> | ||
(HeapPtr) <tt>string:</tt> The string whose terminator should be found | (HeapPtr) <tt>string:</tt> The string whose terminator should be found<br> | ||
Returns: (HeapPtr) The address of the null terminator of the indexed string | Returns: (HeapPtr) The address of the null terminator of the indexed string<br> | ||
===Kernel function 0x48: StrCat(HeapPtr, HeapPtr)=== | ===Kernel function 0x48: StrCat(HeapPtr, HeapPtr)=== | ||
| Line 988: | Line 982: | ||
HeapPtr dest, HeapPtr source;</syntax> | HeapPtr dest, HeapPtr source;</syntax> | ||
(HeapPtr) <tt>dest:</tt> The string whose end is appended to | (HeapPtr) <tt>dest:</tt> The string whose end is appended to<br> | ||
(HeapPtr) <tt>source:</tt> The string to append | (HeapPtr) <tt>source:</tt> The string to append<br> | ||
Returns: (HeapPtr) dest | Returns: (HeapPtr) dest<br> | ||
This function concatenates two strings on the heap. | This function concatenates two strings on the heap. | ||
| Line 999: | Line 993: | ||
HeapPtr foo, HeapPtr bar[, word length];</syntax> | HeapPtr foo, HeapPtr bar[, word length];</syntax> | ||
(HeapPtr) <tt>foo:</tt> The one string to compare | (HeapPtr) <tt>foo:</tt> The one string to compare<br> | ||
(HeapPtr) <tt>bar:</tt> The other string to compare | (HeapPtr) <tt>bar:</tt> The other string to compare<br> | ||
(int) <tt>width:</tt> The maximum number of characters to compare | (int) <tt>width:</tt> The maximum number of characters to compare<br> | ||
Returns: (word) -1 if foo is less than bar, 0 if both are equal, 1 if foo is greater than bar | Returns: (word) -1 if foo is less than bar, 0 if both are equal, 1 if foo is greater than bar<br> | ||
This function simply encapsulates the libc <tt>strcmp</tt>(<tt>char *</tt>, <tt>char *</tt>) and <tt>strncmp</tt>(<tt>char *</tt>, <tt>char *</tt>, <tt>int</tt>) functions. | This function simply encapsulates the libc <tt>strcmp</tt>(<tt>char *</tt>, <tt>char *</tt>) and <tt>strncmp</tt>(<tt>char *</tt>, <tt>char *</tt>, <tt>int</tt>) functions. | ||
| Line 1,011: | Line 1,005: | ||
HeapPtr string;</syntax> | HeapPtr string;</syntax> | ||
(HeapPtr) <tt>string:</tt> The string whose length should be calculated | (HeapPtr) <tt>string:</tt> The string whose length should be calculated<br> | ||
Returns: (word) The length of the specified string | Returns: (word) The length of the specified string<br> | ||
===Kernel function 0x4b: StrCpy(HeapPtr, HeapPtr[, word])=== | ===Kernel function 0x4b: StrCpy(HeapPtr, HeapPtr[, word])=== | ||
| Line 1,019: | Line 1,013: | ||
HeapPtr dest, HeapPtr src[, word length];</syntax> | HeapPtr dest, HeapPtr src[, word length];</syntax> | ||
(HeapPtr) <tt>dest:</tt> The destination to copy the string to | (HeapPtr) <tt>dest:</tt> The destination to copy the string to<br> | ||
(HeapPtr) <tt>src:</tt> The source from which the string is to be copied | (HeapPtr) <tt>src:</tt> The source from which the string is to be copied<br> | ||
(word) <tt>length:</tt> The maximum length of the string to copy | (word) <tt>length:</tt> The maximum length of the string to copy<br> | ||
Returns: (HeapPtr) dest | Returns: (HeapPtr) dest<br> | ||
Copies a string, plus the trailing <nowiki>\0</nowiki> terminator. The length of the string may be reduced with the optional length parameter. This function simply encapsulates the libc <tt>strcpy</tt>(<tt>char *</tt>, <tt>char *</tt>) and <tt>strncpy</tt>(<tt>char *</tt>, <tt>char *</tt>, <tt>int</tt>) functions. | Copies a string, plus the trailing <nowiki>\0</nowiki> terminator. The length of the string may be reduced with the optional length parameter. This function simply encapsulates the libc <tt>strcpy</tt>(<tt>char *</tt>, <tt>char *</tt>) and <tt>strncpy</tt>(<tt>char *</tt>, <tt>char *</tt>, <tt>int</tt>) functions. | ||
| Line 1,031: | Line 1,025: | ||
HeapPtr dest, String format, parameters...;</syntax> | HeapPtr dest, String format, parameters...;</syntax> | ||
(HeapPtr) <tt>dest:</tt> The heap destination to write to | (HeapPtr) <tt>dest:</tt> The heap destination to write to<br> | ||
(String) <tt>format:</tt> The format to use | (String) <tt>format:</tt> The format to use<br> | ||
(misc) <tt>parameters:</tt> The values and strings to insert | (misc) <tt>parameters:</tt> The values and strings to insert<br> | ||
Returns: (HeapPtr) dest | Returns: (HeapPtr) dest<br> | ||
This syscall acts as a frontend to the libc <tt>sprintf</tt>(<tt>char *</tt>, <tt>char *</tt>) function. | This syscall acts as a frontend to the libc <tt>sprintf</tt>(<tt>char *</tt>, <tt>char *</tt>) function. | ||
| Line 1,043: | Line 1,037: | ||
word resnr, word stringnr, HeapPtr dest;</syntax> | word resnr, word stringnr, HeapPtr dest;</syntax> | ||
(word) <tt>resnr</tt>: Number of the text resource to retreive the text from | (word) <tt>resnr</tt>: Number of the text resource to retreive the text from<br> | ||
(word) <tt>stringnr</tt>: Number of the string inside the resource to retreive | (word) <tt>stringnr</tt>: Number of the string inside the resource to retreive<br> | ||
(HeapPtr) <tt>dest</tt>: The destination to write the text to | (HeapPtr) <tt>dest</tt>: The destination to write the text to<br> | ||
Returns: (HeapPtr) dest | Returns: (HeapPtr) dest<br> | ||
Retrieves a string from a text resource and puts it on the heap. | Retrieves a string from a text resource and puts it on the heap. | ||
| Line 1,055: | Line 1,049: | ||
HeapPtr src;</syntax> | HeapPtr src;</syntax> | ||
(HeapPtr) <tt>src</tt>: The address of the string to interpret as a number | (HeapPtr) <tt>src</tt>: The address of the string to interpret as a number<br> | ||
Returns: (word) The numeric value of the supplied string | Returns: (word) The numeric value of the supplied string<br> | ||
This function acts as a frontend to the libc <tt>atoi(char *)</tt> function, with one exception: Numbers beginning with a '$' are interpreted as hexadecimal numbers. | This function acts as a frontend to the libc <tt>atoi(char *)</tt> function, with one exception: Numbers beginning with a '$' are interpreted as hexadecimal numbers. | ||
Kernel function 0x4f: BaseSetter(HeapPtr) | ===Kernel function 0x4f: BaseSetter(HeapPtr)=== | ||
<syntax type="C">kfunct 0x4f: BaseSetter(); | <syntax type="C">kfunct 0x4f: BaseSetter(); | ||
HeapPtr view_obj;</syntax> | HeapPtr view_obj;</syntax> | ||
(HeapPtr) <tt>view_obj</tt>: The view object whose base is to be set | (HeapPtr) <tt>view_obj</tt>: The view object whose base is to be set<br> | ||
Returns: (void) | Returns: (void)<br> | ||
This method is used to set the bounding rectangle of a view. The bounding rectangle is specified by the set {<tt>brLeft</tt>, <tt>brRight</tt>, <tt>brTop</tt>, <tt>brBottom</tt>} of selectors, which indicate the window-relative boundary points of the object's bounding rectangle. The rectangle defined here is used for colission detection, among other things. | This method is used to set the bounding rectangle of a view. The bounding rectangle is specified by the set {<tt>brLeft</tt>, <tt>brRight</tt>, <tt>brTop</tt>, <tt>brBottom</tt>} of selectors, which indicate the window-relative boundary points of the object's bounding rectangle. The rectangle defined here is used for colission detection, among other things. | ||
| Line 1,073: | Line 1,067: | ||
The algorithm employed by FreeSCI to determine these values appears to be either identical or very close to the original algorithm; it depends several of the object's selectors (x, y, z, ystep, view) the width and height of the view indicated by its (view, loop, cel) selectors, and that view's horizontal and vertical pixel offset modifyers (xmod, ymod). The algorithm works as follows: | The algorithm employed by FreeSCI to determine these values appears to be either identical or very close to the original algorithm; it depends several of the object's selectors (x, y, z, ystep, view) the width and height of the view indicated by its (view, loop, cel) selectors, and that view's horizontal and vertical pixel offset modifyers (xmod, ymod). The algorithm works as follows: | ||
<syntax type=" | <syntax type="pascal">brLeft := x - xmod - width / 2 | ||
brRight := brLeft + width | brRight := brLeft + width | ||
brBottom := y - z - ymod + 1 | brBottom := y - z - ymod + 1 | ||
| Line 1,082: | Line 1,076: | ||
HeapPtr object, word angle;</syntax> | HeapPtr object, word angle;</syntax> | ||
(HeapPtr) <tt>object:</tt> The object whose loop selector is to be set | (HeapPtr) <tt>object:</tt> The object whose loop selector is to be set<br> | ||
(word) <tt>angle:</tt> The angle which is to be used as a base to choose the loop angle | (word) <tt>angle:</tt> The angle which is to be used as a base to choose the loop angle<br> | ||
Returns: (void) | Returns: (void)<br> | ||
This function sets the loop selector of the specified object to a value implied by the 'angle' parameter, according to the following table: | This function sets the loop selector of the specified object to a value implied by the 'angle' parameter, according to the following table: | ||
| Line 1,111: | Line 1,105: | ||
HeapPtr obj [, DblList clip_list];</syntax> | HeapPtr obj [, DblList clip_list];</syntax> | ||
(HeapPtr) obj: The object to test | (HeapPtr) obj: The object to test<br> | ||
(DblList) cliplist: An optional list of objects to test ''obj ''against Returns: (int) 1 if ''obj ''can be where it is, 0 if not | (DblList) cliplist: An optional list of objects to test ''obj ''against Returns: (int) 1 if ''obj ''can be where it is, 0 if not<br> | ||
This function first retreives ''obj’s ''signal and illegalBits selectors, plus its brRect (boundary rectangle, consisting of brTop, brBottom, brLeft and brRight). If either of the DONT_RESTORE or IGNORE_ACTOR flags is set, the function returns 1, otherwise it proceeds with verifying that. | This function first retreives ''obj’s ''signal and illegalBits selectors, plus its brRect (boundary rectangle, consisting of brTop, brBottom, brLeft and brRight). If either of the DONT_RESTORE or IGNORE_ACTOR flags is set, the function returns 1, otherwise it proceeds with verifying that. | ||
illegalBits bitwise-AND the disjunction of all elements of | illegalBits bitwise-AND the disjunction of all elements of [[image:math1.png]] a pixel with the color value <tt>n</tt> inside the control map zone delimited by obj's. | ||
[[image:math2.png]]<br> | |||
If both conditions are met, 1 is returned. Otherwise, 0 is returned. | If both conditions are met, 1 is returned. Otherwise, 0 is returned. | ||
| Line 1,127: | Line 1,120: | ||
word map, Point|Rect area;</syntax> | word map, Point|Rect area;</syntax> | ||
(word) <tt>map</tt>: The map to check (bit 0: visual, bit 1: priority, bit 2: special) | (word) <tt>map</tt>: The map to check (bit 0: visual, bit 1: priority, bit 2: special)<br> | ||
(Point) or (Rect) Area: The point or rectangle that is to be scanned | (Point) or (Rect) Area: The point or rectangle that is to be scanned<br> | ||
Returns: (word) The resulting bitfield | Returns: (word) The resulting bitfield<br> | ||
This function scans the indicated point or area on the specified map, and sets the bit corresponding to each color value found correspondingly. For example, if scanning map 4 (special) would touch two areas, one with color value 1 and one with color value 10, the resulting return value would be 0x0402 (binary 0000010000000010). See also "Pictures and movement control" section. | This function scans the indicated point or area on the specified map, and sets the bit corresponding to each color value found correspondingly. For example, if scanning map 4 (special) would touch two areas, one with color value 1 and one with color value 10, the resulting return value would be 0x0402 (binary 0000010000000010). See also "Pictures and movement control" section. | ||
| Line 1,138: | Line 1,131: | ||
HeapPtr mover, word step_factor;</syntax> | HeapPtr mover, word step_factor;</syntax> | ||
(HeapPtr) <tt>mover</tt>: The mover object to initialize | (HeapPtr) <tt>mover</tt>: The mover object to initialize<br> | ||
(word) <tt>step_factor</tt>: A factor to multiply the step size with (defaults to 1) | (word) <tt>step_factor</tt>: A factor to multiply the step size with (defaults to 1)<br> | ||
Returns: (void) | Returns: (void)<br> | ||
Initializes a mover object for bresenham movement from the object's client's coordinates to the coordinates specified by its own pair of (x,y) selectors. To do this, it retreives the mover's client, and calculates the result values according to the algorithm for determining the initial values for iterative line drawing according to the Bresenham line algorithm: | Initializes a mover object for bresenham movement from the object's client's coordinates to the coordinates specified by its own pair of (x,y) selectors. To do this, it retreives the mover's client, and calculates the result values according to the algorithm for determining the initial values for iterative line drawing according to the Bresenham line algorithm: | ||
(the following code is pseudocode Pascal using `::' notation for field access) | (''the following code is pseudocode Pascal using `::' notation for field access'') | ||
<syntax type=Pascal> | <syntax type=Pascal> | ||
client := mover::client | client := mover::client | ||
| Line 1,190: | Line 1,183: | ||
HeapPtr avoider;</syntax> | HeapPtr avoider;</syntax> | ||
Returns: (word) New direction | Returns: (word) New direction<br> | ||
This function is a no-op in later SCI games, but is implemented in some or all pre-0.000.576 interpreters. | This function is a no-op in later SCI games, but is implemented in some or all pre-0.000.576 interpreters. | ||
| Line 1,199: | Line 1,192: | ||
<syntax type="C">kfunct 0x57: SetDebug();</syntax> | <syntax type="C">kfunct 0x57: SetDebug();</syntax> | ||
Returns: (void) | Returns: (void)<br> | ||
This function forces the interpreter to enter debug mode. It is equivalent to pressing LShift-RShift-PadMinus. | This function forces the interpreter to enter debug mode. It is equivalent to pressing LShift-RShift-PadMinus. | ||
| Line 1,215: | Line 1,208: | ||
word mode;</syntax> | word mode;</syntax> | ||
(word) <tt>mode</tt>: 0 to 4 (see below) | (word) <tt>mode</tt>: 0 to 4 (see below)<br> | ||
Returns: (word) The amount of free memory on the heap, in bytes | Returns: (word) The amount of free memory on the heap, in bytes<br> | ||
This function returns the total amount of free memory on the heap if mode == 0. If mode equals 1, the total size of the largest chunk of heap memory is returned. In mode 2, the size of the largest available hunk memory block is returned, and mode 3 returns the total amount of free hunk memory, shiftet to the right by 4 bits. | This function returns the total amount of free memory on the heap if mode == 0. If mode equals 1, the total size of the largest chunk of heap memory is returned. In mode 2, the size of the largest available hunk memory block is returned, and mode 3 returns the total amount of free hunk memory, shiftet to the right by 4 bits. | ||
| Line 1,262: | Line 1,255: | ||
===Kernel function 0x60: SetMenu(word, [word, any]*)=== | ===Kernel function 0x60: SetMenu(word, [word, any]*)=== | ||
;Parameters: | ;Parameters: | ||
:entry | :entry : '''word''' A pair of bytes. In LE notation, the higher byte is the ``menu ID'', and the lower byte is the ``entry ID''. | ||
:key : '''word''' A special key selecting some particular information regarding the menu entry. | :key : '''word''' A special key selecting some particular information regarding the menu entry. | ||
:value : '''word''' A special key selecting some particular information regarding the menu entry. | :value : '''word''' A special key selecting some particular information regarding the menu entry. | ||
| Line 1,272: | Line 1,265: | ||
String game_id, String strspace, HeapPtr *ptrs;</syntax> | String game_id, String strspace, HeapPtr *ptrs;</syntax> | ||
(String) <tt>game_id</tt>: The game ID as a string | (String) <tt>game_id</tt>: The game ID as a string<br> | ||
(String) <tt>strspace</tt>: The string which the result should be stored in | (String) <tt>strspace</tt>: The string which the result should be stored in<br> | ||
(HeapPtr *) <tt>ptrs</tt>: The array of pointers which the string pointers are to be stored in | (HeapPtr *) <tt>ptrs</tt>: The array of pointers which the string pointers are to be stored in<br> | ||
Returns: (word) The number of savegames for the specified game_id | Returns: (word) The number of savegames for the specified game_id<br> | ||
Returns an array of strings describing the existing save games for game_id. The strings are put into strspace one by one, and heap pointers to each of them are put into the ptrs array. The number of saved games is returned in the accumulator. | Returns an array of strings describing the existing save games for game_id. The strings are put into strspace one by one, and heap pointers to each of them are put into the ptrs array. The number of saved games is returned in the accumulator. | ||
| Line 1,284: | Line 1,277: | ||
HeapPtr address;</syntax> | HeapPtr address;</syntax> | ||
(HeapPtr) <tt>address</tt>: The address to write to | (HeapPtr) <tt>address</tt>: The address to write to<br> | ||
Returns: (HeapPtr) The supplied address | Returns: (HeapPtr) The supplied address<br> | ||
This function retrieves the current working directory (CWD) and stores its string representation at the location pointed to by the supplied parameter. | This function retrieves the current working directory (CWD) and stores its string representation at the location pointed to by the supplied parameter. | ||
| Line 1,296: | Line 1,289: | ||
String path;</syntax> | String path;</syntax> | ||
(String) <tt>path</tt>: The path to examine | (String) <tt>path</tt>: The path to examine<br> | ||
Returns: (word) 1 if saving is possible, 0 otherwise | Returns: (word) 1 if saving is possible, 0 otherwise<br> | ||
Returns TRUE if there would be enough space left on the specified path to save the current game (but doesn't actually save). | Returns TRUE if there would be enough space left on the specified path to save the current game (but doesn't actually save). | ||
| Line 1,310: | Line 1,303: | ||
String src, word offset[, char replacement];</syntax> | String src, word offset[, char replacement];</syntax> | ||
(String) <tt>src</tt>: The string to read from | (String) <tt>src</tt>: The string to read from<br> | ||
(word) <tt>offset</tt>: The offset inside the string | (word) <tt>offset</tt>: The offset inside the string<br> | ||
(char) <tt>replacement</tt>: An optional replacement value for the indexed character | (char) <tt>replacement</tt>: An optional replacement value for the indexed character<br> | ||
Returns: (char) The character requested | Returns: (char) The character requested<br> | ||
This function retreives a single character from a string. Optionally, if <tt>replacement</tt> is set, the source character will be replaced with the specified <tt>replacement</tt>. | This function retreives a single character from a string. Optionally, if <tt>replacement</tt> is set, the source character will be replaced with the specified <tt>replacement</tt>. | ||
| Line 1,322: | Line 1,315: | ||
word sub_function, String string1[, String string2];</syntax> | word sub_function, String string1[, String string2];</syntax> | ||
(word) <tt>sub_function</tt>: A numeric value from 0 to 3, inclusive. See below | (word) <tt>sub_function</tt>: A numeric value from 0 to 3, inclusive. See below<br> | ||
(String) <tt>string1</tt>: See below | (String) <tt>string1</tt>: See below<br> | ||
(String) <tt>string2</tt>: See below | (String) <tt>string2</tt>: See below<br> | ||
Returns: See below | Returns: See below<br> | ||
Depending on the value of sub_function, this system call executes one of four defined actions: | Depending on the value of sub_function, this system call executes one of four defined actions: | ||
| Line 1,343: | Line 1,336: | ||
word GET_DEVICE, String input, String output;</syntax> | word GET_DEVICE, String input, String output;</syntax> | ||
(word) <tt>GET_DEVICE</tt>: Constant sub-function identifier (0) | (word) <tt>GET_DEVICE</tt>: Constant sub-function identifier (0)<br> | ||
(String) <tt>input</tt>: A path whose device identifier should be extracted | (String) <tt>input</tt>: A path whose device identifier should be extracted<br> | ||
(String) <tt>output</tt>: The destination of the device identifier | (String) <tt>output</tt>: The destination of the device identifier<br> | ||
Returns: (HeapPtr) Points to the terminating zero character of output | Returns: (HeapPtr) Points to the terminating zero character of output<br> | ||
GET_DEVICE returns the drive/device on which "input" resides in output (and a pointer to the terminating NULL in the accumulator). | GET_DEVICE returns the drive/device on which "input" resides in output (and a pointer to the terminating NULL in the accumulator). | ||
| Line 1,355: | Line 1,348: | ||
word GET_CURRENT_DEVICE, String output;</syntax> | word GET_CURRENT_DEVICE, String output;</syntax> | ||
(word) <tt>GET_CURRENT_DEVICE</tt>: Constant sub-function identifier (1) | (word) <tt>GET_CURRENT_DEVICE</tt>: Constant sub-function identifier (1)<br> | ||
(String) <tt>output</tt>: The destination which the CWD device identifier should be written to | (String) <tt>output</tt>: The destination which the CWD device identifier should be written to<br> | ||
Returns: (HeapPtr) Points to the terminating null character of output | Returns: (HeapPtr) Points to the terminating null character of output<br> | ||
GET_CURRENT_DEVICE returns the drive/device that contains the current working directory (and a pointer to the terminating NULL in the accumulator). | GET_CURRENT_DEVICE returns the drive/device that contains the current working directory (and a pointer to the terminating NULL in the accumulator). | ||
| Line 1,366: | Line 1,359: | ||
word PATHS_EQUAL, String path1, String path2;</syntax> | word PATHS_EQUAL, String path1, String path2;</syntax> | ||
(word) <tt>PATHS_EQUAL</tt>: Constant sub-function identifier (2) | (word) <tt>PATHS_EQUAL</tt>: Constant sub-function identifier (2)<br> | ||
(String) <tt>path1</tt>: First path to compare | (String) <tt>path1</tt>: First path to compare<br> | ||
(String) <tt>path2</tt>: Second path to compare | (String) <tt>path2</tt>: Second path to compare<br> | ||
Returns: (word) 1 if path1 and path2 point to the same physical location, 0 otherwise | Returns: (word) 1 if path1 and path2 point to the same physical location, 0 otherwise<br> | ||
PATHS_EQUAL returns TRUE if the two supplied paths point to the same place. | PATHS_EQUAL returns TRUE if the two supplied paths point to the same place. | ||
| Line 1,378: | Line 1,371: | ||
word IS_FLOPPY, String path;</syntax> | word IS_FLOPPY, String path;</syntax> | ||
(word) <tt>IS_FLOPPY</tt>: Constant sub-function identifier (3) | (word) <tt>IS_FLOPPY</tt>: Constant sub-function identifier (3)<br> | ||
(String) <tt>path</tt>: | (String) <tt>path</tt>:<br> | ||
Returns: (word) 1 if <tt>path</tt> is on a floppy disk, 0 otherwise | Returns: (word) 1 if <tt>path</tt> is on a floppy disk, 0 otherwise<br> | ||
PATHS_EQUAL returns TRUE if the two supplied paths point to the same place. | PATHS_EQUAL returns TRUE if the two supplied paths point to the same place. | ||
===Kernel function 0x68: GetSaveDir()=== | ===Kernel function 0x68: GetSaveDir()=== | ||
<syntax type="C">kfunct 0x68: GetSaveDir(); | <syntax type="C">kfunct 0x68: GetSaveDir();</syntax> | ||
Returns: (String)<br> | |||
This function returns the heap position allocated to store the string representation of the save game directory. This heap space is allocated automatically during startup. | This function returns the heap position allocated to store the string representation of the save game directory. This heap space is allocated automatically during startup. | ||
| Line 1,395: | Line 1,388: | ||
String game_id, word game_nr[, String version];</syntax> | String game_id, word game_nr[, String version];</syntax> | ||
(String) <tt>game_id</tt>: The savegame ID string | (String) <tt>game_id</tt>: The savegame ID string<br> | ||
(word) <tt>game_nr</tt>: The savegame number | (word) <tt>game_nr</tt>: The savegame number<br> | ||
(String) <tt>version</tt>: An optional game version string | (String) <tt>version</tt>: An optional game version string<br> | ||
Returns: (word) 1 if the savegame is loadable, 0 otherwise | Returns: (word) 1 if the savegame is loadable, 0 otherwise<br> | ||
Returns TRUE if the specified save game is valid and loadable (i.e., not for another game/interpreter/version). | Returns TRUE if the specified save game is valid and loadable (i.e., not for another game/interpreter/version). | ||
| Line 1,407: | Line 1,400: | ||
word times [, word direction];</syntax> | word times [, word direction];</syntax> | ||
(word) <tt>times</tt>: Number of times to shake the screen | (word) <tt>times</tt>: Number of times to shake the screen<br> | ||
(word) <tt>direction</tt>: See below | (word) <tt>direction</tt>: See below<br> | ||
Returns: (void) | Returns: (void)<br> | ||
If <tt>direction</tt> is not specified, it defaults to 1. It is a bitmask and defined as follows: | If <tt>direction</tt> is not specified, it defaults to 1. It is a bitmask and defined as follows: | ||
| Line 1,434: | Line 1,427: | ||
word subfunction, word param;</syntax> | word subfunction, word param;</syntax> | ||
(word) <tt>subfunction</tt>: Always 0x0c | (word) <tt>subfunction</tt>: Always 0x0c<br> | ||
(word) <tt>param</tt>: Parameter for the subfunction, purpose unknown | (word) <tt>param</tt>: Parameter for the subfunction, purpose unknown<br> | ||
Returns: (void) | Returns: (void)<br> | ||