Ticket #9028: 0001-convert-SCI-s-engine-comments-to-Doxygen-format-and.patch

File 0001-convert-SCI-s-engine-comments-to-Doxygen-format-and.patch, 53.7 KB (added by SF/lwalkera, 15 years ago)

the patch

  • engines/sci/engine/gc.h 

    From 9dad7c8ab62b82c4134beee5c1af29e37f18ec2f Mon Sep 17 00:00:00 2001
From: Laine Walker-Avina <lwalkera@ieee.org>
Date: Thu, 18 Jun 2009 13:50:24 -0700
Subject: [PATCH] convert SCI's engine comments to Doxygen format and remove one anonymous
 enum

---
 engines/sci/engine/gc.h            |   20 +-
 engines/sci/engine/intmap.h        |    7 +-
 engines/sci/engine/kernel.h        |  179 +++++++------
 engines/sci/engine/seg_manager.cpp |    2 +-
 engines/sci/engine/seg_manager.h   |  267 ++++++++++++--------
 engines/sci/engine/vm.cpp          |    4 +-
 engines/sci/engine/vm.h            |  494 +++++++++++++++++++-----------------
 7 files changed, 547 insertions(+), 426 deletions(-)

diff --git a/engines/sci/engine/gc.h b/engines/sci/engine/gc.h
index e6fa737..9f9347c 100644
    a b struct reg_t_Hash {  
    4545        }
    4646};
    4747
    48 // The reg_t_hash_map is actually really a hashset
     48/*
     49 * The reg_t_hash_map is actually really a hashset
     50 */
    4951typedef Common::HashMap<reg_t, bool, reg_t_Hash, reg_t_EqualTo> reg_t_hash_map;
    5052
     53/**
     54 * Finds all used references and normalises them to their memory addresses
     55 * @param s The state to gather all information from
     56 * @return A hash map containing entries for all used references
     57 */
    5158reg_t_hash_map *find_all_used_references(EngineState *s);
    52 /* Finds all used references and normalises them to their memory addresses
    53 ** Parameters: (EngineState *) s: The state to gather all information from
    54 ** Returns   : (reg_t_hash_map *) A hash map containing entries for all used references
    55 */
    5659
     60/**
     61 * Runs garbage collection on the current system state
     62 * @param s The state in which we should gc
     63 */
    5764void run_gc(EngineState *s);
    58 /* Runs garbage collection on the current system state
    59 ** Parameters: (EngineState *) s: The state in which we should gc
    60 */
    6165
    6266} // End of namespace Sci
    6367

  • engines/sci/engine/intmap.h 

    diff --git a/engines/sci/engine/intmap.h b/engines/sci/engine/intmap.h
index 2cb4f69..1c02897 100644
    a b public:  
    8383
    8484        /**
    8585         * Checks whether a key is in the map, adds it if neccessary.
    86          * @param value         The key to check for/add
     86         * @param key           The key to check for/add
    8787         * @param add           Whether to add the key if it's not in there
    8888         * @param was_added     Set to non-zero if and only if the key is new, ignored if NULL.
    8989         * @return The new (or old) index, or -1 if add was zero and
    … … public:  
    9191         */
    9292        int checkKey(int key, bool add, bool *wasAdded = 0);
    9393
     94        /**
     95         * Looks up a key in the map
     96         * @parmam key The key to look for
     97         * @return The value or -1 if not found
     98         */
    9499        int lookupKey(int key) const;
    95100
    96101

  • engines/sci/engine/kernel.h 

    diff --git a/engines/sci/engine/kernel.h b/engines/sci/engine/kernel.h
index 27d9df0..46913a5 100644
    a b public:  
    6969        uint getKernelNamesSize() const { return _kernelNames.size(); }
    7070        const Common::String &getKernelName(uint number) const { return _kernelNames[number]; }
    7171
    72         /* Determines the selector ID of a selector by its name
    73         **             (const char *) selectorName: Name of the selector to look up
    74         ** Returns   : (int) The appropriate selector ID, or -1 on error
    75         */
     72        /**
     73         * Determines the selector ID of a selector by its name
     74         * @param selectorName Name of the selector to look up
     75         * @return The appropriate selector ID, or -1 on error
     76         */
    7677        int findSelector(const char *selectorName) const;
    7778
    78         /* Detects whether a particular kernel function is required in the game
    79         **             (const char *) functionName: The name of the desired kernel function
    80         ** Returns   : (bool) true if the kernel function is listed in the kernel table,
    81         **                  false otherwise
     79        /**
     80         * Detects whether a particular kernel function is required in the game
     81         * @param functionName The name of the desired kernel function
     82         * @return True if the kernel function is listed in the kernel table, false otherwise
    8283        */
    8384        bool hasKernelFunction(const char *functionName) const;
    8485
    … … private:  
    104105
    105106        /**
    106107        * Loads the kernel selector names.
    107         * Returns true upon success, false otherwise.
     108        * @return True upon success, false otherwise.
    108109        */
    109110        bool loadSelectorNames(bool isOldSci0);
    110111
    111         /* Maps special selectors
    112         ** Returns   : (void)
    113         */
     112        /**
     113         * Maps special selectors
     114         */
    114115        void mapSelectors();
    115116
    116         /* Maps kernel functions
    117         ** Returns   : (void)
    118         */
     117        /**
     118         * Maps kernel functions
     119         */
    119120        void mapFunctions();
    120121
    121122        /**
    … … private:  
    127128        ResourceManager *_resmgr;
    128129
    129130        // Kernel-related lists
    130         // List of opcodes, loaded from vocab.998. This list is only used for debugging
    131         // purposes, as we hardcode the list of opcodes in the sci_opcodes enum (script.h)
     131        /**
     132         * List of opcodes, loaded from vocab.998. This list is only used for debugging
     133         * purposes, as we hardcode the list of opcodes in the sci_opcodes enum (script.h)
     134         */
    132135        Common::Array<opcode> _opcodes;
    133136        Common::StringList _selectorNames;
    134137        Common::StringList _kernelNames;
    … … int invoke_selector(EngineState *s, reg_t object, int selector_id, SelectorInvoc  
    178181
    179182
    180183/******************** Text functionality ********************/
     184/**
     185 * Looks up text referenced by scripts
     186 * SCI uses two values to reference to text: An address, and an index. The address
     187 * determines whether the text should be read from a resource file, or from the heap,
     188 * while the index either refers to the number of the string in the specified source,
     189 * or to a relative position inside the text.
     190 *
     191 * @param s The current state
     192 * @param address The address to look up
     193 * @param index The relative index
     194 * @return The referenced text, or NULL on error.
     195 */
    181196char *kernel_lookup_text(EngineState *s, reg_t address, int index);
    182 /* Looks up text referenced by scripts
    183 ** Parameters: (EngineState *s): The current state
    184 **             (reg_t) address: The address to look up
    185 **             (int) index: The relative index
    186 ** Returns   : (char *): The referenced text, or NULL on error.
    187 ** SCI uses two values to reference to text: An address, and an index. The address
    188 ** determines whether the text should be read from a resource file, or from the heap,
    189 ** while the index either refers to the number of the string in the specified source,
    190 ** or to a relative position inside the text.
    191 */
    192197
    193198
    194199/******************** Debug functionality ********************/
    195 
     200/**
     201 * Checks whether a heap address contains an object
     202 * @param s The current state
     203 * @parm obj The address to check
     204 * @return True if it is an object, false otherwise
     205 */
    196206bool is_object(EngineState *s, reg_t obj);
    197 /* Checks whether a heap address contains an object
    198 ** Parameters: (EngineState *) s: The current state
    199 **             (reg_t) obj: The address to check
    200 ** Returns   : (bool) true if it is an object, false otherwise
    201 */
    202207
    203208/******************** Kernel function parameter macros ********************/
    204209
    205210/* Returns the parameter value or (alt) if not enough parameters were supplied */
    206 
     211/**
     212 * Dereferences a heap pointer
     213 * @param s The state to operate on
     214 * @param pointer The pointer to dereference
     215 * @parm entries The number of values expected (for checking; use 0 for strings)
     216 * @return A physical reference to the address pointed to, or NULL on error or
     217 * if not enugh entries were available.
     218 * reg_t dereferenciation also assures alignedness of data.
     219 */
    207220reg_t *kernel_dereference_reg_pointer(EngineState *s, reg_t pointer, int entries);
    208221byte *kernel_dereference_bulk_pointer(EngineState *s, reg_t pointer, int entries);
    209222#define kernel_dereference_char_pointer(state, pointer, entries) (char*)kernel_dereference_bulk_pointer(state, pointer, entries)
    210 /* Dereferences a heap pointer
    211 ** Parameters: (EngineState *) s: The state to operate on
    212 **             (reg_t ) pointer: The pointer to dereference
    213 **             (int) entries: The number of values expected (for checking)
    214 **                            (use 0 for strings)
    215 ** Returns   : (reg_t/char *): A physical reference to the address pointed
    216 **                        to, or NULL on error or if not enugh entries
    217 **                        were available
    218 ** reg_t dereferenciation also assures alignedness of data.
    219 */
    220223
    221224/******************** Priority macros/functions ********************/
    222 
     225/**
     226 * Finds the position of the priority band specified
     227 * Parameters: (EngineState *) s: State to search in
     228 * (int) band: Band to look for
     229 * Returns   : (int) Offset at which the band starts
     230 */
    223231int _find_priority_band(EngineState *s, int band);
    224 /* Finds the position of the priority band specified
    225 ** Parameters: (EngineState *) s: State to search in
    226 **             (int) band: Band to look for
    227 ** Returns   : (int) Offset at which the band starts
    228 */
    229232
     233/**
     234 * Does the opposite of _find_priority_band
     235 * @param s Engine state
     236 * @param y Coordinate to check
     237 * @return The priority band y belongs to
     238 */
    230239int _find_view_priority(EngineState *s, int y);
    231 /* Does the opposite of _find_priority_band
    232 ** Parameters: (EngineState *) s: State
    233 **             (int) y: Coordinate to check
    234 ** Returns   : (int) The priority band y belongs to
    235 */
    236240
    237241#define SCI0_VIEW_PRIORITY_14_ZONES(y) (((y) < s->priority_first)? 0 : (((y) >= s->priority_last)? 14 : 1\
    238242        + ((((y) - s->priority_first) * 14) / (s->priority_last - s->priority_first))))
    … … int _find_view_priority(EngineState *s, int y);  
    249253
    250254
    251255/******************** Dynamic view list functions ********************/
    252 
     256/**
     257 * Determines the base rectangle of the specified view object
     258 * @param s The state to use
     259 * @param object The object to set
     260 * @return The absolute base rectangle
     261 */
    253262Common::Rect set_base(EngineState *s, reg_t object);
    254 /* Determines the base rectangle of the specified view object
    255 ** Parameters: (EngineState *) s: The state to use
    256 **             (reg_t) object: The object to set
    257 ** Returns   : (abs_rect) The absolute base rectangle
    258 */
    259263
     264/**
     265 * Determines the now-seen rectangle of a view object
     266 * @param s The state to use
     267 * @param object The object to check
     268 * @param clip Flag to determine wheter priority band clipping
     269 * should be performed
     270 * @return The absolute rectangle describing the now-seen area.
     271 */
    260272extern Common::Rect get_nsrect(EngineState *s, reg_t object, byte clip);
    261 /* Determines the now-seen rectangle of a view object
    262 ** Parameters: (EngineState *) s: The state to use
    263 **             (reg_t) object: The object to check
    264 **             (byte) clip: Flag to determine wheter priority band
    265 **                          clipping should be performed
    266 ** Returns   : (abs_rect) The absolute rectangle describing the
    267 ** now-seen area.
    268 */
    269273
     274/**
     275 * Removes all views in anticipation of a new window or text
     276 */
    270277void _k_dyn_view_list_prepare_change(EngineState *s);
    271 /* Removes all views in anticipation of a new window or text */
     278
     279/**
     280 * Redraws all views after a new window or text was added
     281 */
    272282void _k_dyn_view_list_accept_change(EngineState *s);
    273 /* Redraws all views after a new window or text was added */
    274283
    275284
    276285
    277286
    278287/******************** Misc functions ********************/
    279288
    280 void process_sound_events(EngineState *s); /* Get all sound events, apply their changes to the heap */
     289/**
     290 * Get all sound events, apply their changes to the heap
     291 */
     292void process_sound_events(EngineState *s);
    281293
     294/**
     295 * Resolves an address into a list node
     296 * @param s The state to operate on
     297 * @param addr The address to resolve
     298 * @return The list node referenced, or NULL on error
     299 */
    282300Node *lookup_node(EngineState *s, reg_t addr);
    283 /* Resolves an address into a list node
    284 ** Parameters: (EngineState *) s: The state to operate on
    285 **             (reg_t) addr: The address to resolve
    286 ** Returns   : (Node *) The list node referenced, or NULL on error
    287 */
    288 
    289301
     302/**
     303 * Resolves a list pointer to a list
     304 * @param s The state to operate on
     305 * @param addr The address to resolve
     306 * @return The list referenced, or NULL on error
     307 */
    290308List *lookup_list(EngineState *s, reg_t addr);
    291 /* Resolves a list pointer to a list
    292 ** Parameters: (EngineState *) s: The state to operate on
    293 **             (reg_t) addr: The address to resolve
    294 ** Returns   : (List *) The list referenced, or NULL on error
    295 */
    296309
    297310
    298311/******************** Constants ********************/

  • engines/sci/engine/seg_manager.cpp 

    diff --git a/engines/sci/engine/seg_manager.cpp b/engines/sci/engine/seg_manager.cpp
index 98fbd8b..2227167 100644
    a b void SegManager::heapRelocate(reg_t block) {  
    430430
    431431#define INST_LOOKUP_CLASS(id) ((id == 0xffff) ? NULL_REG : get_class_address(s, id, SCRIPT_GET_LOCK, NULL_REG))
    432432
    433 reg_t get_class_address(EngineState *s, int classnr, int lock, reg_t caller);
     433reg_t get_class_address(EngineState *s, int classnr, SCRIPT_GET lock, reg_t caller);
    434434
    435435Object *SegManager::scriptObjInit0(EngineState *s, reg_t obj_pos) {
    436436        Object *obj;

  • engines/sci/engine/seg_manager.h 

    diff --git a/engines/sci/engine/seg_manager.h b/engines/sci/engine/seg_manager.h
index dc91d60..a41d820 100644
    a b namespace Sci {  
    4545
    4646class SegManager : public Common::Serializable {
    4747public:
    48         // Initialize the segment manager
     48        /**
     49         * Initialize the segment manager
     50         */
    4951        SegManager(bool sci1_1);
    5052
    51         // Deallocate all memory associated with the segment manager
     53        /**
     54         * Deallocate all memory associated with the segment manager
     55         */
    5256        ~SegManager();
    5357
    5458        virtual void saveLoadWithSerializer(Common::Serializer &ser);
    5559
    5660        // 1. Scripts
    5761
    58         // Allocate a script into the segment manager
    59         // Parameters: (int) script_nr: number of the script to load
    60         //             (state_t *) s: The state containing resource manager handlers to load the
    61         //                            script data
    62         // Returns   : (int) 0 on failure, 1 on success
    63         //             (int) *seg_id: The segment ID of the newly allocated segment, on success
     62        /**
     63         * Allocate a script into the segment manager
     64         * @param s                             The state containing resource manager
     65         *                                              handlers to load the script data
     66         * @param script_nr             The number of the script to load
     67         * @param seg_id                The segment ID of the newly allocated segment,
     68         *                                              on success
     69         * @return                              0 on failure, 1 on success
     70         */
    6471        Script *allocateScript(EngineState *s, int script_nr, SegmentId *seg_id);
    6572
    6673        // The script must then be initialised; see section (1b.), below.
    6774
    68         // Forcefully deallocate a previously allocated script
    69         // Parameters: (int) script_nr: number of the script to deallocate
    70         // Returns   : (int) 1 on success, 0 on failure
     75        /**
     76         * Forcefully deallocate a previously allocated script
     77         * @param script_nr             number of the script to deallocate
     78         * @return                              1 on success, 0 on failure
     79         */
    7180        int deallocateScript(int script_nr);
    7281
    7382        /**
    … … public:  
    7685         */
    7786        bool scriptIsLoaded(SegmentId seg);
    7887
    79         // Validate whether the specified public function is exported by the script in the specified segment
    80         // Parameters:  (int) pubfunct: Index of the function to validate
    81         //              (int) seg: Segment ID of the script the check is to be performed for
    82         // Returns   :  (uint16) 0 if the public function is invalid, its offset into the script's segment
    83         //                       otherwise
     88        /**
     89         * Validate whether the specified public function is exported by
     90         * the script in the specified segment
     91         * @param pubfunct              Index of the function to validate
     92         * @param seg                   Segment ID of the script the check is to
     93         *                                              be performed for
     94         * @return                              NULL if the public function is invalid, its
     95         *                                              offset into the script's segment otherwise
     96         */
    8497        uint16 validateExportFunc(int pubfunct, SegmentId seg);
    8598
    86         // Get the segment ID associated with a script number
    87         // Parameters: (int) script_nr: Number of the script to look up
    88         // Returns   : (int) The associated segment ID, or -1 if no matching segment exists
     99        /**
     100         * Get the segment ID associated with a script number
     101         * @param script_nr             Number of the script to look up
     102         * @return                              The associated segment ID, or -1 if no
     103         *                                              matching segment exists
     104         */
    89105        SegmentId segGet(int script_nr) const;
    90106
    91107        /**
    92          * Return a pointer to the specified script. If the id is invalid, does not refer
    93          * to a script or the script is not loaded, this will invoke error().
     108         * Return a pointer to the specified script.
     109         * If the id is invalid, does not refer to a script or the script is
     110         * not loaded, this will invoke error().
    94111         * @param seg   ID of the script segment to check for
    95          * @return pointer to the Script object
     112         * @return              A pointer to the Script object
    96113         */
    97114        Script *getScript(SegmentId seg);
    98115
    99116        /**
    100          * Return a pointer to the specified script. If the id is invalid, does not refer
     117         * Return a pointer to the specified script.
     118         * If the id is invalid, does not refer to a script, or
     119         * the script is not loaded, this will return NULL
    101120         * @param seg   ID of the script segment to check for
    102          * @return pointer to the Script object, or NULL
     121         * @return              A pointer to the Script object, or NULL
    103122         */
    104123        Script *getScriptIfLoaded(SegmentId seg);
    105124
    … … public:  
    112131        // to be used during script instantiation,
    113132        // i.e. loading and linking.
    114133
    115         // Initializes a script's local variable block
    116         // Parameters: (SegmentId) seg: Segment containing the script to initialize
    117         //             (int) nr: Number of local variables to allocate
    118         // All variables are initialized to zero.
     134        /**
     135         * Initializes a script's local variable block
     136         * All variables are initialized to zero.
     137         * @param seg   Segment containing the script to initialize
     138         * @param nr    Number of local variables to allocate
     139         */
    119140        void scriptInitialiseLocalsZero(SegmentId seg, int nr);
    120141
    121         // Initializes a script's local variable block according to a prototype
    122         // Parameters: (reg_t) location: Location to initialize from
     142        /**
     143         * Initializes a script's local variable block according to a prototype
     144         * @param location      Location to initialize from
     145         */
    123146        void scriptInitialiseLocals(reg_t location);
    124147
    125         // Initializes an object within the segment manager
    126         // Parameters: (reg_t) obj_pos: Location (segment, offset) of the object
    127         // Returns   : (Object *) A newly created Object describing the object
    128         // obj_pos must point to the beginning of the script/class block (as opposed
    129         // to what the VM considers to be the object location)
    130         // The corresponding Object is stored within the relevant script.
     148        /**
     149         * Initializes an object within the segment manager
     150         * @param obj_pos       Location (segment, offset) of the object. It must
     151         *                                      point to the beginning of the script/class block
     152         *                                      (as opposed to what the VM considers to be the
     153         *                                      object location)
     154         * @returns                     A newly created Object describing the object,
     155         *                                      stored within the relevant script
     156         */
    131157        Object *scriptObjInit(EngineState *s, reg_t obj_pos);
    132158
    133         // Informs the segment manager that a code block must be relocated
    134         // Parameters: (reg_t) location: Start of block to relocate
     159        /**
     160         * Informs the segment manager that a code block must be relocated
     161         * @param location      Start of block to relocate
     162         */
    135163        void scriptAddCodeBlock(reg_t location);
    136164
    137         // Tells the segment manager whether exports are wide (32-bit) or not.
    138         // Parameters: (int) flag: 1 if exports are wide, 0 otherwise
     165        /**
     166         * Tells the segment manager whether exports are wide (32-bit) or not.
     167         * @param flag  1 if exports are wide, 0 otherwise
     168         */
    139169        void setExportWidth(int flag);
    140170
    141         // Processes a relocation block witin a script
    142         // Parameters: (reg_t) obj_pos: Location (segment, offset) of the block
    143         // Returns   : (Object *) Location of the relocation block
    144         // This function is idempotent, but it must only be called after all
    145         // objects have been instantiated, or a run-time error will occur.
     171        /**
     172         * Processes a relocation block witin a script
     173         *  This function is idempotent, but it must only be called after all
     174         *  objects have been instantiated, or a run-time error will occur.
     175         * @param obj_pos       Location (segment, offset) of the block
     176         * @return                      Location of the relocation block
     177         */
    146178        void scriptRelocate(reg_t block);
    147179
    148         // Determines whether the script referenced by the indicated segment is marked as being deleted.
    149         // Parameters: (SegmentId) Segment ID of the script to investigate
    150         // Returns   : (int) 1 iff seg points to a script and the segment is deleted, 0 otherwise
    151         // Will return 0 when applied to an invalid or non-script seg.
     180        /**
     181         * Determines whether the script referenced by the indicated segment
     182         * is marked as being deleted.
     183         * Will return 0 when applied to an invalid or non-script seg.
     184         * @param seg   Segment ID of the script to investigate
     185         * @return              1 iff seg points to a script and the segment is
     186         *                              deleted, 0 otherwise
     187         */
    152188        bool scriptIsMarkedAsDeleted(SegmentId seg);
    153189
    154190
    155191        // 2. Clones
    156192
    157         // Allocate a fresh clone
    158         // Returns : (Clone*): Reference to the memory allocated for the clone
    159         //           (reg_t) *addr: The offset of the freshly allocated clone
     193        /**
     194         * Allocate a fresh clone
     195         * @param addr The offset of the freshly allocated clone
     196         * @return      Reference to the memory allocated for the clone
     197         */
    160198        Clone *alloc_Clone(reg_t *addr);
    161199
    162200
    … … public:  
    166204
    167205        // 4. Stack
    168206
    169         // Allocates a data stack
    170         // Parameters: (int) size: Number of stack entries to reserve
    171         // Returns   : (DataStack *): The physical stack
    172         //             (SegmentId) segid: Segment ID of the stack
     207        /**
     208         * Allocates a data stack
     209         * @param size  Number of stack entries to reserve
     210         * @param segid Segment ID of the stack
     211         * @return              The physical stack
     212         */
    173213        DataStack *allocateStack(int size, SegmentId *segid);
    174214
    175215
    176216        // 5. System Strings
    177217
    178         // Allocates a system string table
    179         // Returns   : (DataStack *): The physical stack
    180         //             (SegmentId) segid: Segment ID of the stack
    181         // See also sys_string_acquire();
     218        /**
     219         * Allocates a system string table
     220         * See also sys_string_acquire();
     221         * @param[in] segid     Segment ID of the stack
     222         * @returns                     The physical stack
     223         */           
    182224        SystemStrings *allocateSysStrings(SegmentId *segid);
    183225
    184226
    185227        // 5. System Strings
    186228
    187         // Allocates a string fragments segment
    188         // Returns   : (SegmentId): Segment ID to use for string fragments
    189         // See also stringfrag.h
     229        /**
     230         * Allocates a string fragments segment
     231         * See also stringfrag.h
     232         * @return      Segment ID to use for string fragments
     233         */
    190234        SegmentId allocateStringFrags();
    191235
    192236
    193237        // 6, 7. Lists and Nodes
    194238
    195         // Allocate a fresh list
    196         // Returns : (listY_t*): Reference to the memory allocated for the list
    197         //           (reg_t) *addr: The offset of the freshly allocated list
     239        /**
     240         * Allocate a fresh list
     241         * @param[in] addr      The offset of the freshly allocated list
     242         * @return                      Reference to the memory allocated for the list
     243         */
    198244        List *alloc_List(reg_t *addr);
    199245
    200         // Allocate a fresh node
    201         // Returns : (node_t*): Reference to the memory allocated for the node
    202         //           (reg_t) *addr: The offset of the freshly allocated node
     246        /**
     247         * Allocate a fresh node
     248         * @param[in] addr      The offset of the freshly allocated node
     249         * @return                      Reference to the memory allocated for the node
     250         */
    203251        Node *alloc_Node(reg_t *addr);
    204252
    205253
    206254        // 8. Hunk Memory
    207255
    208         // Allocate a fresh chunk of the hunk
    209         // Parameters: (int) size: Number of bytes to allocate for the hunk entry
    210         //             (const char *) hunk_type: A descriptive string for the hunk entry,
    211         //                              for debugging purposes
    212         // Returns   : (Hunk *): Reference to the memory allocated for the hunk piece
    213         //             (reg_t) *addr: The offset of the freshly allocated hunk entry
     256        /**
     257         * Allocate a fresh chunk of the hunk
     258         * @param[in] size              Number of bytes to allocate for the hunk entry
     259         * @param[in] hunk_type A descriptive string for the hunk entry, for
     260         *                                              debugging purposes
     261         * @param[out] addr             The offset of the freshly allocated hunk entry
     262         * @return                              Reference to the memory allocated for the hunk
     263         *                                              piece
     264         */
    214265        Hunk *alloc_hunk_entry(const char *hunk_type, int size, reg_t *addr);
    215266
    216         // Deallocates a hunk entry
    217         // Parameters: (reg_t) addr: Offset of the hunk entry to delete
     267        /**
     268         * Deallocates a hunk entry
     269         * @param[in] addr      Offset of the hunk entry to delete
     270         */
    218271        void free_hunk_entry(reg_t addr);
    219272
    220273
    221274        // 9. Dynamic Memory
    222275
    223         // Allocate some dynamic memory
    224         // Parameters: (int) size: Number of bytes to allocate
    225         //             (const char_ *) description: A descriptive string,
    226         //                              for debugging purposes
    227         // Returns   : (unsigned char*): Raw pointer into the allocated dynamic memory
    228         //             (reg_t) *addr: The offset of the freshly allocated X
     276        /**
     277         * Allocate some dynamic memory
     278         * @param[in]  size                     Number of bytes to allocate
     279         * @param[in]  description      A descriptive string for debugging purposes
     280         * @param[out] addr                     The offset of the freshly allocated X
     281         * @return                                      Raw pointer into the allocated dynamic
     282         *                                                      memory
     283         */
    229284        unsigned char *allocDynmem(int size, const char *description, reg_t *addr);
    230285
    231         // Deallocates a piece of dynamic memory
    232         // Parameters: (reg_t) addr: Offset of the dynmem chunk to free
     286        /**
     287         * Deallocates a piece of dynamic memory
     288         * @param[in] addr      Offset of the dynmem chunk to free
     289         */
    233290        int freeDynmem(reg_t addr);
    234291
    235         // Gets the description of a dynmem segment
    236         // Parameters: (reg_t) addr: Segment to describe
    237         // Returns   : (const char *): Pointer to the descriptive string set in
    238         // allocDynmem
     292        /**
     293         * Gets the description of a dynmem segment
     294         * @param[in] addr      Segment to describe
     295         * @return                      Pointer to the descriptive string set in allocDynmem
     296         */
    239297        const char *getDescription(reg_t addr);
    240298
    241299
    … … public:  
    251309
    252310        // Generic Operations on Segments and Addresses
    253311
    254         // Dereferences a raw memory pointer
    255         // Parameters: (reg_t) reg: The reference to dereference
    256         // Returns   : (byte *) The data block referenced
    257         //             (int) size: (optionally) the theoretical maximum size of it
     312        /**
     313         * Dereferences a raw memory pointer
     314         * @param[in]  reg      The reference to dereference
     315         * @param[out] size     (optional) The theoretical maximum size
     316         * @return                      The data block referenced
     317         */
    258318        byte *dereference(reg_t reg, int *size);
    259319
    260320
    … … public:  
    266326        int initialiseScript(Script &scr, EngineState *s, int script_nr);
    267327
    268328private:
    269         IntMapper *id_seg_map; // id - script id; seg - index of heap
     329        IntMapper *id_seg_map; ///< id - script id; seg - index of heap
    270330public: // TODO: make private
    271331        Common::Array<MemObject *> _heap;
    272332        int reserved_id;
    273333        int exports_wide;
    274334        bool isSci1_1;
    275335
    276         SegmentId Clones_seg_id; // ID of the (a) clones segment
    277         SegmentId Lists_seg_id; // ID of the (a) list segment
    278         SegmentId Nodes_seg_id; // ID of the (a) node segment
    279         SegmentId Hunks_seg_id; // ID of the (a) hunk segment
     336        SegmentId Clones_seg_id; ///< ID of the (a) clones segment
     337        SegmentId Lists_seg_id; ///< ID of the (a) list segment
     338        SegmentId Nodes_seg_id; ///< ID of the (a) node segment
     339        SegmentId Hunks_seg_id; ///< ID of the (a) hunk segment
    280340
    281341private:
    282342        MemObject *allocNonscriptSegment(MemObjectType type, SegmentId *segid);
    … … private:  
    295355        Object *scriptObjInit0(EngineState *s, reg_t obj_pos);
    296356        Object *scriptObjInit11(EngineState *s, reg_t obj_pos);
    297357
    298         /* Check segment validity
    299         ** Parameters: (int) seg: The segment to validate
    300         ** Returns   : (bool)   false if 'seg' is an invalid segment
    301         **                      true  if 'seg' is a valid segment
    302         */
     358        /**
     359         * Check segment validity
     360         * @param[in] seg       The segment to validate
     361         * @return                      false if 'seg' is an invalid segment, true if
     362         *                                      'seg' is a valid segment
     363         */
    303364        bool check(SegmentId seg);
    304365
    305366        void dbgPrint(const char* msg, void *i);        // for debug only

  • engines/sci/engine/vm.cpp 

    diff --git a/engines/sci/engine/vm.cpp b/engines/sci/engine/vm.cpp
index 0b84c0e..cbd0b0c 100644
    a b int script_error(EngineState *s, const char *file, int line, const char *reason)  
    193193}
    194194#define CORE_ERROR(area, msg) script_error(s, "[" area "] " __FILE__, __LINE__, msg)
    195195
    196 reg_t get_class_address(EngineState *s, int classnr, int lock, reg_t caller) {
     196reg_t get_class_address(EngineState *s, int classnr, SCRIPT_GET lock, reg_t caller) {
    197197
    198198        if (NULL == s) {
    199199                warning("vm.c: get_class_address(): NULL passed for \"s\"");
    … … SelectorType lookup_selector(EngineState *s, reg_t obj_location, Selector select  
    15501550        return _lookup_selector_function(s, obj_location.segment, obj, selector_id, fptr);
    15511551}
    15521552
    1553 SegmentId script_get_segment(EngineState *s, int script_nr, int load) {
     1553SegmentId script_get_segment(EngineState *s, int script_nr, SCRIPT_GET load) {
    15541554        SegmentId segment;
    15551555
    15561556        if ((load & SCRIPT_GET_LOAD) == SCRIPT_GET_LOAD)

  • engines/sci/engine/vm.h 

    diff --git a/engines/sci/engine/vm.h b/engines/sci/engine/vm.h
index dfbbc39..379719a 100644
    a b struct Breakpoint {  
    287287};
    288288
    289289/**
    290  * Set this to 1 to abort script execution immediately. Aborting will leave the
    291  * debug exec stack intact.
     290 * Set this to 1 to abort script execution immediately. Aborting will
     291 * leave the debug exec stack intact.
    292292 * Set it to 2 to force a replay afterwards.
    293293 */
    294294extern int script_abort_flag;
    … … extern int script_step_counter;  
    307307
    308308/**
    309309 * Executes function pubfunct of the specified script.
    310  * Parameters: (EngineState *) s: The state which is to be executed with
    311  *             (uint16) script: The script which is called
    312  *             (uint16) pubfunct: The exported script function which is to be called
    313  *             (StackPtr) sp: Stack pointer position
    314  *             (reg_t) calling_obj: The heap address of the object which executed the call
    315  *             (uint16) argc: Number of arguments supplied
    316  *             (StackPtr) argp: Pointer to the first supplied argument
    317  * Returns   : (ExecStack *): A pointer to the new exec stack TOS entry
     310 * @param[in] s                         The state which is to be executed with
     311 * @param[in] script            The script which is called
     312 * @param[in] pubfunct          The exported script function which is to
     313 *                                                      be called
     314 * @param[in] sp                        Stack pointer position
     315 * @param[in] calling_obj       The heap address of the object that
     316 *                                                      executed the call
     317 * @param[in] argc                      Number of arguments supplied
     318 * @param[in] argp                      Pointer to the first supplied argument
     319 * @return                                      A pointer to the new exec stack TOS entry
    318320 */
    319 ExecStack *execute_method(EngineState *s, uint16 script, uint16 pubfunct, StackPtr sp, reg_t calling_obj,
    320         uint16 argc, StackPtr argp);
     321ExecStack *execute_method(EngineState *s, uint16 script, uint16 pubfunct,
     322                StackPtr sp, reg_t calling_obj, uint16 argc, StackPtr argp);
    321323
    322324
    323325/**
    324326 * Executes a "send" or related operation to a selector.
    325  * Parameters: (EngineState *) s: The EngineState to operate on
    326  *             (reg_t) send_obj: Heap address of the object to send to
    327  *             (reg_t) work_obj: Heap address of the object initiating the send
    328  *             (StackPtr) sp: Stack pointer position
    329  *             (int) framesize: Size of the send as determined by the "send" operation
    330  *             (StackPtr) argp: Pointer to the beginning of the heap block containing the
    331  *                              data to be sent. This area is a succession of one or more
    332  *                              sequences of [selector_number][argument_counter] and then
    333  *                              "argument_counter" word entries with the parameter values.
    334  * Returns   : (ExecStack *): A pointer to the new execution stack TOS entry
     327 * @param[in] s                 The EngineState to operate on
     328 * @param[in] send_obj  Heap address of the object to send to
     329 * @param[in] work_obj  Heap address of the object initiating the send
     330 * @param[in] sp                Stack pointer position
     331 * @param[in] framesize Size of the send as determined by the "send"
     332 *                                              operation
     333 * @param[in] argp              Pointer to the beginning of the heap block
     334 *                                              containing the data to be sent. This area is a
     335 *                                              succession of one or more sequences of
     336 *                                              [selector_number][argument_counter] and then
     337 *                                              "argument_counter" word entries with the
     338 *                                              parameter values.
     339 * @return                              A pointer to the new execution stack TOS entry
    335340 */
    336341ExecStack *send_selector(EngineState *s, reg_t send_obj, reg_t work_obj,
    337342        StackPtr sp, int framesize, StackPtr argp);
    … … ExecStack *send_selector(EngineState *s, reg_t send_obj, reg_t work_obj,  
    342347/**
    343348 * Adds an entry to the top of the execution stack.
    344349 *
    345  * @param s                             The state with which to execute
    346  * @param pc                    The initial program counter
    347  * @param sp                    The initial stack pointer
    348  * @param objp                  Pointer to the beginning of the current object
    349  * @param argc                  Number of parameters to call with
    350  * @param argp                  Heap pointer to the first parameter
    351  * @param selector              The selector by which it was called or
    352  *                                              NULL_SELECTOR if n.a. For debugging.
    353  * @param sendp                 Pointer to the object which the message was sent to.
    354  *                                              Equal to objp for anything but super.
    355  * @param origin                Number of the execution stack element this entry was created by
    356  *                                              (usually the current TOS number, except for multiple sends).
    357  * @param local_segment The segment to use for local variables,
    358  *                                              or SCI_XS_CALLEE_LOCALS to use obj's segment.
    359  * @return a pointer to the new exec stack TOS entry
    360  */
    361 ExecStack *add_exec_stack_entry(EngineState *s, reg_t pc, StackPtr sp, reg_t objp, int argc,
    362         StackPtr argp, Selector selector, reg_t sendp, int origin, SegmentId local_segment);
     350 * @param[in] s                         The state with which to execute
     351 * @param[in] pc                        The initial program counter
     352 * @param[in] sp                        The initial stack pointer
     353 * @param[in] objp                      Pointer to the beginning of the current object
     354 * @param[in] argc                      Number of parameters to call with
     355 * @param[in] argp                      Heap pointer to the first parameter
     356 * @param[in] selector          The selector by which it was called or
     357 *                                                      NULL_SELECTOR if n.a. For debugging.
     358 * @param[in] sendp                     Pointer to the object which the message was
     359 *                                                      sent to. Equal to objp for anything but super.
     360 * @param[in] origin            Number of the execution stack element this
     361 *                                                      entry was created by (usually the current TOS
     362 *                                                      number, except for multiple sends).
     363 * @param[in] local_segment     The segment to use for local variables,
     364 *                                                      or SCI_XS_CALLEE_LOCALS to use obj's segment.
     365 * @return                                      A pointer to the new exec stack TOS entry
     366 */
     367ExecStack *add_exec_stack_entry(EngineState *s, reg_t pc, StackPtr sp,
     368                reg_t objp, int argc, StackPtr argp, Selector selector,
     369                reg_t sendp, int origin, SegmentId local_segment);
    363370
    364371
    365372/**
    366373 * Adds one varselector access to the execution stack.
    367  * Parameters: (EngineState *) s: The EngineState to use
    368  *             (reg_t) objp: Pointer to the object owning the selector
    369  *             (int) argc: 1 for writing, 0 for reading
    370  *             (StackPtr) argp: Pointer to the address of the data to write -2
    371  *             (int) selector: Selector name
    372  *             (ObjVarRef& ) address: Heap address of the selector
    373  *             (int) origin: Stack frame which the access originated from
    374  * Returns   : (ExecStack *): Pointer to the new exec-TOS element
    375374 * This function is called from send_selector only.
     375 * @param[in] s                 The EngineState to use
     376 * @param[in] objp              Pointer to the object owning the selector
     377 * @param[in] argc              1 for writing, 0 for reading
     378 * @param[in] argp              Pointer to the address of the data to write -2
     379 * @param[in] selector  Selector name
     380 * @param[in] address   Heap address of the selector
     381 * @param[in] origin    Stack frame which the access originated from
     382 * @return                              Pointer to the new exec-TOS element
    376383 */
    377 ExecStack *add_exec_stack_varselector(EngineState *s, reg_t objp, int argc, StackPtr argp,
    378         Selector selector, const ObjVarRef& address, int origin);
    379 
     384ExecStack *add_exec_stack_varselector(EngineState *s, reg_t objp, int argc,
     385                StackPtr argp, Selector selector, const ObjVarRef& address,
     386                int origin);
    380387
     388/**
     389 * This function executes SCI bytecode
     390 * It executes the code on s->heap[pc] until it hits a 'ret' operation
     391 * while (stack_base == stack_pos). Requires s to be set up correctly.
     392 * @param[in] s                 The state to use
     393 * @param[in] restoring 1 if s has just been restored, 0 otherwise
     394 */
    381395void run_vm(EngineState *s, int restoring);
    382 /* Executes the code on s->heap[pc] until it hits a 'ret' operation while (stack_base == stack_pos)
    383 ** Parameters: (EngineState *) s: The state to use
    384 **             (int) restoring: 1 if s has just been restored, 0 otherwise
    385 ** Returns   : (void)
    386 ** This function will execute SCI bytecode. It requires s to be set up
    387 ** correctly.
    388 */
    389396
     397/**
     398 * Handles a fatal error condition
     399 * @param[in] s         The state to recover from
     400 * @param[in] line      Source code line number the error occured in
     401 * @param[in] file      File the error occured in
     402 */
    390403void vm_handle_fatal_error(EngineState *s, int line, const char *file);
    391 /* Handles a fatal error condition
    392 ** Parameters: (EngineState *) s: The state to recover from
    393 **             (int) line: Source code line number the error occured in
    394 **             (const char *) file: File the error occured in
    395 */
    396 
    397 
    398 void script_debug(EngineState *s, reg_t *pc, StackPtr *sp, StackPtr *pp, reg_t *objp,
    399         int *restadjust, SegmentId *segids, reg_t **variables, reg_t **variables_base,
    400         int *variables_nr, int bp);
    401 /* Debugger functionality
    402 ** Parameters: (EngineState *) s: The state at which debugging should take place
    403 **             (reg_t *) pc: Pointer to the program counter
    404 **             (StackPtr *) sp: Pointer to the stack pointer
    405 **             (StackPtr *) pp: Pointer to the frame pointer
    406 **             (reg_t *) objp: Pointer to the object base pointer
    407 **             (int *) restadjust: Pointer to the &rest adjustment value
    408 **             (SegmentId *) segids: four-element array containing segment IDs for locals etc.
    409 **             (reg_t **) variables: four-element array referencing registers for globals etc.
    410 **             (reg_t **) variables_base: four-element array referencing
    411 **                                        register bases for temps etc.
    412 **             (int *) variables_nr: four-element array giving sizes for params etc. (may be NULL)
    413 **             (int) bp: Flag, set to 1 when a breakpoint is triggered
    414 ** Returns   : (void)
    415 */
    416404
     405
     406/**
     407 * Debugger functionality
     408 * @param[in] s                                 The state at which debugging should take
     409 *                                                              place
     410 * @param[in] pc                                Pointer to the program counter
     411 * @param[in] sp                                Pointer to the stack pointer
     412 * @param[in] pp                                Pointer to the frame pointer
     413 * @param[in] objp                              Pointer to the object base pointer
     414 * @param[in] restadjust                Pointer to the &rest adjustment value
     415 * @param[in] segids                    four-element array containing segment IDs
     416 *                                                              for locals etc.
     417 * @param[in] variables                 four-element array referencing registers
     418 *                                                              for globals etc.
     419 * @param[in] variables_base    four-element array referencing register
     420 *                                                              bases for temps etc.
     421 * @param[in] variables_nr              four-element array giving sizes for params
     422 *                                                              etc. (may be NULL)
     423 * @param[in] bp                                Flag, set to 1 when a breakpoint is
     424 *                                                              triggered
     425 */
     426void script_debug(EngineState *s, reg_t *pc, StackPtr *sp, StackPtr *pp,
     427                reg_t *objp, int *restadjust, SegmentId *segids, reg_t **variables,
     428                reg_t **variables_base, int *variables_nr, int bp);
     429
     430/**
     431 * Initializes a EngineState block
     432 * @param[in] s The state to initialize
     433 * @return              0 on success, 1 if vocab.996 (the class table) is missing
     434 *                              or corrupted
     435 */
    417436int script_init_engine(EngineState *s);
    418 /* Initializes a EngineState block
    419 ** Parameters: (EngineState *) s: The state to initialize
    420 ** Returns   : 0 on success, 1 if vocab.996 (the class table) is missing or corrupted
    421 */
    422437
     438/**
     439 * Sets the gamestate's save_dir to the parameter path
     440 * @param[in] s         The state to set
     441 * @param[in] path      Path where save_dir will point to
     442 */
    423443void script_set_gamestate_save_dir(EngineState *s, const char *path);
    424 /* Sets the gamestate's save_dir to the parameter path
    425 ** Parameters: (EngineState *) s: The state to set
    426 **             (const char *) path: Path where save_dir will point to
    427 ** Returns   : (void)
    428 */
    429444
     445/**
     446 * Frees all additional memory associated with a EngineState block
     447 * @param[in] s The EngineState whose elements should be cleared
     448 */
    430449void script_free_engine(EngineState *s);
    431 /* Frees all additional memory associated with a EngineState block
    432 ** Parameters: (EngineState *) s: The EngineState whose elements should be cleared
    433 ** Returns   : (void)
    434 */
    435450
     451/**
     452 * Frees all script memory (heap, hunk, and class tables).
     453 * This operation is implicit in script_free_engine(), but is required for
     454 * restoring the game state.
     455 * @param[in] s The EngineState to free
     456 */
    436457void script_free_vm_memory(EngineState *s);
    437 /* Frees all script memory (heap, hunk, and class tables).
    438 ** Parameters: (EngineState *) s: The EngineState to free
    439 ** Returns   : (void)
    440 ** This operation is implicit in script_free_engine(), but is required for restoring
    441 ** the game state.
    442 */
    443 
    444 
    445 SelectorType lookup_selector(EngineState *s, reg_t obj, Selector selectorid, ObjVarRef *varp, reg_t *fptr);
    446 /* Looks up a selector and returns its type and value
    447 ** Parameters: (EngineState *) s: The EngineState to use
    448 **             (reg_t) obj: Address of the object to look the selector up in
    449 **             (Selector) selectorid: The selector to look up
    450 ** Returns   : (SelectorType) kSelectorNone if the selector was not found in the object or its superclasses.
    451 **                            kSelectorVariable if the selector represents an object-relative variable
    452 **                            kSelectorMethod if the selector represents a method
    453 **             (ObjVarRef *) *varp: A reference to the selector, if
    454 **                              it is a variable
    455 **             (reg_t) *fptr: A reference to the function described by that selector, if it is
    456 **                            a valid function selector.
    457 ** *varindex is written to iff it is non-NULL and the selector indicates a property of the object.
    458 ** *fptr is written to iff it is non-NULL and the selector indicates a member function of that object.
    459 */
    460458
    461 enum {
     459/**
     460 * Looks up a selector and returns its type and value
     461 * varindex is written to iff it is non-NULL and the selector indicates a property of the object.
     462 * @param[in] s                         The EngineState to use
     463 * @param[in] obj                       Address of the object to look the selector up in
     464 * @param[in] selectorid        The selector to look up
     465 * @param[out] varp                     A reference to the selector, if it is a
     466 *                                                      variable.
     467 * @param[out] fptr                     A reference to the function described by that
     468 *                                                      selector, if it is a valid function selector.
     469 *                                                      fptr is written to iff it is non-NULL and the
     470 *                                                      selector indicates a member function of that
     471 *                                                      object.
     472 * @return                                      kSelectorNone if the selector was not found in
     473 *                                                      the object or its superclasses.
     474 *                                                      kSelectorVariable if the selector represents an
     475 *                                                      object-relative variable.
     476 *                                                      kSelectorMethod if the selector represents a
     477 *                                                      method
     478 */
     479SelectorType lookup_selector(EngineState *s, reg_t obj, Selector selectorid,
     480                ObjVarRef *varp, reg_t *fptr);
     481
     482/**
     483 * Parameters for script_get_segment()
     484 */
     485typedef enum {
    462486        SCRIPT_GET_DONT_LOAD = 0, /**< Fail if not loaded */
    463487        SCRIPT_GET_LOAD = 1, /**< Load, if neccessary */
    464488        SCRIPT_GET_LOCK = 3 /**< Load, if neccessary, and lock */
    465 };
     489} SCRIPT_GET;
    466490
    467 SegmentId script_get_segment(EngineState *s, int script_id, int load);
    468 /* Determines the segment occupied by a certain script
    469 ** Parameters: (EngineState *) s: The state to operate on
    470 **             (int) script_id: The script in question
    471 **             (int) load: One of SCRIPT_GET_*
    472 ** Returns   : The script's segment, or 0 on failure
    473 */
     491/**
     492 * Determines the segment occupied by a certain script
     493 * @param[in] s                 The state to operate on
     494 * @param[in] script_id The script in question
     495 * @param[in] load              One of SCRIPT_GET_*
     496 * @return                              The script's segment, or 0 on failure
     497 */
     498SegmentId script_get_segment(EngineState *s, int script_id, SCRIPT_GET load);
    474499
     500/**
     501 * Looks up an entry of the exports table of a script
     502 * @param[in]  s                        The state to operate on
     503 * @param[in]  script_nr        The script to look up in
     504 * @param[out] export_index     The index of the export entry to look up
     505 * @return                                      The handle
     506 */
    475507reg_t script_lookup_export(EngineState *s, int script_nr, int export_index);
    476 /* Looks up an entry of the exports table of a script
    477 ** Parameters: (EngineState *) s: The state to operate on
    478 **             (int) script_nr: The script to look up in
    479 ** Returns   : (int) export_index: index of the export entry to look up
    480 */
    481508
     509/**
     510 * Makes sure that a script and its superclasses get loaded to the heap.
     511 * If the script already has been loaded, only the number of lockers is
     512 * increased. All scripts containing superclasses of this script are loaded
     513 * recursively as well, unless 'recursive' is set to zero. The
     514 * complementary function is "script_uninstantiate()" below.
     515 * @param[in] s                 The state to operate on
     516 * @param[in] script_nr The script number to load
     517 * @return                              The script's segment ID or 0 if out of heap
     518 */
    482519int script_instantiate(EngineState *s, int script_nr);
    483 /* Makes sure that a script and its superclasses get loaded to the heap
    484 ** Parameters: (EngineState *) s: The state to operate on
    485 **             (int) script_nr: The script number to load
    486 ** Returns   : (int) The script's segment ID or 0 if out of heap
    487 ** If the script already has been loaded, only the number of lockers is increased.
    488 ** All scripts containing superclasses of this script aret loaded recursively as well,
    489 ** unless 'recursive' is set to zero.
    490 ** The complementary function is "script_uninstantiate()" below.
    491 */
    492 
    493520
     521/**
     522 * Decreases the numer of lockers of a script and unloads it if that number
     523 * reaches zero.
     524 * This function will recursively unload scripts containing its
     525 * superclasses, if those aren't locked by other scripts as well.
     526 * @param[in] s                 The state to operate on
     527 * @param[in] script_nr The script number that is requestet to be unloaded
     528 */
    494529void script_uninstantiate(EngineState *s, int script_nr);
    495 /* Decreases the numer of lockers of a script and unloads it if that number reaches zero
    496 ** Parameters: (EngineState *) s: The state to operate on
    497 **             (int) script_nr: The script number that is requestet to be unloaded
    498 ** Returns   : (void)
    499 ** This function will recursively unload scripts containing its superclasses, if those
    500 ** aren't locked by other scripts as well.
    501 */
    502 
    503530
     531/**
     532 * Initializes an SCI game
     533 * This function must be run before script_run() is executed. Graphics data
     534 * is initialized iff s->gfx_state != NULL.
     535 * @param[in] s The state to operate on
     536 * @return              0 on success, 1 if an error occured.
     537 */
    504538int game_init(EngineState *s);
    505 /* Initializes an SCI game
    506 ** Parameters: (EngineState *) s: The state to operate on
    507 ** Returns   : (int): 0 on success, 1 if an error occured.
    508 ** This function must be run before script_run() is executed.
    509 ** Graphics data is initialized iff s->gfx_state != NULL.
    510 */
    511539
     540/**
     541 * Initializes the graphics part of an SCI game
     542 * This function may only be called if game_init() did not initialize
     543 * the graphics data.
     544 * @param[in] s The state to initialize the graphics in
     545 * @return              0 on success, 1 if an error occured
     546 */
    512547int game_init_graphics(EngineState *s);
    513 /* Initializes the graphics part of an SCI game
    514 ** Parameters: (EngineState *) s: The state to initialize the graphics in
    515 ** Returns   : (int) 0 on success, 1 if an error occured
    516 ** This function may only be called if game_init() did not initialize
    517 ** the graphics data.
    518 */
    519548
     549/**
     550 * Initializes the sound part of an SCI game
     551 * This function may only be called if game_init() did not initialize
     552 * the sound data.
     553 * @param[in] s                         The state to initialize the sound in
     554 * @param[in] sound_flags       Flags to pass to the sound subsystem
     555 * @return                                      0 on success, 1 if an error occured
     556 */
    520557int game_init_sound(EngineState *s, int sound_flags);
    521 /* Initializes the sound part of an SCI game
    522 ** Parameters: (EngineState *) s: The state to initialize the sound in
    523 **             (int) sound_flags:  Flags to pass to the sound subsystem
    524 ** Returns   : (int) 0 on success, 1 if an error occured
    525 ** This function may only be called if game_init() did not initialize
    526 ** the graphics data.
    527 */
    528 
    529558
     559/**
     560 * Runs an SCI game
     561 * This is the main function for SCI games. It takes a valid state, loads
     562 * script 0 to it, finds the game object, allocates a stack, and runs the
     563 * init method of the game object. In layman's terms, this runs an SCI game.
     564 * Note that, EngineState *s may be changed during the game, e.g. if a game
     565 * state is restored.
     566 * @param[in] s Pointer to the pointer of the state to operate on
     567 * @return              0 on success, 1 if an error occured.
     568 */
    530569int game_run(EngineState **s);
    531 /* Runs an SCI game
    532 ** Parameters: (EngineState **) s: Pointer to the pointer of the state to operate on
    533 ** Returns   : (int): 0 on success, 1 if an error occured.
    534 ** This is the main function for SCI games. It takes a valid state, loads script 0 to it,
    535 ** finds the game object, allocates a stack, and runs the init method of the game object.
    536 ** In layman's terms, this runs an SCI game.
    537 ** By the way, *s may be changed during the game, e.g. if a game state is restored.
    538 */
    539570
     571/**
     572 * Restores an SCI game state and runs the game
     573 * This restores a savegame; otherwise, it behaves just like game_run().
     574 * @param[in] s                         Pointer to the pointer of the state to
     575 *                                                      operate on
     576 * @param[in] savegame_name     Name of the savegame to restore
     577 * @return                                      0 on success, 1 if an error occured.
     578 */
    540579int game_restore(EngineState **s, char *savegame_name);
    541 /* Restores an SCI game state and runs the game
    542 ** Parameters: (EngineState **) s: Pointer to the pointer of the state to operate on
    543 **             (char *) savegame_name: Name of the savegame to restore
    544 ** Returns   : (int): 0 on success, 1 if an error occured.
    545 ** This restores a savegame; otherwise, it behaves just like game_run().
    546 */
    547580
     581/**
     582 * Uninitializes an initialized SCI game
     583 * This function should be run after each script_run() call.
     584 * @param[in] s The state to operate on
     585 * @return              0 on success, 1 if an error occured.
     586 */
    548587int game_exit(EngineState *s);
    549 /* Uninitializes an initialized SCI game
    550 ** Parameters: (EngineState *) s: The state to operate on
    551 ** Returns   : (int): 0 on success, 1 if an error occured.
    552 ** This function should be run after each script_run() call.
    553 */
    554588
     589/**
     590 * Instructs the virtual machine to abort
     591 */
    555592void quit_vm();
    556 /* Instructs the virtual machine to abort
    557 ** Paramteres: (void)
    558 ** Returns   : (void)
    559 */
    560593
     594/**
     595 * Allocates "kernel" memory and returns a handle suitable to be passed on
     596 * to SCI scripts
     597 * @param[in] s         Pointer to the EngineState to operate on
     598 * @param[in] type      A free-form type description string (static)
     599 * @param[in] space     The space to allocate
     600 * @return                      The handle
     601 */
    561602reg_t kalloc(EngineState *s, const char *type, int space);
    562 /* Allocates "kernel" memory and returns a handle suitable to be passed on to SCI scripts
    563 ** Parameters: (EngineState *) s: Pointer to the EngineState to operate on
    564 **             (const char *) type: A free-form type description string (static)
    565 **             (int) space: The space to allocate
    566 ** Returns   : (reg_t) The handle
    567 */
    568603
     604/**
     605 * Returns a pointer to "kernel" memory based on the handle
     606 * @param[in] s                 Pointer to the EngineState to operate on
     607 * @param[in] handle    The handle to use
     608 * @return                              A pointer to the allocated memory
     609 */
    569610byte *kmem(EngineState *s, reg_t handle);
    570 /* Returns a pointer to "kernel" memory based on the handle
    571 ** Parameters: (EngineState *) s: Pointer to the EngineState to operate on
    572 **             (reg_t) handle: The handle to use
    573 ** Returns   : (byte *) A pointer to the allocated memory
    574 */
    575 
    576611
     612/**
     613 * Frees all "kernel" memory associated with a handle
     614 * @param[in] s                 Pointer to the EngineState to operate on
     615 * @param[in] handle    The handle to free
     616 * @return                              0 on success, 1 otherwise
     617 */
    577618int kfree(EngineState *s, reg_t handle);
    578 /* Frees all "kernel" memory associated with a handle
    579 ** Parameters: (EngineState *) s: Pointer to the EngineState to operate on
    580 **             (reg_t) handle: The handle to free
    581 ** Returns   : (int) 0 on success, 1 otherwise
    582 */
    583619
     620/**
     621 * Determines the name of an object
     622 * @param[in] s         Pointer to the EngineState to operate on
     623 * @param[in] pos       Location of the object whose name we want to inspect
     624 * @return                      A name for that object, or a string describing an error
     625 *                                      that occured while looking it up. The string is stored
     626 *                                      in a static buffer and need not be freed (neither may
     627 *                                      it be modified).
     628 */
    584629const char *obj_get_name(EngineState *s, reg_t pos);
    585 /* Determines the name of an object
    586 ** Parameters: (EngineState *) s: Pointer to the EngineState to operate on
    587 **             (reg_t) pos: Location of the object whose name we want to
    588 **                          inspect
    589 ** Returns   : (const char *) A name for that object, or a string describing
    590 **                            an error that occured while looking it up
    591 ** The string is stored in a static buffer and need not be freed (neither
    592 ** may it be modified).
    593 */
    594630
     631/**
     632 * Retrieves an object from the specified location
     633 * @param[in] s                 Pointer to the EngineState to operate on
     634 * @param[in] offset    The object's offset
     635 * @return                              The object in question, or NULL if there is none
     636 */
    595637Object *obj_get(EngineState *s, reg_t offset);
    596 /* Retrieves an object from the specified location
    597 ** Parameters: (EngineState *) s: Pointer to the EngineState to operate on
    598 **             (reg_t) offset: The object's offset
    599 ** Returns   : (Object *) The object in question, or NULL if there is none
    600 */
    601638
     639/**
     640 * Shrink execution stack to size.
     641 * Contains an assert it is not already smaller.
     642 */
    602643void shrink_execution_stack(EngineState *s, uint size);
    603 /* Shrink execution stack to size.
    604 ** Contains an assert it is not already smaller.
    605 */
    606644
    607645} // End of namespace Sci
    608646