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

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

Revision as of 21:49, 9 January 2009

5,930 bytes added , 21:49, 9 January 2009

Merging of the SCI documentation. Work in progress

Timofonic

236

edits

@@ Line 16: / Line 16: @@
 <tt>02 00 80 00 0a 00</tt>
 :before calling <tt>Load()</tt>.
 Return values are returned into the accumulator, unless stated otherwise. If return type is stated as (<tt>void</tt>), then the accumulator is not modified.
 ==Parameter types==
 SCI0 uses only little endian 16 bit integer values for parameters. However, this document distinguishes between different uses of those integers by defining the following variable types:
 ;(word)
 :16 bit signed little endian integer
 ;(HeapPtr)
@@ Line 44: / Line 43: @@
 Most functions exit gracefully if either a NULL HeapPtr or DblList is provided.
 ==SCI0 Kernel functions==
@@ Line 58: / Line 56: @@
 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.
 ===Kernel function <tt>0x01: UnLoad(word, word)</tt>===
@@ Line 191: / Line 188: @@
 (word) <unknown>
 Returns: (void)
 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 375: / Line 372: @@
 Returns: (void) or (&FarPtr)(see above)
 This function executes the specified commands, then draws the supplied text to the active port (unless command 108 was executed).
 ===Kernel function 0x1c: GetEvent(word, HeapPtr)===
@@ Line 1,043: / Line 1,040: @@
 This syscall acts as a frontend to the libc <tt>sprintf</tt>(<tt>char *</tt>, <tt>char *</tt>) function.
+=== Kernel function 0x4d: GetFarText(word, word, HeapPtr) ===
+<syntax type="C">kfunct 0x4d: GetFarText();
+word resnr, word stringnr, HeapPtr dest;</syntax>
+(word) <tt>resnr</tt>: Number of the text resource to retreive the text from
+(word) <tt>stringnr</tt>: Number of the string inside the resource to retreive
+(HeapPtr) <tt>dest</tt>: The destination to write the text to
+Returns: (HeapPtr) dest
+Retrieves a string from a text resource and puts it on the heap.
+===Kernel function 0x4e: ReadNumber(HeapPtr)===
+<syntax type="C">kfunct 0x4e: ReadNumber();
+HeapPtr src;</syntax>
+(HeapPtr) <tt>src</tt>: The address of the string to interpret as a number
+Returns: (word) The numeric value of the supplied string
+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)
+<syntax type="C">kfunct 0x4f: BaseSetter();
+HeapPtr view_obj;</syntax>
+(HeapPtr) <tt>view_obj</tt>: The view object whose base is to be set
+Returns: (void)
+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.
+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="C">brLeft := x - xmod - width / 2
+brRight := brLeft + width
+brBottom := y - z - ymod + 1
+brTop := brBottom - ystep</syntax>
+===Kernel function 0x50: DirLoop(HeapPtr, word)===
+<syntax type="C">kfunct 0x50: DirLoop();
+HeapPtr object, word angle;</syntax>
+(HeapPtr) <tt>object:</tt> The object whose loop selector is to be set
+(word) <tt>angle:</tt> The angle which is to be used as a base to choose the loop angle
+Returns: (void)
+This function sets the loop selector of the specified object to a value implied by the 'angle' parameter, according to the following table:
+{| border="1"
+|'''angle'''
+|'''loop value'''
+|----
+|angle &lt; 45 <nowiki>||</nowiki> angle &gt;= 314
+|3
+|----
+|angle &gt;= 45 &amp;&amp; angle &lt; 135
+|0
+|----
+|angle &gt;= 135 &amp;&amp; angle &lt; 225
+|2
+|----
+|angle &gt;= 225 &amp;&amp; angle &lt; 314
+|1
+|----
+|}
+===Kernel function 0x51: CanBeHere(HeapPtr [, DblList])===
+<syntax type="C">kfunct 0x51: CanBeHere();
+HeapPtr obj [, DblList clip_list];</syntax>
+(HeapPtr) obj: The object to test
+(DblList) cliplist: An optional list of objects to test ''obj ''against Returns: (int) 1 if ''obj ''can be where it is, 0 if not.
+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 <m>delim{lbrace}{2^n}|{exists}</m> a pixel with the color value <tt>n</n> inside the control
+{notexists}pic in clip.list(pic::signal&(DONT_RESTORE|IGNORE_ACTOR)) = 0 wedge pic::brRect inter obj::brRect <> theta
+If both conditions are met, 1 is returned. Otherwise, 0 is returned.
+===Kernel function 0x52: OnControKword, Point | Rect)===
+<syntax type="C">kfunct 0x52: OnControl();
+word map, Point|Rect area;</syntax>
+(word) <tt>map</tt>: The map to check (bit 0: visual, bit 1: priority, bit 2: special)
+(Point) or (Rect) Area: The point or rectangle that is to be scanned
+Returns: (word) The resulting bitfield
+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.
+===Kernel function 0x53: InitBresen(HeapPtr [, word])===
+<syntax type="C">kfunct 0x53: InitBresen();
+HeapPtr mover, word step_factor;</syntax>
+(HeapPtr) <tt>mover</tt>: The mover object to initialize
+(word) <tt>step_factor</tt>: A factor to multiply the step size with (defaults to 1)
+Returns: (void)
+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=?>
+        client := mover::client
+        dx := mover::x - client::x
+        dy := mover::y - client::y
+        vxmax := client::xStep * step_factor
+        vymax := client::yStep * step_factor
+        numstepsx := |dx / vxmax|
+        numstepsy := |dy / vymax|
+        IF numstepsx > numstepsy THEN
+                numsteps := numstepsx
+                mover::b_xAxis := 1
+                d0 := dx
+                d1 := dy
+                s := client::yStep
+        ELSE
+                numsteps := numstepsy
+                mover::b_xAxis := 0
+                d1 := dx
+                d0 := dy
+                s := client::xStep
+        FI
+        mover::dx := dx / numsteps
+        mover::dy := dy / numsteps
+        mover::b_di := - |d0|
+        mover::b_i1 := 2 * (|d1| - |s * numsteps|) * |d0|
+        mover::b_incr := d1 / |d1|
+        mover::b_i2 := mover::b_d1 * 2
+</syntax>