Open main menu
ScummVM :: Wiki

Difference between revisions of "SCI/Specifications/SCI virtual machine/Kernel functions"

SCI/Specifications/SCI virtual machine/Kernel functions (view source)

Revision as of 23:27, 9 January 2009

10,957 bytes added ,  23:27, 9 January 2009
Merging of the SCI documentation. Section "Kernel functions" done
(Merging of the SCI documentation. Work in progress)
(Merging of the SCI documentation. Section "Kernel functions" done)
Line 1: Line 1:
'''WORK IN PROGRESS. DOCUMENT INCOMPLETE'''
=Kernel functions=
=Kernel functions=


Line 1,147: Line 1,145:
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:
   
   
<syntax type=?>
(the following code is pseudocode Pascal using `::' notation for field access)
<syntax type=Pascal>
         client := mover::client
         client := mover::client
         dx := mover::x - client::x
         dx := mover::x - client::x
Line 1,180: Line 1,179:
         mover::b_i2 := mover::b_d1 * 2
         mover::b_i2 := mover::b_d1 * 2
</syntax>
</syntax>
===Kernel function 0x54: DoBresen()===
<syntax type="C">kfunct 0x55: DoBresen();
; Returns: (void)</syntax>
Executes the Bresenham algorithm on the values calculated by InitBresen, and counts down the number of steps. It then invokes CanBeHere() on the resulting coordinates, and sets the new coordinates if it actually Can Be There.
===Kernel function 0x55: DoAvoider(HeapPtr)===
<syntax type="C">kfunct 0x55: DoAvoider();
HeapPtr avoider;</syntax>
Returns: (word) New direction
This function is a no-op in later SCI games, but is implemented in some or all pre-0.000.576 interpreters.
===Kernel function 0x56: SetJump(?)===
===Kernel function 0x57: SetDebug()===
<syntax type="C">kfunct 0x57: SetDebug();</syntax>
Returns: (void)
This function forces the interpreter to enter debug mode. It is equivalent to pressing LShift-RShift-PadMinus.
===Kernel function 0x58: InspectObj(?)===
===Kernel function 0x59: ShowSends(?)===
===Kernel function 0x5a: ShowObjs(?)===
===Kernel function 0x5b: ShowFree(?)===
===Kernel function 0x5c: MemoryInfo(word)===
<syntax type="C">kfunct 0x5c: word mode();
word mode;</syntax>
(word) <tt>mode</tt>: 0 to 4 (see below)
Returns: (word) The amount of free memory on the heap, in bytes
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.
Mode 4 was apparently introduced in SCI01 and reports the amount of free memory provided by DOS in paragraphs.
===Kernel function 0x5d: StackUsage(?)===
===Kernel function 0x5e: Profiler(?)===
===Kernel function 0x5f: GetMenu(word, word)===
;Parameters:
: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''' Special key selecting some particular information regarding the menu entry.
Retrieves some metainformation about an (existing) menu entry. entry selects the menu and entry the information is recovered with respect to, and key specifies which particular information to recover. At the moment, the following kinds of information are known for key:
{|  CELLPADDING=3 BORDER="1"
!  ALIGN="LEFT" | <B>ID</B>
!  ALIGN="LEFT" VALIGN="TOP" WIDTH=99 | <B>FreeSCI macro (<TT>MENU_ATTRIBUTE_</TT>...)</B>
!  ALIGN="LEFT" VALIGN="TOP" WIDTH=269 | <B>Description</B>
|-
|  ALIGN="LEFT" | 0x6d
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=99 | <TT>SAID</TT>
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=269 | The ``<I>Said</I>'' spec associated with the menu entry, or a null pointer. If this spec is matched, the next <TT>GetEvent()</TT> call will behave as if the appropriate menu option had been selected.
|-
|  ALIGN="LEFT" | 0x6e
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=99 | <TT>TEXT</TT>
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=269 | The string currently displayed for the menu item.
|-
|  ALIGN="LEFT" | 0x6f
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=99 | <TT>KEY</TT>
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=269 | An optional key (as reported by <TT>GetKey()</TT>) the menu option should be triggered by.
|-
|  ALIGN="LEFT" | 0x70
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=99 | <TT>ENABLED</TT>
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=269 | Whether the menu option is enabled or not (in the latter case, it is grayed out and cannot be selected).
|-
|  ALIGN="LEFT" | 0x71
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=99 | <TT>TAG</TT>
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=269 | A value without special semantics.
|}
===Kernel function 0x60: SetMenu(word, [word, any]*)===
;Parameters:
: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.
:value : '''word''' A special key selecting some particular information regarding the menu entry.
<tt>SetMenu</tt> is a varargs function; it takes a menu bar <tt>entry</tt> ID (cf. <tt>GetMenu</tt>, section Kernel function 0x5f) followed by any even number of parameters. Each of these parameter pairs begins with a <tt>key</tt>; the second entry is a <tt>value</tt> whose type depends on the key. Semantics of <tt>key</tt> are as in <tt>GetMenu</tt> (cf. section Getmenu).
===Kernel function 0x61: GetSaveFiles(String, String, HeapPtr*)===
<syntax type="C">kfunct 0x61: GetSaveFiles();
String game_id, String strspace, HeapPtr *ptrs;</syntax>
(String) <tt>game_id</tt>: The game ID as a string
(String) <tt>strspace</tt>: The string which the result should be stored in
(HeapPtr *) <tt>ptrs</tt>: The array of pointers which the string pointers are to be stored in
Returns: (word) The number of savegames for the specified game_id.
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.
===Kernel function 0x62: GetCWD(HeapPtr)===
<syntax type="C">kfunct 0x62: GetCWD();
HeapPtr address;</syntax>
(HeapPtr) <tt>address</tt>: The address to write to
Returns: (HeapPtr) The supplied address
This function retrieves the current working directory (CWD) and stores its string representation at the location pointed to by the supplied parameter.
FreeSCI returns a sub-directory of the user's home directory, if applicable, instead of the cwd.
===Kernel function 0x63: CheckFreeSpace(String)===
<syntax type="C">kfunct 0x63: CheckFreeSpace();
String path;</syntax>
(String) <tt>path</tt>: The path to examine
Returns: (word) 1 if saving is possible, 0 otherwise
Returns TRUE if there would be enough space left on the specified path to save the current game (but doesn't actually save).
===Kernel function 0x64: ValidPath(?)===
===Kernel function 0x65: CoordPri(?)===
===Kernel function 0x66: StrAt (String, word[, char])===
<syntax type="C">kfunct 0x66: StrAt();
String src, word offset[, char replacement];</syntax>
(String) <tt>src</tt>: The string to read from
(word) <tt>offset</tt>: The offset inside the string
(char) <tt>replacement</tt>: An optional replacement value for the indexed character
Returns: (char) The character requested
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>.
===Kernel function 0x67: DeviceInfo(word, String[, String])===
<syntax type="C">kfunct 0x67: DeviceInfo();
word sub_function, String string1[, String string2];</syntax>
(word) <tt>sub_function</tt>: A numeric value from 0 to 3, inclusive. See below.
(String) <tt>string1</tt>: See below.
(String) <tt>string2</tt>: See below.
Returns: See below
Depending on the value of sub_function, this system call executes one of four defined actions:
<ol type="0" start=0>
<li>GET_DEVICE
<li>GET_CURRENT_DEVICE
<li>PATHS_EQUAL
<li>IS_FLOPPY
</ol>
See the specific function definitions below for more information.
===Kernel function 0x67: DeviceInfo(GET_DEVICE, String, String)===
<syntax type="C">kfunct 0x67: DeviceInfo();
word GET_DEVICE, String input, String output;</syntax>
(word) <tt>GET_DEVICE</tt>: Constant sub-function identifier (0)
(String) <tt>input</tt>: A path whose device identifier should be extracted
(String) <tt>output</tt>: The destination of the device identifier
Returns: (HeapPtr) Points to the terminating zero character of output
GET_DEVICE returns the drive/device on which "input" resides in output (and a pointer to the terminating NULL in the accumulator).
===Kernel function 0x67: DeviceInfo(GET_CURRENT_DEVICE, String output)===
<syntax type="C">kfunct 0x67: DeviceInfo();
word GET_CURRENT_DEVICE, String output;</syntax>
(word) <tt>GET_CURRENT_DEVICE</tt>: Constant sub-function identifier (1)
(String) <tt>output</tt>: The destination which the CWD device identifier should be written to.
Returns: (HeapPtr) Points to the terminating null character of output
GET_CURRENT_DEVICE returns the drive/device that contains the current working directory (and a pointer to the terminating NULL in the accumulator).
===Kernel function 0x67: DeviceInfo(PATHS_EQUAL, String path1, String path2)===
<syntax type="C">kfunct 0x67: DeviceInfo();
word PATHS_EQUAL, String path1, String path2;</syntax>
(word) <tt>PATHS_EQUAL</tt>: Constant sub-function identifier (2)
(String) <tt>path1</tt>: First path to compare
(String) <tt>path2</tt>: Second path to compare
Returns: (word) 1 if path1 and path2 point to the same physical location, 0 otherwise.
PATHS_EQUAL returns TRUE if the two supplied paths point to the same place.
===Kernel function 0x67: DeviceInfo(IS_FLOPPY, String path)===
<syntax type="C">kfunct 0x67: DeviceInfo();
word IS_FLOPPY, String path;</syntax>
(word) <tt>IS_FLOPPY</tt>: Constant sub-function identifier (3)
(String) <tt>path</tt>:
Returns: (word) 1 if <tt>path</tt> is on a floppy disk, 0 otherwise
PATHS_EQUAL returns TRUE if the two supplied paths point to the same place.
===Kernel function 0x68: GetSaveDir()===
<syntax type="C">kfunct 0x68: GetSaveDir();
; Returns: (String)</syntax>
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.
===Kernel function 0x69: CheckSaveGame(String, word[, String])===
<syntax type="C">kfunct 0x69: CheckSaveGame();
String game_id, word game_nr[, String version];</syntax>
(String) <tt>game_id</tt>: The savegame ID string
(word) <tt>game_nr</tt>: The savegame number
(String) <tt>version</tt>: An optional game version string
Returns: (word) 1 if the savegame is loadable, 0 otherwise
Returns TRUE if the specified save game is valid and loadable (i.e., not for another game/interpreter/version).
===Kernel function 0x6a: ShakeScreen(word[, word])===
<syntax type="C">kfunct 0x6a: ShakeScreen();
word times [, word direction];</syntax>
(word) <tt>times</tt>: Number of times to shake the screen
(word) <tt>direction</tt>: See below
Returns: (void)
If <tt>direction</tt> is not specified, it defaults to 1. It is a bitmask and defined as follows:
* bit 0 Shake 10 pixels downwards
* bit 1 Shake to the right
* bit 2 Unknown, but used
===Kernel function 0x6b: FlushResources(?)===
===Kernel function 0x6c: SinMult(?)===
===Kernel function 0x6d: CosMult(?)===
===Kernel function 0x6e: SinDiv(?)===
===Kernel function 0x6f: CosDiv(?)===
===Kernel function 0x70: Graph(?)===
===Kernel function 0x71: Joystick(word, word)===
<syntax type="C">kfunct 0x71: Joystick();
word subfunction, word param;</syntax>
(word) <tt>subfunction</tt>: Always 0x0c
(word) <tt>param</tt>: Parameter for the subfunction, purpose unknown.
Returns: (void)
Timofonic
245

edits

Retrieved from "https://wiki.scummvm.org/index.php?title=Special:MobileDiff/9803"