diff --git a/.github/workflows/inform-pages-repo.yaml b/.github/workflows/inform-pages-repo.yaml index 71de3e8a0a..43d472bc8f 100644 --- a/.github/workflows/inform-pages-repo.yaml +++ b/.github/workflows/inform-pages-repo.yaml @@ -60,7 +60,7 @@ jobs: - name: Append File Docstrings run: | - python ./scripts/docs/append-file-docs.py + python ./scripts/ci/docs/append-file-docs.py - name: Upload Docs Artifact uses: actions/upload-artifact@v4 diff --git a/.vscode/launch.json b/.vscode/launch.json index 9d77fdb950..e493f71666 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -5,13 +5,13 @@ "version": "0.2.0", "configurations": [ { - "name": "Append File Docs", + "name": "run python script", "type": "python", "request": "launch", - "program": "${workspaceFolder}/scripts/ci/lint-characters.py", + "program": "${workspaceFolder}/scripts/gsrc/copy-common-naming.py", "console": "integratedTerminal", "cwd": "${workspaceFolder}", - "args": ["--fix"] + "args": ["--update-names-from-refs", "--decompiler", "./out/build/Release/bin/decompiler"] }, ] } diff --git a/.vscode/settings.json b/.vscode/settings.json index 1766a70045..fe629a0f67 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -7,99 +7,5 @@ }, "editor.wordBasedSuggestions": "matchingDocuments", "editor.snippetSuggestions": "top" - }, - "python.formatting.provider": "black", - "files.associations": { - "optional": "cpp", - "algorithm": "cpp", - "any": "cpp", - "array": "cpp", - "atomic": "cpp", - "bit": "cpp", - "bitset": "cpp", - "cctype": "cpp", - "charconv": "cpp", - "chrono": "cpp", - "cinttypes": "cpp", - "clocale": "cpp", - "cmath": "cpp", - "codecvt": "cpp", - "compare": "cpp", - "concepts": "cpp", - "condition_variable": "cpp", - "cstdarg": "cpp", - "cstddef": "cpp", - "cstdint": "cpp", - "cstdio": "cpp", - "cstdlib": "cpp", - "cstring": "cpp", - "ctime": "cpp", - "cwchar": "cpp", - "cwctype": "cpp", - "deque": "cpp", - "exception": "cpp", - "filesystem": "cpp", - "format": "cpp", - "forward_list": "cpp", - "fstream": "cpp", - "functional": "cpp", - "future": "cpp", - "initializer_list": "cpp", - "iomanip": "cpp", - "ios": "cpp", - "iosfwd": "cpp", - "iostream": "cpp", - "istream": "cpp", - "iterator": "cpp", - "limits": "cpp", - "list": "cpp", - "locale": "cpp", - "map": "cpp", - "memory": "cpp", - "mutex": "cpp", - "new": "cpp", - "numeric": "cpp", - "ostream": "cpp", - "queue": "cpp", - "random": "cpp", - "ranges": "cpp", - "ratio": "cpp", - "regex": "cpp", - "set": "cpp", - "shared_mutex": "cpp", - "span": "cpp", - "sstream": "cpp", - "stack": "cpp", - "stdexcept": "cpp", - "stop_token": "cpp", - "streambuf": "cpp", - "string": "cpp", - "system_error": "cpp", - "thread": "cpp", - "tuple": "cpp", - "type_traits": "cpp", - "typeinfo": "cpp", - "unordered_map": "cpp", - "unordered_set": "cpp", - "utility": "cpp", - "valarray": "cpp", - "variant": "cpp", - "vector": "cpp", - "xfacet": "cpp", - "xhash": "cpp", - "xiosbase": "cpp", - "xlocale": "cpp", - "xlocbuf": "cpp", - "xlocinfo": "cpp", - "xlocmes": "cpp", - "xlocmon": "cpp", - "xlocnum": "cpp", - "xloctime": "cpp", - "xmemory": "cpp", - "xstddef": "cpp", - "xstring": "cpp", - "xtr1common": "cpp", - "xtree": "cpp", - "xutility": "cpp" } } diff --git a/Taskfile.yml b/Taskfile.yml index a977c9a795..099c57c4d9 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -78,11 +78,7 @@ tasks: desc: "Format code" cmds: # npm install -g prettier - - cmd: npx prettier --write ./decompiler/config/jak1/**/*.jsonc - ignore_error: true - - cmd: npx prettier --write ./decompiler/config/jak2/**/*.jsonc - ignore_error: true - - cmd: npx prettier --write ./decompiler/config/jak3/**/*.jsonc + - cmd: npx prettier --write ./decompiler/config/jak*/**/*.jsonc ignore_error: true format: desc: "Format code" @@ -102,7 +98,7 @@ tasks: - python ./scripts/tasks/clean-decomp.py --game "{{.GAME}}" lint-gsrc-file: cmds: - - python ./scripts/gsrc/lint-gsrc-file.py --game {{.GAME}} --file {{.FILE}} + - python ./scripts/gsrc/lint-gsrc-file.py --game {{.GAME}} --file "{{.FILE}}" update-gsrc: cmds: - python ./scripts/gsrc/update-gsrc-via-refs.py --game "{{.GAME}}" --decompiler "{{.DECOMP_BIN_RELEASE_DIR}}/decompiler" --decompiler_config {{.DECOMP_CONFIG}} --version {{.DECOMP_CONFIG_VERSION}} @@ -112,8 +108,16 @@ tasks: update-gsrc-file: cmds: - task: decomp-file - - python ./scripts/gsrc/update-from-decomp.py --game "{{.GAME}}" --file {{.FILE}} + - python ./scripts/gsrc/update-from-decomp.py --game "{{.GAME}}" --file "{{.FILE}}" - task: lint-gsrc-file + copy-common-naming: + cmds: + - python ./scripts/gsrc/copy-common-naming.py --file "{{.FILE}}" --decompiler "{{.DECOMP_BIN_RELEASE_DIR}}/decompiler" + - task: format-json + copy-common-naming-from-refs: + cmds: + - python ./scripts/gsrc/copy-common-naming.py --update-names-from-refs --decompiler "{{.DECOMP_BIN_RELEASE_DIR}}/decompiler" + - task: format-json # ASSET RIPPING rip-textures: cmds: diff --git a/decompiler/config/jak1_demo/default/hacks.jsonc b/decompiler/config/jak1_demo/default/hacks.jsonc index bdf1358bdc..b77f2ef5dc 100644 --- a/decompiler/config/jak1_demo/default/hacks.jsonc +++ b/decompiler/config/jak1_demo/default/hacks.jsonc @@ -360,7 +360,6 @@ "(anon-function 2 target-tube)", "(anon-function 5 orbit-plat)", "(anon-function 2 ogreboss)" - ], // these functions use pairs and the decompiler @@ -527,7 +526,10 @@ "(method 49 progress)": [[35, 1]], "(method 37 progress)": [[41, 1]], "(method 38 progress)": [[106, 1]], - "(method 39 progress)": [[56, 1], [83, 1]], + "(method 39 progress)": [ + [56, 1], + [83, 1] + ], "(method 41 progress)": [[73, 1]], "(method 42 progress)": [[41, 1]], "(method 43 progress)": [ @@ -557,5 +559,3 @@ "render-boundary-tri" ] } - - diff --git a/decompiler/config/jak1_demo/default/inputs.jsonc b/decompiler/config/jak1_demo/default/inputs.jsonc index 3ef3a4d596..4438a5472b 100644 --- a/decompiler/config/jak1_demo/default/inputs.jsonc +++ b/decompiler/config/jak1_demo/default/inputs.jsonc @@ -232,8 +232,5 @@ //"audio_dir_file_name": "jak1/VAG", "audio_dir_file_name": "", - "streamed_audio_file_names": [ - "VAGWAD.ENG", - "VAGWAD.JAP" - ] + "streamed_audio_file_names": ["VAGWAD.ENG", "VAGWAD.JAP"] } diff --git a/decompiler/config/jak1_demo/default/stack_structures.jsonc b/decompiler/config/jak1_demo/default/stack_structures.jsonc index fe6bb5e48d..338610dedb 100644 --- a/decompiler/config/jak1_demo/default/stack_structures.jsonc +++ b/decompiler/config/jak1_demo/default/stack_structures.jsonc @@ -2641,61 +2641,39 @@ [224, "vector"] ], - "lb-flip":[ - [16, "load-boundary-crossing-command"] - ], + "lb-flip": [[16, "load-boundary-crossing-command"]], - "---lb-save":[ - [16, "file-stream"] - ], + "---lb-save": [[16, "file-stream"]], - "edit-load-boundaries":[ + "edit-load-boundaries": [ [16, "vector"], [32, "vector"], [48, "vector"], [64, "vector"] ], - "triangulate-boundary":[ - [16, "lbvtx"] - ], + "triangulate-boundary": [[16, "lbvtx"]], - "fix-boundary-normals":[ - [16, "vector"] - ], + "fix-boundary-normals": [[16, "vector"]], - "check-closed-boundary":[ - [16, "vector"] - ], + "check-closed-boundary": [[16, "vector"]], - "(event target-racing-start)": [ - [16, "event-message-block"] - ], + "(event target-racing-start)": [[16, "event-message-block"]], - "(exit target-racing-start)": [ - [16, "event-message-block"] - ], + "(exit target-racing-start)": [[16, "event-message-block"]], - "(code target-racing-start)": [ - [16, "event-message-block"] - ], + "(code target-racing-start)": [[16, "event-message-block"]], "target-racing-smack-check": [ [16, "vector"], [32, "vector"] ], - "(trans target-racing)": [ - [16, "vector"] - ], + "(trans target-racing)": [[16, "vector"]], - "(trans target-racing-jump)": [ - [16, "vector"] - ], + "(trans target-racing-jump)": [[16, "vector"]], - "(trans target-racing-bounce)": [ - [16, "vector"] - ], + "(trans target-racing-bounce)": [[16, "vector"]], "(code target-racing-hit)": [ [16, "vector"], @@ -2705,9 +2683,7 @@ [80, "vector"] ], - "(exit target-racing-death)": [ - [16, "event-message-block"] - ], + "(exit target-racing-death)": [[16, "event-message-block"]], "(anon-function 17 racer-states-FIC-LAV-MIS-OGR-ROL)": [ [16, "joint-exploder-tuning"] @@ -2725,9 +2701,7 @@ [48, "event-message-block"] ], - "(post target-racing-get-on)": [ - [16, "vector"] - ], + "(post target-racing-get-on)": [[16, "vector"]], "(code target-racing-get-off-jump)": [ [16, "vector"], @@ -2735,17 +2709,11 @@ [48, "event-message-block"] ], - "(post target-racing-get-off-jump)": [ - [16, "vector"] - ], + "(post target-racing-get-off-jump)": [[16, "vector"]], - "(exit target-racing-clone-anim)": [ - [16, "event-message-block"] - ], + "(exit target-racing-clone-anim)": [[16, "event-message-block"]], - "(code target-racing-clone-anim)": [ - [16, "event-message-block"] - ], + "(code target-racing-clone-anim)": [[16, "event-message-block"]], "placeholder-do-not-add-below!": [] } diff --git a/decompiler/config/jak1_demo/default/type_casts.jsonc b/decompiler/config/jak1_demo/default/type_casts.jsonc index 5d2c1bd7e3..f3e2ff0637 100644 --- a/decompiler/config/jak1_demo/default/type_casts.jsonc +++ b/decompiler/config/jak1_demo/default/type_casts.jsonc @@ -80,9 +80,7 @@ [101, "t9", "(function object object object object object object none)"] ], - "send-event-function": [ - [[7,12], "a0", "process"] - ], + "send-event-function": [[[7, 12], "a0", "process"]], // MATH "log2": [[3, "v1", "int"]], @@ -1107,7 +1105,7 @@ "blackout": [[[20, 24], "v1", "dma-packet"]], "(method 15 load-state)": [ [31, "t9", "(function int)"], - [[291,303], "s5", "entity-actor"], + [[291, 303], "s5", "entity-actor"], [370, "s3", "process-drawable"], [343, "s5", "symbol"], [21, "s5", "symbol"] @@ -1787,13 +1785,9 @@ [140, "s1", "(pointer uint128)"] ], - "(method 15 level)": [ - [[21, 60], "v1", "(inline-array box8s)"] - ], + "(method 15 level)": [[[21, 60], "v1", "(inline-array box8s)"]], - "(method 27 level)": [ - [[23, 68], "s2", "(inline-array box8s)"] - ], + "(method 27 level)": [[[23, 68], "s2", "(inline-array box8s)"]], "unpack-comp-huf": [[[21, 23], "t3", "(pointer uint16)"]], @@ -2295,13 +2289,9 @@ [7, "t9", "(function entity-actor entity-actor)"] ], - "(method 10 drawable-group)": [ - [19, "s5", "drawable-group"] - ], + "(method 10 drawable-group)": [[19, "s5", "drawable-group"]], - "(method 15 drawable-group)": [ - [19, "s5", "drawable-group"] - ], + "(method 15 drawable-group)": [[19, "s5", "drawable-group"]], "(method 14 level-group)": [ [[54, 164], "s1", "process-drawable"], @@ -4001,32 +3991,22 @@ [54, "a0", "pair"] ], - "command-get-int":[ - [27, "gp", "bfloat"] - ], + "command-get-int": [[27, "gp", "bfloat"]], - "command-get-float":[ - [30, "gp", "bfloat"] - ], + "command-get-float": [[30, "gp", "bfloat"]], - "command-get-time":[ - [46, "gp", "bfloat"] - ], + "command-get-time": [[46, "gp", "bfloat"]], - "command-get-param":[ - [125, "gp", "bfloat"] - ], + "command-get-param": [[125, "gp", "bfloat"]], - "command-list-get-process":[ - [[78, 88], "s4", "process-drawable"] - ], + "command-list-get-process": [[[78, 88], "s4", "process-drawable"]], - "add-boundary-shader":[ - [[5,8], "a1", "gs-gif-tag"], + "add-boundary-shader": [ + [[5, 8], "a1", "gs-gif-tag"], [[11, 35], "s5", "adgif-shader"] ], - "render-boundary":[ + "render-boundary": [ [[22, 26], "a0", "dma-packet"], [[32, 35], "a0", "gs-gif-tag"], @@ -4040,7 +4020,7 @@ [[120, 123], "v1", "dma-packet"] ], - "real-main-draw-hook":[ + "real-main-draw-hook": [ [[225, 229], "a0", "dma-packet"], [[235, 238], "a0", "gs-gif-tag"], [243, "a0", "(pointer gs-zbuf)"], @@ -4072,41 +4052,25 @@ [42, "v1", "target"] ], - "(code target-racing-smack)": [ - [30, "v1", "art-joint-anim"] - ], + "(code target-racing-smack)": [[30, "v1", "art-joint-anim"]], - "(code target-racing-hit)": [ - [186, "v1", "art-joint-anim"] - ], + "(code target-racing-hit)": [[186, "v1", "art-joint-anim"]], - "(code target-racing-death)": [ - [242, "v1", "art-joint-anim"] - ], + "(code target-racing-death)": [[242, "v1", "art-joint-anim"]], - "(code target-racing-get-on)": [ - [59, "s3", "racer"] - ], + "(code target-racing-get-on)": [[59, "s3", "racer"]], "(code target-racing-get-off-jump)": [ [67, "s2", "racer"], [145, "v1", "art-joint-anim"] ], - "(code target-racing-get-off-hit-ground)": [ - [13, "v1", "art-joint-anim"] - ], + "(code target-racing-get-off-hit-ground)": [[13, "v1", "art-joint-anim"]], - "(event target-racing-grab)": [ - [24, "a0", "process-drawable"] - ], + "(event target-racing-grab)": [[24, "a0", "process-drawable"]], - "cam-collision-record-draw": [ - [[44, 275], "s5", "cam-collision-record"] - ], - "cam-collision-record-save": [ - [[8, 56], "v1", "cam-collision-record"] - ], + "cam-collision-record-draw": [[[44, 275], "s5", "cam-collision-record"]], + "cam-collision-record-save": [[[8, 56], "v1", "cam-collision-record"]], "placeholder-do-not-add-below": [] } diff --git a/decompiler/config/jak2/all-types.gc b/decompiler/config/jak2/all-types.gc index 988cc17256..e15fc9f15d 100644 --- a/decompiler/config/jak2/all-types.gc +++ b/decompiler/config/jak2/all-types.gc @@ -140,6 +140,9 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype vec4s (uint128) + "Vector of four floats, packed into a 128-bit integer as bitfields. + This behaves like a value type. + This is not the main vector type." ((x float :offset 0) (y float :offset 32) (z float :offset 64) @@ -150,6 +153,9 @@ ) (deftype vector (structure) + "Vector of four floats, stored in a structure. + This behaves like a reference type. + This is the main vector type." ((data float 4 :score -1 :offset-assert 0) (x float :offset 0) (y float :offset 4) @@ -163,6 +169,7 @@ ) (deftype bfloat (basic) + "Boxed (or basic?) float. Just a basic that wraps a single float." ((data float :offset-assert 4) ) :method-count-assert 9 @@ -171,6 +178,8 @@ ) (deftype inline-array-class (basic) + "Base class for basic inline arrays. + The stride is stored in the heap-base of the inline-array-class child class." ((length int32 :offset-assert 4) (allocated-length int32 :offset-assert 8) ;; this is 16-byte aligned. @@ -185,58 +194,168 @@ :flag-assert #x900000010 ) -(define-extern identity (function object object)) -(define-extern 1/ (function float float)) -(define-extern + (function int int int)) -(define-extern - (function int int int)) +(define-extern identity + "The identity function." + (function object object)) +(define-extern 1/ + "Floating point reciprocal." + (function float float)) +(define-extern + + "64-bit integer addition." + (function int int int)) +(define-extern - + "64-bit integer subraction." + (function int int int)) (define-extern * (function int int int)) -(define-extern / (function int int int)) -(define-extern ash (function int int int)) -(define-extern mod (function int int int)) -(define-extern rem (function int int int)) -(define-extern abs (function int int)) -(define-extern min (function int int int)) -(define-extern max (function int int int)) -(define-extern logior (function int int int)) -(define-extern logand (function int int int)) -(define-extern lognor (function int int int)) -(define-extern logxor (function int int int)) -(define-extern lognot (function int int)) -(define-extern false-func (function symbol)) -(define-extern true-func (function symbol)) +(define-extern / + "32-bit signed integer division." + (function int int int)) +(define-extern ash + "64-bit arithmetic shift. (sign-extends)" + (function int int int)) +(define-extern mod + "32-bit mod." + (function int int int)) +(define-extern rem + "32-bit mod (same as mod)." + (function int int int)) +(define-extern abs + "64-bit integer absolute value." + (function int int)) +(define-extern min + "64-bit integer minimum." + (function int int int)) +(define-extern max + "64-bit integer maximum." + (function int int int)) +(define-extern logior + "64-bit bitwise or." + (function int int int)) +(define-extern logand + "64-bit bitwise and." + (function int int int)) +(define-extern lognor + "64-bit bitwise not-or." + (function int int int)) +(define-extern logxor + "64-bit bitwise exclusive or." + (function int int int)) +(define-extern lognot + "64-bit bitwise not." + (function int int)) +(define-extern false-func + "Returns false." + (function symbol)) +(define-extern true-func + "Returns true." + (function symbol)) (define-extern format (function _varargs_ object)) -(define-extern basic-type? (function basic type symbol)) -(define-extern type-type? (function type type symbol)) -(define-extern type? (function object type symbol)) -(define-extern find-parent-method (function type int function)) -(define-extern ref (function object int object)) -(define-extern last (function object object)) -(define-extern member (function object object object)) -(define-extern nmember (function basic object object)) -(define-extern assoc (function object object object)) -(define-extern assoce (function object object object)) -(define-extern nassoc (function string object object)) -(define-extern nassoce (function string object object)) -(define-extern append! (function object object object)) -(define-extern delete! (function object object pair)) -(define-extern delete-car! (function object object object)) -(define-extern insert-cons! (function object object pair)) -(define-extern sort (function pair (function object object object) pair)) -(define-extern mem-copy! (function pointer pointer int pointer)) -(define-extern qmem-copy<-! (function pointer pointer int pointer)) -(define-extern qmem-copy->! (function pointer pointer int pointer)) -(define-extern mem-set32! (function pointer int int pointer)) -(define-extern mem-or! (function pointer pointer int pointer)) +(define-extern basic-type? + "Return if the given basic is a given type. A child of the given type is also acceptable." + (function basic type symbol)) +(define-extern type-type? + "Return if the first type is the second type, or a child of it." + (function type type symbol)) +(define-extern type? + "Return if the given object is an instance of the given type. + Works on basics, bintegers, or symbols." + (function object type symbol)) +(define-extern find-parent-method + "Find the closest parent type that has a different implementation of the given method and return that method. + If it does not exist, return `nothing` function. + This is used to implement call-parent-method." + (function type int function)) +(define-extern ref + "Return the n-th item in a proper list. No bounds checking." + (function object int object)) +(define-extern last + "Return the last object in a proper list." + (function object object)) +(define-extern member + "See if the first argument is in the proper list of the second argument. + Checked with simple equality. + If so, return the list starting at the at point (a truthy value). + Otherwise, return #f. + (member 'b '(a b c)) -> (b c d). + (member 'w '(a b c)) -> #f" + (function object object object)) +(define-extern nmember + "Like member, but membership is checked with the name= function to handle symbols or strings." + (function basic object object)) +(define-extern assoc + "Search an association list for given object. Return #f if not found, otherwise the element with matching car. + (assoc 'a '((a . 1) (b . 2) (c . 3))) -> (a . 1) + (assoc 'x '((a . 1) (b . 2) (c . 3))) -> #f" + (function object object object)) +(define-extern assoce + "Like assoc, but supports a special `else` key which is always considered a match." + (function object object object)) +(define-extern nassoc + "Like assoc, but uses name= instead of = to check equality." + (function string object object)) +(define-extern nassoce + "Like assoce, but uses name= instead of = to check equality." + (function string object object)) +(define-extern append! + "Append the second argument to the end of the list (or empty pair) in the first argument." + (function object object object)) +(define-extern delete! + "Remove an element from the given list, return the list." + (function object object pair)) +(define-extern delete-car! + "Remove an element from the given list with a matching car. Return the list." + (function object object object)) +(define-extern insert-cons! + "Update an association list to have the given (key . value) pair. + If a previous value exists, it is deleted first. + This function always allocates a pair through `cons` on the global heap, which can never be freed, + so it should almost never be used at runtime." + (function object object pair)) +(define-extern sort + "Sort a list using the given comparision function. + The function can return a #t/#f value, or a positive/negative value. + For example, you could use either `-` or `<` as functions to sort integers." + (function pair (function object object object) pair)) +(define-extern mem-copy! + "Basic memory copy. This is not an optimized implementation." + (function pointer pointer int pointer)) +(define-extern qmem-copy<-! + "Copy memory by quadword (16-bytes). Must by 16-byte aligned, size in 16-byte units. Increasing address copy. Not an optimized version." + (function pointer pointer int pointer)) +(define-extern qmem-copy->! + "Copy memory by quadword (16-bytes). Must by 16-byte aligned, size in 16-byte units. Decreasing address copy. Not an optimized version." + (function pointer pointer int pointer)) +(define-extern mem-set32! + "Set memory to the given 32-bit value, repeated n times. (like C memset, but setting int32_t instead of char). + Not an optimized implementation. Must be 4-byte aligned." + (function pointer int int pointer)) +(define-extern mem-or! + "Set the destiation to `dest = dest | src`. Size in bytes. Not an optimized version." + (function pointer pointer int pointer)) (define-extern quad-copy! (function pointer pointer int none)) -(define-extern fact (function int int)) +(define-extern fact + "Factorial." + (function int int)) (define-extern *print-column* binteger) -(define-extern print (function object object)) -(define-extern printl (function object object)) -(define-extern inspect (function object object)) -(define-extern mem-print (function (pointer uint32) int symbol)) +(define-extern print + "Print any boxed object (symbol, pair, basic, binteger) to #t (the REPL). No newline." + (function object object)) +(define-extern printl + "Print any boxed object (symbol, pair, basic, binteger) to #t (the REPL), followed by a newline." + (function object object)) +(define-extern inspect + "Inspect any boxed object (symbol, pair, basic, binteger) to #t (the REPL)." + (function object object)) +(define-extern mem-print + "Print out data in memory in hex." + (function (pointer uint32) int symbol)) (define-extern *trace-list* pair) -(define-extern print-tree-bitmask (function int int symbol)) -(define-extern breakpoint-range-set! (function uint uint uint int)) +(define-extern print-tree-bitmask + "Print out ASCII-art tree structure, from a bitmask of nesting levels." + (function int int symbol)) +(define-extern breakpoint-range-set! + "Unsupported function to set a CPU breakpoint." + (function uint uint uint int)) (define-extern valid? (function object type string symbol object symbol)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; @@ -306,9 +425,9 @@ (self process-tree :offset-assert 32) ) (:methods - (new (symbol type string) _type_) ;; 0 - (activate (_type_ process-tree basic pointer) process-tree) ;; 9 - (deactivate (_type_) none) ;; 10 + (new "Allocate a process-tree with the kernel clock." (symbol type string) _type_) ;; 0 + (activate "Move a process from dead to active, moving it to the given tree." (_type_ process-tree basic pointer) process-tree) ;; 9 + (deactivate "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (_type_) none) ;; 10 (init-from-entity! "Typically the method that does the initial setup on the process, potentially using the [[entity-actor]] provided as part of that. This commonly includes things such as: @@ -317,7 +436,7 @@ - loading the skeleton group / bones - sounds" (_type_ entity-actor) none) ;; 11 - (run-logic? (_type_) symbol) ;; 12 + (run-logic? "Should this process be run? Checked by execute-process-tree." (_type_) symbol) ;; 12 (process-tree-method-13 () none) ;; 13 ) :size-assert #x24 @@ -372,12 +491,15 @@ :flag-assert #xf0000005c (:methods (new (symbol type int) _type_) ;; 0 - (update-rates! (_type_ float) float) ;; 9 - (advance-by! (_type_ float) clock) ;; 10 - (tick! (_type_) clock) ;; 11 - (save! (_type_ (pointer uint64)) int) ;; 12 - (load! (_type_ (pointer uint64)) int) ;; 13 - (reset! (_type_) none) ;; 14 + (update-rates! "Recompute all clock values for the given clock ratio (arg0)." (_type_ float) float) ;; 9 + (advance-by! + "Advance the clock by arg0 timeframes (as a float). + Both counters keep a separate fractional and integer counter." + (_type_ float) clock) ;; 10 + (tick! "Per-game-frame clock tick forward." (_type_) clock) ;; 11 + (save! "Save a clock's state to a buffer, return bytes used." (_type_ (pointer uint64)) int) ;; 12 + (load! "Load a clock's state from a buffer, return bytes used." (_type_ (pointer uint64)) int) ;; 13 + (reset! "Reset a clock to 1000s, rate of 1." (_type_) none) ;; 14 ) ) @@ -397,15 +519,16 @@ :size-assert #x28 :flag-assert #xc00000028 (:methods - (stack-size-set! (_type_ int) none) ;; 9 - (thread-suspend (_type_) none) ;; 10 - (thread-resume (_type_) none) ;; 11 + (stack-size-set! "Adjust the size of the stack that can be stored during a suspend. Must be called before any process allocations." (_type_ int) none) ;; 9 + (thread-suspend "Suspend this thread and jump to the kernel (for use by the kernel only)" (_type_) none) ;; 10 + (thread-resume "Jump from the kernel to the restored thread. (for use by the kernel only)" (_type_) none) ;; 11 ) ) ;; modified for x86. (deftype cpu-thread (thread) +;; registers modified for PC port. ((rreg uint64 7 :offset-assert 40) (freg float 8) @@ -418,7 +541,7 @@ :size-assert #x80 :flag-assert #xc00000080 (:methods - (new (symbol type process symbol int pointer) _type_) ;; 0 + (new "Allocate a thread. If there is already a top-thread for this process, assume this is a temporary thread, and allocate on the bottom of the stack." (symbol type process symbol int pointer) _type_) ;; 0 ) ) @@ -431,9 +554,9 @@ :flag-assert #x1000000024 ;; Failed to read fields. (:methods - (new (symbol type int int string) _type_) ;; 0 - (get-process (_type_ type int) process) ;; 14 - (return-process (_type_ process) none) ;; 15 + (new "Allocate a dead pool and set up dead processes" (symbol type int int string) _type_) ;; 0 + (get-process "Allocate a process from the pool, or #f if it fails." (_type_ type int) process) ;; 14 + (return-process "Return a process to the pool." (_type_ process) none) ;; 15 ) ) @@ -469,19 +592,19 @@ :flag-assert #x1c00000068 ;; Failed to read fields. (:methods - (new (symbol type string int int) _type_) ;; 0 - (init (_type_ symbol int) none) ;; 16 - (compact (dead-pool-heap int) none) ;; 17 - (shrink-heap (dead-pool-heap process) dead-pool-heap) ;; 18 - (churn (dead-pool-heap int) none) ;; 19 - (memory-used (_type_) int) ;; 20 - (memory-total (_type_) int) ;; 21 - (memory-free (dead-pool-heap) int) ;; 22 - (compact-time (dead-pool-heap) uint) ;; 23 - (gap-size (dead-pool-heap dead-pool-heap-rec) int) ;; 24 - (gap-location (dead-pool-heap dead-pool-heap-rec) pointer) ;; 25 - (find-gap (dead-pool-heap dead-pool-heap-rec) dead-pool-heap-rec) ;; 26 - (find-gap-by-size (dead-pool-heap int) dead-pool-heap-rec) ;; 27 + (new "Allocate and initialize a dead-pool-heap." (symbol type string int int) _type_) ;; 0 + (init "Allocate memory for processes and init records." (_type_ symbol int) none) ;; 16 + (compact "Relocate process in memory to remove gaps, increasing free memory for this dead-pool-heap." (dead-pool-heap int) none) ;; 17 + (shrink-heap "Shrink the heap of a process, allowing the dead pool heap to later reclaim the memory during a compact." (dead-pool-heap process) dead-pool-heap) ;; 18 + (churn "Relocate process in memory, to trigger memory bugs related to process relocation." (dead-pool-heap int) none) ;; 19 + (memory-used "Get the total memory used. Memory in between processes that is not used by a process is considered used." (_type_) int) ;; 20 + (memory-total "Get the total size of the heap for processes." (_type_) int) ;; 21 + (memory-free "Get the size of the unused part of the heap." (dead-pool-heap) int) ;; 22 + (compact-time "Get the compaction time (never set)." (dead-pool-heap) uint) ;; 23 + (gap-size "Get the size of the gap (possibly zero) after the given process. Use #f for the gap at the start of the pool memory." (dead-pool-heap dead-pool-heap-rec) int) ;; 24 + (gap-location "Get pointer to gap (possibly zero size) after the given process" (dead-pool-heap dead-pool-heap-rec) pointer) ;; 25 + (find-gap "Find the first process with a nonzero gap after it, after the given process." (dead-pool-heap dead-pool-heap-rec) dead-pool-heap-rec) ;; 26 + (find-gap-by-size "Find the first gap with a size at least this big" (dead-pool-heap int) dead-pool-heap-rec) ;; 27 ) ) @@ -517,7 +640,7 @@ ((exit (function object) :offset-assert 12) ;; guessed by decompiler ) (:methods - (new (symbol type (function object)) protect-frame) + (new "Allocate and set up a protect-frame. This _must_ be used on the stack." (symbol type (function object)) protect-frame) ) :method-count-assert 9 :size-assert #x10 @@ -605,7 +728,7 @@ (stack uint8 :dynamic :offset-assert 128 :score -1) ) (:methods - (new (symbol type string int) _type_) ;; 0 + (new "Allocate a process, set up process heap, self/ppointer, clock." (symbol type string int) _type_) ;; 0 ) (:states dead-state @@ -643,41 +766,84 @@ (define-extern *last-loado-global-usage* int) (define-extern *last-loado-debug-usage* int) (define-extern *kernel-packages* pair) -(define-extern load-package (function string kheap pair)) -(define-extern unload-package (function string pair)) +(define-extern load-package + "If not already loaded, do a blocking dgo-load to load the given CGO." + (function string kheap pair)) +(define-extern unload-package + "Mark a package as unloaded. Does not actually unload." + (function string pair)) (define-extern *kernel-context* kernel-context) (define-extern *dram-stack* (pointer uint8)) (define-extern *null-kernel-context* kernel-context) -(define-extern remove-exit (function none :behavior process)) +(define-extern remove-exit + "Remove the top stack frame. If you have no other stack frames, you can use this before a `go` + to skip the `exit` of the state you are currently in." + (function none :behavior process)) (define-extern stream<-process-mask (function object process-mask process-mask)) (define-extern *master-mode* symbol) (define-extern *pause-lock* symbol) -(define-extern inspect-process-heap (function process symbol)) +(define-extern inspect-process-heap + "Call the inspect method on every object in the process heap." + (function process symbol)) (define-extern return-from-thread (function none)) (define-extern return-from-thread-dead (function none)) (define-extern reset-and-call (function thread function object)) (define-extern method-state (function type basic state)) (define-extern *global-search-name* basic) (define-extern *global-search-count* int) -(define-extern process-by-name (function string process-tree process)) -(define-extern process-not-name (function string process-tree process)) -(define-extern process-count (function process-tree int)) -(define-extern kill-by-name (function string process-tree symbol)) -(define-extern kill-by-type (function type process-tree symbol)) -(define-extern kill-not-name (function string process-tree symbol)) -(define-extern kill-not-type (function type process-tree symbol)) -(define-extern iterate-process-tree (function process-tree (function object object) kernel-context object)) -(define-extern execute-process-tree (function process-tree (function object object) kernel-context object)) -(define-extern search-process-tree (function process-tree (function process-tree object) process)) -(define-extern kernel-dispatcher (function object)) -(define-extern sync-dispatcher (function object)) -(define-extern inspect-process-tree (function process-tree int int symbol process-tree)) +(define-extern process-by-name + "Find the first process with the given name in the process-tree." + (function string process-tree process)) +(define-extern process-not-name + "Find the first process without the given name in the process-tree." + (function string process-tree process)) +(define-extern process-count + "Count the number of processes in the given process-tree." + (function process-tree int)) +(define-extern kill-by-name + "Kill all processes with the given name." + (function string process-tree symbol)) +(define-extern kill-by-type + "Kill all processes with the given type." + (function type process-tree symbol)) +(define-extern kill-not-name + "Kill all processes, except ones with the given name." + (function string process-tree symbol)) +(define-extern kill-not-type + "Kill all processes, except ones with the exact type." + (function type process-tree symbol)) +(define-extern iterate-process-tree + "Call a function on each not-dead process in the tree." + (function process-tree (function object object) kernel-context object)) +(define-extern execute-process-tree + "Iterate over all process, calling the run callback on each, if they should run." + (function process-tree (function object object) kernel-context object)) +(define-extern search-process-tree + "Return the first function in the process-tree which the callback returns #t on." + (function process-tree (function process-tree object) process)) +(define-extern kernel-dispatcher + "Run the GOAL kernel! Runs the function from the listener (if there is one), then all processes" + (function object)) +(define-extern sync-dispatcher + "Run the REPL function." + (function object)) +(define-extern inspect-process-tree + "Display a tree-view of a process-tree." + (function process-tree int int symbol process-tree)) (define-extern throw-dispatch (function catch-frame object none)) (define-extern throw (function symbol object int)) -(define-extern previous-brother (function process-tree object)) -(define-extern change-parent (function process-tree process-tree process-tree)) -(define-extern change-brother (function process-tree process-tree object)) -(define-extern change-to-last-brother (function process-tree process-tree)) +(define-extern previous-brother + "Get the process before this one, at this level." + (function process-tree object)) +(define-extern change-parent + "Reparent a process." + (function process-tree process-tree process-tree)) +(define-extern change-brother + "Unused, and wrong." + (function process-tree process-tree object)) +(define-extern change-to-last-brother + "Move this process to the end of its brother list." + (function process-tree process-tree)) (define-extern run-function-in-process (function process function object object object object object object object)) (define-extern set-to-run-bootstrap (function none)) (define-extern set-to-run (function cpu-thread function object object object object object object pointer)) @@ -753,41 +919,104 @@ ;; gstring ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -(define-extern copy-string<-string (function string string string)) -(define-extern string= (function string string symbol)) -(define-extern string-prefix= (function string string symbol)) -(define-extern charp-prefix= (function (pointer uint8) (pointer uint8) symbol)) -(define-extern string-suffix= (function string string symbol)) -(define-extern string-position (function string string int)) -(define-extern string-charp= (function string (pointer uint8) symbol)) +(define-extern copy-string<-string + "Copy a string. No bounds check. Writes null terminator." + (function string string string)) +(define-extern string= + "Check for string equality." + (function string string symbol)) +(define-extern string-prefix= + "Check if a string starts with a given string." + (function string string symbol)) +(define-extern charp-prefix= + "Check if a c-string starts with a given c-string." + (function (pointer uint8) (pointer uint8) symbol)) +(define-extern string-suffix= + "Check if a string ends with a given string." + (function string string symbol)) +(define-extern string-position + "Find the point where a string occurs in another. If it doesn't, return -1." + (function string string int)) +(define-extern string-charp= + "Check if a string is equal to a c-string." + (function string (pointer uint8) symbol)) (define-extern name= (function object object symbol)) -(define-extern copyn-string<-charp (function string (pointer uint8) int string)) -(define-extern string<-charp (function string (pointer uint8) string)) -(define-extern charp<-string (function (pointer uint8) string int)) -(define-extern copyn-charp<-string (function (pointer uint8) string int none)) -(define-extern copy-charp<-charp (function (pointer uint8) (pointer uint8) (pointer uint8))) -(define-extern cat-string<-string (function string string string)) -(define-extern catn-string<-charp (function string (pointer uint8) int string)) -(define-extern cat-string<-string_to_charp (function string string (pointer uint8) (pointer uint8))) -(define-extern append-character-to-string (function string uint8 int)) -(define-extern charp-basename (function (pointer uint8) (pointer uint8))) -(define-extern clear (function string string)) -(define-extern string? (function string string symbol)) -(define-extern string<=? (function string string symbol)) -(define-extern string>=? (function string string symbol)) +(define-extern copyn-string<-charp + "Copy part of a c-string to a string. Writes null terminator after num-chars." + (function string (pointer uint8) int string)) +(define-extern string<-charp + "Copy a c-string to a string. Writes the null terminator." + (function string (pointer uint8) string)) +(define-extern charp<-string + "Copy a string to a c-string. Writes the null terminator." + (function (pointer uint8) string int)) +(define-extern copyn-charp<-string + "Copy part of a string to a c-string. Writes null terminator, repeatedly, to reach the given length. + If the source is longer than the length, the null terminator is still included." + (function (pointer uint8) string int none)) +(define-extern copy-charp<-charp + "C-string copy, writes null terminator." + (function (pointer uint8) (pointer uint8) (pointer uint8))) +(define-extern cat-string<-string + "Append a string to another." + (function string string string)) +(define-extern catn-string<-charp + "Append part of a string to another. Writes null terminator." + (function string (pointer uint8) int string)) +(define-extern cat-string<-string_to_charp + "Append part of a string to another, up to the given pointer." + (function string string (pointer uint8) (pointer uint8))) +(define-extern append-character-to-string + "Append a single character to a string. Writes null terminator after." + (function string uint8 int)) +(define-extern charp-basename + "Strip the directory and suffix from a c-string." + (function (pointer uint8) (pointer uint8))) +(define-extern clear + "Set string to the empty string." + (function string string)) +(define-extern string? + "Slightly incorrect ordering of strings." + (function string string symbol)) +(define-extern string<=? + "Slightly incorrect ordering of strings." + (function string string symbol)) +(define-extern string>=? + "Slightly incorrect ordering of strings." + (function string string symbol)) (define-extern *string-tmp-str* string) -(define-extern string-skip-to-char (function (pointer uint8) uint (pointer uint8))) -(define-extern string-cat-to-last-char (function string string uint (pointer uint8))) -(define-extern string-skip-whitespace (function (pointer uint8) (pointer uint8))) -(define-extern string-suck-up! (function string (pointer uint8) symbol)) -(define-extern string-strip-leading-whitespace! (function string symbol)) -(define-extern string-strip-trailing-whitespace! (function string symbol)) -(define-extern string-strip-whitespace! (function string symbol)) +(define-extern string-skip-to-char + "Advance to the given character." + (function (pointer uint8) uint (pointer uint8))) +(define-extern string-cat-to-last-char + "Append append-str to end of base-str, up to the last occurance of char" + (function string string uint (pointer uint8))) +(define-extern string-skip-whitespace + "Jump over whitespace chars." + (function (pointer uint8) (pointer uint8))) +(define-extern string-suck-up! + "Move the string forward so the pointer is now at the beginning." + (function string (pointer uint8) symbol)) +(define-extern string-strip-leading-whitespace! + "Strip leading whitespace." + (function string symbol)) +(define-extern string-strip-trailing-whitespace! + "String trailing whitespace." + (function string symbol)) +(define-extern string-strip-whitespace! + "Strip whitespace from the beginning and end of a string" + (function string symbol)) (define-extern string-upcase (function string string none)) (define-extern string-get-arg!! (function string string symbol)) -(define-extern string->int (function string int)) -(define-extern string->float (function string float)) +(define-extern string->int + "Convert string to int." + (function string int)) +(define-extern string->float + "Convert string to float. Finally implemented!" + (function string float)) (define-extern string-get-int32!! (function (pointer int32) string symbol)) (define-extern string-get-float!! (function (pointer float) string symbol)) (define-extern string-get-flag!! (function (pointer symbol) string string string symbol)) @@ -885,46 +1114,124 @@ :flag-assert #x900000008 ) -(define-extern truncate (function float float)) -(define-extern floor (function float float)) -(define-extern ceil (function float float)) -(define-extern integral? (function float symbol)) -(define-extern fractional-part (function float float)) -(define-extern sawtooth-wave (function float float)) -(define-extern triangle-wave (function float float)) -(define-extern log-x-plus-1-order9 (function float float)) -(define-extern logf (function float float)) -(define-extern log2f (function float float)) +(define-extern truncate + "Round (toward zero) to an integer. + @param arg0 float to truncate" + (function float float)) +(define-extern floor + "Round (down) to an integer" + (function float float)) +(define-extern ceil + "Round (up) to an integer" + (function float float)) +(define-extern integral? + "Is this number an integer?" + (function float symbol)) +(define-extern fractional-part + "Get the fractional part of a float." + (function float float)) +(define-extern sawtooth-wave + "Sample a sawtooth with period 1. In range (0, 1)" + (function float float)) +(define-extern triangle-wave + "Sample a triangle wave. Period is 4, in range (-1, 1) (so slope is 1 or -1)." + (function float float)) +(define-extern log-x-plus-1-order9 + "Fast approximation of ln(x + 1). Probably only accurate for x in [0, 1]." + (function float float)) +(define-extern logf + "Natural log." + (function float float)) +(define-extern log2f + "Log base 2." + (function float float)) (define-extern exp-slead (pointer float)) (define-extern exp-strail (pointer float)) (define-extern exp (function float float)) -(define-extern pow (function float float float)) -(define-extern print-exp (function float none)) +(define-extern pow + "Compute arg0^arg1" + (function float float float)) +(define-extern print-exp + "Print in the format AeB where A is in the range (1, 10)" + (function float none)) (define-extern print-time (function object time-frame none)) (define-extern log2 (function int int)) -(define-extern seek (function float float float float)) -(define-extern seek-ease (function float float float float float float)) -(define-extern seek-ease-in-out (function float float float float float float float float)) -(define-extern lerp (function float float float float)) -(define-extern lerp-scale-old (function float float float float float float)) +(define-extern seek + "Move arg0 toward arg1 by at most arg2." + (function float float float float)) +(define-extern seek-ease + "Move arg0 toward arg1, and slow down before reaching the end. + When farther than arg3 away, move by at most arg2. + When closer than arg3, linearly ramp down the movement amount from arg2 to 0 but no lower than arg4." + (function float float float float float float)) +(define-extern seek-ease-in-out + "Move arg0 toward arg2, and slow down at the start and end. + When within arg4 of arg1 (at the beginning of movement), ramp up speed, with a minimum speed of arg6 + When within arg5 of arg2 (at the end of movement), ramp down speed, with a minimum speed of arg5 + Normally, move at most arg3" + (function float float float float float float float float)) +(define-extern lerp + "Linearly interpolate between arg0 and arg1." + (function float float float float)) +(define-extern lerp-scale-old + "Linearly remap arg2 in [arg3, arg4] to [arg0, arg1]. + This is the jak 1 implementation, which I claimed was a bad implementation..." + (function float float float float float float)) (define-extern lerp-scale (function float float float float float float)) -(define-extern lerp-clamp (function float float float float)) -(define-extern seekl (function int int int int)) -(define-extern rand-vu-init (function float float)) +(define-extern lerp-clamp + "Linearly interpolate between arg0 and arg1. arg2 is clamped to [0, 1]" + (function float float float float)) +(define-extern seekl + "Move arg0 toward arg1, by at most arg2." + (function int int int int)) +(define-extern rand-vu-init + "Initialize the VU0 random generator." + (function float float)) (define-extern rand-vu (function float)) -(define-extern rand-vu-nostep (function float)) -(define-extern rand-vu-float-range (function float float float)) -(define-extern rand-vu-percent? (function float symbol)) -(define-extern rand-vu-int-range (function int int int)) -(define-extern rand-vu-int-count (function int int)) -(define-extern rand-vu-int-count-excluding (function int int int)) -(define-extern rand-vu-int-range-exclude (function int int int int)) +(define-extern rand-vu-nostep + "Get the number currently in the random generator. + This will be equal to the last call of (rand-vu). + This will not update the random generator." + (function float)) +(define-extern rand-vu-float-range + "Get a random float in between arg0 and arg1." + (function float float float)) +(define-extern rand-vu-percent? + "Get a boolean that's true with the given probability (in 0, 1)." + (function float symbol)) +(define-extern rand-vu-int-range + "Get an integer in the given range (inclusive)." + (function int int int)) +(define-extern rand-vu-int-count + "Get an integer in the range [0, max)." + (function int int)) +(define-extern rand-vu-int-count-excluding + "Get an integer in the range [0, arg0). + If bit n is set in arg1, exclude this value from being returned." + (function int int int)) +(define-extern rand-vu-int-range-exclude + "Get an integer in the range [0, arg0), excluding arg2. + Note that this doesn't use bits like rand-vu-int-count-excluding." + (function int int int int)) (define-extern *random-generator* random-generator) (define-extern rand-uint31-gen (function random-generator uint)) -(define-extern cube-root (function float float)) -(define-extern int-noise (function int float)) -(define-extern smooth-step (function float float)) -(define-extern smooth-interp (function float float float float float float)) +(define-extern cube-root + "Cube root with cool trick that I don't understand." + (function float float)) +(define-extern int-noise + "Generate random-ish floats in range -1, 1." + (function int float)) +(define-extern smooth-step + "Interpolate between 0, 1 with a cubic polynomial. + These are picked so f(0) = 0, f(1) = 1, f'(0) = f'(1) = 0." + (function float float)) +(define-extern smooth-interp + "Remap arg2 from (arg3, arg4) to (arg0, arg1), using cubic interpolation. + Satisfies: + - f(arg3) = arg0 + - f(arg4) = arg1 + - f'(arg3) = f'(arg4) = 0" + (function float float float float float float)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; vector-h ;; @@ -940,11 +1247,11 @@ :size-assert #xd :flag-assert #xd0000000d (:methods - (new (symbol type int) _type_) ;; 0 - (get-bit (_type_ int) symbol) ;; 9 - (clear-bit (_type_ int) int) ;; 10 - (set-bit (_type_ int) int) ;; 11 - (clear-all! (_type_) _type_) ;; 12 + (new "Allocate a new bit-array with room arg0 bits." (symbol type int) _type_) ;; 0 + (get-bit "Get the nth bit as a boolean." (_type_ int) symbol) ;; 9 + (clear-bit "Set the nth bit to 0." (_type_ int) int) ;; 10 + (set-bit "Set the nth bit to 1." (_type_ int) int) ;; 11 + (clear-all! "Set all bits to 0." (_type_) _type_) ;; 12 ) ) @@ -1339,15 +1646,36 @@ (define-extern *y-vector* vector) (define-extern *z-vector* vector) (define-extern *up-vector* vector) -(define-extern vector-dot (function vector vector float)) -(define-extern vector-dot-vu (function vector vector float)) -(define-extern vector4-dot (function vector vector float)) -(define-extern vector4-dot-vu (function vector vector float)) -(define-extern vector+! (function vector vector vector vector)) -(define-extern vector-! (function vector vector vector vector)) -(define-extern vector-zero! (function vector vector)) -(define-extern vector-reset! (function vector vector)) -(define-extern vector-copy! (function vector vector vector)) +(define-extern vector-dot + "Take the dot product of two vectors. + Only does the x, y, z compoments. + Originally handwritten assembly to space out loads and use FPU accumulator" + (function vector vector float)) +(define-extern vector-dot-vu + "Take the dot product (xyz only). Using VU0." + (function vector vector float)) +(define-extern vector4-dot + "Take the dot product of two vectors. + Does the x, y, z, and w compoments" + (function vector vector float)) +(define-extern vector4-dot-vu + "Take the dot product (xyzw). Using VU0." + (function vector vector float)) +(define-extern vector+! + "Set dst = a + b. The w component of dst is set to 0." + (function vector vector vector vector)) +(define-extern vector-! + "Set dst = a - b. The w componenent of dst is set to 0." + (function vector vector vector vector)) +(define-extern vector-zero! + "Set xyzw to 0." + (function vector vector)) +(define-extern vector-reset! + "Set vector to <0,0,0,1>." + (function vector vector)) +(define-extern vector-copy! + "Copy arg1 to arg0." + (function vector vector vector)) (define-extern vector-length< (function vector float symbol)) (define-extern vector-length> (function vector float symbol)) (define-extern *zero-vector* vector) @@ -1369,18 +1697,24 @@ :size-assert #x20 :flag-assert #x1500000020 (:methods - (add-spheres! (_type_ (inline-array sphere) int) int) ;; 9 - (add-box! (_type_ bounding-box) int) ;; 10 - (add-point! (_type_ vector) none) ;; 11 - (intersects-line-segment? (_type_ vector vector) symbol) ;; 12 - (set-from-point-offset! (_type_ vector vector) none) ;; 13 - (set-from-point-offset-pad! (_type_ vector vector float) int) ;; 14 - (set-to-point! (_type_ vector) none) ;; 15 - (set-from-sphere! (_type_ sphere) none) ;; 16 - (set-from-spheres! (_type_ (inline-array sphere) int) int) ;; 17 - (get-bounding-sphere (_type_ vector) vector) ;; 18 - (inside-xyz? (bounding-box vector) symbol) ;; 19 - (inside-xz? (bounding-box vector) symbol) ;; 20 + (add-spheres! "Add count spheres." (_type_ (inline-array sphere) int) int) ;; 9 + (add-box! "Expand the box as needed to contain the given box." (_type_ bounding-box) int) ;; 10 + (add-point! "Expand the box as needed to contain the given point." (_type_ vector) none) ;; 11 + (intersects-line-segment? + "Check intersection in xz plane, using liang-barsky. Not sure if this actually + a useful check or not..." + (_type_ vector vector) symbol) ;; 12 + (set-from-point-offset! "Set to the smallest box containing arg0, (arg0 + arg1)" (_type_ vector vector) none) ;; 13 + (set-from-point-offset-pad! "Set the box to contain arg0, arg0 + offset, with some padding." (_type_ vector vector float) int) ;; 14 + (set-to-point! "Set the box to be a single point." (_type_ vector) none) ;; 15 + (set-from-sphere! "Set the box to contain a single sphere." (_type_ sphere) none) ;; 16 + (set-from-spheres! + "Reset box to hold the given spheres. + Note: this implementation could be optimized." + (_type_ (inline-array sphere) int) int) ;; 17 + (get-bounding-sphere "Get a bounding sphere for a bounding box." (_type_ vector) vector) ;; 18 + (inside-xyz? "Is the point in the box?" (bounding-box vector) symbol) ;; 19 + (inside-xz? "Is the point in the box? Check xz only." (bounding-box vector) symbol) ;; 20 ) ) @@ -1422,6 +1756,9 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype matrix (structure) + "A 4x4 matrix, stored in row-major order. + some, but not all, functions assume that a matrix is an affine transform. + others assume that the rotation has no scale or shear (and that its inverse is its transpose)." ((data float 16 :offset-assert 0 :score -10) (vector vector 4 :inline :offset 0) (quad uint128 4 :offset 0) @@ -1431,11 +1768,15 @@ :size-assert #x40 :flag-assert #xa00000040 (:methods - (transform-vectors! (_type_ (inline-array vector) (inline-array vector) int) none) ;; 9 + (transform-vectors! "Transform many vectors. This acts like w = 1, even if it isn't. The value of w is copied." (_type_ (inline-array vector) (inline-array vector) int) none) ;; 9 ) ) (deftype matrix3 (structure) + "A 3x3 matrix, stored in row-major order. + NOTE: the rows each have an extra 4-bytes of padding, + so this is really a 3x4 matrix. + This type is rarely used." ((data float 12 :offset-assert 0 :score -10) (vector vector 3 :inline :offset 0) (quad uint128 3 :offset 0) @@ -1446,6 +1787,11 @@ ) (deftype matrix4h (structure) + "A matrix stored using 16-bit integers. + Note that these usually have different scaling for the 4th row which + contains the translation in an affine transform. + So you generally should not unpack these to floats without knowing where they came from + and how they were originally packed (for example, in tie/shrub)." ((data int16 16 :offset-assert 0) (vector4h vector4h 4 :inline :offset 0) (long int64 4 :offset 0) @@ -1455,13 +1801,14 @@ :flag-assert #x900000020 ) -(define-extern matrix-copy! (function matrix matrix matrix)) +(define-extern matrix-copy! "Copy arg1 to arg0" (function matrix matrix matrix)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; quaternion-h ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype quaternion (structure) + "Quaternion. Stored in xyzw order." ((data float 4 :offset-assert 0 :score -1) (x float :offset 0) (y float :offset 4) @@ -1482,13 +1829,19 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype euler-angles (vector) + "Just uses the same xyzw and data array as vector. + The `w` stores an integer that seems to have + bitfields for... something? Like maybe the order? + Euler angles are mostly unused, and the code is a bit of disaster." () :method-count-assert 9 :size-assert #x10 :flag-assert #x900000010 ) -(define-extern EulSafe (array int32)) +(define-extern EulSafe + "Maybe euler angle storage orders? + What is this naming convention?" (array int32)) (define-extern EulNext (array int32)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; @@ -1496,6 +1849,10 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype transform (structure) + "Transformation. w components of vectors should be 1.0 + This can represent any rotation, translation, and scaling. + Note that the scaling is applied before rotation + (meaning it scales along the axes of the pre-transformed frame)." ((trans vector :inline :offset-assert 0) (rot vector :inline :offset-assert 16) (scale vector :inline :offset-assert 32) @@ -1506,6 +1863,9 @@ ) (deftype trs (basic) + "Like transform, but it's a basic. + Note that the trsq child type overrides this rotation with a quaternion. + usage of the plain trs is very limited, at least in Jak 1." ((trans vector :inline :offset-assert 16) (rot vector :inline :offset-assert 32) (scale vector :inline :offset-assert 48) @@ -1577,6 +1937,15 @@ ) (deftype trsqv (trsq) + "A transform with: + - type information (child of [[basic]]) + - rotation stored as quaternion + - velocity information. + This is a very commonly used type to represent the position of an in-game object. + The `root` of a process-drawable (the parent 'in-game object' type) is a [[trsqv]]. + Additionally, the collision system uses [[trsqv]] as the parent type for foreground + collision objects ([[collide-shape]], [[collide-shape-moving]]). + As a result, this type has a lot of weird methods and extra stuff hidden in it." ((pause-adjust-distance meters :offset 4) (nav-radius meters :offset 8) (transv vector :inline :offset-assert 64) @@ -1604,8 +1973,13 @@ (point-toward-point-clear-roll-pitch! (_type_ vector) quaternion) ;; 20 (rot->dir-targ! (_type_) quaternion) ;; 21 (y-angle (_type_) float) ;; 22 - (global-y-angle-to-point (_type_ vector) float) ;; 23 - (relative-y-angle-to-point (_type_ vector) float) ;; 24 + (global-y-angle-to-point + "Get the angle in the xz plane from the position of this trsqv to the point arg0 + (ignores our current yaw)."(_type_ vector) float) ;; 23 + (relative-y-angle-to-point + "Get the y angle between the current orientation and arg0 + (how much we'd have to yaw to point at arg0)." + (_type_ vector) float) ;; 24 (roll-relative-to-gravity (_type_) float) ;; 25 (set-and-limit-velocity "TODO - arg1 is an bitfield of some sort" @@ -1628,197 +2002,461 @@ :flag-assert #x900000008 ) -(define-extern box-vector-enside? (function bounding-box vector symbol)) -(define-extern box-vector-inside? (function bounding-box vector symbol)) -(define-extern liang-barsky-line-clipt (function liang-barsky-line-clip-params float float symbol)) +(define-extern box-vector-enside? + "Is the point in the box? On the edge doesn't count." + (function bounding-box vector symbol)) +(define-extern box-vector-inside? + "Is the point in the box? On the edge counts." + (function bounding-box vector symbol)) +(define-extern liang-barsky-line-clipt + "Clip test in 1 dimension. Is arg1 in arg2?" + (function liang-barsky-line-clip-params float float symbol)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; matrix ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -(define-extern matrix-identity! (function matrix matrix)) +(define-extern matrix-identity! "Set dst to the identity matrix." (function matrix matrix)) (define-extern *identity-matrix* matrix) (define-extern *hermite-matrix* matrix) -(define-extern matrix+! (function matrix matrix matrix matrix)) -(define-extern matrix-! (function matrix matrix matrix matrix)) -(define-extern matrix*! (function matrix matrix matrix matrix)) -(define-extern matrixp*! (function matrix matrix matrix matrix)) -(define-extern vector-matrix*! (function vector vector matrix vector)) +(define-extern matrix+! + "Set dst = src1 + src2. It is okay for any arguments to be the same data. + This is not an efficient implementation." (function matrix matrix matrix matrix)) +(define-extern matrix-! + "Set dst = src1 - src1. It is okay for any arugments to be the same data. + This is not an efficient implementation." (function matrix matrix matrix matrix)) +(define-extern matrix*! + "Set dst = src1 * src2. It is okay for any arguments to be the same data. + This is a moderately efficient implementation." (function matrix matrix matrix matrix)) +(define-extern matrixp*! + "Set dst = src1 * src2. NOTE: this function is a wrapper around matrix*! + that adds no additional functionality. It seems to be a leftover from + a time when matrix*! wasn't safe to use in place. This is unused." (function matrix matrix matrix matrix)) +(define-extern vector-matrix*! "Set dst = vec * mat. dst may be equal to src." (function vector vector matrix vector)) (define-extern vector-rotate*! (function vector vector matrix vector)) -(define-extern vector3s-matrix*! (function vector3s vector3s matrix vector3s)) -(define-extern vector3s-rotate*! (function vector3s vector3s matrix vector3s)) -(define-extern matrix-transpose! (function matrix matrix matrix)) -(define-extern matrix-inverse-of-rot-trans! (function matrix matrix matrix)) -(define-extern matrix-4x4-inverse! (function matrix matrix matrix)) -(define-extern matrix-translate! (function matrix vector matrix)) -(define-extern matrix-translate+! (function matrix matrix vector matrix)) -(define-extern matrix-scale! (function matrix vector matrix)) -(define-extern scale-matrix! (function matrix vector matrix matrix)) -(define-extern matrix-inv-scale! (function matrix vector matrix)) -(define-extern column-scale-matrix! (function matrix vector matrix matrix)) -(define-extern matrix-rotate-x! (function matrix float matrix)) -(define-extern matrix-rotate-y! (function matrix float matrix)) -(define-extern matrix-rotate-z! (function matrix float matrix)) -(define-extern matrix-rotate-zyx! (function matrix vector matrix)) -(define-extern matrix-rotate-xyz-2! (function matrix vector matrix)) -(define-extern matrix-rotate-xyz! (function matrix vector matrix)) -(define-extern matrix-rotate-zxy! (function matrix vector matrix)) -(define-extern matrix-rotate-yxz! (function matrix vector matrix)) -(define-extern matrix-rotate-yzx! (function matrix vector matrix)) -(define-extern matrix-rotate-yxy! (function matrix vector matrix)) -(define-extern matrix-rotate-yx! (function matrix float float matrix)) -(define-extern matrix-axis-sin-cos-vu! "@unused" (function matrix vector float float none)) -(define-extern matrix-axis-sin-cos! (function matrix vector float float matrix)) -(define-extern matrix-axis-angle! (function matrix vector float matrix)) -(define-extern matrix-lerp! (function matrix matrix matrix float matrix)) -(define-extern matrix-3x3-determinant (function matrix float)) -(define-extern matrix3-determinant (function matrix float)) -(define-extern matrix-3x3-inverse! (function matrix matrix matrix)) -(define-extern matrix-3x3-inverse-transpose! (function matrix matrix matrix)) -(define-extern matrix3-inverse-transpose! (function matrix matrix matrix)) -(define-extern matrix-3x3-normalize! (function matrix matrix matrix)) -(define-extern matrix-4x4-determinant (function matrix float)) -(define-extern matrix-4x4-inverse-transpose! (function matrix matrix matrix)) -(define-extern matrix-y-angle (function matrix float)) -(define-extern matrix->trans (function matrix vector vector)) -(define-extern matrix<-trans (function matrix vector matrix)) -(define-extern matrix->scale (function matrix vector vector)) -(define-extern matrix<-scale (function matrix vector matrix)) -(define-extern matrix->quat (function matrix quaternion quaternion)) -(define-extern matrix<-quat (function matrix quaternion matrix)) -(define-extern matrix->transformq (function transformq matrix transformq)) -(define-extern matrix-mirror! (function matrix vector vector matrix)) +(define-extern vector3s-matrix*! + "Set dst to be ([src 1.0] * mat).xyz. Doesn't touch the w of dst. + dst and vec can be the same memory" + (function vector3s vector3s matrix vector3s)) +(define-extern vector3s-rotate*! + "Set dst to vec rotated by the rotation in the homogeneous transform mat. + mat should not have a scale/shear (the upper 3x3 should be a pure rotation)." + (function vector3s vector3s matrix vector3s)) +(define-extern matrix-transpose! "Set dst = src^T. src and dst can be the same." (function matrix matrix matrix)) +(define-extern matrix-inverse-of-rot-trans! + "Set dst = src^-1, assuming src is a homogeneous tranform with only rotation/translation. + NOTE: THIS FUNCTION REQUIRES dst != src" (function matrix matrix matrix)) +(define-extern matrix-4x4-inverse! + "Invert a 4x4 matrix. This assumes that the input is a homogeneous transform. + Src and dst can be the same." (function matrix matrix matrix)) +(define-extern matrix-translate! + "Set dst to a homogeneous transform with only a translation of trans." + (function matrix vector matrix)) +(define-extern matrix-translate+! + "Add the given translation to the translation of homogenous transform mat src + and store in dst. It is okay for dst = src." (function matrix matrix vector matrix)) +(define-extern matrix-scale! + "Set dst to a homogenous transform with only a scale. The x,y,z components + of scale become the x,y,z scaling factors" (function matrix vector matrix)) +(define-extern scale-matrix! + "Scale an existing matrix. Okay for dst = src. The scaling is applied per row. + This means the x component of scale is used to scale the first row of src. + The w component of scale is used." (function matrix vector matrix matrix)) +(define-extern matrix-inv-scale! + "Set dst to a homogeneous transform with only a scale. + The x,y,z components of scale are inverted and used as the x,y,z scaling factors" (function matrix vector matrix)) +(define-extern column-scale-matrix! + "Scale an existing matrix. Okay for dst = src. The scaling is applied column-wise. + Meaning the x component of scale will scale the first column of src." (function matrix vector matrix matrix)) +(define-extern matrix-rotate-x! + "Set dst to a homogeneous transform matrix for a rotation around the x-axis (degrees)." (function matrix float matrix)) +(define-extern matrix-rotate-y! + "Set dst to a homoegeneous transform matrix for a rotation around the y axis (degrees)." (function matrix float matrix)) +(define-extern matrix-rotate-z! + "Set dst to a homogeneous transform matrix for a rotation around the z-axis (degrees)." (function matrix float matrix)) +(define-extern matrix-rotate-zyx! "Rotate in z,y,x order." (function matrix vector matrix)) +(define-extern matrix-rotate-xyz-2! + "Jak 1 version of matrix-rotate-xyz. Slower than the one below." + (function matrix vector matrix)) +(define-extern matrix-rotate-xyz! "Rotate in x,y,z order." (function matrix vector matrix)) +(define-extern matrix-rotate-zxy! "Rotate in z,x,y order." (function matrix vector matrix)) +(define-extern matrix-rotate-yxz! "Rotate in y,x,z order." (function matrix vector matrix)) +(define-extern matrix-rotate-yzx! "Rotate in y,z,x order." (function matrix vector matrix)) +(define-extern matrix-rotate-yxy! + "Rotate. I believe in yxy order? Compared to the other rotations, this one + is quite a bit more optimized and avoid repeated trig operations." + (function matrix vector matrix)) +(define-extern matrix-rotate-yx! "Rotate by y then x." (function matrix float float matrix)) +(define-extern matrix-axis-sin-cos-vu! + "Create an axis-angle rotation matrix. But given the sin/cos of the angle. Uses the VU." (function matrix vector float float none)) +(define-extern matrix-axis-sin-cos! + "Create an axis-angle rotation matrix. But given the sin/cos of the angle." (function matrix vector float float matrix)) +(define-extern matrix-axis-angle! + "Create an axis-angle rotation matrix." + (function matrix vector float matrix)) +(define-extern matrix-lerp! "Lerp an entire matrix, coefficient-wise." (function matrix matrix matrix float matrix)) +(define-extern matrix-3x3-determinant "Compute the determinant of a 3x3 matrix." (function matrix float)) +(define-extern matrix3-determinant "Unused. Not sure if this has limitations compared to the above version." (function matrix float)) +(define-extern matrix-3x3-inverse! "Compute the inverse of a 3x3 matrix. Not very efficient. + Requires src != dst." (function matrix matrix matrix)) +(define-extern matrix-3x3-inverse-transpose! "Invert and transpose. + Requires dst != src." (function matrix matrix matrix)) +(define-extern matrix3-inverse-transpose! "Unused. Not sure if this has limitations compared to other version." (function matrix matrix matrix)) +(define-extern matrix-3x3-normalize! "Unused." (function matrix matrix matrix)) +(define-extern matrix-4x4-determinant + "Take the determinant of a 4x4 matrix, but this is wrong." (function matrix float)) +(define-extern matrix-4x4-inverse-transpose! + "Invert and transpose an entire 4x4. I think has no restrictions, other than dst != src. Unused. + The answer is wrong. The determinant function is wrong." (function matrix matrix matrix)) +(define-extern matrix-y-angle + "If mat has its upper 3x3 as a rotation, gets the y axis rotation." (function matrix float)) +(define-extern matrix->trans + "Multiply xyz by 1/w." + (function matrix vector vector)) +(define-extern matrix<-trans + "Set the translation." + (function matrix vector matrix)) +(define-extern matrix->scale "Get the scale of a matrix." (function matrix vector vector)) +(define-extern matrix<-scale "Set the scale of a matrix by rescaling." (function matrix vector matrix)) +(define-extern matrix->quat + "Convert matrix to quaternion, works for matrix with scale. + unlike matrix->quaternion." (function matrix quaternion quaternion)) +(define-extern matrix<-quat "Modify the rotation part of a transform." (function matrix quaternion matrix)) +(define-extern matrix->transformq + "Create a transformq from a matrix. Allowing scale, etc." (function transformq matrix transformq)) +(define-extern matrix-mirror! "Make a matrix that mirrors. Arguments are unclear." (function matrix vector vector matrix)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; transform ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -(define-extern transform-matrix-calc! (function transform matrix matrix)) -(define-extern transform-matrix-parent-calc! (function transform matrix vector matrix)) -(define-extern trs-matrix-calc! (function trs matrix matrix)) +(define-extern transform-matrix-calc! + "Convert a transform to matrix. Not efficient, and the output is the second arg." + (function transform matrix matrix)) +(define-extern transform-matrix-parent-calc! + "Convert a transform to a matrix, applying an inverse scaling." + (function transform matrix vector matrix)) +(define-extern trs-matrix-calc! + "Convert a trs to a matrix." + (function trs matrix matrix)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; quaternion ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -(define-extern quaternion-axis-angle! (function quaternion float float float float quaternion)) -(define-extern quaternion-vector-angle! (function quaternion vector float quaternion)) -(define-extern vector-angle<-quaternion! (function vector quaternion vector)) -(define-extern quaternion-look-at! (function quaternion vector vector quaternion)) -(define-extern quaternion-zero! (function quaternion quaternion)) -(define-extern quaternion-identity! (function quaternion quaternion)) -(define-extern quaternion-i! (function quaternion quaternion)) -(define-extern quaternion-j! (function quaternion quaternion)) -(define-extern quaternion-k! (function quaternion quaternion)) -(define-extern quaternion-copy! (function quaternion quaternion quaternion)) -(define-extern quaternion-set! (function quaternion float float float float quaternion)) -(define-extern quaternion+! (function quaternion quaternion quaternion quaternion)) -(define-extern quaternion-! (function quaternion quaternion quaternion quaternion)) -(define-extern quaternion-negate! (function quaternion quaternion quaternion)) -(define-extern quaternion-conjugate! (function quaternion quaternion quaternion)) -(define-extern quaternion-float*! (function quaternion quaternion float quaternion)) -(define-extern quaternion-float/! (function quaternion quaternion float quaternion)) -(define-extern quaternion-norm2 (function quaternion float)) -(define-extern quaternion-norm (function quaternion float)) -(define-extern quaternion-normalize! (function quaternion quaternion)) -(define-extern quaternion-inverse! (function quaternion quaternion quaternion)) -(define-extern quaternion-dot (function quaternion quaternion float)) -(define-extern quaternion*! (function quaternion quaternion quaternion quaternion)) -(define-extern quaternion-right-mult-matrix! (function matrix quaternion matrix)) -(define-extern quaternion-left-mult-matrix! (function matrix quaternion matrix)) -(define-extern quaternion->matrix (function matrix quaternion matrix)) -(define-extern quaternion->matrix-2 (function matrix quaternion matrix)) -(define-extern matrix->quaternion (function quaternion matrix quaternion)) -(define-extern matrix-with-scale->quaternion (function quaternion matrix quaternion)) -(define-extern quaternion-vector-len (function quaternion float)) -(define-extern quaternion-log! (function quaternion quaternion quaternion)) -(define-extern quaternion-exp! (function quaternion quaternion quaternion)) -(define-extern quaternion-slerp! (function quaternion quaternion quaternion float quaternion)) -(define-extern quaternion-pseudo-slerp! (function quaternion quaternion quaternion float quaternion)) -(define-extern quaternion-pseudo-seek (function quaternion quaternion quaternion float quaternion)) -(define-extern quaternion-smooth-seek! (function quaternion quaternion quaternion float quaternion)) -(define-extern quaternion-zxy! (function quaternion vector quaternion)) -(define-extern vector-x-quaternion! (function vector quaternion vector)) -(define-extern vector-y-quaternion! (function vector quaternion vector)) -(define-extern vector-z-quaternion! (function vector quaternion vector)) -(define-extern quaternion-x-angle (function quaternion float)) -(define-extern quaternion-y-angle (function quaternion float)) -(define-extern quaternion-z-angle (function quaternion float)) -(define-extern quaternion-vector-y-angle (function quaternion vector float)) -(define-extern quaternion-rotate-local-x! (function quaternion quaternion float quaternion)) -(define-extern quaternion-rotate-local-y! (function quaternion quaternion float quaternion)) -(define-extern quaternion-rotate-local-z! (function quaternion quaternion float quaternion)) -(define-extern quaternion-rotate-y! (function quaternion quaternion float quaternion)) -(define-extern quaternion-rotate-x! (function quaternion quaternion float quaternion)) -(define-extern quaternion-rotate-z! (function quaternion quaternion float quaternion)) -(define-extern quaternion-delta-y (function quaternion quaternion float)) +(define-extern quaternion-axis-angle! + "Construct a quaternion from an axis and angle. The axis should be normalized." + (function quaternion float float float float quaternion)) +(define-extern quaternion-vector-angle! + "Construct a quaternion from an axis and angle. The axis should be normalized." + (function quaternion vector float quaternion)) +(define-extern vector-angle<-quaternion! + "Convert the quaternion arg1 to axis-angle form and store in arg0 (angle goes in w)" + (function vector quaternion vector)) +(define-extern quaternion-look-at! "Look along arg1, with arg2 as up." (function quaternion vector vector quaternion)) +(define-extern quaternion-zero! + "Set quaternion to all 0's." + (function quaternion quaternion)) +(define-extern quaternion-identity! + "Set quaternion to 0,0,0,1 (identity)." + (function quaternion quaternion)) +(define-extern quaternion-i! + "Create unit i quaternion." + (function quaternion quaternion)) +(define-extern quaternion-j! + "Create unit j quaternion." + (function quaternion quaternion)) +(define-extern quaternion-k! + "Create unit k quaternion." + (function quaternion quaternion)) +(define-extern quaternion-copy! + "Set arg0 = arg1." + (function quaternion quaternion quaternion)) +(define-extern quaternion-set! + "Set arg0 = [arg1, arg2, arg3, arg4]." + (function quaternion float float float float quaternion)) +(define-extern quaternion+! + "Add quaternions as vectors." + (function quaternion quaternion quaternion quaternion)) +(define-extern quaternion-! + "Subtract quaternions as vectors." + (function quaternion quaternion quaternion quaternion)) +(define-extern quaternion-negate! + "Set arg0 = -arg1." + (function quaternion quaternion quaternion)) +(define-extern quaternion-conjugate! + "Set arg0 to the conjugate of arg1 (negate only ijk). + If arg1 is normalized, this is equivalent to the inverse + NOTE: this gives you the inverse rotation." + (function quaternion quaternion quaternion)) +(define-extern quaternion-float*! + "Multiply each element." + (function quaternion quaternion float quaternion)) +(define-extern quaternion-float/! + "Divide each element." + (function quaternion quaternion float quaternion)) +(define-extern quaternion-norm2 + "Get the squared norm of a quaternion." + (function quaternion float)) +(define-extern quaternion-norm "Get the norm of a quaternion." (function quaternion float)) +(define-extern quaternion-normalize! + "Normalize a quaternion." + (function quaternion quaternion)) +(define-extern quaternion-inverse! + "Invert a quaternion. The inverse will satisfy q * q^-1 = identity, even if q is not normalized. + If your quaternion is normalized, it is faster/more accurate to do quaternion-conjugate!" + (function quaternion quaternion quaternion)) +(define-extern quaternion-dot + "Treat quaternions as vectors and take the dot product." + (function quaternion quaternion float)) +(define-extern quaternion*! + "Real quaternion multiplication." + (function quaternion quaternion quaternion quaternion)) +(define-extern quaternion-right-mult-matrix! + "Place quaternion coefficients into a matrix. + You can convert a quaternion to a matrix by taking the product of this + right-mult and left-mult matrix, but this method is not used. + Instead, quaternion->matrix is a more efficient implementation." (function matrix quaternion matrix)) +(define-extern quaternion-left-mult-matrix! + "Place quaternion coefficients into a matrix. Unused." (function matrix quaternion matrix)) +(define-extern quaternion->matrix "Convert quaternion to matrix." (function matrix quaternion matrix)) +(define-extern quaternion->matrix-2 "Unused alternate quaternion->matrix function." (function matrix quaternion matrix)) +(define-extern matrix->quaternion "Convert a rotation matrix to a quaternion." (function quaternion matrix quaternion)) +(define-extern matrix-with-scale->quaternion + "Convert a matrix with a rotation and scale into a quaternion (just the rotation)." (function quaternion matrix quaternion)) +(define-extern quaternion-vector-len + "Assuming quaternion is normalized, get the length of the xyz part." + (function quaternion float)) +(define-extern quaternion-log! + "Take the log of a quaternion. Unused." + (function quaternion quaternion quaternion)) +(define-extern quaternion-exp! + "Quaternion exponentiation. Unused." + (function quaternion quaternion quaternion)) +(define-extern quaternion-slerp! + "Real quaternion slerp. Spherical-linear interpolation is a nice way to interpolate + between quaternions." + (function quaternion quaternion quaternion float quaternion)) +(define-extern quaternion-pseudo-slerp! + "This is a bad interpolation between quaternions. It lerps then normalizes. + It will behave extremely poorly for 180 rotations. + It is unused." + (function quaternion quaternion quaternion float quaternion)) +(define-extern quaternion-pseudo-seek + "Seek one quaternion toward another. Not using real slerp, so this is only good if the quaternions + are pretty similar." + (function quaternion quaternion quaternion float quaternion)) +(define-extern quaternion-smooth-seek! "Another hacky rotation interpolation." (function quaternion quaternion quaternion float quaternion)) +(define-extern quaternion-zxy! + "Make a quaternion from a sequence of z, x, y axis rotations." + (function quaternion vector quaternion)) +(define-extern vector-x-quaternion! + "Get the first row of the rotation matrix for this quaternion." + (function vector quaternion vector)) +(define-extern vector-y-quaternion! + "Get the second row of the rotation matrix for this quaternion." + (function vector quaternion vector)) +(define-extern vector-z-quaternion! + "Get the third row of the rotation matrix for this quaternion." + (function vector quaternion vector)) +(define-extern quaternion-x-angle + "Get the x rotation angle. Not very efficient." + (function quaternion float)) +(define-extern quaternion-y-angle + "Get the y rotation angle. Not very efficient." + (function quaternion float)) +(define-extern quaternion-z-angle + "Get the z rotation angle. Not very efficient." + (function quaternion float)) +(define-extern quaternion-vector-y-angle + "Not sure. Angle between quaternion and axis, projected in xz plane?" + (function quaternion vector float)) +(define-extern quaternion-rotate-local-x! + "Rotate existing quaternion along x axis." + (function quaternion quaternion float quaternion)) +(define-extern quaternion-rotate-local-y! + "Rotate existing quaternion along y axis." + (function quaternion quaternion float quaternion)) +(define-extern quaternion-rotate-local-z! + "Rotate existing quaternion along z axis." + (function quaternion quaternion float quaternion)) +(define-extern quaternion-rotate-y! + "Rotate existing quaternion along y axis (right multiply)." + (function quaternion quaternion float quaternion)) +(define-extern quaternion-rotate-x! + "Rotate existing quaternion along x axis (right multiply)." + (function quaternion quaternion float quaternion)) +(define-extern quaternion-rotate-z! + "Rotate existing quaternion along z axis (right multiply)." + (function quaternion quaternion float quaternion)) +(define-extern quaternion-delta-y + "Difference in yaw between two quaternions." + (function quaternion quaternion float)) (define-extern quaternion-rotate-y-to-vector! (function quaternion quaternion quaternion float quaternion)) -(define-extern vector-rotate-x! (function vector vector float vector)) -(define-extern vector-rotate-y! (function vector vector float vector)) -(define-extern vector-rotate-z! (function vector vector float vector)) -(define-extern vector-y-angle (function vector float)) -(define-extern vector-x-angle (function vector float)) -(define-extern quaternion<-rotate-y-vector (function quaternion vector quaternion)) -(define-extern quaternion-validate (function quaternion none)) -(define-extern quaternion-xz-angle (function quaternion float)) +(define-extern vector-rotate-x! "Rotate vector along x axis." (function vector vector float vector)) +(define-extern vector-rotate-y! "Rotate vector along y axis." (function vector vector float vector)) +(define-extern vector-rotate-z! "Rotate vector along z axis." (function vector vector float vector)) +(define-extern vector-y-angle + "Get the yaw angle of a vector." + (function vector float)) +(define-extern vector-x-angle + "Get the pitch angle of a vector." + (function vector float)) +(define-extern quaternion<-rotate-y-vector + "Create a quaternion representing only the yaw of the given vector." + (function quaternion vector quaternion)) +(define-extern quaternion-validate + "Verify that a quaternion is valid, print an error if the length is off by more than 1%.." + (function quaternion none)) +(define-extern quaternion-xz-angle + "Yet another function to compute the yaw of a quaternion. This is a particularly inefficient version." + (function quaternion float)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; euler ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -(define-extern set-eul! (function euler-angles float float float int euler-angles)) -(define-extern eul->matrix (function matrix euler-angles matrix)) -(define-extern matrix->eul (function euler-angles matrix int euler-angles)) -(define-extern eul->quat (function quaternion euler-angles quaternion)) -(define-extern quat->eul (function euler-angles quaternion int euler-angles)) +(define-extern set-eul! + "Set euler angles and the flag bits." + (function euler-angles float float float int euler-angles)) +(define-extern eul->matrix + "Convert from euler angles to 4x4 matrix." + (function matrix euler-angles matrix)) +(define-extern matrix->eul + "Convert matrix to euler angles with given order flag. + Not clear how this works if the matrix has more than just a rotation." + (function euler-angles matrix int euler-angles)) +(define-extern eul->quat + "Convert euler angles to quaternion, not very efficient." + (function quaternion euler-angles quaternion)) +(define-extern quat->eul + "Convert quaternion to euler angles with given order, not very efficient." + (function euler-angles quaternion int euler-angles)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; trigonometry ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -(define-extern radmod (function float float)) -(define-extern deg- (function float float float)) -(define-extern deg-diff (function float float float)) -(define-extern deg-seek (function float float float float)) -(define-extern deg-seek-smooth (function float float float float float)) -(define-extern deg-lerp-clamp (function float float float float)) +(define-extern radmod + "Wrap arg0 to be within (-pi, pi)." + (function float float)) +(define-extern deg- + "Compute arg0-arg1, unwrapped, using rotation units. + Result should be in the range (-180, 180)" + (function float float float)) +(define-extern deg-diff + "Very similar to the function above, but computes arg1 - arg0 instead." + (function float float float)) +(define-extern deg-seek + "Move in toward target by at most max-diff, using rotation units" + (function float float float float)) +(define-extern deg-seek-smooth + "Step amount of the way from in to target, by at most max-diff, using rotation units" + (function float float float float float)) +(define-extern deg-lerp-clamp + "Map [0, 1] to min-val, max-val, handling wrapping and saturating, using rotation units." + (function float float float float)) (define-extern binary-table (array float)) (define-extern sincos-table (array float)) -(define-extern sin (function float float)) -(define-extern sin-rad (function float float)) +(define-extern sin + "Compute the sine of an angle in rotation units. Unwraps it." (function float float)) +(define-extern sin-rad + "Compute the sine of an angle in radians. + No unwrap is done, should be in -pi, pi" (function float float)) (define-extern *sin-poly-vec* vector) (define-extern *sin-poly-vec2* vector) -(define-extern vector-sin-rad! (function vector vector vector)) -(define-extern cos-rad (function float float)) +(define-extern vector-sin-rad! + "Taylor series approximation of sine on all 4 elements in a vector. + Inputs should be in radians, in -pi to pi. + Somehow their coefficients are a little bit off. + Like the first coefficient, which should obviously be 1, is not quite 1." + (function vector vector vector)) +(define-extern cos-rad + "Cosine with taylor series. Input is in radians, in -pi, pi. + - TODO constants" (function float float)) (define-extern *cos-poly-vec* vector) -(define-extern vector-cos-rad! (function vector vector vector)) -(define-extern vector-sincos-rad! (function vector vector vector int)) -(define-extern sincos-rad! (function vector float int)) -(define-extern sincos! (function vector float int)) -(define-extern vector-rad<-vector-deg! (function vector vector none)) -(define-extern vector-rad<-vector-deg/2! (function vector vector int)) -(define-extern vector-sincos! (function vector vector vector int)) -(define-extern tan-rad (function float float)) -(define-extern cos (function float float)) -(define-extern tan (function float float)) -(define-extern atan0 (function float float float)) -(define-extern atan-series-rad (function float float)) -(define-extern atan-rad (function float float)) -(define-extern sign-bit (function int int)) -(define-extern sign-float (function float float)) -(define-extern sign (function float float)) -(define-extern atan2-rad (function float float float)) -(define-extern atan (function float float float)) -(define-extern asin (function float float)) -(define-extern acos (function float float)) -(define-extern acos-rad (function float float)) -(define-extern sinerp (function float float float float)) -(define-extern sinerp-clamp (function float float float float)) -(define-extern coserp (function float float float float)) -(define-extern coserp-clamp (function float float float float)) -(define-extern coserp180 (function float float float float)) -(define-extern coserp180-clamp (function float float float float)) -(define-extern ease-in-out (function int int float)) +(define-extern vector-cos-rad! + "Compute the cosine of all 4 vector elements. + Radians, with no wrapping. Uses taylor series with 4 coefficients." + (function vector vector vector)) +(define-extern vector-sincos-rad! + "Compute the sine and cosine of each element of src, storing it in dst-sin and dst-cos. + This is more efficient than separate calls to sin and cos. + Inputs should be radians in -pi to pi." + (function vector vector vector int)) +(define-extern sincos-rad! + "Compute the sine and cosine of x, store it in the output array. + Has the cosine bug." (function vector float int)) +(define-extern sincos! + "Compute the sine and cosine of x, store it in the output array. + The input is in rotation units, and is unwrapped properly. + Also has the cosine bug" (function vector float int)) +(define-extern vector-rad<-vector-deg! + "Convert a vector in rotation units to radians, and unwrap. + Input can be anything, output will be -2pi to pi." + (function vector vector none)) +(define-extern vector-rad<-vector-deg/2! + "Divide the input by two, and then convert from rotation units to radians, unwrapping. + Not sure why this really needs to be separate the from previous function..." + (function vector vector int)) +(define-extern vector-sincos! + "Compute sine and cosine of each element in a vector, in rotation units" + (function vector vector vector int)) +(define-extern tan-rad + "This function appears to be named wrong and actually operates on rotation units." + (function float float)) +(define-extern cos "Cosine of rotation units." (function float float)) +(define-extern tan "Correctly named tangent of rotation units." (function float float)) +(define-extern atan0 + "Inverse tangent, to rotation units. y,x order. Does not handle signs correctly. + Do not use this function directly, instead use atan2." (function float float float)) +(define-extern atan-series-rad "A helper function for atan." (function float float)) +(define-extern atan-rad + "Inverse tangent in radians." + (function float float)) +(define-extern sign-bit + "Return 1 if bit 31 is set, otherwise 0." + (function int int)) +(define-extern sign-float + "Return 1 if arg0 is positive or zero, -1 otherwise. + Fast (no branching)." (function float float)) +(define-extern sign + "Similar to above, but returns 0 if input is 0. + But is more complicated." (function float float)) +(define-extern atan2-rad + "Atan for radians." + (function float float float)) +(define-extern atan "Atan for rotation units. Signs behave like atan.." (function float float float)) +(define-extern asin + "Inverse sine, rotation units." + (function float float)) +(define-extern acos + "Inverse cosine. Returns rotation units." + (function float float)) +(define-extern acos-rad + "Inverse cosine, radians." + (function float float)) +(define-extern sinerp + "Map amount to min,max using sine. Kinda weird, usually people use cosine." + (function float float float float)) +(define-extern sinerp-clamp + "Like sinerp, but clamp to min,max." + (function float float float float)) +(define-extern coserp + "Weird lerp with cosine (over 90 degrees?)." + (function float float float float)) +(define-extern coserp-clamp + "Weird 90 degree lerp with cosine, clamped to min,max." + (function float float float float)) +(define-extern coserp180 + "Classic lerp with cosine." + (function float float float float)) +(define-extern coserp180-clamp + "Classic coserp with saturation." + (function float float float float)) +(define-extern ease-in-out + "Weird coserp like mapping from 0 to 1 as progress goes from 0 to total." + (function int int float)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; gsound-h ;; @@ -2266,11 +2904,11 @@ :size-assert #x6c :flag-assert #x100000006c (:methods - (new (symbol type basic vector) _type_) ;; 0 - (update! (_type_) int) ;; 9 - (change-sound! (_type_ sound-name) int) ;; 10 - (update-trans! (_type_ vector) int) ;; 11 - (update-vol! (_type_ float) int) ;; 12 + (new "Set up ambient-sound. Can use an entity-actor (grabs from lump), sound-spec, or name as a string." (symbol type basic vector) _type_) ;; 0 + (update! "Per-frame update of ambient sound." (_type_) int) ;; 9 + (change-sound! "Change the sound being played." (_type_ sound-name) int) ;; 10 + (update-trans! "Change the trans of the sound." (_type_ vector) int) ;; 11 + (update-vol! "Change the volume of the sound." (_type_ float) int) ;; 12 (update-pitch-mod! (_type_ float) none) ;; 13 (set-falloff-far! (_type_ float) none) ;; 14 (stop! (_type_) int) ;; 15 @@ -2292,6 +2930,8 @@ ) (deftype timer-mode (uint32) + "This matches the Tn_MODE register structure of the ps2 EE timers. + Only the lower 32 bits of these registers are usable, and the upper 16 hardwired to zero." ((clks timer-clock-selection :offset 0 :size 2) (gate uint8 :offset 2 :size 1) ;; gate function enable (gats uint8 :offset 3 :size 1) ;; gate selection: 0 = hblank, 1 = vblank @@ -2314,6 +2954,9 @@ ) (deftype timer-bank (structure) + "This matches an EE timer (without a HOLD register, timers 2 and 3). + Each register is 128-bits wide, but only the lower 32-bits are usable, and the upper + 16-bits of that are hardwired to zero." ((count uint32 :offset-assert 0) (mode timer-mode :offset 16) (comp uint32 :offset 32) @@ -2324,6 +2967,7 @@ ) (deftype timer-hold-bank (timer-bank) + "This matches an EE timer (with a HOLD register, timers 0 and 1)." ((hold uint32 :offset 48) ) :method-count-assert 9 @@ -2332,6 +2976,9 @@ ) (deftype stopwatch (basic) + "Stopwatches are used to measure CPU clock cycles. + They don't use the timer above, but instead the Count COP0 register, + which counts CPU clock cycles directly." ((prev-time-elapsed time-frame :offset-assert 8) (start-time time-frame :offset-assert 16) (begin-level int32 :offset-assert 24) @@ -2342,7 +2989,9 @@ ) (define-extern *ticks-per-frame* int) -(define-extern timer-init (function timer-bank timer-mode int)) +(define-extern timer-init + "Initiate a timer, start counting at a rate of 1 every 256 bus clocks (BUSCLK: ~147.456MHz)." + (function timer-bank timer-mode int)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; vif-h ;; @@ -2421,6 +3070,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype dma-chcr (uint32) + "Memory mapped DMA channel control register. Typically used to start and check on DMA transfer." ((dir uint8 :offset 0 :size 1) ;; 1 - from memory (mod uint8 :offset 2 :size 2) ;; normal, chain, interleave (asp uint8 :offset 4 :size 2) ;; none, 1, 2 @@ -2435,6 +3085,7 @@ ) (deftype dma-bank (structure) + "Bank of memory mapped DMA registers for a single channel. Used to control DMA." ((chcr dma-chcr :offset 0) (madr uint32 :offset 16) (qwc uint32 :offset 32) @@ -2445,6 +3096,7 @@ ) (deftype dma-bank-source (dma-bank) + "DMA channel registers for a DMA channel supporting source-chain." ((tadr uint32 :offset 48) ) :method-count-assert 9 @@ -2453,6 +3105,7 @@ ) (deftype dma-bank-vif (dma-bank-source) + "DMA channel registers for a DMA channel with call/ret stack." ((as0 uint32 :offset 64) (as1 uint32 :offset 80) ) @@ -2462,6 +3115,7 @@ ) (deftype dma-bank-spr (dma-bank-source) + "DMA channel registers for a DMA channel supporting scratchpad transfer." ((sadr uint32 :offset 128) ) :method-count-assert 9 @@ -2470,6 +3124,7 @@ ) (deftype dma-ctrl (uint32) + "Main DMA control register, shared for all channels." ((dmae uint8 :offset 0 :size 1) (rele uint8 :offset 1 :size 1) (mfd uint8 :offset 2 :size 2) @@ -2495,6 +3150,7 @@ ) (deftype dma-bank-control (structure) + "Memory mapping for shared DMA registers." ((ctrl dma-ctrl :offset 0) (stat uint32 :offset 16) (pcr uint32 :offset 32) @@ -2511,6 +3167,7 @@ ) (deftype vu-code-block (basic) + "Unused type for some VU code. vu-function is used instead." ((name basic :offset-assert 4) (code uint32 :offset-assert 8) (size int32 :offset-assert 12) @@ -2541,6 +3198,7 @@ ) (deftype dma-tag (uint64) + "The 64-bit tag used by the DMA system." ((qwc uint16 :offset 0) ;; quadword count (pce uint8 :offset 26 :size 2) ;; priority (source mode) (id dma-tag-id :offset 28 :size 3) ;; ID (what the tag means) @@ -2554,6 +3212,7 @@ ) (deftype dma-bucket (structure) + "A linked list of DMA data, typically all in the same category. Used to organize the full DMA chain." ((tag dma-tag :offset-assert 0) (last (pointer dma-tag) :offset-assert 8) (dummy uint32 :offset-assert 12) @@ -2639,6 +3298,7 @@ ) (deftype vif-stcycl-imm (uint16) + "The imm field of a VIF code using STCYCL, which adjusts the pattern for storing data." ((cl uint8 :offset 0 :size 8) (wl uint8 :offset 8 :size 8) ) @@ -2646,6 +3306,7 @@ ) (deftype vif-unpack-imm (uint16) + "The imm field of a VIF code using UNPACK, which transfers data to VU memory." ((addr uint16 :offset 0 :size 10) (usn uint8 :offset 14 :size 1) (flg uint8 :offset 15 :size 1) @@ -2654,6 +3315,7 @@ ) (deftype vif-tag (uint32) + "A tag consumed by the VIF, which accepts DMA data." ((imm uint16 :offset 0 :size 16) (num uint8 :offset 16 :size 8) (cmd vif-cmd :offset 24 :size 7) @@ -2675,6 +3337,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype video-params (structure) + "Parameters for the framebuffer." ((set-video-mode symbol :offset-assert 0) (reset-video-mode symbol :offset-assert 4) (display-fbp int32 :offset-assert 8) @@ -3181,6 +3844,7 @@ (deftype dma-foreground-sink (basic) +"A specification for where a foreground renderer should output its DMA data." ((bucket bucket-id :offset-assert 4) (foreground-texture-page tpage-category :offset-assert 8) (foreground-texture-level int8 :offset-assert 9) @@ -3192,6 +3856,9 @@ ) (deftype generic-bucket-state (structure) +"The state of buffers for the generic renderer. +When generating generic DMA data, you must know the previous state +of the VU's memory to properly double-buffer the input and output data." ((gifbuf-adr uint32 :offset-assert 0) (inbuf-adr uint32 :offset-assert 4) ) @@ -3202,6 +3869,8 @@ ) (deftype generic-dma-foreground-sink (dma-foreground-sink) +"A specification for where a foreground generic renderer should output DMA data, +and the state of the VU memory buffers at the end of the bucket." ((state generic-bucket-state :inline :offset-assert 12) ) :method-count-assert 9 @@ -3214,6 +3883,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype profile-segment (structure) +"Confusingly, this has two uses. Either a single event, or a summary of all events within a category." ((name symbol :offset-assert 0) (start-time int16 :offset-assert 4) (end-time int16 :offset-assert 6) @@ -3232,6 +3902,7 @@ (deftype profile-collapse (structure) +"An array of 'summaries'. Each entry in data is a summary of all events within a category." ((count int32 :offset-assert 0) (data profile-segment 48 :inline :offset-assert 4) ) @@ -3242,6 +3913,7 @@ (deftype profile-segment-array (basic) +"All profiling data for a frame, stored as a tree of events. There is one for the VU, and one for the EE." ((count int16 :offset-assert 4) (depth int8 :offset-assert 6) (max-depth int8 :offset-assert 7) @@ -3253,25 +3925,26 @@ :size-assert #x2030 :flag-assert #xd00002030 (:methods - (get-total-time (_type_) int) ;; 9 - (start-frame! (_type_) none) ;; 10 - (start-segment! (_type_ symbol rgba) none) ;; 11 - (end-segment! (_type_) none) ;; 12 + (get-total-time "Get the duration of the top-level event (typically, the whole frame)" (_type_) int) ;; 9 + (start-frame! "Restart the profiler for the start of a frame." (_type_) none) ;; 10 + (start-segment! "Start an event." (_type_ symbol rgba) none) ;; 11 + (end-segment! "Stop the most recently started event." (_type_) none) ;; 12 ) ) (declare-type dma-buffer structure) (deftype profile-array (structure) +"The EE and VU profilers, and the drawing code." ((data profile-segment-array 2 :offset-assert 0) ;; guess ) :method-count-assert 12 :size-assert #x8 :flag-assert #xc00000008 (:methods - (setup-categories! (_type_) none) ;; 9 - (draw-bars! (_type_ dma-buffer int) none) ;; 10 - (draw-text! (_type_) none) ;; 11 + (postprocess-data! "Create the collapsed summary of the collected data." (_type_) none) ;; 9 + (draw-bars! "Generate DMA data for drawing the profile bars." (_type_ dma-buffer int) none) ;; 10 + (draw-text! "Generate DMA data for drawing the profile information screen." (_type_) none) ;; 11 ) ) @@ -3344,6 +4017,7 @@ (deftype dma-packet (structure) +"The header for a DMA transfer, containing an DMA tag, and VIF tags." ((dma dma-tag :offset-assert 0) (vif0 vif-tag :offset-assert 8) (vif1 vif-tag :offset-assert 12) @@ -3355,6 +4029,7 @@ ) (deftype dma-packet-array (inline-array-class) +"Unused dma array. Unclear how it should be used." ((data dma-packet :inline :dynamic :offset-assert 16) ) :method-count-assert 9 @@ -3363,6 +4038,7 @@ ) (deftype dma-gif (structure) +"Believed unused GIF header type." ((gif uint64 2 :offset-assert 0) (quad uint128 :offset 0) ;; added these two @@ -3375,6 +4051,7 @@ ) (deftype dma-gif-packet (structure) +"The header for a DMA transfer that goes directly to GIF, containing DMA, VIF, GIF tags." ((dma-vif dma-packet :inline :offset-assert 0) (gif uint64 2 :offset-assert 16 :score -1) ;; added these two @@ -3389,6 +4066,7 @@ (deftype dma-buffer (basic) +"A buffer for DMA data." ((allocated-length int32 :offset-assert 4) (base pointer :offset-assert 8) (end pointer :offset-assert 12) @@ -3404,20 +4082,34 @@ ) -(define-extern dma-buffer-inplace-new (function dma-buffer int dma-buffer)) -(define-extern dma-buffer-length (function dma-buffer int)) -(define-extern dma-buffer-free (function dma-buffer int)) +(define-extern dma-buffer-inplace-new + "Create a dma-buffer in-place. Does not set the type of the dma-buffer object." + (function dma-buffer int dma-buffer)) +(define-extern dma-buffer-length + "Get length used in quadwords, rounded up." + (function dma-buffer int)) +(define-extern dma-buffer-free + "Get the number of free quadwords between base and end pointers." + (function dma-buffer int)) (define-extern dma-buffer-add-vu-function (function dma-buffer vu-function int symbol)) -(define-extern dma-buffer-send (function dma-bank dma-buffer none)) -(define-extern dma-buffer-send-chain (function dma-bank-source dma-buffer none)) +(define-extern dma-buffer-send + "Send the DMA buffer! DOES NOT TRANSFER TAG, you probably want dma-buffer-send-chain instead." + (function dma-bank dma-buffer none)) +(define-extern dma-buffer-send-chain + "Send the DMA buffer! Sends the tags, so this is suitable for the main graphics chain." + (function dma-bank-source dma-buffer none)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; dma-bucket ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -(define-extern dma-buffer-add-buckets (function dma-buffer int (inline-array dma-bucket))) -(define-extern dma-buffer-patch-buckets (function (inline-array dma-bucket) int (inline-array dma-bucket))) -(define-extern dma-bucket-insert-tag (function (inline-array dma-bucket) bucket-id pointer (pointer dma-tag) pointer)) +(define-extern dma-buffer-add-buckets + "Initialize an array of dma-buckets in a DMA buffer." + (function dma-buffer int (inline-array dma-bucket))) +(define-extern dma-buffer-patch-buckets "Patch together DMA buckets after they have been filled." (function (inline-array dma-bucket) int (inline-array dma-bucket))) +(define-extern dma-bucket-insert-tag + "Add a dma chain to the bucket." + (function (inline-array dma-bucket) bucket-id pointer (pointer dma-tag) pointer)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; dma-disasm ;; @@ -3437,11 +4129,16 @@ ) (define-extern *vif-disasm-table* (array vif-disasm-element)) -(define-extern disasm-vif-details (function symbol (pointer uint8) vif-cmd int symbol)) -(define-extern disasm-vif-tag (function (pointer vif-tag) int symbol symbol int)) -(define-extern disasm-dma-tag (function dma-tag symbol none)) +(define-extern disasm-vif-details "Disassemble the data stored in a vif unpack." (function symbol (pointer uint8) vif-cmd int symbol)) +(define-extern disasm-vif-tag "Disassemble vif tag, and possibly the associated data." (function (pointer vif-tag) int symbol symbol int)) +(define-extern disasm-dma-tag + "Disassemble just the 64-byte dma tag" + (function dma-tag symbol none)) (define-extern *dma-disasm* symbol) -(define-extern disasm-dma-list (function dma-packet symbol symbol symbol int symbol)) +(define-extern disasm-dma-list "Print out an entire DMA list. + If mode is #t, print vif tags too. If mode is 'details, also print data unpacked by vif-tags. + If verbose is #t, print out the addresses of each tag, and total size statistics. + If expected size is negative, it is ignored. Otherwise, only disassemble this much dma data." (function dma-packet symbol symbol symbol int symbol)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; pad ;; @@ -3504,6 +4201,8 @@ (define-extern scf-get-time (function scf-time none)) (deftype hw-cpad (basic) +"Data that comes directly from hardware. +It's 32 bytes + type tag (ignored by C kernel)." ((valid uint8 :offset-assert 4) (status uint8 :offset-assert 5) (button0 uint16 :offset-assert 6) @@ -3520,6 +4219,7 @@ ) (deftype cpad-info (hw-cpad) +"Data from hardware + additional info calculated here." ((number int32 :offset-assert 36) (cpad-file int32 :offset-assert 40) (button0-abs pad-buttons 3 :offset-assert 44) ;; guessed by decompiler @@ -3547,17 +4247,19 @@ :size-assert #x90 :flag-assert #xa00000090 (:methods - (new (symbol type int) _type_) ;; 0 + (new "Allocate a new cpad-info and open the pad itself through the kernel." (symbol type int) _type_) ;; 0 (adjust-to-screen-flip (_type_) int) ;; 9 ) ) (deftype cpad-list (basic) +"List of controllers. It always has two controllers." ((num-cpads int32 :offset-assert 4) (cpads cpad-info 2 :offset-assert 8) ) (:methods - (new (symbol type) _type_) ;; 0 + (new "Create a cpad-list for 2 controllers. It's fine to do this even if one or both controllers + aren't connected yet." (symbol type) _type_) ;; 0 ) :method-count-assert 9 :size-assert #x10 @@ -3595,15 +4297,28 @@ ) (define-extern *cheat-mode* symbol) -(define-extern cpad-invalid! (function cpad-info cpad-info)) -(define-extern analog-input (function int float float float float float)) -(define-extern cpad-set-buzz! (function cpad-info int int time-frame none)) +(define-extern cpad-invalid! + "Reset all data in a [[cpad-info]]." + (function cpad-info cpad-info)) +(define-extern analog-input + "Convert integer input from pad into a float between -out-range and +out-range. + The offset is applied directly to the input. + The center val is the expected value for 0, after applying offset. + The max val is the expected value with the stick pushed all the way." + (function int float float float float float)) +(define-extern cpad-set-buzz! + "Turn on vibration motor `buzz-idx` for duration, at magnitude `buzz-amount`." + (function cpad-info int int time-frame none)) (define-extern *cpad-list* cpad-list) (define-extern *cpad-debug* symbol) -(define-extern service-cpads (function cpad-list)) -(define-extern buzz-stop! (function int none)) +(define-extern service-cpads "Read from cpads and update vibration." (function cpad-list)) +(define-extern buzz-stop! + "Set the buzz to 0 on both vibration motors of the given cpad." + (function int none)) (define-extern *mouse* mouse-info) -(define-extern service-mouse (function none)) +(define-extern service-mouse + "Update the mouse, and draw the cursor." + (function none)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; gs ;; @@ -3785,6 +4500,8 @@ ) (deftype gs-bank (structure) +"Memory layout of the GS's privileged registers (mapped to EE memory). +It is missing the SIGLBLID/LABELID register at 4224 (useless anyway?)" ((pmode gs-pmode :offset-assert 0) (smode2 gs-smode2 :offset 32) (dspfb1 gs-display-fb :offset 112) @@ -3816,6 +4533,7 @@ ;; the GS's ZBUF registers make various settings regarding Z buffer. (deftype gs-zbuf (uint64) +"The GS's ZBUF registers make various settings regarding Z buffer." ((zbp uint16 :offset 0 :size 9) (psm gs-psm :offset 24 :size 4) (zmsk uint8 :offset 32 :size 1) @@ -3826,6 +4544,8 @@ ;; the GS's XYOFFSET registers set the offset value for converting from the primitive coordinate ;; system to the window coordinate system. (deftype gs-xy-offset (uint64) +"The GS's XYOFFSET registers set the offset value for converting from the primitive coordinate +system to the window coordinate system." ((ofx uint16 :offset 0 :size 16) (ofy uint16 :offset 32 :size 16) ) @@ -3836,6 +4556,9 @@ ;; the upper-left/lower-right points of the enabled drawing area are specified by the window ;; coordinate system. (deftype gs-scissor (uint64) +"The GS's SCISSOR registers specify the scissoring area. The coordinate values for +the upper-left/lower-right points of the enabled drawing area are specified by the window +coordinate system." ((scax0 uint16 :offset 0 :size 11) (scax1 uint16 :offset 16 :size 11) (scay0 uint16 :offset 32 :size 11) @@ -3847,6 +4570,8 @@ ;; the GS's PRMODECONT register sets whether to use primitive attributes (IIP, TME, FGE, ABE, ;; AA1, FST, CTXT, FIX) specified by the PRMODE register or the PRIM register. (deftype gs-prmode-cont (uint64) +"The GS's PRMODECONT register sets whether to use primitive attributes (IIP, TME, FGE, ABE, +AA1, FST, CTXT, FIX) specified by the PRMODE register or the PRIM register." ((ac uint8 :offset 0 :size 1)) :flag-assert #x900000008 ) @@ -3854,12 +4579,15 @@ ;; the GS's COLCLAMP register stores settings as to whether clamping for the RGB value of the ;; pixel is performed. (deftype gs-color-clamp (uint64) +"The GS's COLCLAMP register stores settings as to whether clamping for the RGB value of the +pixel is performed." ((clamp uint8 :offset 0 :size 1)) :flag-assert #x900000008 ) ;; the GS's DTHE register stores settings for dithering (performed/not performed). (deftype gs-dthe (uint64) +"The GS's DTHE register stores settings for dithering (performed/not performed)." ((dthe uint8 :offset 0 :size 1)) :flag-assert #x900000008 ) @@ -3884,6 +4612,7 @@ ) ;; the GS's TEST register performs settings related to the pixel test. (deftype gs-test (uint64) +"The GS's TEST register performs settings related to the pixel test." ((ate uint8 :offset 0 :size 1) ;; alpha test enable (atst gs-atest :offset 1 :size 3) ;; alpha test method (aref uint8 :offset 4 :size 8) ;; alpha val reference @@ -3914,6 +4643,8 @@ ;; the GS's RGBAQ register sets the RGBA value of the vertex and the Q value of the normalized ;; texture coordinates. (deftype gs-rgbaq (uint64) +"The GS's RGBAQ register sets the RGBA value of the vertex and the Q value of the normalized +texture coordinates." ((r uint8 :offset 0 :size 8) (g uint8 :offset 8 :size 8) (b uint8 :offset 16 :size 8) @@ -3934,6 +4665,7 @@ ;; the GS's UV register specifies the texel coordinate (UV) values of the vertex. (deftype gs-uv (uint64) +"The GS's UV register specifies the texel coordinate (UV) values of the vertex." ((u uint16 :offset 0 :size 16) ;; Q4 fixed point (v uint16 :offset 16 :size 16) ;; Q4 fixed point ) @@ -3942,6 +4674,7 @@ ;; hack - added for warp. (deftype gs-uv2 (uint64) +"Hack - added for warp." ((u int16 :offset 0 :size 16) ;; Q4 fixed point (v int16 :offset 16 :size 16) ;; Q4 fixed point ) @@ -3951,6 +4684,8 @@ ;; the GS's ST register sets the S and T values of the vertex texture coordinates. ;; The value Q is specified by the RGBAQ register. (deftype gs-st (uint64) +"The GS's ST register sets the S and T values of the vertex texture coordinates. +The value Q is specified by the RGBAQ register." ((s float :offset 0 :size 32) (t float :offset 32 :size 32) ) @@ -3970,6 +4705,9 @@ ;; the GS's TRXPOS register specifies the position and scanning direction of the rectangular area ;; in each buffer where buffer transmission is performed. (deftype gs-trxpos (uint64) +"The GS's TRXPOS register specifies the position and +scanning direction of the rectangular area +in each buffer where buffer transmission is performed." ((ssax uint16 :offset 0 :size 11) (ssay uint16 :offset 16 :size 11) (dsax uint16 :offset 32 :size 11) @@ -3983,6 +4721,9 @@ ;; between buffers is implemented, in units of pixels. ;; The pixel mode must be the one set by the BITBLTBUF register. (deftype gs-trxreg (uint64) +"The GS's TRXREG register specifies the size of the rectangular area, where the transmission +between buffers is implemented, in units of pixels. +The pixel mode must be the one set by the BITBLTBUF register." ((rrw uint16 :offset 0 :size 12) (rrh uint16 :offset 32 :size 12) ) @@ -3994,6 +4735,10 @@ ;; Appropriate settings must be made by the BITBLTBUF/TRXPOS/TRXREG before activating ;; the transmission. (deftype gs-trxdir (uint64) +"The GS's TRXDIR register specifies the transmission direction in the transmission between +buffers, and activates transmission. +Appropriate settings must be made by the BITBLTBUF/TRXPOS/TRXREG before activating +the transmission." ((xdir uint8 :offset 0 :size 2)) :flag-assert #x900000008 ) @@ -4001,6 +4746,8 @@ ;; the GS's BITBLTBUF register stores buffer-related settings for transmission source and ;; destination during transmission between buffers. (deftype gs-bitbltbuf (uint64) +"The GS's BITBLTBUF register stores buffer-related settings for transmission source and +destination during transmission between buffers." ((sbp uint16 :offset 0 :size 14) (sbw uint8 :offset 16 :size 6) (spsm uint8 :offset 24 :size 6) @@ -4013,6 +4760,7 @@ ;; the GS's TEX0 registers set various kinds of information regarding the textures to be used. (deftype gs-tex0 (uint64) +"The GS's TEX0 registers set various kinds of information regarding the textures to be used." ((tbp0 uint16 :offset 0 :size 14) (tbw uint8 :offset 14 :size 6) (psm uint8 :offset 20 :size 6) @@ -4031,6 +4779,7 @@ ;; the GS's TEX1 registers set information on the sampling method of the textures. (deftype gs-tex1 (uint64) +"The GS's TEX1 registers set information on the sampling method of the textures." ((lcm uint8 :offset 0 :size 1) (mxl uint8 :offset 2 :size 3) (mmag uint8 :offset 5 :size 1) @@ -4045,6 +4794,8 @@ ;; the GS's TEXA register sets the Alpha value to be referred to when the Alpha value of the ;; texture is not an 8-bit value. (deftype gs-texa (uint64) +"The GS's TEXA register sets the Alpha value to be referred to when the Alpha value of the +texture is not an 8-bit value." ((ta0 uint8 :offset 0 :size 8) (aem uint8 :offset 15 :size 1) (ta1 uint8 :offset 32 :size 8) @@ -4055,6 +4806,8 @@ ;; the GS's TEXCLUT register specifies the CLUT position in the buffer when the CLUT storage mode ;; is CSM=1 (CSM2 mode). (deftype gs-texclut (uint64) +"The GS's TEXCLUT register specifies the CLUT position in the buffer when the CLUT storage mode +is CSM=1 (CSM2 mode)." ((cbw uint8 :offset 0 :size 6) (cou uint8 :offset 6 :size 6) (cov uint16 :offset 12 :size 10) @@ -4066,6 +4819,8 @@ ;; MIPMAP. ;; MIPTBP1 sets levels 1 to 3, MIPTBP2 sets levels 4 to 6. (deftype gs-miptbp (uint64) +"the GS's MIPTBP registers set the buffer pointer and buffer width of textures when performing +MIPMAP. MIPTBP1 sets levels 1 to 3, MIPTBP2 sets levels 4 to 6." ((tbp1 uint16 :offset 0 :size 14) (tbw1 uint8 :offset 14 :size 6) (tbp2 uint16 :offset 20 :size 14) @@ -4343,6 +5098,7 @@ (deftype gif-packet (basic) +"Unused type for building a dynamically sized gif packet." ((reg-count int32 :offset-assert 4) (gif-tag gs-gif-tag :inline :offset-assert 16) ;; note- added @@ -4433,14 +5189,28 @@ :flag-assert #x9000000c0 ) -(define-extern psm-size (function gs-psm int)) -(define-extern psm-page-height (function gs-psm int)) -(define-extern psm->string (function gs-psm string)) +(define-extern psm-size + "Convert texture format to some type of size." + (function gs-psm int)) +(define-extern psm-page-height + "Convert texture format to some type of page height." + (function gs-psm int)) +(define-extern psm->string + "Get the name of a texture format." + (function gs-psm string)) (define-extern *fog-color* rgba) -(define-extern open-gif-packet (function gif-packet gif-packet)) -(define-extern add-reg-gif-packet (function gif-packet int int none)) -(define-extern close-gif-packet (function gif-packet int gif-packet)) -(define-extern draw-context-set-xy (function draw-context int int none)) +(define-extern open-gif-packet + "Initialize an existing gif-packet for 0 registers." + (function gif-packet gif-packet)) +(define-extern add-reg-gif-packet + "Add a register + value to the packet." + (function gif-packet int int none)) +(define-extern close-gif-packet + "Finish adding registers." + (function gif-packet int gif-packet)) +(define-extern draw-context-set-xy + "Set the origin of the draw context." + (function draw-context int int none)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; display-h ;; @@ -4511,171 +5281,501 @@ ;; geometry ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -(define-extern vector-flatten! (function vector vector vector vector)) -(define-extern vector-reflect! (function vector vector vector vector)) -(define-extern vector-reflect-flat! (function vector vector vector vector)) -(define-extern vector-reflect-flat-above! (function vector vector vector vector)) +(define-extern vector-flatten! + "Get the projection of src onto a plane with the given normal + The normal should have magnitude 1.0." + (function vector vector vector vector)) +(define-extern vector-reflect! + "Reflect a vector off of a plane." + (function vector vector vector vector)) +(define-extern vector-reflect-flat! + "This is a weird one. It doesn't care about the value of src dot normal + and it effectively replaces the component of src normal to the plane with + the plane's normal. I think this requires src/normal to both be unit vectors + in order to make sense. + NOTE: src should point from positive halfspace to negative otherwise it + doesn't work." + (function vector vector vector vector)) +(define-extern vector-reflect-flat-above! + "Not really a reflect. Same as flatten." + (function vector vector vector vector)) (define-extern vector-reflect-flat-gravity! (function vector vector vector vector vector)) -(define-extern vector-segment-distance-point! (function vector vector vector vector float)) -(define-extern vector-line-distance (function vector vector vector float)) -(define-extern vector-line-distance-point! (function vector vector vector vector float)) -(define-extern vector-segment-overlap (function vector vector vector float)) -(define-extern line-sphere-intersection? (function vector vector vector symbol)) -(define-extern vector-orient-by-quat! (function vector vector quaternion vector)) -(define-extern vector-inv-orient-by-quat! (function vector vector quaternion vector)) +(define-extern vector-segment-distance-point! + "Compute the distance from a point to the closest point on the line segment. + arg0 is the point. arg1/arg2 are the endpoints of the line segment. + arg3 is an optional output closest point." + (function vector vector vector vector float)) +(define-extern vector-line-distance + "Weird function: given a point arg1, and an infinite line connecting arg2 and arg1, compute the distance + from arg0 to that line." + (function vector vector vector float)) +(define-extern vector-line-distance-point! + "Same as above function, but returns the point on arg2/arg1 in arg3 (ignored if #f)" + (function vector vector vector vector float)) +(define-extern vector-segment-overlap + "Seems to compute (v1 - v0).dot(v2 - v1), but in a weird way." + (function vector vector vector float)) +(define-extern line-sphere-intersection? + "Does [arg1, arg2] intersect sphere arg0?" + (function vector vector vector symbol)) +(define-extern vector-orient-by-quat! + "Rotate a vector by a quaternion." + (function vector vector quaternion vector)) +(define-extern vector-inv-orient-by-quat! + "Rotate a vector by the inverse rotation." + (function vector vector quaternion vector)) (define-extern forward-down->inv-matrix (function matrix vector vector matrix)) (define-extern forward-down-nopitch->inv-matrix (function matrix vector vector matrix)) -(define-extern forward-up->inv-matrix (function matrix vector vector matrix)) -(define-extern forward-up-nopitch->inv-matrix (function matrix vector vector matrix)) +(define-extern forward-up->inv-matrix + "Create a matrix representing an inverse transform where arg1 is forward (+z) + and arg2 is up (+y). Will use the pitch of forward." + (function matrix vector vector matrix)) +(define-extern forward-up-nopitch->inv-matrix + "Create a matrix representing an inverse transform where arg1 is forward (+z) + and arg2 is up (+y). Will not use the pitch of forward." + (function matrix vector vector matrix)) (define-extern forward-up-nopitch->quaternion (function quaternion vector vector quaternion)) (define-extern forward-up->quaternion (function quaternion vector vector quaternion)) ;; TODO - sometimes the last vector is a matrix? -(define-extern quaternion-from-two-vectors! (function quaternion vector vector quaternion)) -(define-extern quaternion-from-two-vectors-partial! (function quaternion vector vector float quaternion)) +(define-extern quaternion-from-two-vectors! + "Create a quaternion representing the rotation between two vectors." + (function quaternion vector vector quaternion)) +(define-extern quaternion-from-two-vectors-partial! + "Create a quaternion representing the rotation between two vectors, + doing arg3 fraction of the total rotation." + (function quaternion vector vector float quaternion)) (define-extern quaternion-from-two-vectors-max-angle! (function quaternion vector vector float quaternion)) (define-extern quaternion-from-two-vectors-max-angle-partial! (function quaternion vector vector float float quaternion)) -(define-extern matrix-from-two-vectors! (function matrix vector vector matrix)) -(define-extern matrix-from-two-vectors-max-angle! (function matrix vector vector float matrix)) -(define-extern matrix-from-two-vectors-smooth! (function matrix vector vector float int matrix)) -(define-extern matrix-from-two-vectors-the-long-way-smooth! (function matrix vector vector float int matrix)) -(define-extern quaternion-from-two-vectors-smooth! (function quaternion vector vector float int quaternion)) -(define-extern matrix-from-two-vectors-max-angle-partial! (function matrix vector vector float float matrix)) -(define-extern matrix-from-two-vectors-partial-linear! (function matrix vector vector float matrix)) +(define-extern matrix-from-two-vectors! + "Create a rotation matrix representing the rotation between two vectors." + (function matrix vector vector matrix)) +(define-extern matrix-from-two-vectors-max-angle! + "Create a rotation matrix representing the rotation between two vectors, + allowing at most a rotation of arg3 degrees." + (function matrix vector vector float matrix)) +(define-extern matrix-from-two-vectors-smooth! + "This function can help smoothly rotate from a current heading vector to a target one. + It returns a rotation to move arg1 closer to arg2, subject to two different speed limits. + arg3 is a rotations-per-frame rate. This limit takes frame rate into account (when lagging, the rotation is larger) + arg4 is a 'slow down when getting close to the end' limit. + This is used in rotate-toward-orientation, which is much improved from jak 1." + (function matrix vector vector float int matrix)) +(define-extern matrix-from-two-vectors-the-long-way-smooth! + "Same as above, but rotates you away from the target. + Note that the 'near the end' smoothing will apply when you're near the target." + (function matrix vector vector float int matrix)) +(define-extern quaternion-from-two-vectors-smooth! + "Same as above, but returns a quaternion." + (function quaternion vector vector float int quaternion)) +(define-extern matrix-from-two-vectors-max-angle-partial! + "Create a rotation matrix representing the given fraction of the rotation between two heading vectors, + rotating by at most the given angle." + (function matrix vector vector float float matrix)) +(define-extern matrix-from-two-vectors-partial-linear! + "Create a rotation matrix representing doing arg3 fraction of the rotation between two vectors." + (function matrix vector vector float matrix)) (define-extern matrix-remove-z-rot (function matrix vector matrix)) -(define-extern matrix-rot-diff! (function vector matrix matrix float)) -(define-extern quaternion-seek (function quaternion quaternion quaternion float float quaternion)) -(define-extern vector-deg-seek (function vector vector vector float vector)) -(define-extern vector-deg-slerp (function vector vector vector float vector)) -(define-extern vector-vector-deg-slerp! (function vector vector vector float vector vector)) -(define-extern normal-of-plane (function vector vector vector vector vector)) -(define-extern vector-3pt-cross! (function vector vector vector vector vector)) -(define-extern closest-pt-in-triangle (function vector vector matrix vector none)) -(define-extern point-in-triangle-cross (function vector vector vector vector vector symbol)) -(define-extern point-in-plane-<-point+normal! (function vector vector vector vector)) -(define-extern circle-circle-xz-intersect (function sphere sphere vector vector int)) -(define-extern circle-test (function none)) -(define-extern vector-circle-tangent-new (function vector vector vector vector none)) -(define-extern vector-circle-tangent (function vector vector vector vector none)) -(define-extern find-knot-span (function int int float (inline-array vector) int)) -(define-extern calculate-basis-functions-vector! (function vector int float (pointer float) vector)) -(define-extern curve-evaluate! (function vector float (inline-array vector) int (pointer float) int vector)) -(define-extern curve-get-pos! (function vector float curve vector)) -(define-extern curve-length (function curve float)) -(define-extern curve-copy! (function curve curve curve)) -(define-extern curve-closest-point (function curve vector float float int float float)) -(define-extern vector-plane-distance (function vector plane vector float)) -(define-extern intersect-ray-plane (function vector vector vector vector float)) +(define-extern matrix-rot-diff! + "Get the difference of rotation between two matrices, expressed as a quaternion." + (function vector matrix matrix float)) +(define-extern quaternion-seek + "Strange quaternion rotate toward function. arg3 is ignored. arg4 is the max seek amount." (function quaternion quaternion quaternion float float quaternion)) +(define-extern vector-deg-seek + "Make one vector closer to another, doing at most a rotation by arg3 degrees." (function vector vector vector float vector)) +(define-extern vector-deg-slerp + "Slerp for vectors. (imagine that they are the z axis of two frames)" (function vector vector vector float vector)) +(define-extern vector-vector-deg-slerp! + "Unused. No clue what this does." + (function vector vector vector float vector vector)) +(define-extern normal-of-plane + "Given three points on a plane, compute the plane's normal." + (function vector vector vector vector vector)) +(define-extern vector-3pt-cross! + "Cross product of 2 - 1 and 3 - 1. (will give a normal to the plane, but not of magnitude 1)" + (function vector vector vector vector vector)) +(define-extern closest-pt-in-triangle + "arg2 is the vertices of the triangle, arg3 is the normal, arg1 is the input point, arg0 is the output." (function vector vector matrix vector none)) +(define-extern point-in-triangle-cross + "Check if point is in the triangle using cross product check (so you have to get the order of points right)." + (function vector vector vector vector vector symbol)) +(define-extern point-in-plane-<-point+normal! + "Very strange function. Takes a plane, in point-normal form, then returns some other point on that plane. + It will move 1m in two of {x, y, z} directions. The direction not moved in is the one which is closest to point-in-triangle-cross + in the same direction of the normal (this prevent moving huge distances for nearly vertical planes for example)." + (function vector vector vector vector)) +(define-extern circle-circle-xz-intersect + "This function is unused and really complicated, so not implementing it for now." + (function sphere sphere vector vector int)) +(define-extern circle-test + "Test the circle-circle-xz-intersect function." + (function none)) +(define-extern vector-circle-tangent-new + "Unused." + (function vector vector vector vector none)) +(define-extern vector-circle-tangent "Also unused." (function vector vector vector vector none)) +(define-extern find-knot-span + "Binary serach over knots to find which contains the value float in (arg0 arg1). Unused." + (function int int float (inline-array vector) int)) +(define-extern calculate-basis-functions-vector! + "Calculate polynomial basis for a given control point." (function vector int float (pointer float) vector)) +(define-extern curve-evaluate! + "Evaluate a curve. + arg0 is the output + arg1 is the input. + arg2 is control vertices. + arg3 is the number of control vertices. + arg4 is the knot points. + arg5 is the number of knots." (function vector float (inline-array vector) int (pointer float) int vector)) +(define-extern curve-get-pos! + "Get the position on the curve at the given input." + (function vector float curve vector)) +(define-extern curve-length + "Compute the approximate curve length as the sum of distances between knots." + (function curve float)) +(define-extern curve-copy! + "Shallow copy a curve." + (function curve curve curve)) +(define-extern curve-closest-point + "Get the input value for the point on the curve. Approximate! And is O(n_knots)." + (function curve vector float float int float float)) +(define-extern vector-plane-distance + "Unused." + (function vector plane vector float)) +(define-extern intersect-ray-plane + "arg1 is ray direction, arg3 is plane normal, others don't really make sense to me." + (function vector vector vector vector float)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; timer ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -(define-extern timer-count (function timer-bank uint)) -(define-extern disable-irq (function none)) -(define-extern enable-irq (function none)) -(define-extern stopwatch-init (function stopwatch int)) -(define-extern stopwatch-reset (function stopwatch int)) -(define-extern stopwatch-start (function stopwatch int)) -(define-extern stopwatch-stop (function stopwatch none)) -(define-extern stopwatch-begin (function stopwatch int)) -(define-extern stopwatch-end (function stopwatch none)) -(define-extern stopwatch-elapsed-ticks (function stopwatch time-frame)) -(define-extern stopwatch-elapsed-seconds (function stopwatch float)) +(define-extern timer-count + "Return a timer's counter value." + (function timer-bank uint)) +(define-extern disable-irq + "Disable all interrupts. Has no effect on PC Port." + (function none)) +(define-extern enable-irq + "Enable all interrupts. Has no effect on PC Port." + (function none)) +(define-extern stopwatch-init + "Init a stopwatch." + (function stopwatch int)) +(define-extern stopwatch-reset + "Restart a stopwatch's times." + (function stopwatch int)) +(define-extern stopwatch-start + "Start a stopwatch from scratch." + (function stopwatch int)) +(define-extern stopwatch-stop + "Fully stop a stopwatch and save its elapsed time." + (function stopwatch none)) +(define-extern stopwatch-begin + "Begin a stopwatch level, and starts it if it hasn't yet." + (function stopwatch int)) +(define-extern stopwatch-end + "End a stopwatch level. Stops the stopwatch if it's back to level zero. + There is no guard against ending a stopwatch too many times, and a negative level + will cause errors!" + (function stopwatch none)) +(define-extern stopwatch-elapsed-ticks + "Returns the elapsed time so far (in clock cycles) of a stopwatch." + (function stopwatch time-frame)) +(define-extern stopwatch-elapsed-seconds + "Returns the elapsed time so far (in seconds) of a stopwatch." + (function stopwatch float)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; vector ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -(define-extern vector-cross! (function vector vector vector vector)) -(define-extern vector-xz-cross! (function vector vector vector vector)) -(define-extern vector+float! (function vector vector float vector)) -(define-extern vector*! (function vector vector vector vector)) -(define-extern vector+*! (function vector vector vector float vector)) -(define-extern vector-*! (function vector vector vector float vector)) -(define-extern vector/! (function vector vector vector vector)) -(define-extern vector-float*! (function vector vector float vector)) -(define-extern vector-average! (function vector vector vector vector)) -(define-extern vector+float*! (function vector vector vector float vector)) -(define-extern vector--float*! (function vector vector vector float vector)) -(define-extern vector-float/! (function vector vector float vector)) -(define-extern vector-negate! (function vector vector vector)) -(define-extern vector-negate-in-place! (function vector vector)) +(define-extern vector-cross! + "Compute the cross product. The w component is set to junk." + (function vector vector vector vector)) +(define-extern vector-xz-cross! + "Compute the cross product of the xz components of inputs." + (function vector vector vector vector)) +(define-extern vector+float! + "Add float to each component of vector. The w component is set to 1" + (function vector vector float vector)) +(define-extern vector*! + "Elementwise product. Set w = 1." + (function vector vector vector vector)) +(define-extern vector+*! + "set arg0 = arg1 + (arg3 * arg2). The w component will be set to 1." + (function vector vector vector float vector)) +(define-extern vector-*! + "Set arg0 = arg1 - (arg3 * arg2). The w component will be set to 1." + (function vector vector vector float vector)) +(define-extern vector/! + "Set arg0 = arg1 / arg2. The w component will be set to 1. + The implementation is kind of crazy." + (function vector vector vector vector)) +(define-extern vector-float*! + "Multiply all values in a vector by arg2. Set w to 1." + (function vector vector float vector)) +(define-extern vector-average! + "Set arg0 to the average of arg1 and arg2. Set w to 1." + (function vector vector vector vector)) +(define-extern vector+float*! + "arg0 = arg1 + arg2 * arg3." + (function vector vector vector float vector)) +(define-extern vector--float*! + "Set arg0 = arg1 - (arg2 * arg3). The w component will be set to 1. + Is this different from vector-*!" + (function vector vector vector float vector)) +(define-extern vector-float/! + "Divide all components by arg2. The w component will be set to 1." + (function vector vector float vector)) +(define-extern vector-negate! + "Negate xyz, set w to 1." + (function vector vector vector)) +(define-extern vector-negate-in-place! + "Negate xyz. Doesn't touch w." + (function vector vector)) (define-extern vector= (function vector vector symbol)) -(define-extern vector-delta (function vector vector float)) -(define-extern vector-seek! (function vector vector float vector)) -(define-extern vector-smooth-seek! (function vector vector float vector)) -(define-extern vector-seek-2d-xz-smooth! (function vector vector float float vector)) -(define-extern vector-seek-2d-yz-smooth! (function vector vector float float vector)) -(define-extern vector-seek-3d-smooth! (function vector vector float float vector)) -(define-extern seek-with-smooth (function float float float float float float)) -(define-extern vector-identity! (function vector vector)) -(define-extern vector-seconds (function vector vector vector)) -(define-extern vector-seconds! (function vector vector)) -(define-extern vector-v! (function vector vector)) -(define-extern vector-v+! (function vector vector vector vector)) -(define-extern vector-v*float+! (function vector vector vector float vector)) -(define-extern vector-v++! (function vector vector vector)) -(define-extern vector-v*float! (function vector vector float vector)) -(define-extern vector-v*float++! (function vector vector float vector)) -(define-extern vector-to-ups! (function vector vector vector)) -(define-extern vector-from-ups! (function vector vector vector)) -(define-extern vector-length (function vector float)) -(define-extern vector-length-squared (function vector float)) -(define-extern vector-xz-length-squared (function vector float)) -(define-extern vector-xz-length (function vector float)) -(define-extern vector-vector-distance (function vector vector float)) -(define-extern vector-vector-distance-squared (function vector vector float)) -(define-extern vector-vector-xz-distance (function vector vector float)) -(define-extern vector-vector-xy-distance (function vector vector float)) -(define-extern vector-vector-xz-distance-squared (function vector vector float)) -(define-extern vector-normalize! (function vector float vector)) -(define-extern vector-normalize-ret-len! (function vector float float)) -(define-extern vector-normalize-copy! (function vector vector float vector)) -(define-extern vector-xz-normalize! (function vector float vector)) -(define-extern vector-xz-normalize-copy! (function vector vector float vector)) -(define-extern vector-length-max! (function vector float vector)) -(define-extern vector-xz-length-max! (function vector float vector)) -(define-extern vector-rotate-around-x! (function vector vector float vector)) -(define-extern vector-rotate-around-y! (function vector vector float vector)) -(define-extern vector-rotate90-around-y! (function vector vector vector)) -(define-extern vector-rotate-around-z! (function vector vector float vector)) -(define-extern rotate-y<-vector+vector "Get the y rotation between vectors. These should have the same length." (function vector vector float)) -(define-extern rotate-x<-vector+vector (function vector vector float)) -(define-extern rotate-z<-vector+vector (function vector vector float)) -(define-extern vector-cvt.w.s! (function vector vector vector)) -(define-extern vector-cvt.s.w! (function vector vector vector)) -(define-extern rot-zxy-from-vector! (function vector vector vector)) -(define-extern rot-zyx-from-vector! (function vector vector vector)) -(define-extern vector-lerp! (function vector vector vector float vector)) -(define-extern vector-lerp-clamp! (function vector vector vector float vector)) -(define-extern vector4-lerp! (function vector vector vector float vector)) -(define-extern vector4-lerp-clamp! (function vector vector vector float vector)) -(define-extern vector-degi (function vector vector vector)) -(define-extern vector-degf (function vector vector vector)) -(define-extern vector-degmod (function vector vector vector)) -(define-extern vector-deg-diff (function vector vector vector none)) -(define-extern vector-deg-lerp-clamp! (function vector vector vector float vector)) +(define-extern vector-delta + "Sum of the elementwise absolute value of differences." + (function vector vector float)) +(define-extern vector-seek! + "Seek arg0 toward arg1. The arg0 is both read and written. + arg2 is saturated to (0, 1)" + (function vector vector float vector)) +(define-extern vector-smooth-seek! + "Smoothly seek vec toward target. + The step always points toward the target and has length (dist * alpha). + If the step is longer than max-step, the step is projected onto a _square_ with side length arg2. + Note that this doesn't project to a circle like the function below..." + (function vector vector float vector)) +(define-extern vector-seek-2d-xz-smooth! + "Smoothly seek vec's x and z components toward target. + The step always points toward the target and has length (dist * alpha). + If the step is longer than max-step, the step is projected onto a circle of radius max-step. + Doesn't touch y or w." + (function vector vector float float vector)) +(define-extern vector-seek-2d-yz-smooth! + "Smoothly seek vec's y and z components toward target. + The step always points toward the target and has length (dist * alpha). + If the step is longer than max-step, the step is projected onto a circle of radius max-step. + Doesn't touch x or w." + (function vector vector float float vector)) +(define-extern vector-seek-3d-smooth! + "Smoothly seek vec's x, y, and z components toward target. + The step always points toward the target and has length (dist * alpha). + If the step is longer than max-step, the step is projected onto a circle of radius max-step. + Doesn't touch w." + (function vector vector float float vector)) +(define-extern seek-with-smooth + "Move value closer to target. + If we are within deadband, just go straight to target. + If not, try to go alpha*err. If that is a larger step than max-step, limit to max-step" + (function float float float float float float)) +(define-extern vector-identity! + "Set arg0 to 1, 1, 1, 1." + (function vector vector)) +(define-extern vector-seconds + "Convert from actual seconds to the seconds unit." + (function vector vector vector)) +(define-extern vector-seconds! + "Convert from actual seconds to seconds, in place." + (function vector vector)) +(define-extern vector-v! + "Convert a velocity to a displacement per frame. The velocity should be in X/actual_second. + Uses the current process clock." + (function vector vector)) +(define-extern vector-v+! + "Euler forward step, using the current display time settings." + (function vector vector vector vector)) +(define-extern vector-v*float+! + "Euler forward step, scaling velocity by velocity-scale." + (function vector vector vector float vector)) +(define-extern vector-v++! + "Update position in place, using display's current timing." + (function vector vector vector)) +(define-extern vector-v*float! + "Go from velocity to delta-p per frame, scaling by scale." + (function vector vector float vector)) +(define-extern vector-v*float++! + "Update position with given velocity, scaled by scale." + (function vector vector float vector)) +(define-extern vector-to-ups! + "Go from units per frame to units per second?" + (function vector vector vector)) +(define-extern vector-from-ups! + "Go from units per second to units per frame?" + (function vector vector vector)) +(define-extern vector-length + "Get the length of the xyz part." (function vector float)) +(define-extern vector-length-squared + "Get the squared length of the xyz part." + (function vector float)) +(define-extern vector-xz-length-squared + "Get the length of the xz part, squared." + (function vector float)) +(define-extern vector-xz-length "Get the length of the xz part." (function vector float)) +(define-extern vector-vector-distance + "Subtract the xyz parts and get the norm." + (function vector vector float)) +(define-extern vector-vector-distance-squared + "Squared norm of the difference of the xyz parts." + (function vector vector float)) +(define-extern vector-vector-xz-distance + "Distance on the xz plane." + (function vector vector float)) +(define-extern vector-vector-xy-distance + "distance on the xy plane." + (function vector vector float)) +(define-extern vector-vector-xz-distance-squared + "Distance on the xz plane squared." + (function vector vector float)) +(define-extern vector-normalize! + "Modify arg0 in place to have length arg1 for its xyz components. The w part is not changed." + (function vector float vector)) +(define-extern vector-normalize-ret-len! + "Modify arg0 in place to have length arg1 for its xyz components. + The w part isn't changed and the _original_ length is returned." + (function vector float float)) +(define-extern vector-normalize-copy! + "Normalize, but not in place. + This implementation is very good compared to the vector-normalize! one. + The w component is set to 1." + (function vector vector float vector)) +(define-extern vector-xz-normalize! + "Normalize, xz components only." + (function vector float vector)) +(define-extern vector-xz-normalize-copy! + "Normalize, xz components only." + (function vector vector float vector)) +(define-extern vector-length-max! + "Make vector at most arg1 length (xyz only). + If it is larger, project onto sphere. + Doesn't touch w" (function vector float vector)) +(define-extern vector-xz-length-max! + "Make vector at most arg1 length (xz only). + It it is larger, project onto circle. + Doesn't touch w or y." (function vector float vector)) +(define-extern vector-rotate-around-x! + "Rotate a vector around the x axis." + (function vector vector float vector)) +(define-extern vector-rotate-around-y! + "Rotate a vector around the y axis." + (function vector vector float vector)) +(define-extern vector-rotate90-around-y! + "Rotate a vector 90 degrees around y." + (function vector vector vector)) +(define-extern vector-rotate-around-z! + "Rotate a vector around the z axis." + (function vector vector float vector)) +(define-extern rotate-y<-vector+vector + "Get the y rotation between vectors. These should have the same length." + (function vector vector float)) +(define-extern rotate-x<-vector+vector + "Get the x rotation between vectors. These should have the same length." + (function vector vector float)) +(define-extern rotate-z<-vector+vector + "Get the z rotation between vectors. These should have the same length." + (function vector vector float)) +(define-extern vector-cvt.w.s! + "Convert float to int32. Truncate." + (function vector vector vector)) +(define-extern vector-cvt.s.w! + "Convert float to int32." + (function vector vector vector)) +(define-extern rot-zxy-from-vector! + "I think this gives you a vector of euler angles to rotate some unit vector + to arg1." + (function vector vector vector)) +(define-extern rot-zyx-from-vector! + "I think this gives you a vector of euler angles to rotate some unit vector + to arg1." + (function vector vector vector)) +(define-extern vector-lerp! + "Linearly interpolate between two vectors. Alpha isn't clamped. + w will be set to 1." + (function vector vector vector float vector)) +(define-extern vector-lerp-clamp! + "Linearly interpolate between two vectors, clamping alpha to 0, 1. + w will be set to 1." + (function vector vector vector float vector)) +(define-extern vector4-lerp! + "Interpolate all 4 elements of a vector. Alpha is not clamped." + (function vector vector vector float vector)) +(define-extern vector4-lerp-clamp! + "Interpolate all 4 elements of a vector. Alpha is clamped to [0, 1]." + (function vector vector vector float vector)) +(define-extern vector-degi + "Convert a vector (in _rotations_) to degrees units, stored in an int. + Truncates to the nearest _rotation_. + Neither the input or output is a commonly used form. + Unsurprisingly, this strange function is never used." + (function vector vector vector)) +(define-extern vector-degf + "Convert a vector (in integer degree units) to floating point rotations. + Truncates to the nearest _rotation_. + Like the previous function, this is stupid and unused." + (function vector vector vector)) +(define-extern vector-degmod + "This one is actually right. Wraps degrees units (in floats, like they should be) + to +/- half a rotation." + (function vector vector vector)) +(define-extern vector-deg-diff + "Wrapped difference, degrees units. Will have the usual 16-bit accuracy issue." + (function vector vector vector none)) +(define-extern vector-deg-lerp-clamp! + "Apply deg-lerp-clamp to the xyz components of a vector. Sets w = 1." + (function vector vector vector float vector)) (define-extern vector3s-copy! (function vector vector vector)) (define-extern vector3s+! (function vector vector vector vector)) (define-extern vector3s*float! (function vector vector float vector)) (define-extern vector3s-! (function vector vector vector vector)) -(define-extern vector4-add! (function vector4 vector4 vector4 none)) -(define-extern vector4-sub! (function vector4 vector4 vector4 none)) -(define-extern vector4-mul! (function vector4 vector4 vector4 none)) -(define-extern vector4-scale! (function vector4 vector4 float none)) -(define-extern vector4-madd! (function vector4 vector4 vector4 float none)) -(define-extern vector4-msub! (function vector4 vector4 vector4 float none)) -(define-extern vector4-array-add! (function (inline-array vector4) (inline-array vector4) (inline-array vector4) int none)) -(define-extern vector4-array-sub! (function (inline-array vector4) (inline-array vector4) (inline-array vector4) int none)) -(define-extern vector4-array-mul! (function (inline-array vector4) (inline-array vector4) (inline-array vector4) int none)) -(define-extern vector4-array-scale! (function (inline-array vector4) (inline-array vector4) float int none)) -(define-extern vector4-array-madd! (function (inline-array vector4) (inline-array vector4) (inline-array vector4) float int none)) -(define-extern vector4-array-msub! (function (inline-array vector4) (inline-array vector4) (inline-array vector4) float int none)) -(define-extern vector4-array-lerp! (function (inline-array vector4) (inline-array vector4) (inline-array vector4) float int symbol)) -(define-extern spheres-overlap? (function sphere sphere symbol)) -(define-extern sphere<-vector! (function sphere vector sphere)) -(define-extern sphere<-vector+r! (function sphere vector float sphere)) -(define-extern rand-vu-sphere-point! (function vector float vector)) -(define-extern vector-vector-angle-safe (function vector vector float)) +(define-extern vector4-add! + "Add 2 vector4s." + (function vector4 vector4 vector4 none)) +(define-extern vector4-sub! + "Subtract 2 vector4s." + (function vector4 vector4 vector4 none)) +(define-extern vector4-mul! + "Multiple 2 vector4s." + (function vector4 vector4 vector4 none)) +(define-extern vector4-scale! + "arg0 = arg1 * arg2." + (function vector4 vector4 float none)) +(define-extern vector4-madd! + "arg0 = arg1 + arg2 * arg3." + (function vector4 vector4 vector4 float none)) +(define-extern vector4-msub! + "arg0 = arg1 - arg2 * arg3." + (function vector4 vector4 vector4 float none)) +(define-extern vector4-array-add! + "Apply vector4-add! to all arrays." + (function (inline-array vector4) (inline-array vector4) (inline-array vector4) int none)) +(define-extern vector4-array-sub! + "Apply vector4-sub! to all arrays." + (function (inline-array vector4) (inline-array vector4) (inline-array vector4) int none)) +(define-extern vector4-array-mul! + "Apply vector4-mul! to all arrays." + (function (inline-array vector4) (inline-array vector4) (inline-array vector4) int none)) +(define-extern vector4-array-scale! + "Apply vector4-scale! to all arrays." + (function (inline-array vector4) (inline-array vector4) float int none)) +(define-extern vector4-array-madd! "Apply vector4-madd! to all arrays." (function (inline-array vector4) (inline-array vector4) (inline-array vector4) float int none)) +(define-extern vector4-array-msub! "Apply vector4-msub! to all arrays." (function (inline-array vector4) (inline-array vector4) (inline-array vector4) float int none)) +(define-extern vector4-array-lerp! "Apply vector4-lerp! to all arrays." (function (inline-array vector4) (inline-array vector4) (inline-array vector4) float int symbol)) +(define-extern spheres-overlap? + "Do the spheres overlap?" + (function sphere sphere symbol)) +(define-extern sphere<-vector! + "Set the position of the sphere to arg1. Does not change the radius." + (function sphere vector sphere)) +(define-extern sphere<-vector+r! + "Set the position of the sphere from arg1 and the radius from arg2." + (function sphere vector float sphere)) +(define-extern rand-vu-sphere-point! + "Get a random point on the sphere at the origin with radius arg1. + The point is on the surface of the sphere." + (function vector float vector)) +(define-extern vector-vector-angle-safe + "Get the angle between two vectors, with some 'safety' applied..." + (function vector vector float)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; file-io ;; @@ -4721,11 +5821,27 @@ :flag-assert #x900000020 ) -(define-extern file-stream-read-string (function file-stream string string)) +(define-extern file-stream-read-string + "Fill a string with data from a file stream. + Note: this function does not work." + (function file-stream string string)) (define-extern *file-temp-string* string) -(define-extern make-file-name (function file-kind string int symbol string)) -(define-extern make-vfile-name (function file-kind string string)) -(define-extern file-info-correct-version? (function file-info file-kind int symbol)) +(define-extern make-file-name + "Get a file name to open a file with the given kind and name. + The art-group-version argument can be used to override the version + of the art-group. Set it to 0 or less to use the default version. + Similar to MakeFileName in C. + Note: file type enum is different between C and GOAL. + File versions should match those in versions.h. + Uses a single *file-temp-string* buffer, shared with make-vfile-name. + arg3 is unused." (function file-kind string int symbol string)) +(define-extern make-vfile-name + "Make virtual? file name. This makes a name that the kernel knows how to + handle in a specific way. This function is not used." + (function file-kind string string)) +(define-extern file-info-correct-version? + "Check if the version and kind in the info is valid. The `version-override` can specify a + non-default version, or set to 0 for the default version." (function file-info file-kind int symbol)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; loader-h ;; @@ -4752,6 +5868,7 @@ ) (deftype load-dir-art-group (load-dir) +"Specialization of load-dir for `art-group`s." ((art-group-array (array art-group) :offset 12) ) :flag-assert #xb00000010 @@ -4761,6 +5878,7 @@ ) (deftype external-art-buffer (basic) +"An `external-art-buffer` is a buffer that streamed files use." ((index int32 :offset-assert 4) (other external-art-buffer :offset-assert 8) ;; guessed by decompiler (status symbol :offset-assert 12) ;; guessed by decompiler @@ -4798,6 +5916,8 @@ ) (deftype spool-anim (basic) +"A `spool-anim` is metadata for an animation that will be loaded in chunks +to a pair of external-art-buffers." ((name string :offset 16) ;; guessed by decompiler (anim-name basic :offset-assert 20) (buffer external-art-buffer :offset 20 :score -1) ;; added @@ -4814,6 +5934,7 @@ (declare-type process-drawable process) (deftype external-art-control (basic) +"The `external-art-control` manages loading chunks from `spool-anim`s to `external-art-buffer`." ((buffer external-art-buffer 2 :offset-assert 4) ;; guessed by decompiler (rec spool-anim 3 :inline :offset-assert 16) ;; guessed by decompiler (spool-lock handle :offset-assert 160) @@ -4872,6 +5993,8 @@ (declare-type texture-page basic) (deftype texture-id (uint32) +"Unique identifier for a texture +as the tpage number and index of the texture within the tpage." ((index uint16 :offset 8 :size 12) (page uint16 :offset 20 :size 12) ) @@ -4881,6 +6004,7 @@ ) (deftype texture-pool-segment (structure) +"A chunk of VRAM." ((dest uint32 :offset-assert 0) (size uint32 :offset-assert 4) ) @@ -4892,6 +6016,7 @@ ) (deftype texture-pool (basic) +"The manager for the VRAM." ((top int32 :offset-assert 4) (cur int32 :offset-assert 8) (allocate-func (function texture-pool texture-page kheap int texture-page) :offset-assert 12) ;; guessed by decompiler @@ -4911,28 +6036,33 @@ :size-assert #x2d0 :flag-assert #x1a000002d0 (:methods - (new (symbol type) _type_) ;; 0 - (initialize! (_type_) _type_) ;; 9 + (new "Allocate and initialize a texture pool." (symbol type) _type_) ;; 0 + (initialize! "Set up a texture-pool and do the initial division of VRAM." (_type_) _type_) ;; 9 (print-usage (_type_) _type_) ;; 10 - (setup-font-texture (_type_) none) ;; 11 - (allocate-defaults (_type_) none) ;; 12 - (login-level-textures (_type_ level int (pointer texture-id)) none) ;; 13 - (add-level-tpage-dma (_type_ level tpage-category bucket-id) none) ;; 14 - (allocate-vram-words! (_type_ int) int) ;; 15 - (allocate-segment (_type_ texture-pool-segment int) texture-pool-segment) ;; 16 - (unload-page (_type_ texture-page) none) ;; 17 + (setup-font-texture "Set up the font texture. In normal use, the font texture is allocated, and currently uploaded to, the common segment. + This function copies that to the unused upper 8-bits of the depth buffer, and sets up the font + renderer to point to that address." (_type_) none) ;; 11 + (allocate-defaults "Allocate the common segment and set up dynamic texture addresses" (_type_) none) ;; 12 + (login-level-textures "Login all textures for the given level." (_type_ level int (pointer texture-id)) none) ;; 13 + (add-level-tpage-dma "Set up DMA to upload all textures needed to draw this level on this frame." (_type_ level tpage-category bucket-id) none) ;; 14 + (allocate-vram-words! "Increment the bump allocator to allocate vram, by words." (_type_ int) int) ;; 15 + (allocate-segment "Allocate VRAM for a texture-pool-segment" (_type_ texture-pool-segment int) texture-pool-segment) ;; 16 + (unload-page "Remove a page from the texture pool." (_type_ texture-page) none) ;; 17 (get-common-page-slot-by-id (_type_ int) int) ;; 18 - (update-warp-and-hud (_type_) none) ;; 19 - (update-sprites (_type_) none) ;; 20 - (mark-hud-warp-sprite-dirty (_type_) none) ;; 21 - (lay-out-sprite-tex (_type_) none) ;; 22 - (lay-out-hud-tex (_type_) none) ;; 23 - (lay-out-warp-tex (_type_) none) ;; 24 - (clear-ids (_type_) none) ;; 25 + (update-warp-and-hud "Redo warp and hud textures with the current set of loaded levels." (_type_) none) ;; 19 + (update-sprites "Redo sprite texture addresses with the current set of loaded levels." (_type_) none) ;; 20 + (mark-hud-warp-sprite-dirty "Set update flags for hud/sprite/warp. Needed after level load or unload." (_type_) none) ;; 21 + (lay-out-sprite-tex "Lay out VRAM addresses for sprite rendering, which is done in one pass for all levels." (_type_) none) ;; 22 + (lay-out-hud-tex "Lay out VRAM addresses for HUD rendering, which is done all at one for all levels." (_type_) none) ;; 23 + (lay-out-warp-tex "Lay out VRAM addresses for WARP texture rendering, and update adgifs to point to the new address." (_type_) none) ;; 24 + (clear-ids "Reset all cached texture upload IDs. This must be done whenever a texture has its vram address changed." (_type_) none) ;; 25 ) ) (deftype texture-mask (structure) +"Mask where each bit indicates if some part of a tpage is used, by a texture. +Additionally, the w component holds a minimum distance. The texture is only needed +if the distance to the object is smaller than this." ((mask vector4w :inline :offset-assert 0) (dist float :offset 12 :score 1) (long uint64 2 :offset 0) @@ -4944,6 +6074,8 @@ ) (deftype texture-masks (structure) +"Grouping of three masks, corresponding to the 3 segments of the texture. +So mask 0 is needed if segment 0 of the texture is needed, etc..." ((data texture-mask 3 :inline :offset-assert 0) ) :method-count-assert 9 @@ -4952,6 +6084,7 @@ ) (deftype texture-masks-array (inline-array-class) +"Group of all texture-masks for a given tpage." ((data texture-masks :inline :dynamic :offset-assert 16) ) :method-count-assert 9 @@ -4960,6 +6093,7 @@ ) (deftype texture (basic) +"Metadata for a texture." ((w int16 :offset-assert 4) (h int16 :offset-assert 6) (num-mips uint8 :offset-assert 8) @@ -4982,6 +6116,8 @@ ) (deftype texture-page-segment (structure) +"Metadata for a 'segment' of a texture page. +Each texture page has 3 segments - smaller number segments have higher detail mips." ((block-data pointer :offset-assert 0) ;; guessed by decompiler (size uint32 :offset-assert 4) (dest uint32 :offset-assert 8) @@ -5002,6 +6138,11 @@ ) (deftype texture-page (basic) +"A collection of textures. There is a tpage per category per level. +These tpages are loaded from the DVD. +e.g.: prison tfrag is its own tpage. +The tpage has multiple textures, and 3 segments. +Lower number segments are larger and have hi-res versions of textures." ((info file-info :offset-assert 4) (name string :offset-assert 8) (id uint32 :offset-assert 12) @@ -5017,17 +6158,23 @@ :size-assert #x80 :flag-assert #xe00000080 (:methods - (relocate (_type_ kheap (pointer uint8)) texture-page :replace) ;; 7 - (remove-data-from-heap (_type_ kheap) _type_) ;; 9 - (get-leftover-block-count (_type_ int int) int) ;; 10 - (relocate-dests! (_type_ int int) none) ;; 11 - (add-to-dma-buffer (_type_ dma-buffer tex-upload-mode) int) ;; 12 - (upload-now! (_type_ tex-upload-mode) none) ;; 13 + (relocate "Handle a texture page that has been loaded by the linker. + This must run in the linker, since we sometimes kick out textures from the loading heap, which + requires no more allocations made after the texture, and the only time is right after the linker + does the allocation for this GOAL object file." (_type_ kheap (pointer uint8)) texture-page :replace) ;; 7 + (remove-data-from-heap "Bump the kheap pointer to discard this texture data. All metadata is kept. + This is only safe to use if the last thing on the kheap is this texture." (_type_ kheap) _type_) ;; 9 + (get-leftover-block-count "Unused - statistics for how much unused memory we have" (_type_ int int) int) ;; 10 + (relocate-dests! "Update the metadata of this texture so it points to a new vram address." (_type_ int int) none) ;; 11 + (add-to-dma-buffer "Add upload DMA to a DMA buffer. Wrapper for upload-vram-data." (_type_ dma-buffer tex-upload-mode) int) ;; 12 + (upload-now! "Upload a texture to VRAM immediately, wait for DMA to finish." (_type_ tex-upload-mode) none) ;; 13 ) ) (declare-type adgif-shader structure) (deftype shader-ptr (uint32) +"A pointer to an adgif-shader, stored in bits 8-32. This allows them to fit into +an adgif shader easily." ((first-8 uint8 :offset 0 :size 8) ;; added (shader uint32 :offset 8 :size 24)) :method-count-assert 9 @@ -5036,6 +6183,8 @@ ) (deftype texture-link (structure) +"An overlay structure containing a shader-ptr that points to the next adgif-shader +in a linked list." ((next shader-ptr 1 :offset-assert 0) ;; guessed by decompiler ) :method-count-assert 9 @@ -5044,6 +6193,10 @@ ) (deftype texture-page-dir-entry (structure) +"An entry for a texture in the texture-page-dir. +The texture-page-dir contains an entry for each tpage. +Each entry contains a reference to the tpage, and a linked list of shaders +using it." ((length int16 :offset-assert 0) (status uint16 :offset-assert 2) (page texture-page :offset-assert 4) @@ -5057,6 +6210,8 @@ ) (deftype texture-relocate-later (basic) +"Unused in Jak 2, but metadata for postponing tpage copies until a second frame, +to have a smaller impact on frame times when loading." ((memcpy symbol :offset-assert 4) (dest uint32 :offset-assert 8) (source uint32 :offset-assert 12) @@ -5079,6 +6234,10 @@ (deftype adgif-shader (structure) +"GS texturing/blending settings, called adgif-shader. +These are used by many different renderers and partially managed by the texture system. +For example, the texture system will automatically update tbp to point to the location +of the texture." ((quad qword 5 :inline :offset-assert 0 :score -100) (prims gs-reg64 10 :offset 0 :score -100) (reg-0 uint8 :offset 8) @@ -5113,6 +6272,8 @@ ) (deftype texture-base (structure) +"Metadata about an area of VRAM set aside for fancy dynamic texture effects +(sky, eye, etc)." ((vram-page uint32 :offset-assert 0) (vram-block uint32 :offset-assert 4) (vram-word uint32 :offset-assert 8) @@ -5134,19 +6295,24 @@ ) (deftype texture-page-dir (basic) +"The list of all texture pages. +This is static data loaded from the DVD at boot." ((length int32) (entries texture-page-dir-entry 1 :inline) ) (:methods (relocate (_type_ kheap (pointer uint8)) none :replace) ;; 7 - (unlink-shaders-in-heap (_type_ kheap) int) ;; 9 + (unlink-shaders-in-heap "Iterate through all adgifs, splicing out ones that are in the given heap." (_type_ kheap) int) ;; 9 ) :flag-assert #xa00000014 ) (define-extern *texture-masks* texture-masks) (define-extern *texture-masks-array* texture-masks-array) -(define-extern texture-mip->segment (function int int int)) +(define-extern texture-mip->segment + "Figure out which segment of a tpage a given mip level of a texture will be in. + arg0 is the mip level, arg1 is the total number of mips. + Higher mip level is lower detail." (function int int int)) (define-extern *texture-relocate-later* texture-relocate-later) (define-extern *texture-page-dir* texture-page-dir) (define-extern ct32-24-block-table (array int32)) @@ -6191,6 +7357,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype vis-gif-tag (structure) +"Unused." ((fog0 uint32 :offset-assert 0) (strip uint32 :offset-assert 4) (regs uint32 :offset-assert 8) @@ -6202,6 +7369,7 @@ ) (deftype cull-info (structure) +"Also seems unused." ((x-fact float :offset-assert 0) (y-fact float :offset-assert 4) (z-fact float :offset-assert 8) @@ -6300,6 +7468,14 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype fog-corrector (structure) +"The math-camera matrices are used to compute fogging values, which are a per-vertex uint8 that +tells the GS how 'foggy' the color should be. This should be proportional to how far away the vertex +is. There is a scaling factor applied so the fog intensity isn't affected by the field of view angle. + +The fog-corrector stores a fog-end fog-start value that is corrected for the field of view. +The actual correction factor is computed in cam-update.gc. +Without this corrector, the fogginess of the world would change as the FOV changes +(for example, when Jak gets on the zoomer, the FOV changes slightly)." ((fog-end float :offset-assert 0) (fog-start float :offset-assert 4) ) @@ -6308,17 +7484,38 @@ :flag-assert #x900000008 ) -(define-extern fog-corrector-setup (function fog-corrector math-camera none)) +(define-extern fog-corrector-setup + "Set the fog corrector based on the supplied math-camera." + (function fog-corrector math-camera none)) (define-extern *math-camera-fog-correction* fog-corrector) -(define-extern update-math-camera (function math-camera symbol symbol float math-camera)) +(define-extern update-math-camera + "Compute some one-time camera constants. + These should only change when changing aspect ratio." + (function math-camera symbol symbol float math-camera)) (define-extern *math-camera* math-camera) -(define-extern math-cam-start-smoothing (function float float quaternion)) -(define-extern move-target-from-pad (function transform int transform)) -(define-extern transform-point-vector! (function vector vector symbol)) -(define-extern transform-point-qword! (function vector4w vector symbol)) -(define-extern transform-point-vector-scale! (function vector vector float)) -(define-extern reverse-transform-point! (function vector vector vector vector none)) -(define-extern init-for-transform (function matrix none)) +(define-extern math-cam-start-smoothing + "Unused camera smoothing." + (function float float quaternion)) +(define-extern move-target-from-pad + "Unused function to adjust trans based on inputs from the pad. + This function must be extremely old because it takes a non-quaternion transform, + and all [[target]] stuff uses quaternions." (function transform int transform)) +(define-extern transform-point-vector! + "Apply camera transformation to a point. Return true if it is visible or not. + This returns the point in GS coords, but as float instead of int, so it's + not really useful. See [[transform-point-qword!]] for more details." (function vector vector symbol)) +(define-extern transform-point-qword! + "Apply camera transformation to point, returning fixed point 28.4 position + that can be given to the GS directly." (function vector4w vector symbol)) +(define-extern transform-point-vector-scale! + "Similar to transform-point-qword! but returns the scale factor instead." (function vector vector float)) +(define-extern reverse-transform-point! + "Likely transform arg3 from screen space to world coords, using arg1/arg2 for... something." (function vector vector vector vector none)) +(define-extern init-for-transform + "Sets up VU0 registers with camera info. + This is probably a very old function and it's only used by camera debug. + It stashes some data in vector float registers that must be there before calling transform-float-point." + (function matrix none)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; font-h ;; @@ -6498,6 +7695,8 @@ (deftype decomp-work (structure) +"Temporary storage for visibility data decompression. +This is stored on the scratchpad." ((buffer0 uint8 2048 :offset-assert 0) ;; guessed by decompiler (buffer1 uint8 2048 :offset-assert 2048) ;; guessed by decompiler (indices uint16 2048 :offset-assert 4096) ;; guessed by decompiler @@ -6515,6 +7714,7 @@ (deftype profile-work (structure) +"DMA templates for profile drawing." ((sprite-tmpl dma-gif-packet :inline :offset-assert 0) (line-tmpl dma-gif-packet :inline :offset-assert 32) (last-index int32 :offset-assert 64) @@ -6541,18 +7741,28 @@ ;; display ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -(define-extern get-current-time (function time-frame)) -(define-extern get-integral-current-time (function uint)) -(define-extern set-display (function display display)) -(define-extern allocate-dma-buffers (function display display)) +(define-extern get-current-time + "Get the base-clock time." + (function time-frame)) +(define-extern get-integral-current-time + "Get the number of frames that have happened." + (function uint)) +(define-extern set-display "Allocate and initialize clocks for the display." (function display display)) +(define-extern allocate-dma-buffers "Allocate the main, debug, and calc dma buffers." (function display display)) (define-extern *font-context* font-context) -(define-extern draw-sprite2d-xy (function dma-buffer int int int int rgba none)) -(define-extern draw-sprite2d-xy-absolute (function dma-buffer int int int int rgba none)) -(define-extern draw-quad2d (function dma-buffer draw-context none)) -(define-extern screen-gradient (function dma-buffer rgba rgba rgba rgba none)) -(define-extern vif1-handler-debug (function int none)) +(define-extern draw-sprite2d-xy "Draw a sprite primitive with the given color and dimensions." (function dma-buffer int int int int rgba none)) +(define-extern draw-sprite2d-xy-absolute "Draw a sprite primitive, setting the gs-xzyf register to exactly the values specified (no offset/clamp)." (function dma-buffer int int int int rgba none)) +(define-extern draw-quad2d + "Draw a quad that fills the entire context." + (function dma-buffer draw-context none)) +(define-extern screen-gradient + "Fill the screen with a sprite with the given colors." + (function dma-buffer rgba rgba rgba rgba none)) +(define-extern vif1-handler-debug + "Handle the VIF1 interrupt. + The mark register of VIF will be set to the bucket that is now starting." (function int none)) (define-extern vif1-handler (function none)) -(define-extern vblank-handler (function int)) +(define-extern vblank-handler "Record the time of the last two vblanks." (function int)) (define-extern set-display-gs-state (function dma-buffer int int int int int dma-buffer)) (define-extern set-display-gs-state-offset (function dma-buffer int int int int int int int dma-buffer)) (define-extern reset-display-gs-state (function display dma-buffer display)) @@ -6568,6 +7778,18 @@ (deftype connectable (structure) +"A connectable is the linked-list node part of a connection. +The connections themselves are owned by the engine. + +The `next0`/`prev0` references are used for how this belongs in the connectable list +belonging to the [[engine]]. These terminate on special nodes stored in the engine: +`alive-list`/`alive-list-end` for the active connections, and `dead-list`/`dead-list-end` +for the inactive. + +The `next1`/`prev1` references are used to build a linked list _per process_. +The head of this list is the inline connectable in process and it ends with `#f`. +This is a bit confusing at first, but these belong to two linked lists... +These terminate on both ends with `#f`." ((next0 connectable :offset-assert 0) (prev0 connectable :offset-assert 4) (next1 connectable :offset-assert 8) @@ -6582,6 +7804,10 @@ (declare-type engine basic) (deftype connection (connectable) +"This is the actual data for the connection. +It may be used in multiple ways, but the most common is to use `param0` as a function. +It receives `param1`, `param2`, `param3`, and the engine as the arguments. +In some cases, the return value is checked for `'dead`." ((param0 basic :offset-assert 16) (param1 basic :offset-assert 20) ;; guessed by decompiler (param2 int32 :offset-assert 24) ;; guessed by decompiler @@ -6593,17 +7819,25 @@ :flag-assert #xe00000020 ;; field param1 uses ~A with a signed load field param2 uses ~A with a signed load field param3 uses ~A with a signed load (:methods - (get-engine (connection) engine) ;; 9 - (get-process (connection) process) ;; 10 - (belongs-to-engine? (connection engine) symbol) ;; 11 - (belongs-to-process? (connection process) symbol) ;; 12 - (move-to-dead (connection) connection) ;; 13 + (get-engine + "Get the engine for this connection. This must be used on a live connection." (connection) engine) ;; 9 + (get-process "Get the process for this connection." (connection) process) ;; 10 + (belongs-to-engine? + "Check to see if this connection is located in the data section of the engine. + This works on dead or alive connections." (connection engine) symbol) ;; 11 + (belongs-to-process? "Does this connection belong to the given process?" (connection process) symbol) ;; 12 + (move-to-dead "Move this connection from the alive list to the dead list." (connection) connection) ;; 13 ) ) (deftype engine (basic) +"An engine is a collection of connections. +You can iterate over the connections, or run them. +The engine is dynamically sized based on how many connections it can store. + +New for Jak 2: You can use a child class of [[connection]]." ((name symbol :offset-assert 4) (engine-time time-frame :offset 16) (allocated-length int16 :offset 10) @@ -6622,19 +7856,28 @@ ;; Failed to read fields. (:methods (new (symbol type symbol int type) _type_) ;; 0 - (inspect-all-connections (engine) engine) ;; 9 - (apply-to-connections (engine (function connectable none)) int) ;; 10 - (apply-to-connections-reverse (engine (function connectable none)) int) ;; 11 - (execute-connections (engine object) int) ;; 12 - (execute-connections-and-move-to-dead (engine object) int) ;; 13 - (execute-connections-if-needed (engine object) int) ;; 14 - (add-connection (engine process object object object object) connection) ;; 15 - (remove-from-process (engine process) int) ;; 16 - (remove-matching (engine (function connection engine symbol)) int) ;; 17 - (remove-all (engine) int) ;; 18 - (remove-by-param0 (engine object) int) ;; 19 - (remove-by-param1 (engine int) int) ;; 20 - (remove-by-param2 (engine int) int) ;; 21 + (inspect-all-connections "inspect all of the connections." (engine) engine) ;; 9 + (apply-to-connections + "Apply arg0 to all connections for the engine. + It's okay to have arg0 remove the connection." (engine (function connectable none)) int) ;; 10 + (apply-to-connections-reverse + "Apply arg0 to all connections, reverse order. + Do not use arg0 to remove yourself from the list." (engine (function connectable none)) int) ;; 11 + (execute-connections "Run the engine!" (engine object) int) ;; 12 + (execute-connections-and-move-to-dead + "Run the engine! If any objects return `'dead`, remove them." (engine object) int) ;; 13 + (execute-connections-if-needed + "Execute connections, but only if it hasn't been done on this frame." (engine object) int) ;; 14 + (add-connection + "Add a connection between this engine and a given process." (engine process object object object object) connection) ;; 15 + (remove-from-process "Remove all connections from process for this engine." (engine process) int) ;; 16 + (remove-matching + "Call the given function on each connection and the engine. + If it returns truthy, `move-to-dead` that connection." (engine (function connection engine symbol)) int) ;; 17 + (remove-all "Remove all connections from an engine." (engine) int) ;; 18 + (remove-by-param0 "Remove all connections with param0 matching arg0." (engine object) int) ;; 19 + (remove-by-param1 "Remove all connections with param1 matching arg0." (engine int) int) ;; 20 + (remove-by-param2 "Remove all connections with param2 matching arg0." (engine int) int) ;; 21 (get-first-connectable (engine) connectable) ;; 22 (get-last-connectable (engine) connectable) ;; 23 (get-next-connectable (_type_ connectable) connectable) ;; 24 @@ -6644,6 +7887,11 @@ (deftype connection-pers (structure) +"This is another engine system, very similar to the first, but not specific to a process. +Each connection has a `key`, which is like the process, but unlike normal engine, +the key's don't track which engine-pers they belong to. + +Unlike [[engine]], users can use [[engine-pers]] as a parent class." ((next connection-pers :offset-assert 0) (key object :offset-assert 4) (update-time time-frame :offset-assert 8) @@ -6674,17 +7922,29 @@ :flag-assert #xf00000020 (:methods (new (symbol type symbol int type) _type_) ;; 0 - (schedule-callback (_type_ object time-frame) connection-pers) ;; 9 - (kill-callback (_type_ connection-pers) none) ;; 10 - (kill-by-key (_type_ object) none) ;; 11 - (kill-matching (_type_ (function engine-pers connection-pers object object symbol) object object) none) ;; 12 - (update-callback (_type_) none) ;; 13 - (run-pending-updates! (_type_ time-frame) none) ;; 14 + (schedule-callback + "Get a connection for this key. + If no connection exists, add it. + Schedule an update to happen in arg1 seconds." (_type_ object time-frame) connection-pers) ;; 9 + (kill-callback "Called when a connection is removed." (_type_ connection-pers) none) ;; 10 + (kill-by-key "Remove connections with this key, calling `kill-callback`." (_type_ object) none) ;; 11 + (kill-matching "Call the given function on each connection. If it returns truthy, kill that connection." (_type_ (function engine-pers connection-pers object object symbol) object object) none) ;; 12 + (update-callback + "Called when a connection is run. + Users can override this as needed." (_type_) none) ;; 13 + (run-pending-updates! "Run updates if they scheduled. If something is found that has no pending update, kill it. + Note that we won't kill things on this call if they fail to update their `update-time`. + They will survive until the next call to `run-pending-updates`! + (or you can modify their `update-time` before that to prevent them from being killed.)" (_type_ time-frame) none) ;; 14 ) ) -(define-extern connection-process-apply (function process (function object none) symbol)) -(define-extern process-disconnect (function process int)) +(define-extern connection-process-apply + "Apply a function to all connectables of a process." + (function process (function object none) symbol)) +(define-extern process-disconnect + "Disconnect all connections for the given process." + (function process int)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; text-id-h ;; @@ -8645,6 +9905,8 @@ #| (deftype texture-page-dir (basic) +"The list of all texture pages. +This is static data loaded from the DVD at boot." () :method-count-assert 10 :size-assert #x14 @@ -8656,50 +9918,145 @@ ) |# -(define-extern texture-bpp (function gs-psm int)) -(define-extern texture-qwc (function int int gs-psm int)) -(define-extern physical-address (function pointer pointer)) -(define-extern dma-buffer-add-ref-texture (function dma-buffer pointer int int gs-psm none)) -(define-extern gs-find-block (function int int gs-psm int)) -(define-extern gs-page-width (function gs-psm int)) -(define-extern gs-page-height (function gs-psm int)) -(define-extern gs-block-width (function gs-psm int)) -(define-extern gs-block-height (function gs-psm int)) -(define-extern gs-largest-block (function int int gs-psm int)) -(define-extern gs-blocks-used (function int int gs-psm int)) -(define-extern texture-page-default-allocate (function texture-pool texture-page kheap int texture-page)) -(define-extern texture-page-common-allocate (function texture-pool texture-page kheap int texture-page)) -(define-extern texture-page-font-allocate (function texture-pool texture-page kheap int texture-page)) -(define-extern texture-page-common-boot-allocate (function texture-pool texture-page kheap int texture-page)) -(define-extern upload-vram-data (function dma-buffer int pointer int int none)) -(define-extern upload-vram-pages (function texture-pool texture-pool-segment texture-page tex-upload-mode bucket-id int)) -(define-extern update-vram-pages (function texture-pool texture-pool-segment texture-page tex-upload-mode int)) -(define-extern upload-vram-pages-pris (function texture-pool texture-pool-segment texture-page bucket-id (pointer int32) int)) -(define-extern texture-page-level-allocate (function texture-pool texture-page kheap int texture-page)) -(define-extern texture-page-size-check (function texture-pool level symbol int)) -(define-extern set-skull-gem-masks (function none)) -(define-extern upload-textures (function texture-pool none)) +(define-extern texture-bpp + "Get the bits-per-pixel in the given texture format" + (function gs-psm int)) +(define-extern texture-qwc + "Get the number of quadwords needed for a given texture size and format. + Does not consider weird PS2 memory layout stuff." + (function int int gs-psm int)) +(define-extern physical-address + "Strip off high 8-bits of a pointer, to bypass the uncached memory mappings. + This gives an address suitable for DMAing from main memory." + (function pointer pointer)) +(define-extern dma-buffer-add-ref-texture "Upload a texture, by reference. Doesn't copy the texture into the DMA buffer - just a reference, + so it is up to the user to make sure the texture is valid during DMA time. + Doesn't set up GIF for receiving textures." (function dma-buffer pointer int int gs-psm none)) +(define-extern gs-find-block + "Lookup offset of block in PS2's swizzled VRAM, as a block index." + (function int int gs-psm int)) +(define-extern gs-page-width + "Get the width of a page, in pixels, for the given texture format." + (function gs-psm int)) +(define-extern gs-page-height + "Get the height of a page, in pixels, for the given texture format." + (function gs-psm int)) +(define-extern gs-block-width + "Get the width of a block, in pixels, for the texture format." + (function gs-psm int)) +(define-extern gs-block-height + "Get the height of a block, in pixels, for the texture format." + (function gs-psm int)) +(define-extern gs-largest-block + "Get the highest block index used by a texture." + (function int int gs-psm int)) +(define-extern gs-blocks-used + "Get the number of blocks used by a texture. + If the texture isn't an even number of pages, the partially completed + page will be counted as the largest used block. + (gaps in this page are counted as used)" + (function int int gs-psm int)) +(define-extern texture-page-default-allocate + "Texture allocation function for textures that permanently live in VRAM. + The texture data is immediately uploaded, then discarded from the heap. + This should only be called during startup." (function texture-pool texture-page kheap int texture-page)) +(define-extern texture-page-common-allocate + "Texture allocation function for textures that share the common segment. + The texture remains in RAM, and is uploaded to VRAM as needed as part + of the main drawing DMA chain." + (function texture-pool texture-page kheap int texture-page)) +(define-extern texture-page-font-allocate + "Texture allocation function for font. This temporarily stores them in the common segment, + removes them from RAM. This is a bit of hack. Later font setup code expects the font texture + to be in common, and they will eventually be moved into the upper 8-bits of the depth buffer." (function texture-pool texture-page kheap int texture-page)) +(define-extern texture-page-common-boot-allocate + "Allocator function for texture loaded at startup time. + For jak 3, this seems to always do default-allocate (permanently in vram?)" (function texture-pool texture-page kheap int texture-page)) +(define-extern upload-vram-data "Add DMA to later upload a texture, by reference. Sets up the GIF for receiving the texture." (function dma-buffer int pointer int int none)) +(define-extern upload-vram-pages "Add DMA to upload a texture page. Will only upload the portion of data that is not already present in VRAM. + This is the old Jak 1 background texture uploading system, which had this near/far concept + for different mip levels. By jak 2, the background system switched to masks and uses + the -pris variant of this function." (function texture-pool texture-pool-segment texture-page tex-upload-mode bucket-id int)) +(define-extern update-vram-pages + "Likely a debug function for checking the logic of upload-vram-pages. Unused" + (function texture-pool texture-pool-segment texture-page tex-upload-mode int)) +(define-extern upload-vram-pages-pris + "Similar to upload-vram-pages, but skips the near/far mode and instead uses masks. + The foreground/background renderers will generate masks telling us which textures are used. + This lets us skip uploading entire textures, or mip levels that won't need. + (side note: this optimization is what causes many of the texturing issues in pcsx2, + where the ps2 and pcsx2 disagree on the mip level to use.)" (function texture-pool texture-pool-segment texture-page bucket-id (pointer int32) int)) +(define-extern texture-page-level-allocate + "Allocation function for level textures." + (function texture-pool texture-page kheap int texture-page)) +(define-extern texture-page-size-check "Check the size of level textures." (function texture-pool level symbol int)) +(define-extern set-skull-gem-masks "Turn on masks for skull gem textures, so they will be uploaded." (function none)) +(define-extern upload-textures "Set up DMA for all texture uploads for this frame." (function texture-pool none)) (define-extern *txt-dma-list* dma-buffer) -(define-extern texture-relocate (function dma-buffer texture int gs-psm int dma-buffer)) -(define-extern relocate-later (function symbol)) -(define-extern texture-page-login (function texture-id (function texture-pool texture-page kheap int texture-page) kheap texture-page-dir-entry)) -(define-extern lookup-texture-by-id (function texture-id texture)) -(define-extern lookup-texture-by-id-fast (function texture-id texture)) -(define-extern lookup-texture-by-name (function string string (pointer texture-page) texture)) -(define-extern lookup-texture-id-by-name (function string string texture-id)) -(define-extern lookup-level-texture-by-name (function string level (pointer texture-page) texture)) +(define-extern texture-relocate "Move a texture in VRAM." (function dma-buffer texture int gs-psm int dma-buffer)) +(define-extern relocate-later + "Unused in jak 2 and likely unsed in jak 3. Feature to postpone some texture copying until + a later frame. This is only used in cases when texture data must be memcpy'd in RAM, to patch up a hole left + by some data that is now permanently in VRAM, and no longer needed. + Note that Jak2/Jak3 don't have this problem since level textures are now never permanent" + (function symbol)) +(define-extern texture-page-login + "'Login' (initialize) a texture page with the pool. + This has a trick - it doesn't actually require you to pass a texture-page object - instead you pass an ID. + If the texture was loaded at all, it will already be known to the texture pool, and this function will do nothing. + However, if the texture is not present, it will be loaded through a call to `loado`, for use in development." + (function texture-id (function texture-pool texture-page kheap int texture-page) kheap texture-page-dir-entry)) +(define-extern lookup-texture-by-id + "Get a texture by ID, loading it if needed (for debugging only)." + (function texture-id texture)) +(define-extern lookup-texture-by-id-fast + "Get a texture by ID. #f if it does not exist." + (function texture-id texture)) +(define-extern lookup-texture-by-name + "Get a loaded texture by name. Slow." + (function string string (pointer texture-page) texture)) +(define-extern lookup-texture-id-by-name + "Get the ID of a loaded texture by name. Slow." + (function string string texture-id)) +(define-extern lookup-level-texture-by-name "Get a texture from a given level, by name." (function string level (pointer texture-page) texture)) (define-extern *shader-list* pair) (define-extern *edit-shader* texture-id) -(define-extern link-texture-by-id (function texture-id adgif-shader texture-page-dir-entry)) +(define-extern link-texture-by-id + "Add this adgif shader to the linked list of shaders associated with the given texture ID. + Will allocate the link array if it's not already." + (function texture-id adgif-shader texture-page-dir-entry)) (define-extern adgif-shader<-texture! (function adgif-shader texture adgif-shader)) -(define-extern adgif-shader-update! (function adgif-shader texture none)) +(define-extern adgif-shader-update! + "Update k based on uv-dist" + (function adgif-shader texture none)) (define-extern adgif-shader<-texture-with-update! (function adgif-shader texture adgif-shader)) -(define-extern hack-texture (function texture float)) -(define-extern adgif-shader-login (function adgif-shader texture)) -(define-extern adgif-shader-login-no-remap (function adgif-shader texture)) -(define-extern adgif-shader-login-fast (function adgif-shader texture)) -(define-extern adgif-shader-login-no-remap-fast (function adgif-shader texture)) -(define-extern adgif-shader<-texture-simple! (function adgif-shader texture adgif-shader)) +(define-extern hack-texture + "adjust some values of a texture, likely for debug." + (function texture float)) +(define-extern adgif-shader-login + "set up an adgif shader with the texture-pool, so it points to the right vram address. + Will remap textures through the level remap table. + If texture is missing, will load it on debug hardware." + (function adgif-shader texture)) +(define-extern adgif-shader-login-no-remap + "Set up an adgif shader with the texture-pool, so it points to the right vram adress. + This does not do level tpage remapping, so the texture should be one that's not loaded in a combine level tpage." + (function adgif-shader texture)) +(define-extern adgif-shader-login-fast + "Set up an adgif shader with the texture-pool, so it points to the right vram address. + Will remap through the level table, so can be used to refer to textures inside 'squashed' + level tpages. + Will not load texture if it is missing." + (function adgif-shader texture)) +(define-extern adgif-shader-login-no-remap-fast + "Set up an adgif shader with the texture-pool, so it points to the right vram address. + Will not remap through the level tpage table. + Will not load texture if it is missing." + (function adgif-shader texture)) +(define-extern adgif-shader<-texture-simple! + "Simple adgif-shader to texture, just sets vram address and format stuff. + Intended for use with fancy texture stuff that will later set the other regs." + (function adgif-shader texture adgif-shader)) (define-extern set-dirty-mask! (function level int int int none)) (define-extern texture-page-dir-inspect (function texture-page-dir symbol none)) (define-extern *texture-pool* texture-pool) @@ -9085,6 +10442,8 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype joint (basic) +"A joint from an animated skeleton. This defines the graph of the skeleton, and also the bind pose +used for the mesh data. The joints are shared between all instances of the same model." ((name basic :offset-assert 4) (number int32 :offset-assert 8) (parent joint :offset-assert 12) ;; guessed by decompiler @@ -9096,6 +10455,7 @@ ) (deftype bone-cache (structure) +"Unused type. Existed in Jak 1, but wasn't used there." ((bone-matrix uint32 :offset-assert 0) (parent-matrix uint32 :offset-assert 4) (dummy uint32 :offset-assert 8) @@ -9107,6 +10467,9 @@ ) (deftype bone (structure) +"The location and scale of a bone in an animated skeleton. Each instance of a skeleton +has its own copy of the bones. This data is used for collision checking or other gameplay math, +but, despite the name, isn't directly used in rendering." ((transform matrix :inline :offset-assert 0) (position vector :inline :offset 48) (scale vector :inline :offset-assert 64) @@ -9117,6 +10480,8 @@ ) (deftype skeleton (inline-array-class) +"Skeleton is an array of bones for the entire character. The bones are stored in an inline array so they can be +easily dma'd to the scratchpad later." ((bones bone :inline :dynamic)) :method-count-assert 9 :size-assert #x10 @@ -9124,6 +10489,8 @@ ) (deftype cspace (structure) +"A cspace describes how to control a bone. It contains a reference to the joint, bone, and a callback function. +The callback function is used to take the joint transforms out of the joint animation, then update the bone." ((parent cspace :offset-assert 0) (joint joint :offset-assert 4) ;; guessed by decompiler (joint-num int16 :offset-assert 8) @@ -9161,6 +10528,12 @@ (declare-type collide-query structure) (deftype drawable (basic) +"Base class for `drawable` scene graph system. +This base class is really abused in many ways, and the meaning of the various methods differ depending +on the exact type. Not even the ID and bsphere here are always populated. +This is used for very high level organization of different rendering data types, and also very low-level +culling/rendering optimizations. It supports both array-of-references and inline-array containers with precise +control over memory layout for use with DMA." ((id int16 :offset-assert 4) (bsphere vector :inline :offset-assert 16) ) @@ -9168,7 +10541,7 @@ :size-assert #x20 :flag-assert #x1100000020 (:methods - (login (_type_) _type_) ;; 9 + (login "Initialize the object after it is loaded." (_type_) _type_) ;; 9 (draw (_type_ _type_ display-frame) none) ;; 10 (fill-collide-list-from-box (_type_ int collide-list collide-query) int) ;; 11 (fill-collide-list-from-line-sphere (_type_ int collide-list collide-query) int) ;; 12 @@ -9188,6 +10561,7 @@ (deftype drawable-error (drawable) +"A drawable which just represents an error. When drawn, it simply displays a sphere with an error message." ((name string :offset-assert 32) ;; guessed by decompiler ) :method-count-assert 17 @@ -9202,6 +10576,8 @@ (deftype drawable-group (drawable) +"Base class for an array of references to other drawables. +These are typically used for very high-level organization of drawable." ((length int16 :offset 6) (data drawable :dynamic :offset-assert 32) ) @@ -9239,6 +10615,15 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype draw-node (drawable) +"Node in a bounding volume heirarchy. This is a base class, and there are no children. +The child is a pointer to the start of inline array of drawables (note: not a drawable-inline-array, literally a bunch of plain drawables) +The size of this array is child-count. The type is either more draw-nodes, or, some other drawable like tfragment, depending on the flags. +Different renderers have different restrictions on the tree structure, like max child count, or if all children have the same depth. +Generally, tfrag/collide use a very rigid equal depth, max 8 children rule, but with shrub, anything goes. +This is a very awkward data structure to traverse, but it is designed for fast view frustum culling. +Note that there can be multiple ways to reach drawables in here in some cases - for example you can follow +this tree, or check one of the depth arrays found in tfrag. +" ((child-count uint8 :offset 6) (flags uint8 :offset 7) (child drawable :offset 8) ;; guessed by decompiler @@ -9263,6 +10648,8 @@ (deftype draw-node-dma (structure) +"DMA buffer layout for draw node culling routine, which copies draw-nodes directly to scratchpad in bulk. +This would not work with the memory layout of shrub." ((banka draw-node 32 :inline :offset-assert 0) (bankb draw-node 32 :inline :offset-assert 1024) ) @@ -9277,11 +10664,16 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype drawable-tree (drawable-group) +"A drawable tree is a container of drawables of a specific rendering type. +Instead of having a single large tree of mixed types, there will be a tree of tfrags, a tree of ties, etc. +The top-level tfrag tree will have a type that's a child of drawable-tree. +Generally, the object passed to a large renderer is a drawable-tree." () :flag-assert #x1100000020 ) (deftype drawable-tree-array (drawable-group) +"Collection of drawable trees. This might have a tfrag tree, tie tree, etc." ((trees drawable-tree :dynamic :offset 32 :score 100)) :flag-assert #x1100000020 (:methods @@ -9300,6 +10692,9 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype drawable-actor (drawable) +"Wrapper around an entity-actor to put it in the drawable system. +Note that this is never used to actually draw actors - it is just used as a list of all entity-actors +for the entity/birth system." ((actor entity-actor :offset 8) ;; guessed by decompiler ) :method-count-assert 17 @@ -9309,11 +10704,13 @@ (deftype drawable-tree-actor (drawable-tree) +"Adapater for putting the actors in the tree-array." () :flag-assert #x1100000020 ) (deftype drawable-inline-array-actor (drawable-inline-array) +"Array of drawable-actors." ((data drawable-actor 1 :inline) (pad uint8 4)) :flag-assert #x1100000044 @@ -9326,6 +10723,10 @@ (deftype region (structure) +"A region is a closed volume that you can, enter, exit, and be inside. +This stores a unique, and script functions for a single region. +These are stored separately from the actual geometry to allow the geometry to be smaller +and fit in scratchpad/cache better." ((id uint32 :offset-assert 0) (on-enter pair :offset-assert 4) (on-inside pair :offset-assert 8) @@ -9335,12 +10736,13 @@ :size-assert #x10 :flag-assert #xa00000010 (:methods - (region-method-9 (_type_ vector) symbol) ;; 9 + (point-in-region-debug! "Debug check to see if point is in region. This is not efficient, since it has to find the parent geometry of this region." (_type_ vector) symbol) ;; 9 ) ) (deftype region-array (inline-array-class) +"Array of region." ((data region :inline :dynamic :offset-assert 16) ) :method-count-assert 9 @@ -9350,6 +10752,8 @@ (declare-type region-prim-area structure) (deftype drawable-region-prim (drawable) +"Base class for a region + geometry. +Note that all child classes of this must be 32-bytes." ((region region :offset 8) ) :method-count-assert 20 @@ -9365,6 +10769,7 @@ ) (deftype drawable-tree-region-prim (drawable-tree) +"Top-level container for all regions of a level." ((name basic :offset 8) (data2 drawable-inline-array :dynamic :offset 32 :score 1)) :method-count-assert 19 @@ -9378,6 +10783,8 @@ (deftype drawable-inline-array-region-prim (drawable-inline-array) +"Inline array of drawable-region-prim. This actually stores child classes, but they are +exactly the same size as the parent, so it's okay." ((data drawable-region-prim 1 :inline :offset-assert 32) (pad uint8 4)) :flag-assert #x1100000044 @@ -9385,6 +10792,7 @@ (deftype drawable-region-sphere (drawable-region-prim) +"Region where the bsphere of the drawable is the volume." () :method-count-assert 20 :size-assert #x20 @@ -9392,6 +10800,7 @@ ) (deftype region-face-data (structure) +"Data to store a single planar face, as a normal and list of vertices." ((normal vector :inline :offset-assert 0) (normal-offset float :offset 12) (num-points uint32 :offset-assert 16) @@ -9403,6 +10812,7 @@ ) (deftype drawable-region-face (drawable-region-prim) +"A drawable-region which is just a face. Unclear if `on-inside` is used." ((data region-face-data :offset 12) ) :method-count-assert 20 @@ -9411,6 +10821,7 @@ ) (deftype region-face-array (inline-array-class) +"An array of faces that hopefully make a closed volume." ((data drawable-region-face :inline :dynamic :offset 16) (pad0 uint8 4) ) @@ -9420,6 +10831,7 @@ ) (deftype drawable-region-volume (drawable-region-prim) +"A drawable-region which is a bunch of faces that represent a closed volume." ((faces region-face-array :offset 12) ) :method-count-assert 20 @@ -9428,6 +10840,7 @@ ) (deftype region-prim-list (structure) +"A list of drawable-region-prim. This is the return type of queries like `which regions contain this point?`" ((num-items int32 :offset-assert 0) (items drawable-region-prim 320 :offset-assert 4) ) @@ -10440,6 +11853,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype gsf-vertex (structure) +"Vertex used by generic. GSF = generic stripped fragment?" ((data uint32 8 :offset-assert 0) (byte uint8 32 :offset 0) (quad uint128 2 :offset 0) @@ -10459,6 +11873,8 @@ ) (deftype gsf-fx-vertex (structure) +"Color/texture data only. Possibly used to share with a gsf-vertex with +the same position/normal." ((clr vector4ub :inline :offset-assert 0) (tex vector2uh :inline :offset-assert 4) ) @@ -10469,6 +11885,7 @@ (deftype gsf-header (structure) +"Header for generic data." ((num-strips uint8 :offset-assert 0) (num-new-vtxs uint8 :offset-assert 1) (num-dps uint16 :offset-assert 2) @@ -11544,6 +12961,8 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype palette-fade-control (structure) +"Unused interface to the time-of-day control. Was used in jak 1 as an interface between level code, +and the code in mood.gc, which set the actual fade values for time-of-day." ((trans vector :inline :offset-assert 0) (fade float :offset-assert 16) (actor-dist float :offset-assert 20) @@ -11554,6 +12973,8 @@ ) (deftype palette-fade-controls (basic) +"Unused interface to the time-of-day control. Was used in jak 1 as an interface between level code, +and the code in mood.gc, which set the actual fade values for time-of-day." ((control palette-fade-control 8 :inline :offset-assert 16) ;; guessed by decompiler ) :method-count-assert 11 @@ -11567,6 +12988,7 @@ (declare-type sparticle-launch-control inline-array-class) (deftype time-of-day-proc (process) +"Process for running things that change with the time-of-day, like lighting, sun/stars/moon, etc." ((hours int32 :offset-assert 128) (minutes int32 :offset-assert 132) (seconds int32 :offset-assert 136) @@ -11592,6 +13014,9 @@ ) (deftype time-of-day-palette (basic) +"Pre-baked lighting values used by rendering code. The exact meaning of this data can vary, +but in all cases, the time-of-day system can do linear interpolation of two palettes to +blend between them." ((width int32 :offset-assert 4) (height int32 :offset-assert 8) (pad int32 :offset-assert 12) @@ -11620,6 +13045,7 @@ ) (deftype time-of-day-context (basic) +"A mix of inputs/outputs to the time-of-day system." ((interp float 6 :offset-assert 4) ;; guessed by decompiler (current-fog mood-fog :inline :offset-assert 32) (current-sky-color vector :inline :offset-assert 80) @@ -11653,6 +13079,7 @@ (deftype time-of-day-dma (structure) +"Memory layout for the time-of-day interpolation functions." ((outa uint32 256 :offset-assert 0) ;; guessed by decompiler (outb uint32 256 :offset-assert 1024) ;; guessed by decompiler (banka uint32 256 :offset-assert 2048) ;; guessed by decompiler @@ -11671,6 +13098,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype joint-anim (basic) +"Base class for all joint animations. These are animations that store joint transforms." ((name string :offset-assert 4) ;; guessed by decompiler (number int16 :offset-assert 8) (length int16 :offset-assert 10) @@ -11681,11 +13109,13 @@ ) (deftype joint-anim-matrix (joint-anim) +"Joint animation which stores matrices directly. Not used." ((data matrix :inline :dynamic :offset 16)) :flag-assert #x900000010 ) (deftype joint-anim-transformq (joint-anim) +"Joint animation which stores transformq's directly. Not used." ((data transformq :inline :dynamic :offset 16) ) :method-count-assert 9 @@ -11694,6 +13124,7 @@ ) (deftype joint-anim-drawable (joint-anim) +"Mysterious unused joint animation type." ((data drawable :dynamic :offset-assert 12) ;; guessed by decompiler ) :method-count-assert 9 @@ -11702,6 +13133,10 @@ ) (deftype joint-anim-frame (structure) +"Frame containing all joint transforms. Note that there are two special frames: align and prejoint. +The 'align' frame is used for the complicated animation alignment system, which allows the animation to move +a character, among other things. The prejoint is just the root of the skeleton. +The remaining transformq's are the joint transforms you'd expect." ((matrices matrix 2 :inline :offset-assert 0) ;; guessed by decompiler (data transformq :dynamic :inline :offset-assert 128) ;; guessed by decompiler ) @@ -11714,6 +13149,7 @@ ) (deftype joint-anim-compressed-hdr (structure) +"Header for the compressed joint animation format." ((control-bits uint32 14 :offset-assert 0) ;; guessed by decompiler (num-joints uint32 :offset-assert 56) (matrix-bits uint32 :offset-assert 60) @@ -11762,6 +13198,8 @@ ) (deftype art (basic) +"Base class for anything considered `art`. This is typically foreground model data. +This can be either an art container containing more arts, or an actual art thing (art-element)." ((name string :offset 8) ;; guessed by decompiler (length int32 :offset-assert 12) (extra res-lump :offset-assert 16) ;; guessed by decompiler @@ -11779,6 +13217,7 @@ (deftype art-element (art) +"Base class Art which is not a container of more art." ((pad uint8 12)) :method-count-assert 13 :size-assert #x20 @@ -11787,12 +13226,14 @@ (deftype art-mesh-anim (art-element) +"An unused mesh animation." ((data basic :dynamic)) :flag-assert #xd00000020 ) (declare-type merc-eye-anim-block structure) (deftype art-joint-anim (art-element) +"Art for a joint animation. Also contains the eye animation." ((speed float :offset 20) (artist-base float :offset 24) (artist-step float :offset 28) @@ -11824,18 +13265,22 @@ ) (deftype art-mesh-geo (art-element) +"Unused art format for a mesh. This might have been for the renderer that came before merc." ((data basic :dynamic :offset-assert 32) ) :flag-assert #xd00000020 ) (deftype art-joint-geo (art-element) +"Collection of joints for an actor." ((data joint :dynamic :offset-assert 32) ) :flag-assert #xd00000020 ) (deftype art-joint-anim-manager-slot (structure) +"Record for an animation which is additionally compressed with LZO compression over the entire animation. +This is used for short, commonly used animations that always remain in RAM." ((anim art-joint-anim :offset-assert 0) (comp-data uint32 :offset-assert 4) (time-stamp uint64 :offset-assert 8) @@ -11847,6 +13292,7 @@ (deftype art-joint-anim-manager (basic) +"Cache for LZO decompression of animations." ((kheap kheap :inline) (free-index int32) (slot art-joint-anim-manager-slot 64 :inline) @@ -11866,6 +13312,8 @@ ) (deftype skeleton-group (art-group) +"Unlike other art types, the skeleton-groups are defined in GOAL code. +This stores settings like the name of the art-group, shadow/level-of-detail settings, etc." ((art-group-name string :offset-assert 32) ;; guessed by decompiler (jgeo int32 :offset-assert 36) (janim int32 :offset-assert 40) @@ -11894,6 +13342,7 @@ (declare-type merc-ctrl art-element) (deftype lod-group (structure) +"A single level of detail mesh." ((geo merc-ctrl :offset-assert 0) ;; guessed by decompiler (dist meters :offset-assert 4) ) @@ -11904,6 +13353,7 @@ ) (deftype lod-set (structure) +"All the different level-of-detail meshes for an actor." ((lod lod-group 6 :inline :offset-assert 0) ;; guessed by decompiler (max-lod int8 :offset-assert 48) ) @@ -11957,6 +13407,8 @@ (declare-type joint-control basic) (deftype draw-control (basic) +"The draw-control is a collection of all the stuff that the foreground rendering system needs to draw something. +Each process-drawable has a draw-control." ((process process-drawable :offset-assert 4) (status draw-control-status) (data-format draw-control-data-format) @@ -12019,6 +13471,9 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype pris-mtx (structure) +"Matrix for merc rendering. Named after the earlier 'pris' renderer. +Contains a transformation matrix for vertices, one for normals, and a scale. +This matrix is likely not used by generic VU1, but is used by the merc -> generic converter." ((data float 32 :offset-assert 0) ;; guessed by decompiler (vector vector 8 :offset 0) ;; guessed by decompiler (t-mtx matrix :inline :offset 0) @@ -12041,6 +13496,7 @@ ) (deftype generic-constants (structure) +"Constant data sent to VU1 for generic rendering." ((fog vector :inline :offset-assert 0) (adgif gs-gif-tag :inline :offset-assert 16) ;; was qword (hvdf-offset vector :inline :offset-assert 32) @@ -12104,6 +13560,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype ripple-merc-query (inline-array-class) +"Information about which merc vertices to apply the 'ripple' effect to." ((start-vertex int32 :offset-assert 16) (vertex-skip int32 :offset-assert 20) (vertex-count int32 :offset-assert 24) @@ -12116,6 +13573,7 @@ ) (deftype merc-byte-header (structure) +"Header for a single [[merc-fragment]] uploaded to the VU." ((srcdest-off uint8 :offset-assert 0) (rgba-off uint8 :offset-assert 1) (lump-off uint8 :offset-assert 2) @@ -12137,6 +13595,7 @@ ) (deftype merc-fragment (structure) +"A single merc fragment that fits into VU memory." ((header merc-byte-header :inline :offset-assert 0) (rest uint8 1 :offset-assert 23) ;; guessed by decompiler ) @@ -12149,6 +13608,7 @@ ) (deftype merc-vtx (structure) +"A packed merc vertex." ((mat-0 uint8 :offset-assert 0) (mat-1 uint8 :offset-assert 1) (nrm-x uint8 :offset-assert 2) @@ -12168,6 +13628,7 @@ ) (deftype merc-fp-header (structure) +"Merc header for a [[merc-fragment]]'s floating point data." ((x-add float :offset-assert 0) (y-add float :offset-assert 4) (z-add float :offset-assert 8) @@ -12182,6 +13643,7 @@ ) (deftype merc-mat-dest (structure) +"Metadata for a merc matrix upload." ((matrix-number uint8 :offset-assert 0) (matrix-dest uint8 :offset-assert 1) ) @@ -12192,6 +13654,7 @@ ) (deftype merc-fragment-control (structure) +"Data about a [[merc-fragment]] needed for merc DMA generation." ((unsigned-four-count uint8 :offset-assert 0) (lump-four-count uint8 :offset-assert 1) (fp-qwc uint8 :offset-assert 2) @@ -12204,11 +13667,13 @@ ) (deftype merc-blend-data (structure) ;; was unknown! +"Packed BLERC data." ((int8-data int8 :dynamic :offset-assert 0) ) ) (deftype merc-blend-ctrl (structure) +"Information about the vertices of a model modified by BLERC." ((blend-vtx-count uint8 :offset-assert 0) (nonzero-index-count uint8 :offset-assert 1) (bt-index uint8 :dynamic :offset-assert 2) ;; guessed by decompiler @@ -12219,6 +13684,7 @@ ) (deftype mei-envmap-tint (structure) +"Data for the extra 'envmap tint' effect." ((fade0 float :offset-assert 0) (fade1 float :offset-assert 4) (tint rgba :offset-assert 8) @@ -12230,6 +13696,7 @@ ) (deftype mei-texture-scroll (structure) +"Data for the extra 'texscroll' effect." ((max-dist float :offset-assert 0) (st-int-scale uint8 :offset-assert 4) (time-factor uint8 :offset-assert 5) @@ -12244,6 +13711,7 @@ ) (deftype mei-ripple (structure) +"Data for the extra 'ripple' effect." ((x-base float :offset-assert 0) (z-base float :offset-assert 4) (grid-size float :offset-assert 8) @@ -12255,6 +13723,7 @@ ) (deftype merc-extra-info (structure) +"Info for merc extra effects." ((envmap-tint-offset uint8 :offset-assert 0) (shader-offset uint8 :offset-assert 1) (texture-scroll-offset uint8 :offset-assert 2) @@ -12280,6 +13749,7 @@ ) (deftype merc-effect (structure) +"A collection of [[merc-fragment]]s with data for any extra effects." ((frag-geo merc-fragment :offset-assert 0) (frag-ctrl merc-fragment-control :offset-assert 4) (blend-data merc-blend-data :offset-assert 8) @@ -12303,6 +13773,7 @@ ) (deftype merc-eye-ctrl (structure) +"Eye info for both eyes of a merc model." ((eye-slot int8 :offset-assert 0) (shader-offset int8 :offset-assert 1) (shader-count int8 :offset-assert 2) @@ -12320,6 +13791,7 @@ ) (deftype merc-eye-anim-frame (structure) +"A single frame of a merc eye animation." ((pupil-trans-x int8 :offset-assert 0) (pupil-trans-y int8 :offset-assert 1) (blink int8 :offset-assert 2) @@ -12335,6 +13807,7 @@ ) (deftype merc-eye-anim-block (structure) +"A list of eye animation frames." ((max-frame int16 :offset-assert 0) (data merc-eye-anim-frame :inline :dynamic :offset-assert 8) ;; guessed by decompiler ) @@ -12352,6 +13825,8 @@ ) (deftype merc-ctrl-header (structure) +"The header for a [[merc-ctrl]], +containing metadata about the model used for drawing." ((xyz-scale float :offset-assert 0) (st-magic uint32 :offset-assert 4) (st-out-a uint32 :offset-assert 8) @@ -12407,6 +13882,8 @@ ) (deftype merc-ctrl (art-element) +"The merc data for a single model as it's stored in an art group. +Consists of a header and a list of [[merc-effect]]s." ((num-joints int32 :offset 20) (seg-table (array uint64) :offset 24) (header merc-ctrl-header :inline :offset-assert 32) @@ -12965,6 +14442,7 @@ ) (deftype shadow-settings (structure) +"Settings used to draw a shadow." ((flags shadow-flags :offset 12) ;; shadow-flags (center vector :inline :offset 0 :score -1) (shadow-dir vector :inline :offset-assert 16) @@ -13000,6 +14478,7 @@ ) (deftype shadow-data (structure) +"DMA data for the shadow renderer." ((dma-unpack-template dma-packet :inline :offset-assert 0) (dma-cnt dma-tag :offset-assert 16) ;; was u64 (vif-nop vif-tag :offset-assert 24) ;; guessed by decompiler @@ -13144,6 +14623,7 @@ ) (deftype shadow-geo (art-element) +"The low poly model used for drawing the shadow." ((version uint32 :offset 20) (total-qwc uint32 :offset-assert 32) (num-joints uint32 :offset-assert 36) @@ -13176,6 +14656,7 @@ ) (deftype mc-file-info (structure) +"Data stored in a save file." ((present int32 :offset-assert 0) (blind-data float 16 :offset 4) ;; guessed by decompiler (blind-data-int8 int8 64 :offset 4) ;; guessed by decompiler @@ -13201,6 +14682,7 @@ ) (deftype mc-slot-info (structure) +"Data about a memory card slot." ((handle int32 :offset-assert 0) (known int32 :offset-assert 4) (formatted int32 :offset-assert 8) @@ -13247,9 +14729,13 @@ (define-extern mc-save (function int int pointer int mc-status-code)) (define-extern mc-load (function int int pointer mc-status-code)) (declare-type mc-slot-info structure) -(define-extern mc-sync (function int)) +(define-extern mc-sync + "Synchronize the memory card state." + (function int)) (define-extern mc-get-slot-info (function int mc-slot-info none)) -(define-extern show-mc-info (function dma-buffer none)) +(define-extern show-mc-info + "Display the memory card debug text." + (function dma-buffer none)) (define-extern mc-check-result (function mc-status-code)) ;; mc-makefile @@ -13771,6 +15257,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype talker-speech-class (structure) +"Contains metadata about a voice line or hint text being played/displayed." ((name string :offset-assert 0) (channel gui-channel :offset-assert 4) (flags uint8 :offset-assert 5) @@ -14263,6 +15750,8 @@ (declare-type joint-control basic) (deftype joint-control-channel (structure) +"A single animation channel that controls a number of joints. +Multiple channels are used to blend animations together." ((parent joint-control :offset-assert 0) (frame-group art-joint-anim :offset-assert 4) (frame-num float :offset-assert 8) @@ -14336,6 +15825,7 @@ (declare-type effect-control basic) (deftype joint-control (basic) +"Every [[process-drawable]] has a [[joint-control]] that handles all the animation channels." ((status joint-control-status) (allocated-length uint8) (active-channels uint8) @@ -14374,6 +15864,7 @@ ) (deftype channel-upload-info (structure) +"Information about an upload of animation data to a single joint channel." ((fixed joint-anim-compressed-fixed :offset-assert 0) (fixed-qwc int32 :offset-assert 4) (frame joint-anim-compressed-frame :offset-assert 8) @@ -14528,6 +16019,8 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype mercneric-chain (structure) +"A DMA chain for drawing with mercneric, and metadata needed to append. +This chain is assumed to run with a specific tpage from a specific level available." ((first uint32 :offset-assert 0) (next uint32 :offset-assert 4) (state generic-bucket-state :inline :offset-assert 8) @@ -14540,6 +16033,8 @@ ) (deftype merc-chain (structure) +"A DMA chain for drawing with merc. +This chain is assumed to run with a specific tpage from a specific level available." ((first dma-packet :offset-assert 0) (patch dma-packet :offset-assert 4) (vu1-bucket bucket-id :offset-assert 8) @@ -14551,6 +16046,7 @@ ) (deftype foreground-bucket (structure) +"A foreground bucket is merc, emerc, and mercneric chain for a given texture mode." ((merc merc-chain :inline :offset-assert 0) (emerc merc-chain :inline :offset-assert 12) (mercneric mercneric-chain :inline :offset-assert 24) @@ -14561,6 +16057,9 @@ ) (deftype foreground-level-buckets (structure) +"Collection of buckets for a single level. +Each bucket has a different texture. The order is: +tfrag, pris, shrub, alpha, water, pris, pris2" ((data foreground-bucket 7 :inline :offset-assert 0) ) :method-count-assert 9 @@ -14570,6 +16069,7 @@ (deftype foreground-bucket-grid (structure) +"Array of buckets for each level, plus the single warp chain shared between everybody." ((level-buckets foreground-level-buckets 7 :inline :offset-assert 0) (warp-chain mercneric-chain :inline :offset-assert 2352) ) @@ -14579,6 +16079,8 @@ ) (deftype foreground-regs (structure) +"Frequently accessed foreground values. These are in scratchpad for fast access +during foreground processing." ((dist float :offset-assert 0) (merc-used uint32 :offset-assert 4) (emerc-used uint32 :offset-assert 8) @@ -14600,6 +16102,9 @@ ) (deftype foreground-work (structure) +"Memory map for scratchpad during foreground processing. +This is not used by the renderers, bone matrix, or joint code - just the code +that assigns stuff to buckets and prepares DMA for merc (or requests for generic merc)." ((regs foreground-regs :inline :offset-assert 0) (draw-index-map uint8 7 :offset 64) ;; ???? (grid foreground-bucket-grid :inline :offset-assert 80) @@ -14614,6 +16119,7 @@ ) (deftype texscroll-globals (structure) +"List of all merc-effects that need texscroll applied." ((requests int32 :offset-assert 0) (effects merc-effect 32 :offset-assert 4) ;; guessed by decompiler ) @@ -14623,6 +16129,8 @@ ) (deftype merc-effect-bucket-info (structure) +"Scratch info computed per-merc-effect by the foreground code, then later read by merc +DMA generation. This is only for the currently-processing merc model's effects." ((color-fade rgba :offset-assert 0) ;; guessed by decompiler (alpha uint8 :offset 3) (merc-path uint8 :offset-assert 4) @@ -14637,6 +16145,7 @@ ) (deftype merc-bucket-info (structure) +"Scratch info for the current merc-ctrl. Written by the foreground code, read by merc DMA generation." ((light vu-lights :inline :offset-assert 0) (needs-clip int32 :offset-assert 112) (need-mercprime-if-merc int32 :offset-assert 116) @@ -14649,6 +16158,7 @@ ) (deftype foreground-globals (structure) +"The foreground renderer state: all DMA chains, settings for the current merc-ctrl, texscroll list." ((foreground-grid foreground-bucket-grid :inline :offset-assert 0) (merc-bucket-info merc-bucket-info :inline :offset-assert 2384) (texscroll texscroll-globals :inline :offset-assert 3024) @@ -14659,6 +16169,7 @@ ) (deftype shadow-dma-packet (structure) +"DMA tag for submitting shadow data." ((tag generic-merc-tag :inline :offset-assert 0) (settings shadow-settings :inline :offset-assert 16) (geo-ref dma-packet :inline :offset-assert 96) @@ -14800,6 +16311,7 @@ ;; TODO confirm, this is just copied from jak1 (deftype res-tag (uint128) +"Metadata about a property in a [[res-lump]], such as name, element type and element count." ((name symbol :offset 0) (key-frame float :offset 32) (elt-type type :offset 64) @@ -14822,6 +16334,9 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype res-tag-pair (uint64) +"The indices of two [[res-tag]]s. If the specific key-frame time is in between two +res-tags, this type is used to return the indices of the first res-tag before and after +the specified time." ((lo int32 :offset 0) (hi int32 :offset 32) ) @@ -14829,6 +16344,7 @@ ) (deftype res-lump (basic) +"A collection of [[res-tag]]s and their data." ((length int32 :offset-assert 4) (allocated-length int32 :offset-assert 8) (data-base pointer :offset-assert 12) ;; guessed by decompiler @@ -14843,19 +16359,62 @@ ;; field extra uses ~A with a signed load (:methods (new (symbol type int int) _type_) ;; 0 - (get-property-data (_type_ symbol symbol float pointer (pointer res-tag) pointer) pointer :no-virtual) ;; 9 - (get-property-struct (_type_ symbol symbol float structure (pointer res-tag) pointer) structure :no-virtual) ;; 10 - (get-property-value (_type_ symbol symbol float uint128 (pointer res-tag) pointer) uint128 :no-virtual) ;; 11 + (get-property-data + "Returns an address to a given property's data at a specific time stamp, or default on error. + @param name is the name of the property you want, mode is its lookup mode ('interp 'base 'exact), time is the timestamp. + @param default is the default result returned in the case of an error. + @param tag-addr is an address to a res-tag. The current base tag is written to this. Ignored if tag-addr is #f + @param buf-addr is an address to the data buffer used to write interpolated data to. It must have enough space! Only necessary for 'interp mode." + (_type_ symbol symbol float pointer (pointer res-tag) pointer) pointer :no-virtual) ;; 9 + (get-property-struct + "Returns a given struct property's value at a specific time stamp, or default on error. + @param name is the name of the property you want, `mode` is its lookup mode ('interp 'base 'exact), `time` is the timestamp. + @param default is the default result returned in the case of an error. + @param tag-addr is an address to a [[res-tag]]. The current base tag is written to this. Ignored if tag-addr is #f. + @param buf-addr is an address to the data buffer used to write interpolated data to. + It must have enough space! Only necessary for 'interp mode." (_type_ symbol symbol float structure (pointer res-tag) pointer) structure :no-virtual) ;; 10 + (get-property-value + "Returns a given value property's value at a specific time stamp, or default on error. + @param name is the name of the property you want, `mode` is its lookup mode ('interp 'base 'exact), `time` is the timestamp. + @param default is the default result returned in the case of an error. + @param tag-addr is an address to a res-tag. The current base tag is written to this. Ignored if `tag-addr` is #f. + @param buf-addr is an address to the data buffer used to write interpolated data to. + It must have enough space! Only necessary for 'interp mode." (_type_ symbol symbol float uint128 (pointer res-tag) pointer) uint128 :no-virtual) ;; 11 (get-property-value-float (_type_ symbol symbol float float (pointer res-tag) pointer) float :no-virtual) ;; 12 - (get-tag-index-data (_type_ int) pointer) ;; 13 - (get-tag-data (_type_ res-tag) pointer) ;; 14 - (allocate-data-memory-for-tag! (_type_ res-tag) res-tag) ;; 15 - (sort! (_type_) _type_) ;; 16 - (add-data! (_type_ res-tag pointer) res-lump) ;; 17 - (add-32bit-data! (_type_ res-tag object) res-lump) ;; 18 - (lookup-tag-idx (_type_ symbol symbol float) res-tag-pair :no-virtual) ;; 19 - (make-property-data (_type_ float res-tag-pair pointer) pointer) ;; 20 - (get-curve-data! (_type_ curve symbol symbol float) symbol) ;; 21 + (get-tag-index-data "Get the data address of the n'th tag." (_type_ int) pointer) ;; 13 + (get-tag-data "Get the data address of the specified tag." (_type_ res-tag) pointer) ;; 14 + (allocate-data-memory-for-tag! + "Find space for the data described by arg0 in this. + Returns a tag with data-offset set correctly for this res-lump. + If the lump already contains memory for the given tag, and it is big enough, + it will be reused. Alignment will be at least 8 bytes. + If the input tag has elt-count = 0, it will return a tag for elt-count = 1." (_type_ res-tag) res-tag) ;; 15 + (sort! "Sort all tags based on name, then key-frame." (_type_) _type_) ;; 16 + (add-data! + "Given a tag and a pointer to its data, copy it to this res-lump. + This doesn't seem to do the right thing if the given tag is a non-inline tag + with > 1 element." (_type_ res-tag pointer) res-lump) ;; 17 + (add-32bit-data! "Add a single 32-bit value using [[add-data!]]." (_type_ res-tag object) res-lump) ;; 18 + (lookup-tag-idx + "Look up the index of the tag containing with the given name and timestamp. + Correct lookups return a res-tag-pair, which contains one tag index in the lower 32 bits and one in the upper 32 bits. + Depending on the mode, they may be the same, or they may be two tags that you should interpolate + between, if the exact time was not found. + + @param name-sym should be the name of the thing you want. + @param time is for the timestamp you want. + If mode = 'base, then both the indices are the same and the timestamp is ignored. + If mode = 'interp, then it tries to get closest below/closest above (or both the same, if exact match found). + If mode = 'exact, then it requires an exact timestamp match and both indices are the same. + If things go wrong, returns a negative number." (_type_ symbol symbol float) res-tag-pair :no-virtual) ;; 19 + (make-property-data + "Returns (a pointer to) the value data of a property with the tag-pair. + If tag-pair does not represent an exact point in the timeline, then the data is interpolated based on time + with the result written into buf. buf must have enough space to copy all of the data. + Otherwise, simply returns an address to the resource binary." (_type_ float res-tag-pair pointer) pointer) ;; 20 + (get-curve-data! + "Read curve data and write it to curve-target. Return #t if both + control points and knots data was succesfully read, #f otherwise." (_type_ curve symbol symbol float) symbol) ;; 21 ) ) @@ -14989,6 +16548,9 @@ (declare-type control-info basic) (deftype surface (basic) +"Definition of a bunch of parameters for different types of surfaces. +Parameters include values such as max speed, friction, callback functions that run +on impact, during touch, on exit, etc." ((name symbol) ;(data float 30 :score -1) (turnv float :offset-assert 8) @@ -15624,6 +17186,10 @@ (declare-type carry-info basic) (declare-type rigid-body-control basic) (deftype process-drawable (process) +"This is the main base class for in-game objects. +This handles drawing, collision, animation, navigation, particles, sounds, physics, etc. +The actual child classes will add most of the functionality, and this just serves as a common +container for references to the `-control` objects for this object." ((root trsqv :offset-assert 128) ;; guessed by decompiler (node-list cspace-array :offset-assert 132) ;; guessed by decompiler (draw draw-control :offset-assert 136) ;; guessed by decompiler @@ -15659,6 +17225,9 @@ ) (deftype process-drawable-reserved (process-drawable) +"A process drawable with a lot of unused method slots. +GOAL cannot increase the number of methods at runtime, so, for interactive development, it is useful +to have a type with a large number of slots which can be turned into real methods without needed to reboot the PS2." () :method-count-assert 178 :size-assert #xc8 @@ -15826,6 +17395,7 @@ ) (deftype attack-dir-info (structure) +"Information about the position/direction of an attack." ((dir vector :inline :offset-assert 0) (xz-dir vector :inline :offset-assert 16) (attacker-velocity vector :inline :offset-assert 32) @@ -15885,6 +17455,7 @@ (declare-type touching-shapes-entry structure) (deftype attack-info (structure) +"Information about an incoming attack." ((trans vector :inline :offset-assert 0) (vector vector :inline :offset-assert 16) (attacker-velocity vector :inline :offset-assert 32) @@ -16101,6 +17672,7 @@ ) (deftype sync-info-params (structure) +"Parameters used to set up a [[sync-info]]." ((sync-type symbol :offset-assert 0) (sync-flags sync-flags :offset-assert 8) (entity basic :offset-assert 16) @@ -16309,6 +17881,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype smush-control (structure) +"This holds information about the current state of an object's smush." ((start-time time-frame :offset-assert 0) ;; time-frame (period float :offset-assert 8) (duration float :offset-assert 12) @@ -16430,6 +18003,8 @@ ;; ---joint-mod-h:track-mode (deftype joint-mod (basic) +"Utility to modify a joint transform from code, rather than just getting it from animation. +This is used to make jak look toward an enemy, for example." ((mode joint-mod-mode) (process process-drawable) (joint cspace) @@ -16478,7 +18053,7 @@ (mode-set! (_type_ joint-mod-mode) none) ;; 9 (target-set! (_type_ vector) none) ;; 10 (look-at! (_type_ vector symbol process) none :behavior process) ;; 11 - (reset-blend! (_type_) _type_) ;; 12 + (reset-blend! "Set the blend to 0." (_type_) _type_) ;; 12 (twist-set! (_type_ float float float) vector) ;; 13 (trs-set! (_type_ vector quaternion vector) none) ;; 14 (shut-down (_type_) none) ;; 15 @@ -16511,6 +18086,7 @@ ) (deftype joint-mod-set-local (basic) +"Override the trans, quat, and scale of the joint transform. The component to override is selected by the flag." ((transform transformq :inline :offset-assert 16) (set-rotation symbol :offset-assert 64) (set-scale symbol :offset-assert 68) @@ -16526,6 +18102,8 @@ ) (deftype joint-mod-add-local (basic) +"Add to the trans, rotate the quat, and multiply the scale of the joint transform. The components can be selected by the flag. +Unlike jak 2, this actually multiplies the scale, instead of adding." ((transform transformq :inline :offset-assert 16) (add-rotation symbol :offset-assert 64) (add-scale symbol :offset-assert 68) @@ -16541,6 +18119,8 @@ ) (deftype joint-mod-set-world (basic) +"Directly overwrite the _bone_ transform (ignoring the parent entirely). +This does not pay attention to the flags." ((transform transformq :inline :offset-assert 16) (node-index int32 :offset-assert 64) (enable symbol :offset-assert 68) @@ -16554,6 +18134,8 @@ ) (deftype joint-mod-blend-local (basic) +"Blend the _joint_ transform between this transform and the animated one. +Then, apply the normal parented transform." ((transform transformq :inline :offset-assert 16) (blend-transform transformq :inline :offset-assert 64) (node-index int32 :offset-assert 112) @@ -16569,6 +18151,7 @@ ) (deftype joint-mod-spinner (basic) +"Control a joint by just spinning it around an axis." ((spin-axis vector :inline :offset-assert 16) (angle float :offset-assert 32) (spin-rate float :offset-assert 36) @@ -16591,6 +18174,7 @@ ) (deftype joint-mod-blend-world (basic) +"Blend the _bone_ transform between this one and the animated one." ((transform transformq :inline :offset-assert 16) (blend-transform transformq :inline :offset-assert 64) (blend-flags joint-mod-blend-flags :offset-assert 112) @@ -16653,16 +18237,19 @@ ) ) -(define-extern joint-mod-debug-draw (function joint-mod none)) +(define-extern joint-mod-debug-draw "Debug draw the bone transform for the associated bone of a joint-mod" (function joint-mod none)) (define-extern *joint-axis-vectors* (inline-array vector)) (define-extern joint-mod-wheel-callback (function cspace transformq none)) -(define-extern joint-mod-set-local-callback (function cspace transformq none)) -(define-extern joint-mod-add-local-callback (function cspace transformq none)) -(define-extern joint-mod-set-world-callback (function cspace transformq none)) -(define-extern joint-mod-blend-local-callback (function cspace transformq none)) -(define-extern joint-mod-spinner-callback (function cspace transformq none)) -(define-extern joint-mod-blend-world-callback (function cspace transformq none)) -(define-extern joint-mod-rotate-local-callback (function cspace transformq none)) +(define-extern joint-mod-set-local-callback "Callback for joint-mod-rotate-local. See comment on that type." (function cspace transformq none)) +(define-extern joint-mod-add-local-callback "Callback for joint-mod-add-local. See comment on that type." (function cspace transformq none)) +(define-extern joint-mod-set-world-callback "Callback for joint-mod-set-world. See comment on that type." (function cspace transformq none)) +(define-extern joint-mod-blend-local-callback "Callback for joint-mod-blend-local. See comment on that type." (function cspace transformq none)) +(define-extern joint-mod-spinner-callback + "cspace callback for joint-mod-spinner. Update the cspace's bone from the parent transformq, plus the rotation from this spinner." + (function cspace transformq none)) +(define-extern joint-mod-blend-world-callback "Callback for joint-mod-blend-local. See comment on that type." (function cspace transformq none)) +(define-extern joint-mod-rotate-local-callback + "Apply an additional rotation to the transform (left side quaternion multiplication" (function cspace transformq none)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; collide-func-h ;; @@ -16676,6 +18263,7 @@ (declare-type collide-mesh-cache-tri structure) (deftype collide-tri-result (structure) +"A triangle result of a collision." ((vertex vector 3 :inline :offset-assert 0) ;; guessed by decompiler (intersect vector :inline :offset-assert 48) (normal vector :inline :offset-assert 64) @@ -16688,6 +18276,7 @@ ) (deftype collide-mesh-tri (structure) +"A triangle for foreground collision meshes." ((vertex-index uint8 3 :offset-assert 0) ;; guessed by decompiler (unused uint8 :offset-assert 3) (pat pat-surface :offset-assert 4) ;; guessed by decompiler @@ -16699,6 +18288,8 @@ ) (deftype collide-mesh (basic) +"A collision mesh for foreground objects, +bound to the joint specified by `joint-id`." ((joint-id int32 :offset-assert 4) (num-tris uint32 :offset-assert 8) (num-verts uint32 :offset-assert 12) @@ -16720,6 +18311,7 @@ ) (deftype collide-mesh-cache-tri (structure) +"A triangle stored in the foreground mesh collide cache." ((vertex vector 3 :inline :offset-assert 0) ;; guessed by decompiler (normal vector :inline :offset-assert 48) (bbox4w bounding-box4w :inline :offset-assert 64) @@ -16731,6 +18323,7 @@ ) (deftype collide-mesh-cache-entry (structure) +"A foreground mesh collide cache entry." ((mat matrix :inline :offset-assert 0) (tris collide-mesh-cache-tri :dynamic :inline :offset-assert 64) ) @@ -16741,6 +18334,7 @@ (declare-type collide-shape-prim-mesh basic) (deftype collide-mesh-cache (basic) +"A collide cache for foreground meshes." ((used-size uint32 :offset-assert 4) (max-size uint32 :offset-assert 8) (id uint32 :offset-assert 12) ;; guessed by decompiler @@ -16751,8 +18345,9 @@ :flag-assert #xd0000bb90 (:methods (populate-for-prim-mesh (_type_ collide-shape-prim-mesh) collide-mesh-cache-entry) ;; 9 - (is-id? (_type_ int) symbol) ;; 10 - (next-id! (_type_) uint) ;; 11 + (is-id? "Does this cache have the given ID?" (_type_ int) symbol) ;; 10 + (next-id! "Reset all used entries in the cache and increment the ID. + If the id is zero, set it to 1." (_type_) uint) ;; 11 (allocate! (_type_ int) collide-mesh-cache-entry) ;; 12 ) ) @@ -16793,6 +18388,7 @@ (declare-type collide-shape-prim basic) (deftype collide-rider (structure) +"Something that rides a moving object." ((rider-handle handle :offset-assert 0) (sticky-prim collide-shape-prim :offset-assert 8) (prim-ry float :offset-assert 12) @@ -16804,6 +18400,7 @@ ) (deftype collide-rider-pool (basic) +"A pool containing all the riders of an object." ((alloc-count int32 :offset-assert 4) (riders collide-rider 20 :inline :offset-assert 16) ) @@ -16878,6 +18475,7 @@ ) (deftype collide-prim-core (structure) +"Collide primitives use this to store their world sphere and their collision flags." ((world-sphere vector :inline :offset-assert 0) (collide-as collide-spec :offset 16) ;; guessed by decompiler (collide-with collide-spec :offset-assert 20) @@ -16896,6 +18494,7 @@ (declare-type collide-cache basic) (deftype collide-shape-prim (basic) +"Base class for collide primitives." ((cshape collide-shape :offset-assert 4) (prim-id uint32 :offset-assert 8) (transform-index int8 :offset-assert 12) @@ -16933,6 +18532,7 @@ (deftype collide-shape-prim-sphere (collide-shape-prim) +"A sphere primitive for collide shapes." ((pat pat-surface :offset 64) (nav-radius float :offset 68) ) @@ -16947,6 +18547,7 @@ (deftype collide-shape-prim-mesh (collide-shape-prim) +"A mesh primitive for collide shapes." ((mesh collide-mesh :offset 64) (mesh-id int32 :offset 68) (mesh-cache-id uint32 :offset 72) @@ -16962,6 +18563,7 @@ ) (deftype collide-shape-prim-group (collide-shape-prim) +"A group of collide primitives." ((num-children uint8 :offset 64) (num-alloc-children uint8 :offset 65) (child (inline-array collide-shape-prim) :offset 68) ;; total guess.. @@ -16995,6 +18597,8 @@ (declare-type collide-query structure) (declare-type water-info structure) (deftype collide-shape (trsqv) +"The parent of all of an object's collide primitives. +Most [[process-drawable]]s have a [[collide-shape]] that represents their root transform." ((actor-hash-index int16 :offset 12) (process process-drawable :offset-assert 140) (max-iteration-count uint8 :offset-assert 144) @@ -17176,6 +18780,7 @@ (declare-type control-info basic) (declare-type rigid-body structure) (deftype collide-shape-moving (collide-shape) +"A [[collide-shape]] for moving objects." ((rider-time time-frame :offset-assert 200) (rider-last-move vector :inline :offset-assert 208) (trans-old vector :inline :offset-assert 224) @@ -17274,6 +18879,7 @@ ) (deftype part-spawner (process) +"A process that spawns a specified particle group." ((root trsqv :offset-assert 128) ;; guessed by decompiler (part sparticle-launch-control :offset-assert 132) ;; guessed by decompiler (sound ambient-sound :offset-assert 136) ;; guessed by decompiler @@ -17959,6 +19565,8 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype touching-prim (structure) +"A collide primitive that's touching another. +Potentially also stores the triangle that is involved." ((cprim collide-shape-prim :offset-assert 0) ;; guessed by decompiler (has-tri? symbol :offset-assert 4) ;; guessed by decompiler (tri collide-tri-result :inline :offset-assert 16) @@ -17970,6 +19578,7 @@ (declare-type touching-shapes-entry structure) (deftype touching-prims-entry (structure) +"A record of two primitives touching." ((next touching-prims-entry :offset-assert 0) (prev touching-prims-entry :offset-assert 4) (allocated? symbol :offset-assert 8) ;; guessed by decompiler @@ -17988,6 +19597,7 @@ ) (deftype touching-prims-entry-pool (structure) +"A pool of up to 64 touching prim records." ((head touching-prims-entry :offset-assert 0) (nodes touching-prims-entry 64 :inline :offset-assert 16) ;; guessed by decompiler ) @@ -18004,6 +19614,8 @@ ) (deftype touching-shapes-entry (structure) +"A record of two collide shapes touching, +storing a record of the primitives involved." ((cshape1 collide-shape :offset-assert 0) ;; guessed by decompiler (cshape2 collide-shape :offset-assert 4) ;; guessed by decompiler (resolve-u int8 :offset-assert 8) @@ -18026,6 +19638,7 @@ ) (deftype touching-list (structure) +"Contains a record of touching collide shape pairs." ((num-touching-shapes int32 :offset-assert 0) (resolve-u int8 :offset-assert 4) (touching-shapes touching-shapes-entry 32 :inline :offset-assert 8) ;; guessed by decompiler @@ -18051,6 +19664,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype pilot-edge-grab-info (structure) +"Info for edge grabs on zoomers." ((local-pos vector :inline :offset-assert 0) (local-dir vector :inline :offset-assert 16) (handle handle :offset-assert 32) @@ -18095,6 +19709,7 @@ (declare-type collide-edge-work structure) (deftype collide-edge-tri (structure) +"A triangle involved in edge grab collision." ((ctri collide-cache-tri :offset-assert 0) ;; guessed by decompiler (normal vector :inline :offset-assert 16) ) @@ -18226,8 +19841,12 @@ ;; process-drawable-h ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -(define-extern cspace-by-name-no-fail (function process-drawable string cspace)) -(define-extern cspace-index-by-name-no-fail (function process-drawable string int)) +(define-extern cspace-by-name-no-fail + "Like [[cspace-by-name]], but prints an error if the [[cspace]] was not found and returns the `node-list`." + (function process-drawable string cspace)) +(define-extern cspace-index-by-name-no-fail + "Like [[cspace-index-by-name]], but prints an error if the [[cspace]] was not found and returns 0." + (function process-drawable string int)) (define-extern num-func-none (function joint-control-channel float float float float :behavior process)) (define-extern num-func-+! (function joint-control-channel float float float float :behavior process)) (define-extern num-func--! (function joint-control-channel float float float float :behavior process)) @@ -18308,6 +19927,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype process-taskable (process-focusable) +"The parent class for NPCs that can be talked to." ((task game-task-control :offset-assert 204) (ambient ambient-control :inline :offset-assert 208) (neck-joint-index int32 :offset-assert 224) @@ -18357,6 +19977,7 @@ ;; otherwise looks good (deftype focus (structure) +"A structure that keeps a handle to a [[process-focusable]]." ((handle handle :offset-assert 0) (collide-with collide-spec :offset-assert 8) ) @@ -18364,10 +19985,12 @@ :size-assert #xc :flag-assert #xd0000000c (:methods - (clear-focused (_type_) none) ;; 9 - (collide-check? (_type_ process-focusable) object) ;; 10 - (reset-to-collide-spec (_type_ collide-spec) none) ;; 11 - (try-update-focus (_type_ process-focusable) symbol) ;; 12 + (clear-focused "Reset the focus' handle." (_type_) none) ;; 9 + (collide-check? + "If the focused process is not dead, + check that the [[collide-spec]] of the focus and the process match." (_type_ process-focusable) object) ;; 10 + (reset-to-collide-spec "Reset this focus with the given [[collide-spec]]." (_type_ collide-spec) none) ;; 11 + (try-update-focus "Try to set the `handle` of this focus to the given process." (_type_ process-focusable) symbol) ;; 12 ) ) @@ -18421,6 +20044,7 @@ ) (deftype effect-control (basic) +"An effect such as a particle with sound effects that plays during an animation." ((process process-drawable :offset-assert 4) ;; guessed by decompiler (flags effect-control-flag :offset-assert 8) (last-frame-group art-joint-anim :offset-assert 12) ;; guessed by decompiler @@ -18457,6 +20081,7 @@ ) (deftype collide-frag-mesh (basic) +"Unused Jak 1 background collision mesh fragment." ((packed-data uint32 :offset-assert 4) (pat-array uint32 :offset-assert 8) (strip-data-len uint16 :offset-assert 12) @@ -18473,6 +20098,7 @@ ) (deftype collide-fragment (drawable) +"Unused Jak 1 background collision drawable tree node." ((mesh collide-frag-mesh :offset 8) ;; guessed by decompiler (collide-new basic :offset 12) ) @@ -18482,6 +20108,7 @@ ) (deftype drawable-inline-array-collide-fragment (drawable-inline-array) +"Unused Jak 1 background collision drawable tree inline-array class." ((data collide-fragment 1 :inline :offset-assert 32) ;; guessed by decompiler (pad uint32) ) @@ -18491,6 +20118,7 @@ ) (deftype drawable-tree-collide-fragment (drawable-tree) +"Unused jak 1 background collision data." () :flag-assert #x1100000020 ) @@ -18501,6 +20129,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype collide-hash-scratch (structure) +"Scratchpad memory layout for collide-hash. Bitmask of things that have already been checked" ((collidable-bits uint128 128 :offset-assert 0) (poly-bits uint64 2 :offset 0) (id-bits uint32 512 :offset 0) @@ -18512,6 +20141,9 @@ ) (deftype collide-hash-bucket (structure) +"A bucket is a reference to a list of items that intersect a grid cell. +For the broadphase, the items are collide-hash-item (wrapper of collide-hash-fragment). +For the narrowphase, the items are entries in the index list, which contains poly indices." ((index int16 :offset-assert 0) (count int16 :offset-assert 2) ) @@ -18521,6 +20153,8 @@ ) (deftype collide-hash-item (structure) +"Items that are 'hashed' in the broadphase. Contains unique ID for checking against already-visited-bitmask +and a pointer to the actual collide-hash-fragment, or possibly a TIE." ((id uint32 :offset-assert 0) (collidable basic :offset-assert 4) ) @@ -18531,6 +20165,7 @@ ) (deftype collide-hash-poly (structure) +"A polygon in the narrow-phase data. This is just indices into the vertex and PAT tables." ((data uint8 4 :offset-assert 0 :score -1) (vert-index0 uint8 :offset 0) (vert-index1 uint8 :offset 1) @@ -18555,6 +20190,8 @@ ) (deftype collide-hash-fragment (drawable) +"A mesh fragment for the Jak2/Jak3 collision system. This is a 'hash' of triangles into a grid +where the 'hash' function is just identity." ((num-buckets uint16 :offset 4) (num-indices uint16 :offset 6) (pat-array uint32 :offset 8) @@ -18579,6 +20216,8 @@ ) (deftype collide-hash-fragment-array (array) +"A collection of collide-hash-fragments. These are used by the instanced collision if a single instance +needs more than 1 collide-hash-fragment worth of triangles." ((fragments collide-hash-fragment :dynamic :offset 16)) :method-count-assert 9 :size-assert #x10 @@ -18806,7 +20445,7 @@ ) ) -(define-extern spawn-projectile (function type projectile-init-by-other-params process-tree dead-pool (pointer process))) +(define-extern spawn-projectile "Create a new process for a projectile of the given type." (function type projectile-init-by-other-params process-tree dead-pool (pointer process))) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; find-nearest-h ;; @@ -19104,6 +20743,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype tr-stat (structure) +"triangle stats for a renderer. This can apply to a lot of different renderer types." ((groups uint16 :offset-assert 0) (fragments uint16 :offset-assert 2) (tris uint32 :offset-assert 4) @@ -19117,6 +20757,7 @@ ) (deftype merc-global-stats (structure) +"Triangle stats for all merc renderers." ((merc tr-stat :inline :offset-assert 0) (emerc tr-stat :inline :offset-assert 16) (mercneric tr-stat :inline :offset-assert 32) @@ -19127,6 +20768,8 @@ ) (deftype perf-stat (structure) +"Performance statistics for a single 'bucket' or category. Unlike the more general profile-bars, +this records statistics like cache hits/instruction counts." ((frame-number uint32 :offset-assert 0) (count uint32 :offset-assert 4) (cycles uint32 :offset-assert 8) @@ -19155,6 +20798,7 @@ ) (deftype perf-stat-array (inline-array-class) +"Array of all stats for all buckets." ((data perf-stat :dynamic :inline :offset-assert 16) ;; guessed by decompiler ) :method-count-assert 9 @@ -19225,6 +20869,8 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype bsp-node (structure) +"A node in the 'BSP' tree. This is really a bounding volume tree, where each volume is an axis-aligned box, containing 2 child boxes. +This is used for precomputed visibility, based on the camera position. This is not used for collision." ((front int16 :offset-assert 0) ;; int32 (back int16 :offset-assert 2) ;; int32 (front-box-min vector4b :inline :offset-assert 4) @@ -19239,6 +20885,7 @@ ) (deftype game-level (basic) +"Unused in Jak 1, 2, and 3!" ((master-bsp basic :offset-assert 4) ) :method-count-assert 9 @@ -19247,6 +20894,9 @@ ) (deftype view-frustum (structure) +"A view frustum, expressed as corners. +This representation is not very useful, and is used in only one spot to generate camera planes +in a very inefficient way." ((hither-top-left vector :inline :offset-assert 0) (hither-top-right vector :inline :offset-assert 16) (hither-bottom-left vector :inline :offset-assert 32) @@ -19274,6 +20924,8 @@ ) (deftype bsp-header (drawable) +"The bsp-header is really an entire level. +This probably started as a very simple structure, but now it is extremely complicated." ( ;; TYPE 0 (info file-info :offset 4) @@ -19361,6 +21013,8 @@ ;; totally broken (deftype collide-stats (structure) +"Very strange collide stats type. It has been somewhat broken in all versions of the game. +The final stopwatch is cut off. For jak 3, I just fixed it." ((calls uint32 :offset-assert 0) (spheres uint32 :offset-assert 4) (nodes uint32 :offset-assert 8) @@ -19378,14 +21032,20 @@ :flag-assert #x900000078 ) -(define-extern inspect-bsp-tree (function bsp-header bsp-node none)) -(define-extern map-bsp-tree (function (function bsp-node none) bsp-header bsp-node none)) +(define-extern inspect-bsp-tree + "Attempt to print a bsp-tree, but it is actually broken since the jak 2 bsp format change" + (function bsp-header bsp-node none)) +(define-extern map-bsp-tree + "Attempt to call a function on all bsp-tree nodes, but it is actually broken since the jak 2 bsp format" + (function (function bsp-node none) bsp-header bsp-node none)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; collide-cache-h ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype collide-puss-sphere (structure) +"A query sphere from the user for the porbe-using-spheres query. +This is used internally by the collide-cache implementation." ((bsphere sphere :inline :offset-assert 0) (bbox4w bounding-box4w :inline :offset-assert 16) ) @@ -19395,6 +21055,7 @@ ) (deftype collide-puss-work (structure) +"Scratchpad memory map for probe-using-spheres query." ((closest-pt vector :inline :offset-assert 0) (tri-normal vector :inline :offset-assert 16) (tri-bbox4w bounding-box4w :inline :offset-assert 32) @@ -19411,6 +21072,8 @@ ) (deftype collide-cache-tri (structure) +"A single triangle inside the collision cache. +Contains a reference back to the source object (like a collide-shape or water-control), and the prim itself." ((vertex vector 3 :inline :offset-assert 0) ;; guessed by decompiler (extra-quad uint8 16 :offset-assert 48) ;; guessed by decompiler (pat pat-surface :offset 48) ;; guessed by decompiler @@ -19426,6 +21089,8 @@ ) (deftype collide-cache-prim (structure) +"A primitive inside the collide-cache. +This can represent a sphere, a triangle mesh, or a group of other primitives within a bounding sphere." ((prim-core collide-prim-core :inline :offset-assert 0) (extra-quad uint8 16 :offset-assert 32) ;; guessed by decompiler (ccache collide-cache :offset 32) ;; guessed by decompiler @@ -19452,6 +21117,12 @@ (deftype collide-cache (basic) +"The collide-cache is a structure to accelerate collision queries. +In particular, it helps with queries where you don't know what you might hit. +It can detect collision with the background geometry, foreground dynamic collision shapes (spheres and meshes), and water. +To use it, it must first be 'filled' with geometry. Then you can manually inspect the geometry, or use one of the queries. +The supported queries are 'line-sphere' (raycast) and 'spheres' (check if intersecting anything). +It is not useful for ollision queries against a specific foreground object, like 'am I on top of platform X right now?'." ((num-tris int32 :offset-assert 4) (num-tris-u32 uint32 :offset 4) (num-prims int32 :offset-assert 8) @@ -19492,6 +21163,8 @@ (declare-type instance-tie basic) (deftype collide-list-item (structure) +"Entry on the broad-phase collision list. +Can represent instanced collision, as a TIE instance, or a single non-instanced mesh fragment." ((mesh instance-tie :offset-assert 0) ;; guessed by decompiler (inst basic :offset-assert 4) ) @@ -19502,6 +21175,7 @@ ) (deftype collide-list (structure) +"List of items returned by the broad-phase collision query." ((num-items int32 :offset-assert 0) (items collide-list-item 256 :inline :offset 16) ;; guessed by decompiler ) @@ -19518,6 +21192,8 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype collide-query (structure) +"Very general collision-query structure. The meaning is different depending on where it used. +This has both inputs from the user, and collision results." ((best-other-tri collide-tri-result :inline :offset-assert 0) (best-my-tri collide-tri-result :inline :offset 0) (ignore-processes process-tree 2 :offset-assert 88) @@ -19602,6 +21278,8 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype billboard (drawable) +"A billboard for shrubbery in the distance. This is simple a quad that faces the camera. +The only data needed is the texture/mode. The location is determined by bsphere." ((flat adgif-shader :inline :offset-assert 32) ) :method-count-assert 17 @@ -19610,6 +21288,7 @@ ) (deftype shrub-view-data (structure) +"Camera and general settings for shrubbery VU1 program." ((data uint128 3 :offset-assert 0) ;; guessed by decompiler (texture-giftag gs-gif-tag :inline :offset 0) ;; was qword (consts vector :inline :offset 16 :score -1) @@ -19629,6 +21308,8 @@ ) (deftype shrubbery (drawable) +"Prototype (mesh/geometry) for a shrub. not _really_ a drawable in any way, as it +overwrites all the normal drawable fields." ((textures (inline-array adgif-shader) :offset 4) ;; header breakdown: ;; [0] - number of textures / 2 @@ -19654,6 +21335,7 @@ ) (deftype instance-shrubbery (instance) +"Instance of a shrub." ((flat-normal vector :inline :offset-assert 64) (flat-hwidth float :offset 76) (color uint32 :offset 8) @@ -19664,6 +21346,7 @@ ) (deftype drawable-inline-array-instance-shrub (drawable-inline-array) +"Array of shrub instances stored in the level data." ((data instance-shrubbery 1 :inline :offset-assert 32) (pad uint32) ) @@ -19671,6 +21354,7 @@ ) (deftype drawable-tree-instance-shrub (drawable-tree) +"Drawable-tree for the shrubs." ((info prototype-array-shrub-info :offset 8) (colors-added time-of-day-palette :offset 12) ;; added ) @@ -19678,6 +21362,9 @@ ) (deftype generic-shrub-fragment (drawable) +"Shrub data, converted into the format for generic. +The shrub renderer doesn't support clipping, so it falls back to generic. +This requires storing the data for all shrubs prototype twice!" ((textures (inline-array adgif-shader) :offset 4) ;; guessed by decompiler (vtx-cnt uint32 :offset 8) (cnt-qwc uint8 :offset 12) @@ -19706,6 +21393,7 @@ ) (deftype prototype-trans-shrubbery (prototype-shrubbery) +"Array of transparent shrub prototypes." () :flag-assert #x1100000044 ) @@ -19716,6 +21404,7 @@ ) (deftype shrubbery-matrix (structure) +"Instance matrix for a shrub, contains interpolated color." ((mat matrix :inline :offset-assert 0) (color qword :inline :offset-assert 64) ) @@ -19725,6 +21414,7 @@ ) (deftype shrub-near-packet (structure) +"DMA templates for generic rendering of shrubs." ((matrix-tmpl dma-packet :inline :offset-assert 0) (header-tmpl dma-packet :inline :offset-assert 16) (stq-tmpl dma-packet :inline :offset-assert 32) @@ -19740,6 +21430,7 @@ ) (deftype instance-shrub-work (structure) +"Scratchpad layout for generating shrub DMA." ((dummy qword 3 :inline :offset-assert 0) ;; guessed by decompiler (chaina qword 8 :inline :offset-assert 48) ;; guessed by decompiler (chainb qword 8 :inline :offset-assert 176) ;; guessed by decompiler @@ -19827,7 +21518,9 @@ :flag-assert #x9000038a0 ) -(define-extern shrubbery-login-post-texture (function shrubbery none)) +(define-extern shrubbery-login-post-texture + "Do some weird fix-up to the shrubbery textures. this is likely to present normal-looking adgifs to the texture system, but then we scramble them up for easier consumption by VU1." + (function shrubbery none)) (define-extern *shrub-state* int) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; @@ -19835,6 +21528,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype tie-fragment-debug (structure) +"Optional debug information about a tie-fragment." ((num-tris uint16 :offset-assert 0) (num-dverts uint16 :offset-assert 2) (debug-lines (array vector-array) :offset-assert 4) @@ -19845,6 +21539,7 @@ ) (deftype tie-fragment (drawable) +"A mesh fragment of a TIE. This is a chunk of mesh that is rendered by VU1, stored as DMA chains." ((gif-ref (inline-array adgif-shader) :offset 4) ;; guessed by decompiler (point-ref uint32 :offset 8) (color-index uint16 :offset 12) @@ -19867,6 +21562,7 @@ ) (deftype instance-tie (instance) +"A TIE model instance." ((color-indices uint32 :offset 8) (bucket-ptr prototype-bucket-tie :offset 12) ;; guessed by decompiler (max-scale uint16 :offset 38) @@ -19888,6 +21584,7 @@ ) (deftype drawable-tree-instance-tie (drawable-tree) +"Top-level drawable-tree for TIEs" ((prototypes proxy-prototype-array-tie :offset 8) ) :method-count-assert 17 @@ -19908,6 +21605,7 @@ (deftype tie-matrix (structure) +"Per-instance matrix for TIE VU1 rendering." ((mat matrix :inline :offset-assert 0) (morph qword :inline :offset-assert 64) (fog qword :inline :offset-assert 80) @@ -19923,6 +21621,7 @@ ) (deftype instance-tie-work (structure) +"workspace for TIE instance DMA generation" ((wind-const vector :inline :offset-assert 0) (hmge-d vector :inline :offset-assert 16) (hvdf-offset vector :inline :offset-assert 32) @@ -19976,6 +21675,7 @@ ) (deftype instance-tie-dma (structure) +"Scratchpad memory layout for TIE instance DMA generation." ((banka instance-tie 32 :inline :offset-assert 0) (bankb instance-tie 32 :inline :offset-assert 2048) (outa uint128 256 :offset-assert 4096) @@ -19989,6 +21689,7 @@ ) (deftype prototype-tie-work (structure) +"workspace for TIE protype DMA generation." ((upload-flushe dma-packet :inline :offset-assert 0) (upload-palette dma-packet :inline :offset-assert 16) (upload-model-0 dma-packet :inline :offset-assert 32) @@ -20164,6 +21865,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype tfragment-stats (structure) +"Triangle and vertex stats for a single tfragment." ((num-tris uint16 4 :offset-assert 0) ;; guessed by decompiler (num-dverts uint16 4 :offset-assert 8) ;; guessed by decompiler ) @@ -20173,6 +21875,7 @@ ) (deftype tfragment-debug-data (structure) +"Optional debug information (stats, lines) for a tfragment." ((stats tfragment-stats :inline :offset-assert 0) (debug-lines (array vector-array) :offset-assert 16) ;; guessed by decompiler ) @@ -20182,6 +21885,7 @@ ) (deftype generic-tfragment (structure) +"Unused. Could have been a way to render tfrag's through generic." ((dummy int32 :offset-assert 0) ) :method-count-assert 9 @@ -20190,6 +21894,7 @@ ) (deftype tfragment (drawable) +"A tfrag mesh fragment. This is just references to DMA data, plus some metadata." ((color-index uint16 :offset 6) (debug-data tfragment-debug-data :offset 8) (color-indices uint32 :offset 12) @@ -20241,6 +21946,7 @@ ) (deftype drawable-tree-tfrag (drawable-tree) +"top level tfrag tree." ((time-of-day-pal time-of-day-palette :offset 12) (arrays drawable-inline-array :dynamic :offset 32 :score 100) ;; either drawable-inline-array-node or drawable-inline-array-tfrag ) @@ -20259,6 +21965,7 @@ (deftype tfrag-dists (structure) +"Distances for mesh level-of-detail blending for use on VU1." ((data uint32 16 :offset-assert 0 :score -1) (vector vector 4 :inline :offset 0 :score -1) (k0s vector 2 :inline :offset 0) @@ -20271,6 +21978,7 @@ (deftype tfrag-data (structure) +"Constants for VU1 data memory for tfrag rendering." ((data uint32 56 :offset 0 :score -1) (vector vector 14 :inline :offset 0 :score -1) (fog vector :inline :offset 0) @@ -20293,6 +22001,7 @@ ) (deftype tfrag-control (structure) +"VU1 'control' data containing address and counters." ((num-base-points uint32 :offset-assert 0) (num-shared-base-points uint32 :offset-assert 4) (num-level0-points uint32 :offset-assert 8) @@ -20320,6 +22029,7 @@ ) (deftype tfrag-stats (structure) +"TFRAG statistics computed on EE." ((from int32 :offset-assert 0) (to int32 :offset-assert 4) (cnt int32 :offset-assert 8) @@ -20351,6 +22061,7 @@ ) (deftype tfrag-work (structure) +"Scratch space for generating TFRAG DMA." ((base-tmpl dma-packet :inline :offset-assert 0) (level-0-tmpl dma-packet :inline :offset-assert 16) (common-tmpl dma-packet :inline :offset-assert 32) @@ -20383,6 +22094,7 @@ ) (deftype tfrag-dma (structure) +"Memory layout for to/from scratchpad for tfrag." ((banka tfragment 16 :inline :offset-assert 0) (bankb tfragment 16 :inline :offset-assert 1024) (outa uint128 128 :offset-assert 2048) @@ -20400,6 +22112,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype background-work (basic) +"List of all things for the background renderer to draw." ((tfrag-tree-count int32 :offset-assert 4) (tfrag-trees drawable-tree-tfrag 8 :offset-assert 8) ;; guessed by decompiler (tfrag-levels level 8 :offset-assert 40) ;; guessed by decompiler @@ -20429,6 +22142,8 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype subdivide-settings (basic) +"Input settings for distances for switching mesh level of details. +These are set by the level code and read by rendering code." ((dist float 5 :offset-assert 4) ;; guessed by decompiler (meters float 5 :offset-assert 24) ;; guessed by decompiler (close float 8 :offset-assert 44) ;; guessed by decompiler @@ -20443,6 +22158,7 @@ ) (deftype subdivide-dists (structure) +"Unused subdivide distances. Internally, tfrag/tie figure these out instead." ((data uint32 32 :offset-assert 0) ;; guessed by decompiler (vector vector 8 :inline :offset 0) ;; guessed by decompiler (k0s uint128 4 :offset 0) ;; guessed by decompiler @@ -20454,6 +22170,7 @@ ) (deftype terrain-stats (structure) +"Desptie the name `terrain-stats`, these are more general triangle stats for all renderers." ((pris tr-stat :inline :offset-assert 0) (tie-generic tr-stat :inline :offset-assert 16) (tie-vanish tr-stat :inline :offset-assert 32) @@ -20507,6 +22224,9 @@ ) (deftype background-area (structure) +"Scratchpad memory layout for most background rendering +This uses the full scratchpad so it should only be used when the stack isn't on the scratchpad (rendering code). +Interestingly, dma-area went from a union of all the -dma types to a plain array of bytes in jak 3." ((dma-area dma-area :inline :offset-assert 0) (vis-list uint8 2048 :offset-assert 14496) ;; guessed by decompiler ) @@ -20516,6 +22236,7 @@ ) (deftype foreground-area (structure) +"Scratchpad memory layout for most foreground rendering." ((generic-work generic-work :inline :offset-assert 0) (foreground-work foreground-work :inline :offset 0) (joint-work joint-work :inline :offset 0) @@ -20528,6 +22249,7 @@ ) (deftype region-prim-area (structure) +"Scratchpad memory layout for regions." ((region-prim-list region-prim-list :inline :offset-assert 0) (pos vector :inline :offset-assert 1296) (unknown-vector-uiyb1 vector :inline :offset-assert 1312) @@ -20582,6 +22304,7 @@ ) (deftype sprite-area (structure) +"Scratchpad memory layout for sprites." ((clock-data vector 13 :inline :offset-assert 0) (buffer uint8 :dynamic :offset-assert 208) ) @@ -20591,6 +22314,7 @@ ) (deftype work-area (structure) +"All scratchpad memory layouts." ((background background-area :inline :offset-assert 0) (foreground foreground-area :inline :offset 0) (region-prim region-prim-area :inline :offset 0) @@ -20602,6 +22326,7 @@ ) (deftype terrain-context (structure) +"Useless wrapper around work-area. (this added some stuff in jak 1)" ((work work-area :inline :offset-assert 0) ) :method-count-assert 9 @@ -20635,6 +22360,7 @@ ) (deftype entity-perm (structure) +"Entity information that gets persisted in the save file." ((user-object object 2 :offset-assert 0) ;; guessed by decompiler (user-uint64 uint64 :offset 0) (user-float float 2 :offset 0) ;; guessed by decompiler @@ -20660,6 +22386,7 @@ (deftype entity-links (structure) +"A linked list of entities with some extra data about their current status." ((prev-link entity-links :offset-assert 0) (next-link entity-links :offset-assert 4) (entity entity :offset-assert 8) @@ -20693,6 +22420,8 @@ (deftype entity-links-array (inline-array-class) +"An array of [[entity-links]]. +Levels store a reference to this which holds all the entities in the level." ((data entity-links :dynamic :inline :offset-assert 16) ;; guessed by decompiler ) :method-count-assert 9 @@ -20949,6 +22678,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype eye (structure) +"Data for a single eye." ((data vector 2 :inline :offset-assert 0) ;; guessed by decompiler (x float :offset 0) (y float :offset 4) @@ -20963,6 +22693,7 @@ ) (deftype eye-control (structure) +"Information about the state of both eyes of a [[process-drawable]]." ((process handle :offset-assert 0) (draw-flag symbol :offset-assert 8) (different-eyes symbol :offset-assert 12) @@ -20979,6 +22710,7 @@ ) (deftype eye-control-array (basic) +"An array of [[eye-control]]s." ((data eye-control 16 :inline :offset-assert 16) ;; guessed by decompiler ) :method-count-assert 9 @@ -20996,6 +22728,7 @@ ) (deftype eye-work (structure) +"Eye renderer DMA data." ((sprite-tmpl dma-gif-packet :inline :offset-assert 0) (sprite-tmpl2 dma-gif-packet :inline :offset-assert 32) (adgif-tmpl dma-gif-packet :inline :offset-assert 64) @@ -21147,6 +22880,7 @@ (deftype sparticle-birthinfo (structure) +"Used internally by the sparticle code." ((sprite uint32 :offset-assert 0) (anim int32 :offset-assert 4) (anim-speed float :offset-assert 8) @@ -21163,6 +22897,7 @@ ) (deftype sp-field-init-spec (structure) +"Part of a particle definition - how to initialize a field of a particle." ((field sp-field-id :offset-assert 0) (flags sp-flag :offset-assert 2) (initial-valuef float :offset-assert 4) @@ -21185,6 +22920,7 @@ ) (deftype sparticle-launcher (basic) +"A definition of a single particle, as a list of init specs." ((birthaccum float :offset-assert 4) (soundaccum float :offset-assert 8) (init-specs (inline-array sp-field-init-spec) :offset-assert 12) ;; guessed by decompiler @@ -21201,6 +22937,7 @@ ) (deftype sparticle-group-item (structure) +"A reference to a single sparticle-launcher (by ID) and some parameters for using it." ((launcher uint32 :offset-assert 0) (fade-after meters :offset-assert 4) (falloff-to meters :offset-assert 8) @@ -21219,6 +22956,7 @@ (declare-type sparticle-cpuinfo structure) (deftype sparticle-launch-state (structure) +"The state associated with a launcher of a given sparticle." ((group-item sparticle-group-item :offset-assert 0) (flags sp-launch-state-flags :offset-assert 4) (randomize uint16 :offset-assert 6) @@ -21241,6 +22979,7 @@ ) (deftype sparticle-launch-group (basic) +"Definition of multiple a particle-group, which is a collection of particle effects." ((length int16 :offset-assert 4) (duration uint16 :offset-assert 6) (linger-duration uint16 :offset-assert 8) @@ -21264,6 +23003,10 @@ ) (deftype sparticle-launch-control (inline-array-class) +"Top-level type containing all the state needed to launch a particle group. +These are typically owned by a process, and allocated on the process heap. +These refer to static particle definitions, and then spawn particles that are tracked by the +particle system itself. This type just holds the launching-related state." ((group sparticle-launch-group :offset-assert 16) ;; guessed by decompiler (proc process-drawable :offset-assert 20) ;; guessed by decompiler (local-clock int32 :offset-assert 24) @@ -21334,6 +23077,7 @@ (declare-type sparticle-system basic) (deftype sparticle-cpuinfo (structure) +"The per-particle information. This stays on the CPU, and isn't uploaded to the VU." ((sprite sprite-vec-data-2d :offset-assert 0) (adgif adgif-shader :offset-assert 4) (radius float :offset-assert 8) @@ -21379,6 +23123,7 @@ ) (deftype sparticle-launchinfo (structure) +"Settings for launching a particle. These are a temporary thing consumed by the assembly particle code, and modified by particle callbacks." ((launchrot vector :inline :offset-assert 0) ; NOTE - both used as a vector3s and a normal vector (conerot vector :inline :offset-assert 16) (rotate-x float :offset-assert 32) @@ -21399,6 +23144,8 @@ ) (deftype sparticle-system (basic) +"An entire particle 'system', which is a pipeline for spawning, updating, and generating sprite-renderer DMA data. +There are separate systems for different modes of sprite rendering: 2D/billboard, full 3D, and screen-space (HUD)" ((blocks int32 2 :offset-assert 4) ;; guessed by decompiler (length int32 2 :offset-assert 12) ;; guessed by decompiler (num-alloc int32 2 :offset-assert 20) ;; guessed by decompiler @@ -21424,6 +23171,11 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype actor-link-info (basic) +"A linked list of actors. + +Actors allocate this on their process heap if they have a +`next-actor` or `prev-actor` defined in their lump +and use it for entity lookups." ((process process :offset-assert 4) ;; guessed by decompiler (next entity-actor :offset-assert 8) ;; guessed by decompiler (prev entity-actor :offset-assert 12) ;; guessed by decompiler @@ -21432,33 +23184,55 @@ :size-assert #x10 :flag-assert #x1a00000010 (:methods - (new (symbol type process symbol) _type_) ;; 0 - (get-matching-actor-type-mask (_type_ type) int) ;; 9 - (actor-count-before (_type_) int) ;; 10 - (link-to-next-and-prev-actor (_type_) actor-link-info) ;; 11 + (new + "Set up an actor-link-info for the given process. + The entity of this process should be the entity-actor + that will get this actor-link-info." (symbol type process symbol) _type_) ;; 0 + (get-matching-actor-type-mask + "Iterate through _all_ actors that are part of this actor list. + If the nth actor is type matching-type, then set the nth bit of the result." (_type_ type) int) ;; 9 + (actor-count-before "Get the number of actors before this actor in the list." (_type_) int) ;; 10 + (link-to-next-and-prev-actor + "Redo the linking in the constructor by looking up the next/prev actor." (_type_) actor-link-info) ;; 11 (get-next (_type_) entity-actor) ;; 12 (get-prev (_type_) entity-actor) ;; 13 - (get-next-process (_type_) process) ;; 14 - (get-prev-process (_type_) process) ;; 15 - (apply-function-forward (_type_ (function entity-actor object object) object) int) ;; 16 - (apply-function-reverse (_type_ (function entity-actor object object) object) int) ;; 17 - (apply-all (_type_ (function entity-actor object object) object) int) ;; 18 + (get-next-process "Get the process for the next, if it exists." (_type_) process) ;; 14 + (get-prev-process "Get the process for the prev, if it exists." (_type_) process) ;; 15 + (apply-function-forward + "Iterate forward through actors, and apply this function. Starts at (-> this next) + If the function returns truthy, stop iterating." (_type_ (function entity-actor object object) object) int) ;; 16 + (apply-function-reverse + "Iterate backward through actors and apply function. + If the function returns truth, stop iterating." (_type_ (function entity-actor object object) object) int) ;; 17 + (apply-all + "Apply to all entities. Starts at the back and hits everyone, including this object." (_type_ (function entity-actor object object) object) int) ;; 18 (send-to-all (_type_ symbol) none) ;; 19 - (send-to-all-after (_type_ symbol) object) ;; 20 - (send-to-all-before (_type_ symbol) object) ;; 21 - (send-to-next-and-prev (_type_ symbol) none) ;; 22 - (send-to-next (_type_ symbol) none) ;; 23 - (send-to-prev (_type_ symbol) none) ;; 24 - (actor-count (_type_) int) ;; 25 + (send-to-all-after "Send an event to all processes after this link with no parameters." (_type_ symbol) object) ;; 20 + (send-to-all-before "Send an event to all processes before this link with no parameters." (_type_ symbol) object) ;; 21 + (send-to-next-and-prev "Send an event to both next and prev with no params." (_type_ symbol) none) ;; 22 + (send-to-next "Send event arg0 to the next actor's process." (_type_ symbol) none) ;; 23 + (send-to-prev "Send event arg1 to the next actor's process." (_type_ symbol) none) ;; 24 + (actor-count "Count the number of actors in the entire list." (_type_) int) ;; 25 ) ) -(define-extern entity-actor-lookup (function res-lump symbol int entity-actor)) -(define-extern entity-actor-count (function res-lump symbol int)) -(define-extern actor-link-subtask-complete-hook (function entity-actor (pointer symbol) symbol)) +(define-extern entity-actor-lookup + "Given an entity (the res-lump), look up a reference to another entity and return that entity." + (function res-lump symbol int entity-actor)) +(define-extern entity-actor-count + "Get the number of entities that this res references under the name. + This works on more than just next/prev." + (function res-lump symbol int)) +(define-extern actor-link-subtask-complete-hook + "Sets arg1 if the thing is complete. Does not continue the apply if the complete perm is set." + (function entity-actor (pointer symbol) symbol)) (define-extern actor-link-subtask-incomplete-count-hook (function entity-actor (pointer uint64) symbol)) -(define-extern actor-link-dead-hook (function entity-actor (pointer symbol) symbol)) -(define-extern alt-actor-list-subtask-incomplete-count (function process-drawable int)) +(define-extern actor-link-dead-hook + "Sets arg1 if the thing is dead. Does not continue the apply if the dead perm is set." + (function entity-actor (pointer symbol) symbol)) +(define-extern alt-actor-list-subtask-incomplete-count + "Get the number of alt-actors which do not have the complete bit set in their perm." + (function process-drawable int)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; camera-h ;; @@ -22833,6 +24607,7 @@ (define-extern rpc-call (function int uint uint uint int uint int uint)) (deftype rpc-buffer (basic) +"Buffer for storing input/output data for a remote procedure call to the overlord driver on the IOP." ((elt-size uint32 :offset-assert 4) (elt-count uint32 :offset-assert 8) (elt-used uint32 :offset-assert 12) @@ -22849,6 +24624,8 @@ ) (deftype rpc-buffer-pair (basic) +"A double buffer of RPC buffers. This is used to let the game queue up data in one buffer while +the other is being read/written by overlord." ((buffer rpc-buffer 2 :offset-assert 4) ;; guessed by decompiler (current rpc-buffer :offset-assert 12) ;; guessed by decompiler (last-recv-buffer pointer :offset-assert 16) ;; guessed by decompiler @@ -22859,12 +24636,12 @@ :flag-assert #xf00000018 (:methods (new (symbol type uint uint int) rpc-buffer-pair) ;; 0 - (call (rpc-buffer-pair uint pointer uint) int) ;; 9 - (add-element (rpc-buffer-pair) pointer) ;; 10 - (decrement-elt-used (rpc-buffer-pair) int) ;; 11 - (sync (rpc-buffer-pair symbol) int) ;; 12 - (check-busy (rpc-buffer-pair) symbol) ;; 13 - (pop-last-received (rpc-buffer-pair) pointer) ;; 14 + (call "Start an async RPC call. If there is already one in progress, stall and wait for it to finish." (rpc-buffer-pair uint pointer uint) int) ;; 9 + (add-element "Add an element. If the buffer is full, flush it!" (rpc-buffer-pair) pointer) ;; 10 + (decrement-elt-used "Remove the most recently queued element." (rpc-buffer-pair) int) ;; 11 + (sync "Wait for an in-progress rpc to finish." (rpc-buffer-pair symbol) int) ;; 12 + (check-busy "Check to see if an rpc is in progress." (rpc-buffer-pair) symbol) ;; 13 + (pop-last-received "Pop the response from the most recently completed rpc call." (rpc-buffer-pair) pointer) ;; 14 ) ) @@ -22884,10 +24661,11 @@ ) (deftype path-control (basic) - "An abstraction around a [[curve]], providing tools such as: - - debug drawing - - conveniant vertex accessing - - vertex finding/searching algorithms" + "The path-control is a reference a path data, which is just a list of points. + Although it contains a `curve`, the knot part is not populated, so it's just treated as + a bunch of line segments from the control points. + The child class curve-control does fill out the knot data and is a proper b-spline. + These path-controls are typically allocated on a process heap." ((flags path-control-flag :offset-assert 4) (name symbol :offset-assert 8) (process process-drawable :offset-assert 12) @@ -22897,7 +24675,7 @@ :size-assert #x24 :flag-assert #x1b00000024 (:methods - (new (symbol type process symbol float entity symbol) _type_) ;; 0 + (new "Allocate a new path-control, set up the curve to point to the specified lump data." (symbol type process symbol float entity symbol) _type_) ;; 0 (debug-draw (_type_) none) ;; 9 (get-point-in-path! "Depending on the value of `idx`, the result can be quite different: @@ -22983,7 +24761,7 @@ ) (deftype curve-control (path-control) - "Identical in terms of data to a [[path-control]] but has different implementation" + "A curve-control is like a path control, but it has both control points and knot points." () :method-count-assert 27 :size-assert #x24 @@ -23005,6 +24783,7 @@ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype nav-mesh-work-debug (structure) +"Debug outputs for the nav-mesh assembly functions" ((debug-vec1 vector :inline :offset-assert 0) (debug-vec2 vector :inline :offset-assert 16) (debug-vec3 vector :inline :offset-assert 32) @@ -23025,6 +24804,7 @@ ) (deftype nav-mesh-work (structure) +"Workspace for nav-mesh processing functions." ((vert0-table int8 4 :offset-assert 0) (vert1-table int8 4 :offset-assert 4) (edge-mask-table uint8 3 :offset-assert 8) @@ -23050,6 +24830,7 @@ ) (deftype nav-mesh-link (structure) +"Link between two different meshes" ((id uint32 :offset-assert 0) (dest-mesh-id uint32 :offset-assert 4) (src-link-poly-id uint8 :offset-assert 8) @@ -23064,6 +24845,8 @@ ) (deftype nav-poly (structure) +"Polygon within a nav-mesh. Can be a tri or quad. +Based on the implementation of point-poly-intersection?, these should likely be convex." ((data uint8 64 :offset-assert 0 :score -10) (vertex vector 4 :inline :offset 0) ;; changed to vector from uint8 in jak 1 (vertex0 vector :inline :offset 0) @@ -23175,6 +24958,7 @@ (declare-type grid-hash basic) (declare-type sphere-hash grid-hash) (deftype nav-mesh (basic) +"Mesh used for creature/enemy navigation." ((work nav-mesh-work :offset-assert 4) (poly-array (inline-array nav-poly) :offset-assert 8) ;; is this actually an inline-array? (static-sphere-count uint8 :offset-assert 12) @@ -23232,11 +25016,11 @@ (nav-mesh-method-34 (_type_ vector vector float) float) ;; 34 (nav-mesh-method-35 (_type_ vector vector float) float) ;; 35 (debug-draw-poly (_type_ nav-poly rgba) none) ;; 36 - (point-in-poly? (_type_ nav-poly vector) symbol) ;; 37 + (point-in-poly? "Check if a point is inside a poly of this mesh" (_type_ nav-poly vector) symbol) ;; 37 (nav-mesh-method-38 (_type_ nav-poly vector vector vector (pointer nav-poly)) vector) ;; 38 - (closest-point-on-boundary (_type_ nav-poly vector vector) none) ;; 39 + (closest-point-on-boundary "Find the point on the polygon edge that is closest to the query point." (_type_ nav-poly vector vector) none) ;; 39 (project-point-onto-plane-of-poly-local (_type_ nav-poly vector vector vector) none) ;; 40 - (project-point-into-poly-2d (_type_ nav-poly vector vector) none) ;; 41 + (project-point-into-poly-2d "Find the point in the polygon closest to the query point." (_type_ nav-poly vector vector) none) ;; 41 (find-poly-containing-point-local (_type_ nav-find-poly-parms) nav-poly) ;; 42 (find-nearest-poly-to-point-local (_type_ nav-find-poly-parms) nav-find-poly-parms) ;; 43 (is-in-mesh-local? (_type_ vector float float) symbol) ;; 44 @@ -23246,12 +25030,24 @@ ) -(define-extern vector-normalize-unity! (function vector vector)) -(define-extern vector-normalize-unity-copy! (function vector vector vector)) -(define-extern debug-validate-current-poly (function symbol)) -(define-extern init-ray (function nav-ray none)) -(define-extern point-poly-intersection? (function nav-mesh vector int (inline-array vector) symbol)) -(define-extern nav-sphere-from-cam (function none)) +(define-extern vector-normalize-unity! + "Normalize a vector (xyz only) in place." + (function vector vector)) +(define-extern vector-normalize-unity-copy! + "Normalize a vector (xyz only)" + (function vector vector vector)) +(define-extern debug-validate-current-poly + "Not implemented." + (function symbol)) +(define-extern init-ray + "Set up a nav-ray. Assumes that dest-pos and current-pos are set." + (function nav-ray none)) +(define-extern point-poly-intersection? + "Check if a point is inside a poly." + (function nav-mesh vector int (inline-array vector) symbol)) +(define-extern nav-sphere-from-cam + "Print out a SPHEREM from the current camera position, possibly used by their level-building tool." + (function none)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; nav-control-h ;; @@ -23501,6 +25297,7 @@ ) (deftype grid-hash-box (structure) +"Integer coordinate box for the spatial hash grid." ((min int8 3 :offset-assert 0) (max int8 3 :offset-assert 3) ) @@ -23512,6 +25309,9 @@ (declare-type grid-hash-work basic) (deftype grid-hash (basic) +"The grid-hash is the basic 3D grid used in the spatial-hash, which is used for runtime +actor collision dectection by hashing actor spheres into grid cells, and avoiding the typical +O(n^2) 'check everybody against everybody' collision loop." ((work grid-hash-work :offset-assert 4) (search-box grid-hash-box :inline :offset-assert 8) (bucket-size int16 :offset-assert 14) @@ -23570,6 +25370,7 @@ ) (deftype sphere-hash (grid-hash) +"An extension of grid hash that holds spheres inside of the grid." ((sphere-array (inline-array sphere) :offset-assert 88) (max-object-count int16 :offset-assert 92) (pad int16 :offset-assert 94) @@ -23602,6 +25403,7 @@ ) (deftype spatial-hash (sphere-hash) +"An extension of sphere-hash that associates an object with each sphere." ((object-array (inline-array hash-object-info) :offset-assert 104) (mem-object-array (inline-array hash-object-info) :offset-assert 108) (spr-object-array (inline-array hash-object-info) :offset-assert 112) @@ -23644,6 +25446,7 @@ ) (deftype load-dgo-msg (structure) +"IOP RPC message for loading a dgo." ((rsvd uint16 :offset-assert 0) (result load-msg-result :offset-assert 2) (b1 pointer :offset-assert 4) ;; guessed by decompiler @@ -23658,6 +25461,7 @@ ) (deftype load-chunk-msg (structure) +"IOP RPC message for loading a chunk of a chunked animation" ((rsvd uint16 :offset-assert 0) (result load-msg-result :offset-assert 2) (address pointer :offset-assert 4) ;; guessed by decompiler @@ -23672,6 +25476,7 @@ ) (deftype play-chunk-msg (structure) +"IOP RPC message for playing some streamed audio." ((rsvd uint16 :offset-assert 0) (result uint16 :offset-assert 2) (address pointer :offset-assert 4) @@ -23700,29 +25505,49 @@ (define-extern *load-str-lock* symbol) (define-extern *que-str-lock* symbol) (define-extern *dgo-name* string) -(define-extern str-load (function string int pointer int symbol)) -(define-extern str-load-status (function (pointer int32) symbol)) -(define-extern str-load-cancel (function none)) -(define-extern str-play-async (function string sound-id none)) -(define-extern str-play-stop (function string sound-id none)) -(define-extern str-play-queue (function string string string string (pointer uint32) pointer none)) -(define-extern str-ambient-play (function string none)) -(define-extern str-ambient-stop (function string none)) -(define-extern str-play-kick (function none)) ;; +(define-extern str-load + "Send a message to the IOP to start loading a chunk of a .STR file to the EE." + (function string int pointer int symbol)) +(define-extern str-load-status + "Get the status of the most recent load. + Return 'busy if in progress, 'error if failed, or 'complete. + If 'complete, returns the maxlen value from the IOP." + (function (pointer int32) symbol)) +(define-extern str-load-cancel + "Cancel a streaming load. Note that this does not actually stop the transfer, so the IOP may continue writing to the buffer." + (function none)) +(define-extern str-play-async "Start playing a streaming audio." (function string sound-id none)) +(define-extern str-play-stop + "Stop playing streaming audio." + (function string sound-id none)) +(define-extern str-play-queue "Queue up streaming data, allowing it to start playing without delay." (function string string string string (pointer uint32) pointer none)) +(define-extern str-ambient-play "Start playing ambient (unused?)." (function string none)) +(define-extern str-ambient-stop "Stop playing ambient (unused?)." (function string none)) +(define-extern str-play-kick + "Do an empty RPC on play so the IOP code runs and can update buffers." + (function none)) ;; (define-extern *dgo-time* time-frame) -(define-extern dgo-load-begin (function string pointer pointer pointer load-dgo-msg)) -(define-extern dgo-load-get-next (function (pointer symbol) pointer)) -(define-extern dgo-load-continue (function pointer pointer pointer load-dgo-msg)) -(define-extern dgo-load-cancel (function none)) -(define-extern find-temp-buffer (function int pointer)) -(define-extern dgo-load-link (function dgo-header kheap uint symbol symbol symbol)) -(define-extern destroy-mem (function (pointer uint32) (pointer uint32) none)) +(define-extern dgo-load-begin "Start a DGO load!" (function string pointer pointer pointer load-dgo-msg)) +(define-extern dgo-load-get-next "Get the address of the most recently loaded object. #f is there is none. Returns if this is the last by arg0." (function (pointer symbol) pointer)) +(define-extern dgo-load-continue + "Inform the IOP that it is safe to start loading the next object." + (function pointer pointer pointer load-dgo-msg)) +(define-extern dgo-load-cancel "Abort a DGO load." (function none)) +(define-extern find-temp-buffer + "Unused function to find some temporary leftover space in DMA buffer. + Unused since jak 1, and checks the same buffer twice??" + (function int pointer)) +(define-extern dgo-load-link "Start the async linker on a GOAL object file that was just loaded." (function dgo-header kheap uint symbol symbol symbol)) +(define-extern destroy-mem + "Overwrite memory with #xffffffff for debugging." + (function (pointer uint32) (pointer uint32) none)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; ramdisk ;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (deftype ramdisk-rpc-fill (structure) +"Unused RAMDISK rpc to load files from DVD to the IOP RAM." ((rsvd1 int32 :offset-assert 0) (ee-id int32 :offset-assert 4) (rsvd2 int32 2 :offset-assert 8) ;; guessed by decompiler @@ -23734,6 +25559,7 @@ ) (deftype ramdisk-rpc-load (structure) +"Unused RAMDISK rpc to load files from DVD to the IOP RAM." ((rsvd int32 :offset-assert 0) (ee-id int32 :offset-assert 4) (offset uint32 :offset-assert 8) @@ -23745,6 +25571,7 @@ ) (deftype ramdisk-rpc-load-to-ee (structure) +"Unused RAMDISK rpc to load files from DVD to the IOP RAM." ((rsvd int32 :offset-assert 0) (addr int32 :offset-assert 4) (offset int32 :offset-assert 8) @@ -23829,62 +25656,125 @@ (define-extern *sound-loop-engine* engine-sound-pers) (define-extern *sound-player-rpc* rpc-buffer-pair) (define-extern *sound-loader-rpc* rpc-buffer-pair) -(define-extern sound-name= (function sound-name sound-name symbol)) +(define-extern sound-name= + "Are two sound names the same?" + (function sound-name sound-name symbol)) (define-extern *sound-iop-info* sound-iop-info) -(define-extern str-is-playing? (function symbol)) -(define-extern str-id-is-playing? (function int symbol)) -(define-extern current-str-pos (function sound-id int)) -(define-extern is-ramdisk-loaded? (function symbol symbol)) -(define-extern is-cd-in? (function symbol)) -(define-extern new-sound-id (function sound-id)) -(define-extern check-irx-version (function int)) -(define-extern sound-bank-iop-store (function sound-name sound-id)) -(define-extern sound-bank-iop-free (function sound-name sound-id)) -(define-extern sound-bank-load (function sound-name sound-id)) -(define-extern sound-bank-load-from-iop (function sound-name sound-id)) -(define-extern sound-bank-load-from-ee (function sound-name pointer sound-id)) -(define-extern sound-bank-unload (function sound-name int)) -(define-extern sound-music-load (function sound-name int)) -(define-extern sound-music-unload (function int)) -(define-extern set-language (function language-enum int)) -(define-extern sound-set-stereo-mode (function stereo-mode none)) -(define-extern list-sounds (function none)) -(define-extern sound-command->string (function sound-command string)) -(define-extern sound-buffer-dump (function int)) +(define-extern str-is-playing? "Is any streaming audio playing?" (function symbol)) +(define-extern str-id-is-playing? "Is any streaming audio with the given ID playing?" (function int symbol)) +(define-extern current-str-pos + "Get the current stream position of the given sound ID, or -1 if it is not playing." + (function sound-id int)) +(define-extern is-ramdisk-loaded? + "Check if the ramdisk-name is set to this (unused)." + (function symbol symbol)) +(define-extern is-cd-in? + "Is the CD/DVD in the ps2?" + (function symbol)) +(define-extern new-sound-id + "Allocate a new sound ID, used to identify a unique playback of a sound." + (function sound-id)) +(define-extern check-irx-version + "Confirm OVERLORD version is correct and set up the sound-iop-info address so the OVERLORD can report back to the EE." + (function int)) +(define-extern sound-bank-iop-store + "Send a iop-store RPC to loader with the given name" + (function sound-name sound-id)) +(define-extern sound-bank-iop-free + "Send a iop-free RPC to loader with the given name" + (function sound-name sound-id)) +(define-extern sound-bank-load "Send RPC to load a sound bank." (function sound-name sound-id)) +(define-extern sound-bank-load-from-iop + "Send load-bank-from-iop rpc to loader" + (function sound-name sound-id)) +(define-extern sound-bank-load-from-ee + "Send load-bank-from-ee rpc to loader" + (function sound-name pointer sound-id)) +(define-extern sound-bank-unload + "Send unload-bank rpc to loader" + (function sound-name int)) +(define-extern sound-music-load + "Send load-music rpc to loader" + (function sound-name int)) +(define-extern sound-music-unload + "Send unload-music rpc to loader." + (function int)) +(define-extern set-language "Send set-language rpc to loader. Note this is only for sound, no game text is changed." (function language-enum int)) +(define-extern sound-set-stereo-mode "Send set-stereo-mode rpc to loader." (function stereo-mode none)) +(define-extern list-sounds + "Send list-sounds rpc to loader." + (function none)) +(define-extern sound-command->string + "Convert sound-command enum to string." + (function sound-command string)) +(define-extern sound-buffer-dump + "Print out all sound-commands in the buffer." + (function int)) (define-extern *sound-player-enable* symbol) -(define-extern swap-sound-buffers (function vector vector vector float int)) -(define-extern get-sound-buffer-entry (function pointer)) -(define-extern free-last-sound-buffer-entry (function none)) -(define-extern sound-basic-cb (function int (pointer int32) none)) -(define-extern sound-trans-convert (function vector3w vector int)) -(define-extern sound-angle-convert (function float int)) -(define-extern string->sound-name (function string sound-name)) -(define-extern sound-set-volume (function sound-group float int)) -(define-extern sound-set-reverb (function int float float uint int)) -(define-extern sound-set-ear-trans (function vector vector vector float int)) +(define-extern swap-sound-buffers "Per-frame update of sound system - update loop-engine, update ear trans, send player RPC, check for missing/dirty CD." (function vector vector vector float int)) +(define-extern get-sound-buffer-entry + "Allocate a new entry in the player RPC queue, to be flushed on the next frame." + (function pointer)) +(define-extern free-last-sound-buffer-entry + "Remove the last thing added with get-sound-buffer-entry." + (function none)) +(define-extern sound-basic-cb + "Unknown and unused callback." + (function int (pointer int32) none)) +(define-extern sound-trans-convert "Convert a GOAL translation (meters) to integer format for the IOP" (function vector3w vector int)) +(define-extern sound-angle-convert + "Convert a GOAL angle to integer format for the iop" + (function float int)) +(define-extern string->sound-name "Create a sound-name from a string" (function string sound-name)) +(define-extern sound-set-volume "Send set-master-volume rpc." (function sound-group float int)) +(define-extern sound-set-reverb + "Send set-reverb rpc" + (function int float float uint int)) +(define-extern sound-set-ear-trans "Send set-ear-trans rpc" (function vector vector vector float int)) (define-extern sound-play-by-name - "Last arg can by a symbol with value [[#t]], in which case it will pull `trans` [[vector]] off the current [[process-drawable]] + "Send play rpc to play a sound! + Last arg can by a symbol with value [[#t]], in which case it will pull `trans` [[vector]] off the current [[process-drawable]] otherwise, an explicit [[vector]] can be provided" (function sound-name sound-id int int int sound-group object sound-id :behavior process-drawable)) -(define-extern sound-play-by-spec (function sound-spec sound-id vector sound-id :behavior process-drawable)) ;; vector or symbol for final arg? -(define-extern sound-pause (function sound-id int)) -(define-extern sound-stop (function sound-id int)) -(define-extern sound-continue (function sound-id int)) -(define-extern sound-group-pause (function sound-group int)) -(define-extern sound-group-stop (function sound-group int)) -(define-extern sound-group-continue (function sound-group int)) -(define-extern sound-set-flava (function uint uint int)) -(define-extern sound-set-midi-reg (function int int int)) -(define-extern sound-set-fps (function int int)) -(define-extern sound-volume-off (function int)) +(define-extern sound-play-by-spec "Send play rpc to play a sound!" (function sound-spec sound-id vector sound-id :behavior process-drawable)) ;; vector or symbol for final arg? +(define-extern sound-pause + "Send pause-sound rpc to pause by id" + (function sound-id int)) +(define-extern sound-stop + "Send stop-sound rpc to stop by id" + (function sound-id int)) +(define-extern sound-continue + "Send continue-sound rpc to continue by id" + (function sound-id int)) +(define-extern sound-group-pause "Send pause-group rpc" (function sound-group int)) +(define-extern sound-group-stop "Send stop-group rpc" (function sound-group int)) +(define-extern sound-group-continue "Send continue-group rpc" (function sound-group int)) +(define-extern sound-set-flava + "Send set-flava rpc" + (function uint uint int)) +(define-extern sound-set-midi-reg + "Send set-midi-reg rpc" + (function int int int)) +(define-extern sound-set-fps + "Send set-fps rpc" + (function int int)) +(define-extern sound-volume-off + "Adjust settings to turn all sound volume off" + (function int)) (define-extern *ambient-spec* sound-spec) -(define-extern show-iop-info (function dma-buffer int)) -(define-extern show-iop-memory (function dma-buffer int)) -(define-extern ear-trans (function int vector)) -(define-extern make-sqrt-table (function int)) -(define-extern loader-test-command (function sound-command uint none)) -(define-extern doppler-pitch-shift (function vector vector float)) -(define-extern sound-bank-reload (function none)) +(define-extern show-iop-info "Display iop info on screen." (function dma-buffer int)) +(define-extern show-iop-memory + "Display iop memory stats on screen" + (function dma-buffer int)) +(define-extern ear-trans "Get the current location of the ear. Use 1 for the settings ear-handle, or 0 for the camera." (function int vector)) +(define-extern make-sqrt-table "Generate integer square-root table used in the IOP." (function int)) +(define-extern loader-test-command + "Send a command to loader by ID." + (function sound-command uint none)) +(define-extern doppler-pitch-shift + "Compute pitch shift for the doppler effect. This is done assuming the listener is *target* and has *target*'s velocity." + (function vector vector float)) +(define-extern sound-bank-reload "Start a background process to unload all sound banks, then load them again." (function none)) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; transformq ;; @@ -24649,6 +26539,7 @@ #| (deftype merc-fragment-control (structure) +"Data about a [[merc-fragment]] needed for merc DMA generation." () :method-count-assert 9 :size-assert #x4 @@ -24659,6 +26550,8 @@ #| (deftype merc-ctrl (art-element) +"The merc data for a single model as it's stored in an art group. +Consists of a header and a list of [[merc-effect]]s." () :method-count-assert 13 :size-assert #xa0 @@ -24898,6 +26791,7 @@ #| (deftype gsf-vertex (structure) +"Vertex used by generic. GSF = generic stripped fragment?" () :method-count-assert 9 :size-assert #x20 diff --git a/decompiler/config/jak2/ntsc_v1/var_names.jsonc b/decompiler/config/jak2/ntsc_v1/var_names.jsonc index 32c04cbde4..f98925f8b6 100644 --- a/decompiler/config/jak2/ntsc_v1/var_names.jsonc +++ b/decompiler/config/jak2/ntsc_v1/var_names.jsonc @@ -755,13 +755,13 @@ "args": ["nav", "sphere", "max-spheres"] }, "texture-bpp": { - "args": ["tex-fmt"] + "args": ["tex-format"] }, "texture-qwc": { - "args": ["width", "height", "tex-fmt"] + "args": ["w", "h", "tex-format"] }, "physical-address": { - "args": ["ptr"] + "args": ["addr"] }, "dma-buffer-add-ref-texture": { "args": ["dma-buf", "tex-data-ptr", "width", "height", "tex-fmt"], @@ -773,7 +773,7 @@ } }, "gs-find-block": { - "args": ["bx", "by", "fmt"] + "args": ["bx", "by", "tex-format"] }, "(method 18 texture-pool)": { "args": ["this", "tpage-id"] @@ -786,7 +786,7 @@ } }, "(method 16 texture-pool)": { - "args": ["this", "seg", "num-words"] + "args": ["this", "segment", "size"] }, "(method 9 texture-page)": { "args": ["this", "heap"] @@ -803,11 +803,7 @@ } }, "texture-page-common-allocate": { - "args": ["pool", "tpage", "heap", "tpage-id"], - "vars": { - "s5-0": "vram-loc", - "s4-0": "seg" - } + "args": ["pool", "page", "heap", "page-id"] }, "texture-page-font-allocate": { "args": ["pool", "tpage", "heap", "tpage-id"], @@ -875,16 +871,7 @@ } }, "update-vram-pages": { - "args": ["pool", "dest-seg", "tpage", "mode", "bucket"], - "vars": { - "t1-0": "vram-ptr", - "t2-0": "tpage-num-chunks", - "v1-2": "chunks-pending", - "t0-1": "tpage-id", - "a1-4": "adjusted-num-chunks", - "a2-3": "chunk-idx", - "a3-8": "chunk-ptr" - } + "args": ["pool", "pool-segment", "page", "mode"] }, "upload-vram-pages-pris": { "args": ["pool", "dest-seg", "tpage", "bucket"], @@ -904,10 +891,7 @@ } }, "texture-page-level-allocate": { - "args": ["pool", "tpage", "heap", "tpage-id"], - "vars": { - "s2-0": "common-page-slot-id" - } + "args": ["pool", "page", "heap", "page-id"] }, "texture-page-size-check": { "args": ["pool", "lev", "silent"] @@ -940,15 +924,7 @@ "args": ["dma-buff", "tex", "dest-loc", "dest-fmt", "clut-dst"] }, "(method 11 texture-page)": { - "args": ["this", "new-dest", "segs"], - "vars": { - "v1-0": "new-tbp", - "a3-4": "old-tbp", - "t0-1": "tex-idx", - "t1-6": "tex", - "t2-0": "num-mips", - "t3-4": "mip-idx" - } + "args": ["this", "new-dest", "seg-id"] }, "(method 7 texture-page)": { "args": ["this", "loading-heap", "name"], @@ -959,13 +935,7 @@ } }, "texture-page-login": { - "args": ["tex-id", "alloc-func", "heap"], - "vars": { - "s5-0": "dir-entry", - "s4-0": "old-alloc-func", - "s3-0": "name", - "s2-0": "loaded-tpage" - } + "args": ["id", "alloc-func", "heap"] }, "(method 9 texture-page-dir)": { "args": ["this", "heap"], @@ -4731,5 +4701,629 @@ "gp-1": "_fog-idx", "v1-5": "fog-idx" } + }, + "vector-xz-normalize!": { + "args": ["vec", "arg1"] + }, + "mem-print": { + "args": ["ptr", "word-count"] + }, + "(method 3 inline-array-class)": { + "args": ["idx-to-remove"] + }, + "valid?": { + "args": [ + "obj", + "expected-type", + "err-msg-str", + "allow-false", + "err-msg-dest" + ] + }, + "print-tree-bitmask": { + "args": ["mask", "count"] + }, + "inspect": { + "args": ["obj"] + }, + "printl": { + "args": ["obj"] + }, + "print": { + "args": ["obj"] + }, + "fact": { + "args": ["x"] + }, + "mem-or!": { + "args": ["dst", "src", "bytes"] + }, + "mem-set32!": { + "args": ["dst", "word-count", "value"] + }, + "qmem-copy->!": { + "args": ["dst", "src", "qwc"] + }, + "qmem-copy<-!": { + "args": ["dst", "src", "qwc"] + }, + "mem-copy!": { + "args": ["dst", "src", "bytes"] + }, + "(method 0 inline-array-class)": { + "args": ["allocation", "type-to-make", "count"] + }, + "sort": { + "args": ["list", "compare-func"] + }, + "insert-cons!": { + "args": ["new-obj", "list"] + }, + "delete-car!": { + "args": ["car-to-match", "list"] + }, + "delete!": { + "args": ["obj", "list"] + }, + "append!": { + "args": ["list", "new-obj"] + }, + "nassoce": { + "args": ["key", "assoc-list"] + }, + "nassoc": { + "args": ["key", "assoc-list"] + }, + "assoce": { + "args": ["key", "assoc-list"] + }, + "assoc": { + "args": ["key", "assoc-list"] + }, + "nmember": { + "args": ["obj-to-find", "list"] + }, + "member": { + "args": ["obj-to-find", "list"] + }, + "last": { + "args": ["list"] + }, + "ref": { + "args": ["list", "idx"] + }, + "find-parent-method": { + "args": ["typ", "method-id"] + }, + "type?": { + "args": ["obj", "desired-type"] + }, + "type-type?": { + "args": ["check-type", "parent-type"] + }, + "basic-type?": { + "args": ["obj", "typ"] + }, + "lognot": { + "args": ["x"] + }, + "logxor": { + "args": ["a", "b"] + }, + "lognor": { + "args": ["a", "b"] + }, + "logand": { + "args": ["a", "b"] + }, + "logior": { + "args": ["a", "b"] + }, + "max": { + "args": ["a", "b"] + }, + "min": { + "args": ["a", "b"] + }, + "abs": { + "args": ["x"] + }, + "rem": { + "args": ["a", "b"] + }, + "mod": { + "args": ["a", "b"] + }, + "ash": { + "args": ["x", "shift-amount"] + }, + "/": { + "args": ["a", "b"] + }, + "*": { + "args": ["a", "b"] + }, + "-": { + "args": ["a", "b"] + }, + "+": { + "args": ["a", "b"] + }, + "1/": { + "args": ["x"] + }, + "identity": { + "args": ["obj"] + }, + "(method 10 process-tree)": { + "args": ["this", "ent"] + }, + "change-to-last-brother": { + "args": ["proc"] + }, + "change-parent": { + "args": ["proc-to-change", "new-parent"] + }, + "previous-brother": { + "args": ["tree"] + }, + "(method 0 protect-frame)": { + "args": ["stack-addr", "type-to-make", "exit-func"] + }, + "inspect-process-tree": { + "args": ["tree", "depth", "mask", "detail"] + }, + "search-process-tree": { + "args": ["tree", "callback"] + }, + "execute-process-tree": { + "args": ["tree", "callback", "context"] + }, + "iterate-process-tree": { + "args": ["tree", "callback", "context"] + }, + "kill-not-type": { + "args": ["typ", "tree"] + }, + "kill-not-name": { + "args": ["name", "tree"] + }, + "kill-by-type": { + "args": ["typ", "tree"] + }, + "kill-by-name": { + "args": ["name", "tree"] + }, + "process-count": { + "args": ["tree"] + }, + "process-not-name": { + "args": ["name", "tree"] + }, + "process-by-name": { + "args": ["process-name", "tree"] + }, + "(method 19 dead-pool-heap)": { + "args": ["this", "count"] + }, + "(method 18 dead-pool-heap)": { + "args": ["this", "proc"] + }, + "(method 15 dead-pool-heap)": { + "args": ["this", "proc"] + }, + "(method 27 dead-pool-heap)": { + "args": ["this", "size"] + }, + "(method 26 dead-pool-heap)": { + "args": ["this", "first-rec"] + }, + "(method 24 dead-pool-heap)": { + "args": ["this", "first-rec"] + }, + "(method 25 dead-pool-heap)": { + "args": ["this", "rec"] + }, + "(method 16 dead-pool-heap)": { + "args": ["this", "allocation", "heap-size"] + }, + "(method 0 dead-pool-heap)": { + "args": ["allocation", "type-to-make", "name", "max-num-proc", "heap-size"] + }, + "(method 15 dead-pool)": { + "args": ["this", "proc"] + }, + "(method 0 dead-pool)": { + "args": ["allocation", "type-to-make", "num-proc", "process-size", "name"] + }, + "inspect-process-heap": { + "args": ["proc"] + }, + "(method 9 thread)": { + "args": ["this", "size-bytes"] + }, + "unload-package": { + "args": ["package-name"] + }, + "load-package": { + "args": ["package-name", "heap"] + }, + "string>=?": { + "args": ["a", "b"] + }, + "string<=?": { + "args": ["a", "b"] + }, + "string>?": { + "args": ["a", "b"] + }, + "stringstring": { + "args": ["cmd"] + }, + "doppler-pitch-shift": { + "args": ["sound-pos", "sound-vel"] + }, + "loader-test-command": { + "args": ["cmd", "param"] + }, + "show-iop-memory": { + "args": ["dma"] + }, + "(method 10 ambient-sound)": { + "args": ["this", "new-sound"] + }, + "sound-set-fps": { + "args": ["fps"] + }, + "sound-set-midi-reg": { + "args": ["reg", "val"] + }, + "sound-set-flava": { + "args": ["flava", "excitement"] + }, + "sound-continue": { + "args": ["id"] + }, + "sound-stop": { + "args": ["id"] + }, + "sound-pause": { + "args": ["id"] + }, + "sound-set-reverb": { + "args": ["reverb", "left", "right", "core"] + }, + "sound-angle-convert": { + "args": ["float-angle"] + }, + "sound-music-load": { + "args": ["name"] + }, + "sound-bank-unload": { + "args": ["name"] + }, + "sound-bank-load-from-ee": { + "args": ["name", "addr"] + }, + "sound-bank-load-from-iop": { + "args": ["name"] + }, + "sound-bank-iop-free": { + "args": ["name"] + }, + "sound-bank-iop-store": { + "args": ["name"] + }, + "is-ramdisk-loaded?": { + "args": ["name"] + }, + "current-str-pos": { + "args": ["id"] + }, + "sound-name=": { + "args": ["a", "b"] + }, + "copy-string<-string": { + "args": ["dst", "src"] + }, + "(method 10 collide-mesh-cache)": { + "args": ["this", "id"] + }, + "(method 11 touching-prims-entry-pool)": { + "vars": { + "v1-0": "prev", + "a1-0": "current", + "a2-0": "next" + } + }, + "dma-bucket-insert-tag": { + "args": ["buckets", "bucket", "start-tag", "end-tag-to-patch"] + }, + "dma-buffer-add-buckets": { + "args": ["dma-buf", "bucket-count"] + }, + "dma-buffer-send-chain": { + "args": ["chan", "buf"] + }, + "dma-buffer-send": { + "args": ["chan", "buf"] + }, + "dma-buffer-free": { + "args": ["dma-buf"] + }, + "dma-buffer-length": { + "args": ["dma-buf"] + }, + "dma-buffer-inplace-new": { + "args": ["dma-buff", "size-bytes"] + }, + "disasm-dma-tag": { + "args": ["tag", "format-dest"] + }, + "(method 17 res-lump)": { + "args": ["this", "tag", "arg2"] + }, + "(method 20 res-lump)": { + "args": ["this", "arg1", "tag-pair", "arg3"] + }, + "(method 13 effect-control)": { + "args": ["this", "offset"] + }, + "(method 0 effect-control)": { + "args": ["allocation", "type-to-make", "proc"] + }, + "(method 0 path-control)": { + "args": [ + "allocation", + "type-to-make", + "proc", + "lump-name", + "lump-time", + "lump-actor", + "must-exist" + ] + }, + "merc-fragment-fp-data": { + "args": ["frag"] + }, + "vector-rad<-vector-deg/2!": { + "args": ["out", "in"] + }, + "vector-rad<-vector-deg!": { + "args": ["out", "in"] + }, + "(method 12 focus)": { + "args": ["this", "proc"] + }, + "(method 10 focus)": { + "args": ["this", "proc"], + "vars": { + "s5-0": "root", + "v1-2": "cshape" + } + }, + "(method 11 focus)": { + "args": ["this", "cspec"] + }, + "service-mouse": { + "vars": { + "gp-0": "mouse" + } + }, + "(method 12 smush-control)": { + "args": [ + "this", + "amplitude", + "period", + "duration", + "damp-amplitude", + "damp-period", + "clock" + ] + }, + "(method 11 smush-control)": { + "vars": { + "f30-0": "elapsed-time", + "f0-2": "period" + } + }, + "(method 10 smush-control)": { + "vars": { + "f30-0": "elapsed-time", + "f0-2": "period" + } } } diff --git a/decompiler/config/jak3/all-types.gc b/decompiler/config/jak3/all-types.gc index 341da1c8ce..cb6b2b27b8 100644 --- a/decompiler/config/jak3/all-types.gc +++ b/decompiler/config/jak3/all-types.gc @@ -12111,7 +12111,7 @@ (:methods (debug-draw-region (_type_ int) none) ;; 17 (track-region (_type_ region-prim-area) symbol) ;; 18 - (within-area? (_type_ region-prim-area) symbol) ;; 19 + (within-area? "@returns Whether or not the object overlaps with the provided [[region-prim-area]]'s extent" (_type_ region-prim-area) symbol) ;; 19 ) ) diff --git a/decompiler/config/jak3/ntsc_v1/var_names.jsonc b/decompiler/config/jak3/ntsc_v1/var_names.jsonc index 933c7c135d..7511e8261d 100644 --- a/decompiler/config/jak3/ntsc_v1/var_names.jsonc +++ b/decompiler/config/jak3/ntsc_v1/var_names.jsonc @@ -1159,5 +1159,20 @@ "gp-1": "_fog-idx", "v1-5": "fog-idx" } + }, + "vector-xz-normalize!": { + "args": ["vec", "arg1"] + }, + "(method 10 texture-page)": { + "args": ["this", "num-segments", "upload-offset"], + "vars": { + "v1-0": "offset", + "a2-1": "i" + } + }, + "(method 0 align-control)": { + "vars": { + "v0-0": ["this", "align-control"] + } } } diff --git a/goal_src/jak2/engine/ambient/ambient.gc b/goal_src/jak2/engine/ambient/ambient.gc index 2cfe9de08b..ce996c5ff1 100644 --- a/goal_src/jak2/engine/ambient/ambient.gc +++ b/goal_src/jak2/engine/ambient/ambient.gc @@ -477,7 +477,7 @@ (and (nonzero? (-> self message-id)) (= (get-status *gui-control* (-> self message-id)) (gui-status active)) (or (not (time-elapsed? (-> self state-time) (the-as time-frame (-> self message text-duration)))) - (and (logtest? (-> self message flags) 16) (-> self region) (region-method-9 (-> self region) (target-pos 0))) + (and (logtest? (-> self message flags) 16) (-> self region) (point-in-region-debug! (-> self region) (target-pos 0))) ) ) (not (time-elapsed? (-> self state-time) (seconds 0.05))) diff --git a/goal_src/jak2/engine/game/main.gc b/goal_src/jak2/engine/game/main.gc index b361ffdea8..1ee2e27747 100644 --- a/goal_src/jak2/engine/game/main.gc +++ b/goal_src/jak2/engine/game/main.gc @@ -698,7 +698,7 @@ ) (while (< i s0-4) (let ((draw? #f)) - (when (and *display-region-inside* (!= tree-name 'water) (region-method-9 (-> region region) (target-pos 0))) + (when (and *display-region-inside* (!= tree-name 'water) (point-in-region-debug! (-> region region) (target-pos 0))) (true! draw?) (format *stdcon* "~1kinside region-~D [~A] (l: ~A)~%" (-> region region id) tree-name (-> lev name))) (when (and *region-debug-inspect* (or (= *region-debug-inspect* region) (and *merge-region-prims* (= (-> region region id) (-> *region-debug-inspect* region id))))) @@ -734,7 +734,7 @@ (debug-draw-buffers) (with-dma-buffer-add-bucket ((s3-0 (-> arg0 frames (-> arg0 on-screen) debug-buf)) (bucket-id debug-no-zbuf2)) (when (or *display-profile* *stats-profile-bars*) - (setup-categories! (-> arg0 frames (-> arg0 on-screen) profile-array)) + (postprocess-data! (-> arg0 frames (-> arg0 on-screen) profile-array)) (let ((a2-0 7)) (if *display-profile* (draw-bars! *profile-array* s3-0 a2-0) diff --git a/goal_src/jak2/engine/level/region-h.gc b/goal_src/jak2/engine/level/region-h.gc index d1cbbe210a..88b235cdcb 100644 --- a/goal_src/jak2/engine/level/region-h.gc +++ b/goal_src/jak2/engine/level/region-h.gc @@ -16,7 +16,7 @@ (on-exit pair) ) (:methods - (region-method-9 (_type_ vector) symbol) + (point-in-region-debug! (_type_ vector) symbol) ) ) diff --git a/goal_src/jak2/engine/level/region.gc b/goal_src/jak2/engine/level/region.gc index 4fe048cedf..77678774c2 100644 --- a/goal_src/jak2/engine/level/region.gc +++ b/goal_src/jak2/engine/level/region.gc @@ -499,7 +499,7 @@ otherwise, add the [[drawable-region-sphere]] to `region-start-prim-list` and in ) ;; WARN: Return type mismatch int vs symbol. -(defmethod region-method-9 ((this region) (arg0 vector)) +(defmethod point-in-region-debug! ((this region) (arg0 vector)) (local-vars (sv-16 int) (sv-32 int)) (sphere<-vector+r! (the-as sphere (-> (the-as region-prim-area (scratchpad-object region-prim-area)) pos)) arg0 0.0) (dotimes (s5-0 (-> *level* length)) diff --git a/goal_src/jak2/engine/util/profile-h.gc b/goal_src/jak2/engine/util/profile-h.gc index b69b02d3cc..f78fecc2a0 100644 --- a/goal_src/jak2/engine/util/profile-h.gc +++ b/goal_src/jak2/engine/util/profile-h.gc @@ -68,7 +68,7 @@ The "count" can be used for whatever you want (ex: fragments, VU calls, etc) ((data profile-segment-array 2) ) (:methods - (setup-categories! (_type_) none) + (postprocess-data! (_type_) none) (draw-bars! (_type_ dma-buffer int) none) (draw-text! (_type_) none) ) diff --git a/goal_src/jak2/engine/util/profile.gc b/goal_src/jak2/engine/util/profile.gc index 416da3225a..a6e30e40bc 100644 --- a/goal_src/jak2/engine/util/profile.gc +++ b/goal_src/jak2/engine/util/profile.gc @@ -382,7 +382,7 @@ ) ) -(defmethod setup-categories! ((this profile-array)) +(defmethod postprocess-data! ((this profile-array)) "Summarize data collected." ;; loop over both EE and VU profilers diff --git a/scripts/docs/append-file-docs.py b/scripts/ci/docs/append-file-docs.py similarity index 98% rename from scripts/docs/append-file-docs.py rename to scripts/ci/docs/append-file-docs.py index cf9b0188e1..3338d9da9b 100644 --- a/scripts/docs/append-file-docs.py +++ b/scripts/ci/docs/append-file-docs.py @@ -42,3 +42,4 @@ def append_file_docs(game_name): append_file_docs("jak1") append_file_docs("jak2") +append_file_docs("jak3") diff --git a/scripts/gsrc/copy-common-naming.py b/scripts/gsrc/copy-common-naming.py new file mode 100644 index 0000000000..360e8f01b0 --- /dev/null +++ b/scripts/gsrc/copy-common-naming.py @@ -0,0 +1,191 @@ +# The goal of this script is fairly straight forward +# Given a object file name, decompile it for both jak 2 and jak 3 WITHOUT variable casts +# Get all function definitions and compare the function bodies. +# - if the function bodies are the same, copy the variables from whichever game has them defined to the other +# - also, if it's a function and a docstring exists on one side but not the other, copy the docstring to the other side's all-types file + +import argparse +import glob +import json +import os + +from utils import decompile_file, is_file_in_game + + +parser = argparse.ArgumentParser("copy-common-naming") +parser.add_argument("--file", help="The name of the file", type=str) +parser.add_argument("--decompiler", help="The path to the decompiler", type=str) +parser.add_argument("--update-names-from-refs", help="The decomp config version", action='store_true') +args = parser.parse_args() + +def find_all_function_defs(lines): + store = {} + in_function_def = False + in_docstring = False + passed_potential_docstring = False + current_function_name = None + for line in lines: + if line.startswith("; .function") and "top-level" not in line: + current_function_name = line.split(".function")[1].strip() + store[current_function_name] = { + "docstring": [], + "definition": [], + } + passed_potential_docstring = False + in_docstring = False + continue + if current_function_name is not None and line.startswith(";;-*-OpenGOAL-Start-*-"): + in_function_def = True + continue + if current_function_name is not None and line.startswith(";;-*-OpenGOAL-End-*-"): + in_function_def = False + continue + if line.strip() == "": + continue + if in_function_def: + if not passed_potential_docstring and line.strip().startswith("\""): + in_docstring = True + if in_docstring: + store[current_function_name]["docstring"].append(line.strip()) + if line.strip().endswith("\""): + in_docstring = False + else: + store[current_function_name]["definition"].append(line) + if len(store[current_function_name]["definition"]) > 1 and line.startswith(" "): + passed_potential_docstring = True + return store + +def get_var_casts_for_game(game_name): + return json.load(open("./decompiler/config/{}/ntsc_v1/var_names.jsonc".format(game_name), "r")) + +def save_var_casts_for_game(game_name, casts): + with open("./decompiler/config/{}/ntsc_v1/var_names.jsonc".format(game_name), "w") as f: + json.dump(casts, f, indent=2) + +def get_all_types_for_game(game_name): + return open("./decompiler/config/{}/all-types.gc".format(game_name), "r").readlines() + +jak2_alltypes = get_all_types_for_game("jak2") +jak3_alltypes = get_all_types_for_game("jak3") + +file_stats = "" + +def update_file_var_name_casts(file_name, modify_alltypes): + global file_stats + # Check if the file exists in both games + if not is_file_in_game("jak3", file_name) or not is_file_in_game("jak2", file_name): + print("File not found in both games") + return + + # Decompile the file for both games + decompile_file(args.decompiler, "jak3/jak3_config.jsonc", "ntsc_v1", "[\"{}\"]".format(file_name), True) + decompile_file(args.decompiler, "jak2/jak2_config.jsonc", "ntsc_v1", "[\"{}\"]".format(file_name), True) + + # Go grab the contents of each file + jak2_file_contents = open("./decompiler_out/jak2/{}_ir2.asm".format(file_name), "r").readlines() + jak3_file_contents = open("./decompiler_out/jak3/{}_ir2.asm".format(file_name), "r").readlines() + + # Read in the function definitions for each file to find which ones match + + jak2_function_defs = find_all_function_defs(jak2_file_contents) + jak3_function_defs = find_all_function_defs(jak3_file_contents) + + # print(jak2_function_defs["vector-xz-cross!"]) + # print() + # print(jak3_function_defs["vector-xz-cross!"]) + + # Compare functions to see which ones are eligible + matching_func_names = [] + for func_name in jak2_function_defs: + if func_name in jak3_function_defs and jak2_function_defs[func_name]["definition"] == jak3_function_defs[func_name]["definition"]: + matching_func_names.append(func_name) + + # print(matching_func_names) + file_stats = file_stats + "Found {} matching functions in {}\n".format(len(matching_func_names), file_name) + + # Go grab the var casts for each game + jak2_var_casts = get_var_casts_for_game("jak2") + jak3_var_casts = get_var_casts_for_game("jak3") + + # For each eligible matching function, copy over the var casts + # The assumption is if it exists in jak 3 it's better (done more recently) so we use that + # else, use jak 2's if it exists + for func_name in matching_func_names: + if func_name in jak3_var_casts: + jak2_var_casts[func_name] = jak3_var_casts[func_name] + elif func_name in jak2_var_casts: + jak3_var_casts[func_name] = jak2_var_casts[func_name] + + save_var_casts_for_game("jak2", jak2_var_casts) + save_var_casts_for_game("jak3", jak3_var_casts) + + # Automatically copy docstrings for functions (methods are way to annoying to do with hack scripts now) + if modify_alltypes: + for func_name in matching_func_names: + if func_name.startswith("("): + continue + # handle the case where the jak 3 version has a docstring, but jak 2 does not + if len(jak3_function_defs[func_name]["docstring"]) != 0 and len(jak2_function_defs[func_name]["docstring"]) == 0: + for line_no, line in enumerate(jak2_alltypes): + line = jak2_alltypes[line_no] + if line.startswith("(define-extern {}".format(func_name)): + jak2_alltypes[line_no] = line.replace("(define-extern {} ".format(func_name), "(define-extern {}\n {}\n ".format(func_name, "\n ".join(jak3_function_defs[func_name]["docstring"]))) + break + # handle the case where jak 2 has a docstring but jak 3 does not + elif len(jak2_function_defs[func_name]["docstring"]) != 0 and len(jak3_function_defs[func_name]["docstring"]) == 0: + for line_no, line in enumerate(jak3_alltypes): + line = jak3_alltypes[line_no] + if line.startswith("(define-extern {}".format(func_name)): + jak3_alltypes[line_no] = line.replace("(define-extern {} ".format(func_name), "(define-extern {}\n {}\n ".format(func_name, "\n ".join(jak2_function_defs[func_name]["docstring"]))) + break + +if args.update_names_from_refs: + reference_test_files = glob.glob("./test/decompiler/reference/jak3/**/*_REF.gc", recursive=True) + for file_no, reference_test_file in enumerate(reference_test_files): + file_name = os.path.basename(reference_test_file).split("_REF.gc")[0] + print("({}/{}) Checking Var Name Casts for {}...".format(file_no+1, len(reference_test_files), file_name)) + update_file_var_name_casts(file_name, False) +else: + update_file_var_name_casts(args.file, True) + +print(file_stats) + +def get_type_docstrings_from_alltypes(lines): + store = {} + awaiting_next_docstring = True + current_type_name = None + for line in lines: + if line.startswith("(deftype"): + current_type_name = line.split("deftype ")[1].split("(")[0].strip() + awaiting_next_docstring = False + store[current_type_name] = [] + continue + if line.strip().startswith("(") and not line.strip().endswith("\""): + awaiting_next_docstring = True + continue + if not awaiting_next_docstring: + store[current_type_name].append(line.strip()) + return store + +jak2_type_docs = get_type_docstrings_from_alltypes(jak2_alltypes) +jak3_type_docs = get_type_docstrings_from_alltypes(jak3_alltypes) + +# If a docstring exists in jak3 but not in jak2, copy it back +new_jak2_alltypes = [] +for line_no, line in enumerate(jak2_alltypes): + line = jak2_alltypes[line_no] + new_jak2_alltypes.append(line) + if line.startswith("(deftype "): + current_type_name = line.split("deftype ")[1].split("(")[0].strip() + if current_type_name in jak3_type_docs and len(jak2_type_docs[current_type_name]) == 0: + for docstring_line in jak3_type_docs[current_type_name]: + new_jak2_alltypes.append(" " + docstring_line + "\n") +jak2_alltypes = new_jak2_alltypes + +# Save all-types +def get_all_types_for_game(game_name, lines): + with open("./decompiler/config/{}/all-types.gc".format(game_name), "w") as f: + f.writelines(lines) + +get_all_types_for_game("jak2", jak2_alltypes) +get_all_types_for_game("jak3", jak3_alltypes) diff --git a/scripts/gsrc/find-missing-refs.py b/scripts/gsrc/find-missing-refs.py index 432a8a03c7..f8a34423c2 100644 --- a/scripts/gsrc/find-missing-refs.py +++ b/scripts/gsrc/find-missing-refs.py @@ -23,8 +23,6 @@ for file in file_list: gsrc_length = len(fp.readlines()) if gsrc_length > 15: - if file_name == "enemy-h": - print(file_name) # check if ref exists ref_path = get_ref_path_from_filename("jak2", file_name, "./test/decompiler/reference/") if not os.path.exists(ref_path): diff --git a/scripts/gsrc/requirements.txt b/scripts/gsrc/requirements.txt deleted file mode 100644 index be8060c80b..0000000000 --- a/scripts/gsrc/requirements.txt +++ /dev/null @@ -1,3 +0,0 @@ -rapidfuzz -GitPython -colorama diff --git a/scripts/gsrc/update-from-decomp.py b/scripts/gsrc/update-from-decomp.py index 0344158a8f..c728ce089e 100644 --- a/scripts/gsrc/update-from-decomp.py +++ b/scripts/gsrc/update-from-decomp.py @@ -36,13 +36,9 @@ # - there are likely ways to make this more efficient import argparse -import os from code_retention.all_types_retention import update_alltypes_named_blocks from code_retention.code_retention import is_line_start_of_form, has_form_ended from utils import get_gsrc_path_from_filename -import shutil -from pathlib import Path -import subprocess parser = argparse.ArgumentParser("update-from-decomp") parser.add_argument("--game", help="The name of the game", type=str) @@ -64,7 +60,6 @@ comments = [] debug_lines = [] decomp_ignore_forms = ["defmethod inspect"] decomp_ignore_errors = False -update_with_merge = False with open(gsrc_path) as f: lines_temp = f.readlines() @@ -78,26 +73,8 @@ with open(gsrc_path) as f: decomp_ignore_errors = True if "og:ignore-form" in line: decomp_ignore_forms.append(line.partition("ignore-form:")[2].strip()) - if "og:update-with-merge" in line: - update_with_merge = True lines.append(line) -# If we are going to `update_with_merge` then make a backup of the file, and -# an empty file to use as the common ancestor. -# -# This means that all changes will be flagged as a conflict and will not be able to be -# merged into the repo without being explicitly resolved -if update_with_merge: - subprocess.run( - [ - "git", - "restore", - gsrc_path - ] - ) - shutil.copyfile(gsrc_path, gsrc_path.replace(".gc", ".before.gc")) - Path(gsrc_path.replace(".gc", ".empty.gc")).touch() - if args.debug: with open(gsrc_path, "w") as f: f.writelines(debug_lines) @@ -207,29 +184,3 @@ with open(gsrc_path, "w") as f: while i + lines_to_ignore < len(final_lines): f.write(final_lines[i]) i = i + 1 - -# If we need to merge, now is the time! -if update_with_merge: - shutil.move(gsrc_path, gsrc_path.replace(".gc", ".after.gc")) - shutil.move(gsrc_path.replace(".gc", ".before.gc"), gsrc_path) - subprocess.run( - [ - "git", - "merge-file", - gsrc_path, - gsrc_path.replace(".gc", ".empty.gc"), - gsrc_path.replace(".gc", ".after.gc"), - "-L", - "Before Updating", - "-L", - "ignored", - "-L", - "After Updating", - ] - ) - if os.path.exists(gsrc_path.replace(".gc", ".empty.gc")): - os.remove(gsrc_path.replace(".gc", ".empty.gc")) - if os.path.exists(gsrc_path.replace(".gc", ".before.gc")): - os.remove(gsrc_path.replace(".gc", ".before.gc")) - if os.path.exists(gsrc_path.replace(".gc", ".after.gc")): - os.remove(gsrc_path.replace(".gc", ".after.gc")) diff --git a/scripts/gsrc/update-gsrc-via-refs.py b/scripts/gsrc/update-gsrc-via-refs.py index 532bb34f9e..16c35a32c2 100644 --- a/scripts/gsrc/update-gsrc-via-refs.py +++ b/scripts/gsrc/update-gsrc-via-refs.py @@ -1,8 +1,9 @@ # Updates files in gsrc if they are modified in the reference test folder # Uses git -import subprocess from git import Repo +from utils import decompile_file + repo = Repo("./") import argparse @@ -45,19 +46,7 @@ else: all_names = str(file_names).replace("'", "\"").replace("{", "[").replace("}", "]"); print("Decompiling - {}".format(all_names)) -# Decompile file -subprocess.run( - [ - args.decompiler, - "./decompiler/config/{}".format(args.decompiler_config), - "./iso_data", - "./decompiler_out", - "--version", - args.version, - "--config-override", - '{{"levels_extract": false, "process_art_groups": false, "decompile_code": true, "allowed_objects": {}}}'.format(all_names), - ] -) +decompile_file(args.decompiler, args.decompiler_config, args.version, all_names, False) for file_name in file_names: print("Updating - {}".format(file_name)) diff --git a/scripts/gsrc/utils.py b/scripts/gsrc/utils.py index e448cbcad6..72a4f94f58 100644 --- a/scripts/gsrc/utils.py +++ b/scripts/gsrc/utils.py @@ -1,5 +1,6 @@ import json import os +import subprocess jak1_files = None jak2_files = None @@ -21,6 +22,15 @@ def get_file_list(game_name): case "jak3": return jak3_files +def is_file_in_game(game_name, file_name): + file_list = get_file_list(game_name) + for f in file_list: + if f[2] != 3 and f[2] != 5: + continue + if f[0] == file_name: + return True + return False + def get_gsrc_path_from_filename(game_name, file_name): file_list = get_file_list(game_name) src_path = "" @@ -53,3 +63,21 @@ def get_ref_path_from_filename(game_name, file_name, ref_folder): exit(1) path = os.path.join(ref_folder, game_name, src_path, "{}_REF.gc".format(file_name)) return path + +def decompile_file(decompiler_path, decompiler_config, game_version, file_names, omit_var_casts=False): + decompiler_args = '{{"levels_extract": false, "process_art_groups": false, "decompile_code": true, "allowed_objects": {}}}'.format(file_names) + if omit_var_casts: + decompiler_args = '{{"levels_extract": false, "process_art_groups": false, "decompile_code": true, "ignore_var_name_casts": true, "allowed_objects": {}}}'.format(file_names) + subprocess.run( + [ + decompiler_path, + "./decompiler/config/{}".format(decompiler_config), + "./iso_data", + "./decompiler_out", + "--version", + game_version, + "--config-override", + decompiler_args, + ], + stdout = subprocess.DEVNULL +) diff --git a/test/decompiler/reference/jak2/engine/ai/enemy-h_REF.gc b/test/decompiler/reference/jak2/engine/ai/enemy-h_REF.gc index 2f04ef6b41..410489d38c 100644 --- a/test/decompiler/reference/jak2/engine/ai/enemy-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/ai/enemy-h_REF.gc @@ -713,6 +713,7 @@ ;; definition for method 9 of type enemy-focus ;; WARN: Return type mismatch enemy-flag vs none. (defmethod clear-focused ((this enemy-focus)) + "Reset the focus' handle." (let ((t9-0 (method-of-type focus clear-focused))) (t9-0 this) ) diff --git a/test/decompiler/reference/jak2/engine/ai/enemy_REF.gc b/test/decompiler/reference/jak2/engine/ai/enemy_REF.gc index bc735f1035..6e3ccc2fff 100644 --- a/test/decompiler/reference/jak2/engine/ai/enemy_REF.gc +++ b/test/decompiler/reference/jak2/engine/ai/enemy_REF.gc @@ -127,6 +127,7 @@ ;; definition for method 12 of type enemy ;; WARN: disable def twice: 40. This may happen when a cond (no else) is nested inside of another conditional, but it should be rare. (defmethod run-logic? ((this enemy)) + "Should this process be run? Checked by execute-process-tree." (cond ((logtest? (-> this mask) (process-mask actor-pause)) (let ((draw (-> this draw))) @@ -1365,6 +1366,7 @@ This commonly includes things such as: ;; definition for method 11 of type enemy-focus ;; WARN: Return type mismatch int vs none. (defmethod reset-to-collide-spec ((this enemy-focus) (arg0 collide-spec)) + "Reset this focus with the given [[collide-spec]]." (let ((t9-0 (method-of-type focus reset-to-collide-spec))) (t9-0 this arg0) ) diff --git a/test/decompiler/reference/jak2/engine/ambient/ambient-h_REF.gc b/test/decompiler/reference/jak2/engine/ambient/ambient-h_REF.gc index ac8923f4da..224cd0012e 100644 --- a/test/decompiler/reference/jak2/engine/ambient/ambient-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/ambient/ambient-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type talker-speech-class (deftype talker-speech-class (structure) + "Contains metadata about a voice line or hint text being played/displayed." ((name string) (channel gui-channel) (flags uint8) diff --git a/test/decompiler/reference/jak2/engine/ambient/ambient_REF.gc b/test/decompiler/reference/jak2/engine/ambient/ambient_REF.gc index 745a2b0da4..ca8461557b 100644 --- a/test/decompiler/reference/jak2/engine/ambient/ambient_REF.gc +++ b/test/decompiler/reference/jak2/engine/ambient/ambient_REF.gc @@ -271,6 +271,7 @@ ;; definition for method 10 of type talker (defmethod deactivate ((this talker)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (send-event (handle->process (-> this voicebox)) 'die) (call-parent-method this) (none) @@ -494,7 +495,10 @@ (and (nonzero? (-> self message-id)) (= (get-status *gui-control* (-> self message-id)) (gui-status active)) (or (not (time-elapsed? (-> self state-time) (the-as time-frame (-> self message text-duration)))) - (and (logtest? (-> self message flags) 16) (-> self region) (region-method-9 (-> self region) (target-pos 0))) + (and (logtest? (-> self message flags) 16) + (-> self region) + (point-in-region-debug! (-> self region) (target-pos 0)) + ) ) ) (not (time-elapsed? (-> self state-time) (seconds 0.05))) diff --git a/test/decompiler/reference/jak2/engine/anim/fma-sphere_REF.gc b/test/decompiler/reference/jak2/engine/anim/fma-sphere_REF.gc index 9a1bde417f..27083982fe 100644 --- a/test/decompiler/reference/jak2/engine/anim/fma-sphere_REF.gc +++ b/test/decompiler/reference/jak2/engine/anim/fma-sphere_REF.gc @@ -42,6 +42,7 @@ ;; definition for method 12 of type fma-sphere (defmethod run-logic? ((this fma-sphere)) + "Should this process be run? Checked by execute-process-tree." (or (logtest? *display-scene-control* (scene-controls display-controls)) (and *display-nav-marks* (logtest? (-> this mode) (fma-sphere-mode nav))) (logtest? (-> this mode) (fma-sphere-mode deadly-overlap)) diff --git a/test/decompiler/reference/jak2/engine/anim/joint-h_REF.gc b/test/decompiler/reference/jak2/engine/anim/joint-h_REF.gc index 2c3aaa5236..70045db595 100644 --- a/test/decompiler/reference/jak2/engine/anim/joint-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/anim/joint-h_REF.gc @@ -3,6 +3,8 @@ ;; definition of type joint-control-channel (deftype joint-control-channel (structure) + "A single animation channel that controls a number of joints. +Multiple channels are used to blend animations together." ((parent joint-control) (frame-group art-joint-anim) (frame-num float) @@ -140,6 +142,7 @@ ;; definition of type joint-control (deftype joint-control (basic) + "Every [[process-drawable]] has a [[joint-control]] that handles all the animation channels." ((status joint-control-status) (allocated-length uint8) (active-channels uint8) @@ -250,6 +253,7 @@ ;; definition of type channel-upload-info (deftype channel-upload-info (structure) + "Information about an upload of animation data to a single joint channel." ((fixed joint-anim-compressed-fixed) (fixed-qwc int32) (frame joint-anim-compressed-frame) diff --git a/test/decompiler/reference/jak2/engine/anim/joint-mod-h_REF.gc b/test/decompiler/reference/jak2/engine/anim/joint-mod-h_REF.gc index ba132b8c96..12f7012a16 100644 --- a/test/decompiler/reference/jak2/engine/anim/joint-mod-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/anim/joint-mod-h_REF.gc @@ -3,6 +3,8 @@ ;; definition of type joint-mod (deftype joint-mod (basic) + "Utility to modify a joint transform from code, rather than just getting it from animation. +This is used to make jak look toward an enemy, for example." ((mode joint-mod-mode) (process process-drawable) (joint cspace) @@ -150,6 +152,7 @@ ;; definition (debug) for function joint-mod-debug-draw ;; WARN: Return type mismatch int vs none. (defun-debug joint-mod-debug-draw ((arg0 joint-mod)) + "Debug draw the bone transform for the associated bone of a joint-mod" (add-debug-matrix #t (bucket-id debug-no-zbuf1) (-> arg0 joint bone transform) (meters 2)) 0 (none) @@ -157,6 +160,7 @@ ;; definition for method 12 of type joint-mod (defmethod reset-blend! ((this joint-mod)) + "Set the blend to 0." (set! (-> this blend) 0.0) this ) @@ -248,6 +252,7 @@ ;; definition of type joint-mod-set-local (deftype joint-mod-set-local (basic) + "Override the trans, quat, and scale of the joint transform. The component to override is selected by the flag." ((transform transformq :inline) (set-rotation symbol) (set-scale symbol) @@ -278,6 +283,7 @@ ;; definition for function joint-mod-set-local-callback ;; INFO: Used lq/sq (defun joint-mod-set-local-callback ((arg0 cspace) (arg1 transformq)) + "Callback for joint-mod-rotate-local. See comment on that type." (let ((v1-0 (the-as joint-mod-set-local (-> arg0 param1)))) (cond ((-> v1-0 enable) @@ -328,6 +334,8 @@ ;; definition of type joint-mod-add-local (deftype joint-mod-add-local (basic) + "Add to the trans, rotate the quat, and multiply the scale of the joint transform. The components can be selected by the flag. +Unlike jak 2, this actually multiplies the scale, instead of adding." ((transform transformq :inline) (add-rotation symbol) (add-scale symbol) @@ -357,6 +365,7 @@ ;; definition for function joint-mod-add-local-callback (defun joint-mod-add-local-callback ((arg0 cspace) (arg1 transformq)) + "Callback for joint-mod-add-local. See comment on that type." (let ((s4-0 (the-as joint-mod-add-local (-> arg0 param1)))) (when (-> s4-0 enable) (if (-> s4-0 add-translation) @@ -402,6 +411,8 @@ ;; definition of type joint-mod-set-world (deftype joint-mod-set-world (basic) + "Directly overwrite the _bone_ transform (ignoring the parent entirely). +This does not pay attention to the flags." ((transform transformq :inline) (node-index int32) (enable symbol) @@ -428,6 +439,7 @@ ;; definition for function joint-mod-set-world-callback ;; WARN: Return type mismatch object vs none. (defun joint-mod-set-world-callback ((arg0 cspace) (arg1 transformq)) + "Callback for joint-mod-set-world. See comment on that type." (let ((v1-0 (the-as joint-mod-set-world (-> arg0 param1)))) (if (-> v1-0 enable) (cspace<-transformq! arg0 (-> v1-0 transform)) @@ -456,6 +468,8 @@ ;; definition of type joint-mod-blend-local (deftype joint-mod-blend-local (basic) + "Blend the _joint_ transform between this transform and the animated one. +Then, apply the normal parented transform." ((transform transformq :inline) (blend-transform transformq :inline) (node-index int32) @@ -485,6 +499,7 @@ ;; definition for function joint-mod-blend-local-callback (defun joint-mod-blend-local-callback ((arg0 cspace) (arg1 transformq)) + "Callback for joint-mod-blend-local. See comment on that type." (let ((gp-0 (the-as joint-mod-blend-local (-> arg0 param1)))) (cond ((-> gp-0 enable) @@ -526,6 +541,7 @@ ;; definition of type joint-mod-spinner (deftype joint-mod-spinner (basic) + "Control a joint by just spinning it around an axis." ((spin-axis vector :inline) (angle float) (spin-rate float) @@ -552,31 +568,32 @@ ) ;; definition for function joint-mod-spinner-callback -(defun joint-mod-spinner-callback ((arg0 cspace) (arg1 transformq)) - (let ((gp-0 (the-as joint-mod-spinner (-> arg0 param1)))) +(defun joint-mod-spinner-callback ((bone-cspace cspace) (joint-transform transformq)) + "cspace callback for joint-mod-spinner. Update the cspace's bone from the parent transformq, plus the rotation from this spinner." + (let ((gp-0 (the-as joint-mod-spinner (-> bone-cspace param1)))) (when (-> gp-0 enable) (let ((f30-0 (the float (sar (shl (the int (+ (-> gp-0 angle) (* (-> gp-0 spin-rate) (seconds-per-frame)))) 48) 48)) ) ) - (quaternion-vector-angle! (-> arg1 quat) (-> gp-0 spin-axis) f30-0) + (quaternion-vector-angle! (-> joint-transform quat) (-> gp-0 spin-axis) f30-0) (set! (-> gp-0 angle) f30-0) ) ) ) - (cspace<-parented-transformq-joint! arg0 arg1) + (cspace<-parented-transformq-joint! bone-cspace joint-transform) (none) ) ;; definition for method 0 of type joint-mod-spinner ;; INFO: Used lq/sq -(defmethod new joint-mod-spinner ((allocation symbol) (type-to-make type) (arg0 process-drawable) (arg1 int) (arg2 vector) (arg3 float)) +(defmethod new joint-mod-spinner ((allocation symbol) (type-to-make type) (proc process-drawable) (bone-idx int) (axis vector) (rate float)) (let ((v0-0 (object-new allocation type-to-make (the-as int (-> type-to-make size))))) - (set! (-> v0-0 spin-axis quad) (-> arg2 quad)) - (set! (-> v0-0 spin-rate) arg3) + (set! (-> v0-0 spin-axis quad) (-> axis quad)) + (set! (-> v0-0 spin-rate) rate) (set! (-> v0-0 enable) #t) (set! (-> v0-0 angle) 0.0) - (let ((a0-3 (-> arg0 node-list data arg1))) + (let ((a0-3 (-> proc node-list data bone-idx))) (set! (-> a0-3 param0) joint-mod-spinner-callback) (set! (-> a0-3 param1) v0-0) ) @@ -586,6 +603,7 @@ ;; definition of type joint-mod-blend-world (deftype joint-mod-blend-world (basic) + "Blend the _bone_ transform between this one and the animated one." ((transform transformq :inline) (blend-transform transformq :inline) (blend-flags joint-mod-blend-flags) @@ -618,6 +636,7 @@ ;; definition for function joint-mod-blend-world-callback ;; WARN: Return type mismatch object vs none. (defun joint-mod-blend-world-callback ((arg0 cspace) (arg1 transformq)) + "Callback for joint-mod-blend-local. See comment on that type." (rlet ((vf0 :class vf) (vf4 :class vf) (vf5 :class vf) @@ -737,6 +756,7 @@ ;; definition for function joint-mod-rotate-local-callback (defun joint-mod-rotate-local-callback ((arg0 cspace) (arg1 transformq)) + "Apply an additional rotation to the transform (left side quaternion multiplication" (let ((v1-0 (the-as joint-mod-rotate-local (-> arg0 param1)))) (new 'stack-no-clear 'vector) (if (-> v1-0 enable) diff --git a/test/decompiler/reference/jak2/engine/anim/mspace-h_REF.gc b/test/decompiler/reference/jak2/engine/anim/mspace-h_REF.gc index e355042004..cd0d2e91e0 100644 --- a/test/decompiler/reference/jak2/engine/anim/mspace-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/anim/mspace-h_REF.gc @@ -3,6 +3,8 @@ ;; definition of type joint (deftype joint (basic) + "A joint from an animated skeleton. This defines the graph of the skeleton, and also the bind pose +used for the mesh data. The joints are shared between all instances of the same model." ((name basic) (number int32) (parent joint) @@ -27,6 +29,7 @@ ;; definition of type bone-cache (deftype bone-cache (structure) + "Unused type. Existed in Jak 1, but wasn't used there." ((bone-matrix uint32) (parent-matrix uint32) (dummy uint32) @@ -51,6 +54,9 @@ ;; definition of type bone (deftype bone (structure) + "The location and scale of a bone in an animated skeleton. Each instance of a skeleton +has its own copy of the bones. This data is used for collision checking or other gameplay math, +but, despite the name, isn't directly used in rendering." ((transform matrix :inline) (position vector :inline :overlay-at (-> transform data 12)) (scale vector :inline) @@ -73,6 +79,8 @@ ;; definition of type skeleton (deftype skeleton (inline-array-class) + "Skeleton is an array of bones for the entire character. The bones are stored in an inline array so they can be +easily dma'd to the scratchpad later." ((bones bone :inline :dynamic) ) ) @@ -96,6 +104,8 @@ ;; definition of type cspace (deftype cspace (structure) + "A cspace describes how to control a bone. It contains a reference to the joint, bone, and a callback function. +The callback function is used to take the joint transforms out of the joint animation, then update the bone." ((parent cspace) (joint joint) (joint-num int16) diff --git a/test/decompiler/reference/jak2/engine/collide/collide-cache-h_REF.gc b/test/decompiler/reference/jak2/engine/collide/collide-cache-h_REF.gc index d8bf652b50..eae9548a94 100644 --- a/test/decompiler/reference/jak2/engine/collide/collide-cache-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/collide/collide-cache-h_REF.gc @@ -3,6 +3,8 @@ ;; definition of type collide-puss-sphere (deftype collide-puss-sphere (structure) + "A query sphere from the user for the porbe-using-spheres query. +This is used internally by the collide-cache implementation." ((bsphere sphere :inline) (bbox4w bounding-box4w :inline) ) @@ -23,6 +25,7 @@ ;; definition of type collide-puss-work (deftype collide-puss-work (structure) + "Scratchpad memory map for probe-using-spheres query." ((closest-pt vector :inline) (tri-normal vector :inline) (tri-bbox4w bounding-box4w :inline) @@ -53,6 +56,8 @@ ;; definition of type collide-cache-tri (deftype collide-cache-tri (structure) + "A single triangle inside the collision cache. +Contains a reference back to the source object (like a collide-shape or water-control), and the prim itself." ((vertex vector 3 :inline) (extra-quad uint8 16) (pat pat-surface :overlay-at (-> extra-quad 0)) @@ -84,6 +89,8 @@ ;; definition of type collide-cache-prim (deftype collide-cache-prim (structure) + "A primitive inside the collide-cache. +This can represent a sphere, a triangle mesh, or a group of other primitives within a bounding sphere." ((prim-core collide-prim-core :inline) (extra-quad uint8 16) (ccache collide-cache :overlay-at (-> extra-quad 0)) @@ -126,6 +133,12 @@ ;; definition of type collide-cache (deftype collide-cache (basic) + "The collide-cache is a structure to accelerate collision queries. +In particular, it helps with queries where you don't know what you might hit. +It can detect collision with the background geometry, foreground dynamic collision shapes (spheres and meshes), and water. +To use it, it must first be 'filled' with geometry. Then you can manually inspect the geometry, or use one of the queries. +The supported queries are 'line-sphere' (raycast) and 'spheres' (check if intersecting anything). +It is not useful for ollision queries against a specific foreground object, like 'am I on top of platform X right now?'." ((num-tris int32) (num-tris-u32 uint32 :overlay-at num-tris) (num-prims int32) @@ -183,6 +196,8 @@ ;; definition of type collide-list-item (deftype collide-list-item (structure) + "Entry on the broad-phase collision list. +Can represent instanced collision, as a TIE instance, or a single non-instanced mesh fragment." ((mesh instance-tie) (inst basic) ) @@ -204,6 +219,7 @@ ;; definition of type collide-list (deftype collide-list (structure) + "List of items returned by the broad-phase collision query." ((num-items int32) (items collide-list-item 256 :inline :offset 16) ) diff --git a/test/decompiler/reference/jak2/engine/collide/collide-edge-grab-h_REF.gc b/test/decompiler/reference/jak2/engine/collide/collide-edge-grab-h_REF.gc index 5ca16f1c4f..c1aec46115 100644 --- a/test/decompiler/reference/jak2/engine/collide/collide-edge-grab-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/collide/collide-edge-grab-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type pilot-edge-grab-info (deftype pilot-edge-grab-info (structure) + "Info for edge grabs on zoomers." ((local-pos vector :inline) (local-dir vector :inline) (handle handle) @@ -85,6 +86,7 @@ ;; definition of type collide-edge-tri (deftype collide-edge-tri (structure) + "A triangle involved in edge grab collision." ((ctri collide-cache-tri) (normal vector :inline) ) diff --git a/test/decompiler/reference/jak2/engine/collide/collide-frag-h_REF.gc b/test/decompiler/reference/jak2/engine/collide/collide-frag-h_REF.gc index 5b0f25a135..ac1ceeba6b 100644 --- a/test/decompiler/reference/jak2/engine/collide/collide-frag-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/collide/collide-frag-h_REF.gc @@ -26,6 +26,7 @@ ;; definition of type collide-frag-mesh (deftype collide-frag-mesh (basic) + "Unused Jak 1 background collision mesh fragment." ((packed-data uint32) (pat-array uint32) (strip-data-len uint16) @@ -60,6 +61,7 @@ ;; definition of type collide-fragment (deftype collide-fragment (drawable) + "Unused Jak 1 background collision drawable tree node." ((mesh collide-frag-mesh :offset 8) (collide-new basic :offset 12) ) @@ -82,6 +84,7 @@ ;; definition of type drawable-inline-array-collide-fragment (deftype drawable-inline-array-collide-fragment (drawable-inline-array) + "Unused Jak 1 background collision drawable tree inline-array class." ((data collide-fragment 1 :inline) (pad uint32) ) @@ -104,6 +107,7 @@ ;; definition of type drawable-tree-collide-fragment (deftype drawable-tree-collide-fragment (drawable-tree) + "Unused jak 1 background collision data." () ) diff --git a/test/decompiler/reference/jak2/engine/collide/collide-frag_REF.gc b/test/decompiler/reference/jak2/engine/collide/collide-frag_REF.gc index ba29727f42..c3ba45e438 100644 --- a/test/decompiler/reference/jak2/engine/collide/collide-frag_REF.gc +++ b/test/decompiler/reference/jak2/engine/collide/collide-frag_REF.gc @@ -3,6 +3,7 @@ ;; definition for method 9 of type drawable-tree-collide-fragment (defmethod login ((this drawable-tree-collide-fragment)) + "Initialize the object after it is loaded." this ) @@ -59,6 +60,7 @@ ;; definition for method 9 of type drawable-inline-array-collide-fragment (defmethod login ((this drawable-inline-array-collide-fragment)) + "Initialize the object after it is loaded." this ) diff --git a/test/decompiler/reference/jak2/engine/collide/collide-h_REF.gc b/test/decompiler/reference/jak2/engine/collide/collide-h_REF.gc index e2b8a9e484..ad7a439db7 100644 --- a/test/decompiler/reference/jak2/engine/collide/collide-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/collide/collide-h_REF.gc @@ -3,6 +3,8 @@ ;; definition of type collide-query (deftype collide-query (structure) + "Very general collision-query structure. The meaning is different depending on where it used. +This has both inputs from the user, and collision results." ((best-other-tri collide-tri-result :inline) (best-my-tri collide-tri-result :inline :overlay-at best-other-tri) (ignore-processes process-tree 2) diff --git a/test/decompiler/reference/jak2/engine/collide/collide-mesh-h_REF.gc b/test/decompiler/reference/jak2/engine/collide/collide-mesh-h_REF.gc index 008be8a87f..114da30f6a 100644 --- a/test/decompiler/reference/jak2/engine/collide/collide-mesh-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/collide/collide-mesh-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type collide-tri-result (deftype collide-tri-result (structure) + "A triangle result of a collision." ((vertex vector 3 :inline) (intersect vector :inline) (normal vector :inline) @@ -29,6 +30,7 @@ ;; definition of type collide-mesh-tri (deftype collide-mesh-tri (structure) + "A triangle for foreground collision meshes." ((vertex-index uint8 3) (unused uint8) (pat pat-surface) @@ -52,6 +54,8 @@ ;; definition of type collide-mesh (deftype collide-mesh (basic) + "A collision mesh for foreground objects, +bound to the joint specified by `joint-id`." ((joint-id int32) (num-tris uint32) (num-verts uint32) @@ -87,6 +91,7 @@ ;; definition of type collide-mesh-cache-tri (deftype collide-mesh-cache-tri (structure) + "A triangle stored in the foreground mesh collide cache." ((vertex vector 3 :inline) (normal vector :inline) (bbox4w bounding-box4w :inline) @@ -111,6 +116,7 @@ ;; definition of type collide-mesh-cache-entry (deftype collide-mesh-cache-entry (structure) + "A foreground mesh collide cache entry." ((mat matrix :inline) (tris collide-mesh-cache-tri :inline :dynamic) ) @@ -131,6 +137,7 @@ ;; definition of type collide-mesh-cache (deftype collide-mesh-cache (basic) + "A collide cache for foreground meshes." ((used-size uint32) (max-size uint32) (id uint32) @@ -163,8 +170,9 @@ ;; ERROR: function was not converted to expressions. Cannot decompile. ;; definition for method 10 of type collide-mesh-cache -(defmethod is-id? ((this collide-mesh-cache) (arg0 int)) - (= (-> this id) arg0) +(defmethod is-id? ((this collide-mesh-cache) (id int)) + "Does this cache have the given ID?" + (= (-> this id) id) ) ;; failed to figure out what this is: diff --git a/test/decompiler/reference/jak2/engine/collide/collide-shape-h_REF.gc b/test/decompiler/reference/jak2/engine/collide/collide-shape-h_REF.gc index 641482a89b..6d210aeaf4 100644 --- a/test/decompiler/reference/jak2/engine/collide/collide-shape-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/collide/collide-shape-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type collide-rider (deftype collide-rider (structure) + "Something that rides a moving object." ((rider-handle handle) (sticky-prim collide-shape-prim) (prim-ry float) @@ -27,6 +28,7 @@ ;; definition of type collide-rider-pool (deftype collide-rider-pool (basic) + "A pool containing all the riders of an object." ((alloc-count int32) (riders collide-rider 20 :inline) ) @@ -165,6 +167,7 @@ ;; definition of type collide-prim-core (deftype collide-prim-core (structure) + "Collide primitives use this to store their world sphere and their collision flags." ((world-sphere vector :inline) (collide-as collide-spec :offset 16) (collide-with collide-spec) @@ -195,6 +198,7 @@ ;; definition of type collide-shape-prim (deftype collide-shape-prim (basic) + "Base class for collide primitives." ((cshape collide-shape) (prim-id uint32) (transform-index int8) @@ -473,6 +477,7 @@ ;; definition of type collide-shape-prim-sphere (deftype collide-shape-prim-sphere (collide-shape-prim) + "A sphere primitive for collide shapes." ((pat pat-surface :overlay-at (-> specific 0)) (nav-radius float :overlay-at (-> specific 4)) ) @@ -731,6 +736,7 @@ ;; definition of type collide-shape-prim-mesh (deftype collide-shape-prim-mesh (collide-shape-prim) + "A mesh primitive for collide shapes." ((mesh collide-mesh :overlay-at (-> specific 0)) (mesh-id int32 :overlay-at (-> specific 4)) (mesh-cache-id uint32 :overlay-at (-> specific 8)) @@ -993,6 +999,7 @@ ;; definition of type collide-shape-prim-group (deftype collide-shape-prim-group (collide-shape-prim) + "A group of collide primitives." ((num-children uint8 :overlay-at (-> specific 0)) (num-alloc-children uint8 :overlay-at (-> specific 1)) (child (inline-array collide-shape-prim) :overlay-at (-> specific 4)) @@ -1253,6 +1260,8 @@ ;; definition of type collide-shape (deftype collide-shape (trsqv) + "The parent of all of an object's collide primitives. +Most [[process-drawable]]s have a [[collide-shape]] that represents their root transform." ((actor-hash-index int16 :offset 12) (process process-drawable) (max-iteration-count uint8) @@ -1549,6 +1558,7 @@ ;; definition of type collide-shape-moving (deftype collide-shape-moving (collide-shape) + "A [[collide-shape]] for moving objects." ((rider-time time-frame) (rider-last-move vector :inline) (trans-old vector :inline) diff --git a/test/decompiler/reference/jak2/engine/collide/collide-touch-h_REF.gc b/test/decompiler/reference/jak2/engine/collide/collide-touch-h_REF.gc index 9c094c0a63..6a482f6d05 100644 --- a/test/decompiler/reference/jak2/engine/collide/collide-touch-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/collide/collide-touch-h_REF.gc @@ -3,6 +3,8 @@ ;; definition of type touching-prim (deftype touching-prim (structure) + "A collide primitive that's touching another. +Potentially also stores the triangle that is involved." ((cprim collide-shape-prim) (has-tri? symbol) (tri collide-tri-result :inline) @@ -25,6 +27,7 @@ ;; definition of type touching-prims-entry (deftype touching-prims-entry (structure) + "A record of two primitives touching." ((next touching-prims-entry) (prev touching-prims-entry) (allocated? symbol) @@ -58,6 +61,7 @@ ;; definition of type touching-prims-entry-pool (deftype touching-prims-entry-pool (structure) + "A pool of up to 64 touching prim records." ((head touching-prims-entry) (nodes touching-prims-entry 64 :inline) ) @@ -86,20 +90,20 @@ ;; definition for method 11 of type touching-prims-entry-pool ;; WARN: Return type mismatch int vs none. (defmethod init-list! ((this touching-prims-entry-pool)) - (let ((v1-0 (the-as touching-prims-entry #f))) - (let ((a1-0 (the-as touching-prims-entry (-> this nodes)))) - (set! (-> this head) a1-0) + (let ((prev (the-as touching-prims-entry #f))) + (let ((current (the-as touching-prims-entry (-> this nodes)))) + (set! (-> this head) current) (countdown (a0-1 64) - (set! (-> a1-0 prev) v1-0) - (let ((a2-0 (&+ a1-0 240))) - (set! (-> a1-0 next) (the-as touching-prims-entry a2-0)) - (set! (-> a1-0 allocated?) #f) - (set! v1-0 a1-0) - (set! a1-0 (the-as touching-prims-entry a2-0)) + (set! (-> current prev) prev) + (let ((next (&+ current 240))) + (set! (-> current next) (the-as touching-prims-entry next)) + (set! (-> current allocated?) #f) + (set! prev current) + (set! current (the-as touching-prims-entry next)) ) ) ) - (set! (-> v1-0 next) #f) + (set! (-> prev next) #f) ) 0 (none) @@ -121,6 +125,8 @@ ;; definition of type touching-shapes-entry (deftype touching-shapes-entry (structure) + "A record of two collide shapes touching, +storing a record of the primitives involved." ((cshape1 collide-shape) (cshape2 collide-shape) (resolve-u int8) @@ -158,6 +164,7 @@ ;; definition of type touching-list (deftype touching-list (structure) + "Contains a record of touching collide shape pairs." ((num-touching-shapes int32) (resolve-u int8) (touching-shapes touching-shapes-entry 32 :inline) diff --git a/test/decompiler/reference/jak2/engine/common_objs/collectables_REF.gc b/test/decompiler/reference/jak2/engine/common_objs/collectables_REF.gc index 8400021453..0c161301a5 100644 --- a/test/decompiler/reference/jak2/engine/common_objs/collectables_REF.gc +++ b/test/decompiler/reference/jak2/engine/common_objs/collectables_REF.gc @@ -1531,6 +1531,7 @@ This commonly includes things such as: ;; definition for method 10 of type eco-pill (defmethod deactivate ((this eco-pill)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (+! (-> *game-info* live-eco-pill-count) -1) ((method-of-type collectable deactivate) this) (none) @@ -1589,6 +1590,7 @@ This commonly includes things such as: ;; definition for method 12 of type money (defmethod run-logic? ((this money)) + "Should this process be run? Checked by execute-process-tree." (or (not (logtest? (-> this mask) (process-mask actor-pause))) (or (and (nonzero? (-> this draw)) (logtest? (-> this draw status) (draw-control-status on-screen)) @@ -1604,6 +1606,7 @@ This commonly includes things such as: ;; definition for method 10 of type money (defmethod deactivate ((this money)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (when (and (-> this next-state) (= (-> this next-state name) 'pickup)) (case (-> this pickup-type) (((pickup-type gem)) @@ -1849,6 +1852,7 @@ This commonly includes things such as: ;; definition for method 10 of type gem (defmethod deactivate ((this gem)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (+! (-> *game-info* live-gem-count) -1) (call-parent-method this) (none) diff --git a/test/decompiler/reference/jak2/engine/common_objs/generic-obs-h_REF.gc b/test/decompiler/reference/jak2/engine/common_objs/generic-obs-h_REF.gc index 11d18cfbff..cc5f238fc7 100644 --- a/test/decompiler/reference/jak2/engine/common_objs/generic-obs-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/common_objs/generic-obs-h_REF.gc @@ -67,6 +67,7 @@ ;; definition of type part-spawner (deftype part-spawner (process) + "A process that spawns a specified particle group." ((root trsqv) (part sparticle-launch-control) (sound ambient-sound) diff --git a/test/decompiler/reference/jak2/engine/common_objs/generic-obs_REF.gc b/test/decompiler/reference/jak2/engine/common_objs/generic-obs_REF.gc index 6ae90384f4..e5ba29499f 100644 --- a/test/decompiler/reference/jak2/engine/common_objs/generic-obs_REF.gc +++ b/test/decompiler/reference/jak2/engine/common_objs/generic-obs_REF.gc @@ -1306,6 +1306,7 @@ This commonly includes things such as: ;; definition for method 10 of type part-tracker (defmethod deactivate ((this part-tracker)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this part)) (kill-and-free-particles (-> this part)) ) @@ -2077,6 +2078,7 @@ This commonly includes things such as: ;; definition for method 10 of type part-spawner (defmethod deactivate ((this part-spawner)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this part)) (kill-and-free-particles (-> this part)) ) diff --git a/test/decompiler/reference/jak2/engine/common_objs/projectile-h_REF.gc b/test/decompiler/reference/jak2/engine/common_objs/projectile-h_REF.gc index 85bdce6c48..09428f11c0 100644 --- a/test/decompiler/reference/jak2/engine/common_objs/projectile-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/common_objs/projectile-h_REF.gc @@ -138,6 +138,7 @@ ;; definition for function spawn-projectile (defun spawn-projectile ((arg0 type) (arg1 projectile-init-by-other-params) (arg2 process-tree) (arg3 dead-pool)) + "Create a new process for a projectile of the given type." (let ((s4-0 (get-process arg3 arg0 #x4000))) (when s4-0 (let ((t9-1 (method-of-type process activate))) diff --git a/test/decompiler/reference/jak2/engine/common_objs/projectile_REF.gc b/test/decompiler/reference/jak2/engine/common_objs/projectile_REF.gc index e4cf7be3ac..4a5bd2ae5e 100644 --- a/test/decompiler/reference/jak2/engine/common_objs/projectile_REF.gc +++ b/test/decompiler/reference/jak2/engine/common_objs/projectile_REF.gc @@ -470,6 +470,7 @@ If we've met or exceeded the projectiles maximum allowed hits, switch to the [[p ;; definition for method 10 of type projectile (defmethod deactivate ((this projectile)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (stop-sound! this) ((method-of-type process-drawable deactivate) this) (none) diff --git a/test/decompiler/reference/jak2/engine/data/art-h_REF.gc b/test/decompiler/reference/jak2/engine/data/art-h_REF.gc index 21d6964e2b..f45db8dfc1 100644 --- a/test/decompiler/reference/jak2/engine/data/art-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/data/art-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type joint-anim (deftype joint-anim (basic) + "Base class for all joint animations. These are animations that store joint transforms." ((name string) (number int16) (length int16) @@ -25,12 +26,14 @@ ;; definition of type joint-anim-matrix (deftype joint-anim-matrix (joint-anim) + "Joint animation which stores matrices directly. Not used." ((data matrix :inline :dynamic :offset 16) ) ) ;; definition of type joint-anim-transformq (deftype joint-anim-transformq (joint-anim) + "Joint animation which stores transformq's directly. Not used." ((data transformq :inline :dynamic :offset 16) ) ) @@ -55,6 +58,7 @@ ;; definition of type joint-anim-drawable (deftype joint-anim-drawable (joint-anim) + "Mysterious unused joint animation type." ((data drawable :dynamic) ) ) @@ -76,6 +80,10 @@ ;; definition of type joint-anim-frame (deftype joint-anim-frame (structure) + "Frame containing all joint transforms. Note that there are two special frames: align and prejoint. +The 'align' frame is used for the complicated animation alignment system, which allows the animation to move +a character, among other things. The prejoint is just the root of the skeleton. +The remaining transformq's are the joint transforms you'd expect." ((matrices matrix 2 :inline) (data transformq :inline :dynamic) ) @@ -110,6 +118,7 @@ ;; definition of type joint-anim-compressed-hdr (deftype joint-anim-compressed-hdr (structure) + "Header for the compressed joint animation format." ((control-bits uint32 14) (num-joints uint32) (matrix-bits uint32) @@ -214,6 +223,8 @@ ;; definition of type art (deftype art (basic) + "Base class for anything considered `art`. This is typically foreground model data. +This can be either an art container containing more arts, or an actual art thing (art-element)." ((name string :offset 8) (length int32) (extra res-lump) @@ -242,6 +253,7 @@ ;; definition of type art-element (deftype art-element (art) + "Base class Art which is not a container of more art." ((pad uint8 12) ) ) @@ -262,12 +274,14 @@ ;; definition of type art-mesh-anim (deftype art-mesh-anim (art-element) + "An unused mesh animation." ((data basic :dynamic) ) ) ;; definition of type art-joint-anim (deftype art-joint-anim (art-element) + "Art for a joint animation. Also contains the eye animation." ((speed float :overlay-at (-> pad 0)) (artist-base float :overlay-at (-> pad 4)) (artist-step float :overlay-at (-> pad 8)) @@ -315,18 +329,22 @@ ;; definition of type art-mesh-geo (deftype art-mesh-geo (art-element) + "Unused art format for a mesh. This might have been for the renderer that came before merc." ((data basic :dynamic) ) ) ;; definition of type art-joint-geo (deftype art-joint-geo (art-element) + "Collection of joints for an actor." ((data joint :dynamic) ) ) ;; definition of type art-joint-anim-manager-slot (deftype art-joint-anim-manager-slot (structure) + "Record for an animation which is additionally compressed with LZO compression over the entire animation. +This is used for short, commonly used animations that always remain in RAM." ((anim art-joint-anim) (comp-data uint32) (time-stamp uint64) @@ -349,6 +367,7 @@ ;; definition of type art-joint-anim-manager (deftype art-joint-anim-manager (basic) + "Cache for LZO decompression of animations." ((kheap kheap :inline) (free-index int32) (slot art-joint-anim-manager-slot 64 :inline) @@ -399,6 +418,8 @@ ;; definition of type skeleton-group (deftype skeleton-group (art-group) + "Unlike other art types, the skeleton-groups are defined in GOAL code. +This stores settings like the name of the art-group, shadow/level-of-detail settings, etc." ((art-group-name string) (jgeo int32) (janim int32) @@ -456,6 +477,7 @@ ;; definition of type lod-group (deftype lod-group (structure) + "A single level of detail mesh." ((geo merc-ctrl) (dist meters) ) @@ -477,6 +499,7 @@ ;; definition of type lod-set (deftype lod-set (structure) + "All the different level-of-detail meshes for an actor." ((lod lod-group 6 :inline) (max-lod int8) ) @@ -500,6 +523,8 @@ ;; definition of type draw-control (deftype draw-control (basic) + "The draw-control is a collection of all the stuff that the foreground rendering system needs to draw something. +Each process-drawable has a draw-control." ((process process-drawable) (status draw-control-status) (data-format draw-control-data-format) diff --git a/test/decompiler/reference/jak2/engine/debug/editable-player_REF.gc b/test/decompiler/reference/jak2/engine/debug/editable-player_REF.gc index 83961e6ba3..57faf94014 100644 --- a/test/decompiler/reference/jak2/engine/debug/editable-player_REF.gc +++ b/test/decompiler/reference/jak2/engine/debug/editable-player_REF.gc @@ -1425,6 +1425,7 @@ ;; definition for method 10 of type editable-player (defmethod deactivate ((this editable-player)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (dotimes (v1-0 (-> *level* length)) (let ((a1-3 (-> *level* level v1-0))) (if (= (-> a1-3 status) 'active) diff --git a/test/decompiler/reference/jak2/engine/debug/nav/nav-graph-editor_REF.gc b/test/decompiler/reference/jak2/engine/debug/nav/nav-graph-editor_REF.gc index 6b4b24f05c..10fba8472e 100644 --- a/test/decompiler/reference/jak2/engine/debug/nav/nav-graph-editor_REF.gc +++ b/test/decompiler/reference/jak2/engine/debug/nav/nav-graph-editor_REF.gc @@ -211,6 +211,7 @@ ;; definition for method 10 of type nav-graph-editor (defmethod deactivate ((this nav-graph-editor)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (set! *nav-graph-editor* (the-as (pointer nav-graph-editor) #f)) ((method-of-type process deactivate) this) (none) diff --git a/test/decompiler/reference/jak2/engine/debug/part-tester_REF.gc b/test/decompiler/reference/jak2/engine/debug/part-tester_REF.gc index 31509c8beb..20e05f5234 100644 --- a/test/decompiler/reference/jak2/engine/debug/part-tester_REF.gc +++ b/test/decompiler/reference/jak2/engine/debug/part-tester_REF.gc @@ -45,6 +45,7 @@ ;; definition for method 10 of type part-tester (defmethod deactivate ((this part-tester)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this part)) (kill-and-free-particles (-> this part)) ) diff --git a/test/decompiler/reference/jak2/engine/debug/stats-h_REF.gc b/test/decompiler/reference/jak2/engine/debug/stats-h_REF.gc index a7ede37f20..d612c60f51 100644 --- a/test/decompiler/reference/jak2/engine/debug/stats-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/debug/stats-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type tr-stat (deftype tr-stat (structure) + "triangle stats for a renderer. This can apply to a lot of different renderer types." ((groups uint16) (fragments uint16) (tris uint32) @@ -31,6 +32,7 @@ ;; definition of type merc-global-stats (deftype merc-global-stats (structure) + "Triangle stats for all merc renderers." ((merc tr-stat :inline) (emerc tr-stat :inline) (mercneric tr-stat :inline) @@ -53,6 +55,8 @@ ;; definition of type perf-stat (deftype perf-stat (structure) + "Performance statistics for a single 'bucket' or category. Unlike the more general profile-bars, +this records statistics like cache hits/instruction counts." ((frame-number uint32) (count uint32) (cycles uint32) @@ -265,6 +269,7 @@ ;; definition of type perf-stat-array (deftype perf-stat-array (inline-array-class) + "Array of all stats for all buckets." ((data perf-stat :inline :dynamic) ) ) diff --git a/test/decompiler/reference/jak2/engine/dma/dma-bucket_REF.gc b/test/decompiler/reference/jak2/engine/dma/dma-bucket_REF.gc index 7828f146d3..3bb16815b5 100644 --- a/test/decompiler/reference/jak2/engine/dma/dma-bucket_REF.gc +++ b/test/decompiler/reference/jak2/engine/dma/dma-bucket_REF.gc @@ -3,17 +3,18 @@ ;; definition for function dma-buffer-add-buckets ;; WARN: Return type mismatch pointer vs (inline-array dma-bucket). -(defun dma-buffer-add-buckets ((arg0 dma-buffer) (arg1 int)) - (let ((v0-0 (-> arg0 base))) +(defun dma-buffer-add-buckets ((dma-buf dma-buffer) (bucket-count int)) + "Initialize an array of dma-buckets in a DMA buffer." + (let ((v0-0 (-> dma-buf base))) (let ((v1-0 (the-as object v0-0))) - (dotimes (a2-0 arg1) + (dotimes (a2-0 bucket-count) (set! (-> (the-as dma-bucket v1-0) tag) (new 'static 'dma-tag :id (dma-tag-id next) :addr (the-as int (&+ (the-as pointer v1-0) 16))) ) (set! (-> (the-as dma-bucket v1-0) last) (the-as (pointer dma-tag) v1-0)) (set! v1-0 (&+ (the-as pointer v1-0) 16)) ) - (set! (-> arg0 base) (the-as pointer v1-0)) + (set! (-> dma-buf base) (the-as pointer v1-0)) ) (the-as (inline-array dma-bucket) v0-0) ) @@ -22,6 +23,7 @@ ;; definition for function dma-buffer-patch-buckets ;; WARN: Return type mismatch object vs (inline-array dma-bucket). (defun dma-buffer-patch-buckets ((arg0 (inline-array dma-bucket)) (arg1 int)) + "Patch together DMA buckets after they have been filled." (when (nonzero? arg0) (dotimes (v1-1 arg1) (cond @@ -51,12 +53,17 @@ ) ;; definition for function dma-bucket-insert-tag -(defun dma-bucket-insert-tag ((arg0 (inline-array dma-bucket)) (arg1 bucket-id) (arg2 pointer) (arg3 (pointer dma-tag))) - (let ((v1-1 (-> arg0 arg1))) - (set! (-> (the-as dma-bucket (-> v1-1 last)) next) (the-as uint arg2)) - (set! (-> v1-1 last) arg3) +(defun dma-bucket-insert-tag ((buckets (inline-array dma-bucket)) + (bucket bucket-id) + (start-tag pointer) + (end-tag-to-patch (pointer dma-tag)) + ) + "Add a dma chain to the bucket." + (let ((v1-1 (-> buckets bucket))) + (set! (-> (the-as dma-bucket (-> v1-1 last)) next) (the-as uint start-tag)) + (set! (-> v1-1 last) end-tag-to-patch) ) - arg2 + start-tag ) ;; failed to figure out what this is: diff --git a/test/decompiler/reference/jak2/engine/dma/dma-buffer_REF.gc b/test/decompiler/reference/jak2/engine/dma/dma-buffer_REF.gc index 3a739384c3..f98dd2b8a6 100644 --- a/test/decompiler/reference/jak2/engine/dma/dma-buffer_REF.gc +++ b/test/decompiler/reference/jak2/engine/dma/dma-buffer_REF.gc @@ -3,6 +3,7 @@ ;; definition of type dma-packet (deftype dma-packet (structure) + "The header for a DMA transfer, containing an DMA tag, and VIF tags." ((dma dma-tag) (vif0 vif-tag) (vif1 vif-tag) @@ -28,6 +29,7 @@ ;; definition of type dma-packet-array (deftype dma-packet-array (inline-array-class) + "Unused dma array. Unclear how it should be used." ((data dma-packet :inline :dynamic) ) ) @@ -51,6 +53,7 @@ ;; definition of type dma-gif (deftype dma-gif (structure) + "Believed unused GIF header type." ((gif uint64 2) (quad uint128 :overlay-at (-> gif 0)) (gif0 uint64 :overlay-at (-> gif 0)) @@ -74,6 +77,7 @@ ;; definition of type dma-gif-packet (deftype dma-gif-packet (structure) + "The header for a DMA transfer that goes directly to GIF, containing DMA, VIF, GIF tags." ((dma-vif dma-packet :inline) (gif uint64 2) (gif0 uint64 :overlay-at (-> gif 0)) @@ -98,6 +102,7 @@ ;; definition of type dma-buffer (deftype dma-buffer (basic) + "A buffer for DMA data." ((allocated-length int32) (base pointer) (end pointer) @@ -134,10 +139,11 @@ ) ;; definition for function dma-buffer-inplace-new -(defun dma-buffer-inplace-new ((arg0 dma-buffer) (arg1 int)) - (set! (-> arg0 base) (-> arg0 data)) - (set! (-> arg0 allocated-length) arg1) - arg0 +(defun dma-buffer-inplace-new ((dma-buff dma-buffer) (size-bytes int)) + "Create a dma-buffer in-place. Does not set the type of the dma-buffer object." + (set! (-> dma-buff base) (-> dma-buff data)) + (set! (-> dma-buff allocated-length) size-bytes) + dma-buff ) ;; definition for method 4 of type dma-buffer @@ -151,13 +157,15 @@ ) ;; definition for function dma-buffer-length -(defun dma-buffer-length ((arg0 dma-buffer)) - (shr (+ (&- (-> arg0 base) (the-as uint (-> arg0 data))) 15) 4) +(defun dma-buffer-length ((dma-buf dma-buffer)) + "Get length used in quadwords, rounded up." + (shr (+ (&- (-> dma-buf base) (the-as uint (-> dma-buf data))) 15) 4) ) ;; definition for function dma-buffer-free -(defun dma-buffer-free ((arg0 dma-buffer)) - (shr (+ (&- (-> arg0 end) (the-as uint (-> arg0 base))) 15) 4) +(defun dma-buffer-free ((dma-buf dma-buffer)) + "Get the number of free quadwords between base and end pointers." + (shr (+ (&- (-> dma-buf end) (the-as uint (-> dma-buf base))) 15) 4) ) ;; definition for function dma-buffer-add-vu-function @@ -188,21 +196,23 @@ ) ;; definition for function dma-buffer-send -(defun dma-buffer-send ((arg0 dma-bank) (arg1 dma-buffer)) - (when (< (-> arg1 allocated-length) (&- (-> arg1 base) (the-as uint (-> arg1 data)))) +(defun dma-buffer-send ((chan dma-bank) (buf dma-buffer)) + "Send the DMA buffer! DOES NOT TRANSFER TAG, you probably want dma-buffer-send-chain instead." + (when (< (-> buf allocated-length) (&- (-> buf base) (the-as uint (-> buf data)))) (crash!) 0 ) - (dma-send arg0 (the-as uint (-> arg1 data)) (the-as uint (dma-buffer-length arg1))) + (dma-send chan (the-as uint (-> buf data)) (the-as uint (dma-buffer-length buf))) (none) ) ;; definition for function dma-buffer-send-chain -(defun dma-buffer-send-chain ((arg0 dma-bank-source) (arg1 dma-buffer)) - (when (< (-> arg1 allocated-length) (&- (-> arg1 base) (the-as uint (-> arg1 data)))) +(defun dma-buffer-send-chain ((chan dma-bank-source) (buf dma-buffer)) + "Send the DMA buffer! Sends the tags, so this is suitable for the main graphics chain." + (when (< (-> buf allocated-length) (&- (-> buf base) (the-as uint (-> buf data)))) (crash!) 0 ) - (dma-send-chain arg0 (the-as uint (-> arg1 data))) + (dma-send-chain chan (the-as uint (-> buf data))) (none) ) diff --git a/test/decompiler/reference/jak2/engine/dma/dma-disasm_REF.gc b/test/decompiler/reference/jak2/engine/dma/dma-disasm_REF.gc index 58b71a8d59..2412765ae8 100644 --- a/test/decompiler/reference/jak2/engine/dma/dma-disasm_REF.gc +++ b/test/decompiler/reference/jak2/engine/dma/dma-disasm_REF.gc @@ -200,6 +200,7 @@ ;; definition for function disasm-vif-details (defun disasm-vif-details ((arg0 symbol) (arg1 (pointer uint8)) (arg2 vif-cmd) (arg3 int)) + "Disassemble the data stored in a vif unpack." (let ((s4-0 arg3)) (cond ((= arg2 (vif-cmd unpack-v4-8)) @@ -308,6 +309,7 @@ ;; definition for function disasm-vif-tag ;; INFO: Used lq/sq (defun disasm-vif-tag ((arg0 (pointer vif-tag)) (arg1 int) (arg2 symbol) (arg3 symbol)) + "Disassemble vif tag, and possibly the associated data." (local-vars (sv-16 vif-cmd) (sv-32 (pointer vif-tag)) (sv-48 int) (sv-64 vif-unpack-imm)) (let ((gp-0 0)) (while (< gp-0 (* arg1 4)) @@ -445,12 +447,13 @@ ;; definition for function disasm-dma-tag ;; WARN: Return type mismatch object vs none. -(defun disasm-dma-tag ((arg0 dma-tag) (arg1 symbol)) - (format arg1 "(dma-tag ") +(defun disasm-dma-tag ((tag dma-tag) (format-dest symbol)) + "Disassemble just the 64-byte dma tag" + (format format-dest "(dma-tag ") (let ((t9-1 format) - (a0-2 arg1) + (a0-2 format-dest) (a1-2 "~s") - (v1-1 (-> arg0 id)) + (v1-1 (-> tag id)) ) (t9-1 a0-2 a1-2 (cond ((= v1-1 (dma-tag-id refe)) @@ -483,22 +486,22 @@ ) ) ) - (if (> (-> arg0 addr) 0) - (format arg1 " :addr #x~8x" (-> arg0 addr)) + (if (> (-> tag addr) 0) + (format format-dest " :addr #x~8x" (-> tag addr)) ) - (if (> (-> arg0 qwc) 0) - (format arg1 " :qwc ~d" (-> arg0 qwc)) + (if (> (-> tag qwc) 0) + (format format-dest " :qwc ~d" (-> tag qwc)) ) - (if (> (-> arg0 spr) 0) - (format arg1 " :spr ~d" (-> arg0 spr)) + (if (> (-> tag spr) 0) + (format format-dest " :spr ~d" (-> tag spr)) ) - (if (> (-> arg0 irq) 0) - (format arg1 " :irq ~d" (-> arg0 irq)) + (if (> (-> tag irq) 0) + (format format-dest " :irq ~d" (-> tag irq)) ) - (if (> (-> arg0 pce) 0) - (format arg1 " :pce ~d" (-> arg0 pce)) + (if (> (-> tag pce) 0) + (format format-dest " :pce ~d" (-> tag pce)) ) - (format arg1 ")~%") + (format format-dest ")~%") (none) ) @@ -509,6 +512,10 @@ ;; WARN: Check prologue - tricky store of a0 ;; INFO: Used lq/sq (defun disasm-dma-list ((arg0 dma-packet) (arg1 symbol) (arg2 symbol) (arg3 symbol) (arg4 int)) + "Print out an entire DMA list. +If mode is #t, print vif tags too. If mode is 'details, also print data unpacked by vif-tags. +If verbose is #t, print out the addresses of each tag, and total size statistics. +If expected size is negative, it is ignored. Otherwise, only disassemble this much dma data." (local-vars (sv-16 object) (sv-32 dma-packet) diff --git a/test/decompiler/reference/jak2/engine/dma/dma-h_REF.gc b/test/decompiler/reference/jak2/engine/dma/dma-h_REF.gc index 23c1167dbc..3e9d457b33 100644 --- a/test/decompiler/reference/jak2/engine/dma/dma-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/dma/dma-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type dma-chcr (deftype dma-chcr (uint32) + "Memory mapped DMA channel control register. Typically used to start and check on DMA transfer." ((dir uint8 :offset 0 :size 1) (mod uint8 :offset 2 :size 2) (asp uint8 :offset 4 :size 2) @@ -33,6 +34,7 @@ ;; definition of type dma-bank (deftype dma-bank (structure) + "Bank of memory mapped DMA registers for a single channel. Used to control DMA." ((chcr dma-chcr :offset 0) (madr uint32 :offset 16) (qwc uint32 :offset 32) @@ -55,6 +57,7 @@ ;; definition of type dma-bank-source (deftype dma-bank-source (dma-bank) + "DMA channel registers for a DMA channel supporting source-chain." ((tadr uint32 :offset 48) ) ) @@ -76,6 +79,7 @@ ;; definition of type dma-bank-vif (deftype dma-bank-vif (dma-bank-source) + "DMA channel registers for a DMA channel with call/ret stack." ((as0 uint32 :offset 64) (as1 uint32 :offset 80) ) @@ -100,6 +104,7 @@ ;; definition of type dma-bank-spr (deftype dma-bank-spr (dma-bank-source) + "DMA channel registers for a DMA channel supporting scratchpad transfer." ((sadr uint32 :offset 128) ) ) @@ -122,6 +127,7 @@ ;; definition of type dma-ctrl (deftype dma-ctrl (uint32) + "Main DMA control register, shared for all channels." ((dmae uint8 :offset 0 :size 1) (rele uint8 :offset 1 :size 1) (mfd uint8 :offset 2 :size 2) @@ -146,6 +152,7 @@ ;; definition of type dma-bank-control (deftype dma-bank-control (structure) + "Memory mapping for shared DMA registers." ((ctrl dma-ctrl :offset 0) (stat uint32 :offset 16) (pcr uint32 :offset 32) @@ -180,6 +187,7 @@ ;; definition of type vu-code-block (deftype vu-code-block (basic) + "Unused type for some VU code. vu-function is used instead." ((name basic) (code uint32) (size int32) @@ -209,6 +217,7 @@ ;; definition of type dma-tag (deftype dma-tag (uint64) + "The 64-bit tag used by the DMA system." ((qwc uint16 :offset 0 :size 16) (pce uint8 :offset 26 :size 2) (id dma-tag-id :offset 28 :size 3) @@ -237,6 +246,7 @@ ;; definition of type dma-bucket (deftype dma-bucket (structure) + "A linked list of DMA data, typically all in the same category. Used to organize the full DMA chain." ((tag dma-tag) (last (pointer dma-tag)) (dummy uint32) @@ -288,6 +298,7 @@ ;; definition of type vif-stcycl-imm (deftype vif-stcycl-imm (uint16) + "The imm field of a VIF code using STCYCL, which adjusts the pattern for storing data." ((cl uint8 :offset 0 :size 8) (wl uint8 :offset 8 :size 8) ) @@ -295,6 +306,7 @@ ;; definition of type vif-unpack-imm (deftype vif-unpack-imm (uint16) + "The imm field of a VIF code using UNPACK, which transfers data to VU memory." ((addr uint16 :offset 0 :size 10) (usn uint8 :offset 14 :size 1) (flg uint8 :offset 15 :size 1) @@ -303,6 +315,7 @@ ;; definition of type vif-tag (deftype vif-tag (uint32) + "A tag consumed by the VIF, which accepts DMA data." ((imm uint16 :offset 0 :size 16) (num uint8 :offset 16 :size 8) (cmd vif-cmd :offset 24 :size 7) diff --git a/test/decompiler/reference/jak2/engine/draw/draw-node-h_REF.gc b/test/decompiler/reference/jak2/engine/draw/draw-node-h_REF.gc index a27f573e80..6d55d1a90b 100644 --- a/test/decompiler/reference/jak2/engine/draw/draw-node-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/draw/draw-node-h_REF.gc @@ -3,6 +3,15 @@ ;; definition of type draw-node (deftype draw-node (drawable) + "Node in a bounding volume heirarchy. This is a base class, and there are no children. +The child is a pointer to the start of inline array of drawables (note: not a drawable-inline-array, literally a bunch of plain drawables) +The size of this array is child-count. The type is either more draw-nodes, or, some other drawable like tfragment, depending on the flags. +Different renderers have different restrictions on the tree structure, like max child count, or if all children have the same depth. +Generally, tfrag/collide use a very rigid equal depth, max 8 children rule, but with shrub, anything goes. +This is a very awkward data structure to traverse, but it is designed for fast view frustum culling. +Note that there can be multiple ways to reach drawables in here in some cases - for example you can follow +this tree, or check one of the depth arrays found in tfrag. +" ((child-count uint8 :offset 6) (flags uint8 :offset 7) (child drawable :offset 8) @@ -36,6 +45,8 @@ ;; definition of type draw-node-dma (deftype draw-node-dma (structure) + "DMA buffer layout for draw node culling routine, which copies draw-nodes directly to scratchpad in bulk. +This would not work with the memory layout of shrub." ((banka draw-node 32 :inline) (bankb draw-node 32 :inline) ) diff --git a/test/decompiler/reference/jak2/engine/draw/drawable-actor-h_REF.gc b/test/decompiler/reference/jak2/engine/draw/drawable-actor-h_REF.gc index 0e8c9e727e..dbe5d61739 100644 --- a/test/decompiler/reference/jak2/engine/draw/drawable-actor-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/draw/drawable-actor-h_REF.gc @@ -3,6 +3,9 @@ ;; definition of type drawable-actor (deftype drawable-actor (drawable) + "Wrapper around an entity-actor to put it in the drawable system. +Note that this is never used to actually draw actors - it is just used as a list of all entity-actors +for the entity/birth system." ((actor entity-actor :offset 8) ) ) @@ -23,11 +26,13 @@ ;; definition of type drawable-tree-actor (deftype drawable-tree-actor (drawable-tree) + "Adapater for putting the actors in the tree-array." () ) ;; definition of type drawable-inline-array-actor (deftype drawable-inline-array-actor (drawable-inline-array) + "Array of drawable-actors." ((data drawable-actor 1 :inline) (pad uint8 4) ) diff --git a/test/decompiler/reference/jak2/engine/draw/drawable-group-h_REF.gc b/test/decompiler/reference/jak2/engine/draw/drawable-group-h_REF.gc index 56a6953c4b..0b7e0c3533 100644 --- a/test/decompiler/reference/jak2/engine/draw/drawable-group-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/draw/drawable-group-h_REF.gc @@ -3,6 +3,8 @@ ;; definition of type drawable-group (deftype drawable-group (drawable) + "Base class for an array of references to other drawables. +These are typically used for very high-level organization of drawable." ((length int16 :offset 6) (data drawable :dynamic) ) diff --git a/test/decompiler/reference/jak2/engine/draw/drawable-group_REF.gc b/test/decompiler/reference/jak2/engine/draw/drawable-group_REF.gc index 26f988dc42..6a51c54fc3 100644 --- a/test/decompiler/reference/jak2/engine/draw/drawable-group_REF.gc +++ b/test/decompiler/reference/jak2/engine/draw/drawable-group_REF.gc @@ -48,6 +48,7 @@ ;; definition for method 9 of type drawable-group (defmethod login ((this drawable-group)) + "Initialize the object after it is loaded." (dotimes (idx (-> this length)) (login (-> this data idx)) ) diff --git a/test/decompiler/reference/jak2/engine/draw/drawable-h_REF.gc b/test/decompiler/reference/jak2/engine/draw/drawable-h_REF.gc index 198bbf1b8e..2fc6b8c37f 100644 --- a/test/decompiler/reference/jak2/engine/draw/drawable-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/draw/drawable-h_REF.gc @@ -3,6 +3,12 @@ ;; definition of type drawable (deftype drawable (basic) + "Base class for `drawable` scene graph system. +This base class is really abused in many ways, and the meaning of the various methods differ depending +on the exact type. Not even the ID and bsphere here are always populated. +This is used for very high level organization of different rendering data types, and also very low-level +culling/rendering optimizations. It supports both array-of-references and inline-array containers with precise +control over memory layout for use with DMA." ((id int16) (bsphere vector :inline) ) @@ -33,6 +39,7 @@ ;; definition of type drawable-error (deftype drawable-error (drawable) + "A drawable which just represents an error. When drawn, it simply displays a sphere with an error message." ((name string) ) ) diff --git a/test/decompiler/reference/jak2/engine/draw/drawable-inline-array_REF.gc b/test/decompiler/reference/jak2/engine/draw/drawable-inline-array_REF.gc index 78f95c2c4c..29192dcdc2 100644 --- a/test/decompiler/reference/jak2/engine/draw/drawable-inline-array_REF.gc +++ b/test/decompiler/reference/jak2/engine/draw/drawable-inline-array_REF.gc @@ -8,6 +8,7 @@ ;; definition for method 9 of type drawable-inline-array (defmethod login ((this drawable-inline-array)) + "Initialize the object after it is loaded." this ) diff --git a/test/decompiler/reference/jak2/engine/draw/drawable-tree-h_REF.gc b/test/decompiler/reference/jak2/engine/draw/drawable-tree-h_REF.gc index 97f3eca17e..2ae12e1084 100644 --- a/test/decompiler/reference/jak2/engine/draw/drawable-tree-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/draw/drawable-tree-h_REF.gc @@ -3,11 +3,16 @@ ;; definition of type drawable-tree (deftype drawable-tree (drawable-group) + "A drawable tree is a container of drawables of a specific rendering type. +Instead of having a single large tree of mixed types, there will be a tree of tfrags, a tree of ties, etc. +The top-level tfrag tree will have a type that's a child of drawable-tree. +Generally, the object passed to a large renderer is a drawable-tree." () ) ;; definition of type drawable-tree-array (deftype drawable-tree-array (drawable-group) + "Collection of drawable trees. This might have a tfrag tree, tie tree, etc." ((trees drawable-tree :dynamic :offset 32) ) ) diff --git a/test/decompiler/reference/jak2/engine/draw/drawable_REF.gc b/test/decompiler/reference/jak2/engine/draw/drawable_REF.gc index 55a75407c1..99cc84ba38 100644 --- a/test/decompiler/reference/jak2/engine/draw/drawable_REF.gc +++ b/test/decompiler/reference/jak2/engine/draw/drawable_REF.gc @@ -193,6 +193,7 @@ ;; definition for method 9 of type drawable (defmethod login ((this drawable)) + "Initialize the object after it is loaded." this ) diff --git a/test/decompiler/reference/jak2/engine/entity/actor-link-h_REF.gc b/test/decompiler/reference/jak2/engine/entity/actor-link-h_REF.gc index 8d520a50f2..ac07fdb353 100644 --- a/test/decompiler/reference/jak2/engine/entity/actor-link-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/entity/actor-link-h_REF.gc @@ -5,6 +5,7 @@ ;; INFO: Used lq/sq ;; WARN: Return type mismatch entity vs entity-actor. (defun entity-actor-lookup ((arg0 res-lump) (arg1 symbol) (arg2 int)) + "Given an entity (the res-lump), look up a reference to another entity and return that entity." (local-vars (sv-16 res-tag)) (set! sv-16 (new 'static 'res-tag)) (let ((v1-1 (res-lump-data arg0 arg1 pointer :tag-ptr (& sv-16)))) @@ -24,6 +25,8 @@ ;; WARN: Check prologue - tricky store of r0 ;; INFO: Used lq/sq (defun entity-actor-count ((arg0 res-lump) (arg1 symbol)) + "Get the number of entities that this res references under the name. +This works on more than just next/prev." (local-vars (sv-16 res-tag)) (set! sv-16 (new 'static 'res-tag)) (if (res-lump-data arg0 arg1 pointer :tag-ptr (& sv-16)) @@ -34,6 +37,11 @@ ;; definition of type actor-link-info (deftype actor-link-info (basic) + "A linked list of actors. + +Actors allocate this on their process heap if they have a +`next-actor` or `prev-actor` defined in their lump +and use it for entity lookups." ((process process) (next entity-actor) (prev entity-actor) @@ -86,6 +94,9 @@ ;; definition for method 0 of type actor-link-info (defmethod new actor-link-info ((allocation symbol) (type-to-make type) (arg0 process) (arg1 symbol)) + "Set up an actor-link-info for the given process. +The entity of this process should be the entity-actor +that will get this actor-link-info." (let* ((a0-1 (-> arg0 entity)) (s4-0 (entity-actor-lookup a0-1 'next-actor 0)) (a0-2 (-> arg0 entity)) @@ -115,17 +126,20 @@ ;; definition for method 14 of type actor-link-info ;; WARN: Return type mismatch basic vs process. (defmethod get-next-process ((this actor-link-info)) + "Get the process for the next, if it exists." (the-as process (and (-> this next) (-> this next extra process))) ) ;; definition for method 15 of type actor-link-info ;; WARN: Return type mismatch basic vs process. (defmethod get-prev-process ((this actor-link-info)) + "Get the process for the prev, if it exists." (the-as process (and (-> this prev) (-> this prev extra process))) ) ;; definition for method 11 of type actor-link-info (defmethod link-to-next-and-prev-actor ((this actor-link-info)) + "Redo the linking in the constructor by looking up the next/prev actor." (let ((a0-1 (-> this process entity))) (set! (-> this next) (entity-actor-lookup a0-1 'next-actor 0)) ) @@ -137,6 +151,8 @@ ;; definition for method 16 of type actor-link-info (defmethod apply-function-forward ((this actor-link-info) (arg0 (function entity-actor object object)) (arg1 object)) + "Iterate forward through actors, and apply this function. Starts at (-> this next) +If the function returns truthy, stop iterating." (let ((s3-0 (-> this next))) (while s3-0 (if (arg0 s3-0 arg1) @@ -150,6 +166,8 @@ ;; definition for method 17 of type actor-link-info (defmethod apply-function-reverse ((this actor-link-info) (arg0 (function entity-actor object object)) (arg1 object)) + "Iterate backward through actors and apply function. +If the function returns truth, stop iterating." (let ((s3-0 (-> this prev))) (while s3-0 (if (arg0 s3-0 arg1) @@ -163,6 +181,7 @@ ;; definition for method 18 of type actor-link-info (defmethod apply-all ((this actor-link-info) (arg0 (function entity-actor object object)) (arg1 object)) + "Apply to all entities. Starts at the back and hits everyone, including this object." (let ((s4-0 (-> this process entity))) (while (let ((a0-2 s4-0)) (entity-actor-lookup a0-2 'prev-actor 0) @@ -183,6 +202,7 @@ ;; definition for method 20 of type actor-link-info (defmethod send-to-all-after ((this actor-link-info) (arg0 symbol)) + "Send an event to all processes after this link with no parameters." (with-pp (let ((s4-0 (-> this next)) (s5-0 (the-as object #f)) @@ -207,6 +227,7 @@ ;; definition for method 21 of type actor-link-info (defmethod send-to-all-before ((this actor-link-info) (arg0 symbol)) + "Send an event to all processes before this link with no parameters." (with-pp (let ((s4-0 (-> this prev)) (s5-0 (the-as object #f)) @@ -232,6 +253,7 @@ ;; definition for method 23 of type actor-link-info ;; WARN: Return type mismatch symbol vs none. (defmethod send-to-next ((this actor-link-info) (arg0 symbol)) + "Send event arg0 to the next actor's process." (let ((a0-1 (-> this next))) (when a0-1 (let ((a0-2 (-> a0-1 extra process))) @@ -247,6 +269,7 @@ ;; definition for method 24 of type actor-link-info ;; WARN: Return type mismatch symbol vs none. (defmethod send-to-prev ((this actor-link-info) (arg0 symbol)) + "Send event arg1 to the next actor's process." (let ((a0-1 (-> this prev))) (when a0-1 (let ((a0-2 (-> a0-1 extra process))) @@ -262,6 +285,7 @@ ;; definition for method 22 of type actor-link-info ;; WARN: Return type mismatch symbol vs none. (defmethod send-to-next-and-prev ((this actor-link-info) (arg0 symbol)) + "Send an event to both next and prev with no params." (send-to-next this arg0) (send-to-prev this arg0) (none) @@ -277,6 +301,7 @@ ;; definition for method 25 of type actor-link-info (defmethod actor-count ((this actor-link-info)) + "Count the number of actors in the entire list." (let ((s5-0 (-> this process entity)) (gp-0 0) ) @@ -297,6 +322,8 @@ ;; definition for method 9 of type actor-link-info (defmethod get-matching-actor-type-mask ((this actor-link-info) (arg0 type)) + "Iterate through _all_ actors that are part of this actor list. +If the nth actor is type matching-type, then set the nth bit of the result." (let ((s3-0 (-> this process entity)) (s5-0 0) ) @@ -322,6 +349,7 @@ ;; definition for method 10 of type actor-link-info (defmethod actor-count-before ((this actor-link-info)) + "Get the number of actors before this actor in the list." (let* ((s5-0 (-> this process entity)) (s4-0 s5-0) (gp-0 0) @@ -343,6 +371,7 @@ ;; definition for function actor-link-subtask-complete-hook (defun actor-link-subtask-complete-hook ((arg0 entity-actor) (arg1 (pointer symbol))) + "Sets arg1 if the thing is complete. Does not continue the apply if the complete perm is set." (cond ((logtest? (-> arg0 extra perm status) (entity-perm-status subtask-complete)) (set! (-> arg1 0) #t) @@ -370,6 +399,7 @@ ;; definition for function actor-link-dead-hook (defun actor-link-dead-hook ((arg0 entity-actor) (arg1 (pointer symbol))) + "Sets arg1 if the thing is dead. Does not continue the apply if the dead perm is set." (cond ((logtest? (-> arg0 extra perm status) (entity-perm-status dead)) (set! (-> arg1 0) #t) @@ -384,6 +414,7 @@ ;; definition for function alt-actor-list-subtask-incomplete-count (defun alt-actor-list-subtask-incomplete-count ((arg0 process-drawable)) + "Get the number of alt-actors which do not have the complete bit set in their perm." (let ((s4-0 (entity-actor-count (-> arg0 entity) 'alt-actor)) (gp-0 0) ) diff --git a/test/decompiler/reference/jak2/engine/entity/entity-h_REF.gc b/test/decompiler/reference/jak2/engine/entity/entity-h_REF.gc index d5a831f52d..841e3243db 100644 --- a/test/decompiler/reference/jak2/engine/entity/entity-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/entity/entity-h_REF.gc @@ -12,6 +12,7 @@ ;; definition of type entity-perm (deftype entity-perm (structure) + "Entity information that gets persisted in the save file." ((user-object object 2) (user-uint64 uint64 :overlay-at (-> user-object 0)) (user-float float 2 :overlay-at (-> user-object 0)) @@ -60,6 +61,7 @@ ;; definition of type entity-links (deftype entity-links (structure) + "A linked list of entities with some extra data about their current status." ((prev-link entity-links) (next-link entity-links) (entity entity) @@ -188,6 +190,8 @@ ;; definition of type entity-links-array (deftype entity-links-array (inline-array-class) + "An array of [[entity-links]]. +Levels store a reference to this which holds all the entities in the level." ((data entity-links :inline :dynamic) ) ) diff --git a/test/decompiler/reference/jak2/engine/entity/entity_REF.gc b/test/decompiler/reference/jak2/engine/entity/entity_REF.gc index 1fdbf07763..9222b23f5a 100644 --- a/test/decompiler/reference/jak2/engine/entity/entity_REF.gc +++ b/test/decompiler/reference/jak2/engine/entity/entity_REF.gc @@ -2283,6 +2283,7 @@ ;; definition for method 12 of type process-drawable (defmethod run-logic? ((this process-drawable)) + "Should this process be run? Checked by execute-process-tree." (or (not (logtest? (-> this mask) (process-mask actor-pause))) (or (>= (+ (-> *ACTOR-bank* pause-dist) (-> this root pause-adjust-distance)) (vector-vector-distance (-> this root trans) (math-camera-pos)) diff --git a/test/decompiler/reference/jak2/engine/entity/res-h_REF.gc b/test/decompiler/reference/jak2/engine/entity/res-h_REF.gc index 01b9144a8f..b0ee201b52 100644 --- a/test/decompiler/reference/jak2/engine/entity/res-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/entity/res-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type res-tag (deftype res-tag (uint128) + "Metadata about a property in a [[res-lump]], such as name, element type and element count." ((name symbol :offset 0 :size 32) (key-frame float :offset 32 :size 32) (elt-type type :offset 64 :size 32) @@ -14,6 +15,7 @@ ;; definition of type res-lump (deftype res-lump (basic) + "A collection of [[res-tag]]s and their data." ((length int32) (allocated-length int32) (data-base pointer) @@ -41,7 +43,6 @@ ) ;; definition for method 3 of type res-lump -;; INFO: this function exists in multiple non-identical object files (defmethod inspect ((this res-lump)) (when (not this) (set! this this) diff --git a/test/decompiler/reference/jak2/engine/entity/res_REF.gc b/test/decompiler/reference/jak2/engine/entity/res_REF.gc index 806af37a12..4895d6a6b5 100644 --- a/test/decompiler/reference/jak2/engine/entity/res_REF.gc +++ b/test/decompiler/reference/jak2/engine/entity/res_REF.gc @@ -37,11 +37,13 @@ ;; definition for method 13 of type res-lump ;; INFO: Used lq/sq (defmethod get-tag-index-data ((this res-lump) (arg0 int)) + "Get the data address of the n'th tag." (&+ (-> this data-base) (-> this tag arg0 data-offset)) ) ;; definition for method 14 of type res-lump (defmethod get-tag-data ((this res-lump) (arg0 res-tag)) + "Get the data address of the specified tag." (&+ (-> this data-base) (-> arg0 data-offset)) ) @@ -69,7 +71,6 @@ ) ;; definition for method 3 of type res-lump -;; INFO: this function exists in multiple non-identical object files ;; INFO: Used lq/sq (defmethod inspect ((this res-lump)) (format #t "[~8x] ~A~%" this (-> this type)) @@ -114,6 +115,17 @@ ;; INFO: Used lq/sq ;; WARN: Return type mismatch int vs res-tag-pair. (defmethod lookup-tag-idx ((this res-lump) (arg0 symbol) (arg1 symbol) (arg2 float)) + "Look up the index of the tag containing with the given name and timestamp. +Correct lookups return a res-tag-pair, which contains one tag index in the lower 32 bits and one in the upper 32 bits. +Depending on the mode, they may be the same, or they may be two tags that you should interpolate +between, if the exact time was not found. + +@param name-sym should be the name of the thing you want. +@param time is for the timestamp you want. +If mode = 'base, then both the indices are the same and the timestamp is ignored. +If mode = 'interp, then it tries to get closest below/closest above (or both the same, if exact match found). +If mode = 'exact, then it requires an exact timestamp match and both indices are the same. +If things go wrong, returns a negative number." (local-vars (t4-1 int)) (when (or (= arg0 'id) (= arg0 'aid) @@ -213,22 +225,26 @@ ;; definition for method 20 of type res-lump ;; INFO: Used lq/sq -(defmethod make-property-data ((this res-lump) (arg0 float) (arg1 res-tag-pair) (arg2 pointer)) +(defmethod make-property-data ((this res-lump) (arg1 float) (tag-pair res-tag-pair) (arg3 pointer)) + "Returns (a pointer to) the value data of a property with the tag-pair. +If tag-pair does not represent an exact point in the timeline, then the data is interpolated based on time +with the result written into buf. buf must have enough space to copy all of the data. +Otherwise, simply returns an address to the resource binary." (rlet ((vf1 :class vf) (vf2 :class vf) (vf3 :class vf) (vf4 :class vf) ) - (let* ((t0-2 (-> this tag (-> arg1 lo))) - (t1-2 (-> this tag (-> arg1 hi))) + (let* ((t0-2 (-> this tag (-> tag-pair lo))) + (t1-2 (-> this tag (-> tag-pair hi))) (v1-6 (-> t0-2 elt-count)) ) (cond ((zero? (-> t0-2 inlined?)) (&+ (-> this data-base) (-> t0-2 data-offset)) ) - ((or (not arg2) - (= (-> arg1 lo) (-> arg1 hi)) + ((or (not arg3) + (= (-> tag-pair lo) (-> tag-pair hi)) (!= v1-6 (-> t1-2 elt-count)) (!= (-> t0-2 elt-type) (-> t1-2 elt-type)) ) @@ -237,7 +253,7 @@ ) ) (else - (let* ((f0-2 (/ (- arg0 (-> t0-2 key-frame)) (- (-> t1-2 key-frame) (-> t0-2 key-frame)))) + (let* ((f0-2 (/ (- arg1 (-> t0-2 key-frame)) (- (-> t1-2 key-frame) (-> t0-2 key-frame)))) (a1-4 this) (a2-7 t0-2) (a1-6 (&+ (-> a1-4 data-base) (-> a2-7 data-offset))) @@ -246,18 +262,18 @@ (case (-> t0-2 elt-type symbol) (('float) (dotimes (a0-8 (the-as int v1-6)) - (set! (-> (the-as (pointer float) (&+ arg2 (* a0-8 4)))) + (set! (-> (the-as (pointer float) (&+ arg3 (* a0-8 4)))) (+ (* (-> (the-as (pointer float) (&+ a1-6 (* a0-8 4)))) (- 1.0 f0-2)) (* (-> (the-as (pointer float) (&+ a2-13 (* a0-8 4)))) f0-2) ) ) ) - arg2 + arg3 ) (('integer 'sinteger 'uinteger 'int64 'uint64) (let ((a0-10 (the int (* 4096.0 f0-2)))) (dotimes (t0-10 (the-as int v1-6)) - (set! (-> (the-as (pointer int64) (&+ arg2 (* t0-10 8)))) + (set! (-> (the-as (pointer int64) (&+ arg3 (* t0-10 8)))) (sar (+ (* (the-as int (-> (the-as (pointer uint64) (&+ a1-6 (* t0-10 8))))) (- 4096 a0-10)) (* (the-as int (-> (the-as (pointer uint64) (&+ a2-13 (* t0-10 8))))) a0-10) @@ -267,12 +283,12 @@ ) ) ) - arg2 + arg3 ) (('int8) (let ((a0-12 (the int (* 4096.0 f0-2)))) (dotimes (t0-11 (the-as int v1-6)) - (set! (-> (the-as (pointer int8) (&+ arg2 t0-11))) + (set! (-> (the-as (pointer int8) (&+ arg3 t0-11))) (sar (+ (* (-> (the-as (pointer int8) (&+ a1-6 t0-11))) (- 4096 a0-12)) (* (-> (the-as (pointer int8) (&+ a2-13 t0-11))) a0-12) @@ -282,12 +298,12 @@ ) ) ) - arg2 + arg3 ) (('uint8) (let ((a0-14 (the int (* 4096.0 f0-2)))) (dotimes (t0-12 (the-as int v1-6)) - (set! (-> (the-as (pointer uint8) (&+ arg2 t0-12))) + (set! (-> (the-as (pointer uint8) (&+ arg3 t0-12))) (shr (+ (* (-> (the-as (pointer uint8) (&+ a1-6 t0-12))) (the-as uint (- 4096 a0-14))) (* (-> (the-as (pointer uint8) (&+ a2-13 t0-12))) (the-as uint a0-14)) @@ -297,12 +313,12 @@ ) ) ) - arg2 + arg3 ) (('int16) (let ((a0-16 (the int (* 4096.0 f0-2)))) (dotimes (t0-13 (the-as int v1-6)) - (set! (-> (the-as (pointer int16) (&+ arg2 (* t0-13 2)))) + (set! (-> (the-as (pointer int16) (&+ arg3 (* t0-13 2)))) (sar (+ (* (-> (the-as (pointer int16) (&+ a1-6 (* t0-13 2)))) (- 4096 a0-16)) (* (-> (the-as (pointer int16) (&+ a2-13 (* t0-13 2)))) a0-16) @@ -312,12 +328,12 @@ ) ) ) - arg2 + arg3 ) (('uint16) (let ((a0-18 (the int (* 4096.0 f0-2)))) (dotimes (t0-14 (the-as int v1-6)) - (set! (-> (the-as (pointer uint16) (&+ arg2 (* t0-14 2)))) + (set! (-> (the-as (pointer uint16) (&+ arg3 (* t0-14 2)))) (shr (+ (* (-> (the-as (pointer uint16) (&+ a1-6 (* t0-14 2)))) (the-as uint (- 4096 a0-18))) (* (-> (the-as (pointer uint16) (&+ a2-13 (* t0-14 2)))) (the-as uint a0-18)) @@ -327,12 +343,12 @@ ) ) ) - arg2 + arg3 ) (('int32) (let ((a0-20 (the int (* 4096.0 f0-2)))) (dotimes (t0-15 (the-as int v1-6)) - (set! (-> (the-as (pointer int32) (&+ arg2 (* t0-15 4)))) + (set! (-> (the-as (pointer int32) (&+ arg3 (* t0-15 4)))) (sar (+ (* (-> (the-as (pointer int32) (&+ a1-6 (* t0-15 4)))) (- 4096 a0-20)) (* (-> (the-as (pointer int32) (&+ a2-13 (* t0-15 4)))) a0-20) @@ -342,12 +358,12 @@ ) ) ) - arg2 + arg3 ) (('uint32) (let ((a0-22 (the int (* 4096.0 f0-2)))) (dotimes (t0-16 (the-as int v1-6)) - (set! (-> (the-as (pointer uint32) (&+ arg2 (* t0-16 4)))) + (set! (-> (the-as (pointer uint32) (&+ arg3 (* t0-16 4)))) (shr (+ (* (-> (the-as (pointer uint32) (&+ a1-6 (* t0-16 4)))) (the-as uint (- 4096 a0-22))) (* (-> (the-as (pointer uint32) (&+ a2-13 (* t0-16 4)))) (the-as uint a0-22)) @@ -357,7 +373,7 @@ ) ) ) - arg2 + arg3 ) (('vector) (let ((a0-23 f0-2)) @@ -376,9 +392,9 @@ (.mul.x.vf vf1 vf1 vf4) (.mul.x.vf vf2 vf2 vf3) (.add.vf vf1 vf1 vf2) - (.svf (&-> (the-as (pointer uint128) (+ (* a0-26 16) (the-as int arg2))) 0) vf1) + (.svf (&-> (the-as (pointer uint128) (+ (* a0-26 16) (the-as int arg3))) 0) vf1) ) - arg2 + arg3 ) (else (let ((a0-27 t0-2)) @@ -403,6 +419,11 @@ (arg4 (pointer res-tag)) (arg5 pointer) ) + "Returns an address to a given property's data at a specific time stamp, or default on error. +@param name is the name of the property you want, mode is its lookup mode ('interp 'base 'exact), time is the timestamp. +@param default is the default result returned in the case of an error. +@param tag-addr is an address to a res-tag. The current base tag is written to this. Ignored if tag-addr is #f +@param buf-addr is an address to the data buffer used to write interpolated data to. It must have enough space! Only necessary for 'interp mode." (let ((s3-0 (lookup-tag-idx this arg0 arg1 arg2))) (cond ((< (the-as int s3-0) 0) @@ -430,6 +451,12 @@ (arg4 (pointer res-tag)) (arg5 pointer) ) + "Returns a given struct property's value at a specific time stamp, or default on error. +@param name is the name of the property you want, `mode` is its lookup mode ('interp 'base 'exact), `time` is the timestamp. +@param default is the default result returned in the case of an error. +@param tag-addr is an address to a [[res-tag]]. The current base tag is written to this. Ignored if tag-addr is #f. +@param buf-addr is an address to the data buffer used to write interpolated data to. +It must have enough space! Only necessary for 'interp mode." (let ((s3-0 (lookup-tag-idx this arg0 arg1 arg2))) (cond ((< (the-as int s3-0) 0) @@ -463,6 +490,12 @@ (arg4 (pointer res-tag)) (arg5 pointer) ) + "Returns a given value property's value at a specific time stamp, or default on error. +@param name is the name of the property you want, `mode` is its lookup mode ('interp 'base 'exact), `time` is the timestamp. +@param default is the default result returned in the case of an error. +@param tag-addr is an address to a res-tag. The current base tag is written to this. Ignored if `tag-addr` is #f. +@param buf-addr is an address to the data buffer used to write interpolated data to. +It must have enough space! Only necessary for 'interp mode." (let ((a2-1 (lookup-tag-idx this arg0 arg1 arg2))) (cond ((< (the-as int a2-1) 0) @@ -613,6 +646,7 @@ ;; definition for method 16 of type res-lump ;; INFO: Used lq/sq (defmethod sort! ((this res-lump)) + "Sort all tags based on name, then key-frame." (let ((v1-0 -1)) (while (nonzero? v1-0) (set! v1-0 0) @@ -642,6 +676,11 @@ ;; definition for method 15 of type res-lump ;; INFO: Used lq/sq (defmethod allocate-data-memory-for-tag! ((this res-lump) (arg0 res-tag)) + "Find space for the data described by arg0 in this. +Returns a tag with data-offset set correctly for this res-lump. +If the lump already contains memory for the given tag, and it is big enough, +it will be reused. Alignment will be at least 8 bytes. +If the input tag has elt-count = 0, it will return a tag for elt-count = 1." (local-vars (resource-mem pointer)) (let* ((tag-pair (lookup-tag-idx this (-> arg0 name) 'exact (-> arg0 key-frame))) (existing-tag (-> this tag (-> tag-pair lo))) @@ -705,8 +744,11 @@ ) ;; definition for method 17 of type res-lump -(defmethod add-data! ((this res-lump) (arg0 res-tag) (arg1 pointer)) - (let ((a0-2 (allocate-data-memory-for-tag! this arg0))) +(defmethod add-data! ((this res-lump) (tag res-tag) (arg2 pointer)) + "Given a tag and a pointer to its data, copy it to this res-lump. +This doesn't seem to do the right thing if the given tag is a non-inline tag +with > 1 element." + (let ((a0-2 (allocate-data-memory-for-tag! this tag))) (when a0-2 (let* ((v1-2 this) (a1-1 a0-2) @@ -715,11 +757,11 @@ (cond ((zero? (-> a0-2 inlined?)) (length a0-2) - (set! (-> (the-as (pointer pointer) s4-0) 0) arg1) + (set! (-> (the-as (pointer pointer) s4-0) 0) arg2) ) (else (let ((a2-1 (length a0-2))) - (mem-copy! s4-0 arg1 a2-1) + (mem-copy! s4-0 arg2 a2-1) ) ) ) @@ -731,6 +773,7 @@ ;; definition for method 18 of type res-lump (defmethod add-32bit-data! ((this res-lump) (arg0 res-tag) (arg1 object)) + "Add a single 32-bit value using [[add-data!]]." (local-vars (sv-16 object)) (set! sv-16 arg1) (let* ((v1-0 arg0) @@ -743,6 +786,8 @@ ;; definition for method 21 of type res-lump ;; INFO: Used lq/sq (defmethod get-curve-data! ((this res-lump) (arg0 curve) (arg1 symbol) (arg2 symbol) (arg3 float)) + "Read curve data and write it to curve-target. Return #t if both +control points and knots data was succesfully read, #f otherwise." (local-vars (sv-16 res-tag) (sv-32 res-tag)) (let ((s5-0 #f)) (set! sv-16 (new 'static 'res-tag)) diff --git a/test/decompiler/reference/jak2/engine/game/effect-control-h_REF.gc b/test/decompiler/reference/jak2/engine/game/effect-control-h_REF.gc index 1ac2189b6c..bb3943755b 100644 --- a/test/decompiler/reference/jak2/engine/game/effect-control-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/game/effect-control-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type effect-control (deftype effect-control (basic) + "An effect such as a particle with sound effects that plays during an animation." ((process process-drawable) (flags effect-control-flag) (last-frame-group art-joint-anim) @@ -43,11 +44,11 @@ ) ;; definition for method 0 of type effect-control -(defmethod new effect-control ((allocation symbol) (type-to-make type) (arg0 process-drawable)) +(defmethod new effect-control ((allocation symbol) (type-to-make type) (proc process-drawable)) (cond - ((res-lump-struct (-> arg0 draw jgeo extra) 'effect-name structure) + ((res-lump-struct (-> proc draw jgeo extra) 'effect-name structure) (let ((v0-1 (object-new allocation type-to-make (the-as int (-> type-to-make size))))) - (set! (-> v0-1 process) arg0) + (set! (-> v0-1 process) proc) (set! (-> v0-1 last-frame-group) #f) v0-1 ) @@ -60,8 +61,8 @@ ;; definition for method 13 of type effect-control ;; WARN: Return type mismatch int vs none. -(defmethod set-channel-offset! ((this effect-control) (arg0 int)) - (set! (-> this channel-offset) arg0) +(defmethod set-channel-offset! ((this effect-control) (offset int)) + (set! (-> this channel-offset) offset) 0 (none) ) diff --git a/test/decompiler/reference/jak2/engine/game/game-h_REF.gc b/test/decompiler/reference/jak2/engine/game/game-h_REF.gc index abcdc5c1af..8a0ef7d449 100644 --- a/test/decompiler/reference/jak2/engine/game/game-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/game/game-h_REF.gc @@ -3,6 +3,10 @@ ;; definition of type process-drawable (deftype process-drawable (process) + "This is the main base class for in-game objects. +This handles drawing, collision, animation, navigation, particles, sounds, physics, etc. +The actual child classes will add most of the functionality, and this just serves as a common +container for references to the `-control` objects for this object." ((root trsqv) (node-list cspace-array) (draw draw-control) @@ -67,6 +71,9 @@ ;; definition of type process-drawable-reserved (deftype process-drawable-reserved (process-drawable) + "A process drawable with a lot of unused method slots. +GOAL cannot increase the number of methods at runtime, so, for interactive development, it is useful +to have a type with a large number of slots which can be turned into real methods without needed to reboot the PS2." () (:methods (process-drawable-reserved-method-20 () none) @@ -245,6 +252,7 @@ ;; definition of type attack-dir-info (deftype attack-dir-info (structure) + "Information about the position/direction of an attack." ((dir vector :inline) (xz-dir vector :inline) (attacker-velocity vector :inline) @@ -269,6 +277,7 @@ ;; definition of type attack-info (deftype attack-info (structure) + "Information about an incoming attack." ((trans vector :inline) (vector vector :inline) (attacker-velocity vector :inline) diff --git a/test/decompiler/reference/jak2/engine/game/main_REF.gc b/test/decompiler/reference/jak2/engine/game/main_REF.gc index 825067cbb3..e9d905a565 100644 --- a/test/decompiler/reference/jak2/engine/game/main_REF.gc +++ b/test/decompiler/reference/jak2/engine/game/main_REF.gc @@ -1218,7 +1218,7 @@ (bucket-id debug-no-zbuf2) ) (when (or *display-profile* *stats-profile-bars*) - (setup-categories! (-> arg0 frames (-> arg0 on-screen) profile-array)) + (postprocess-data! (-> arg0 frames (-> arg0 on-screen) profile-array)) (let ((a2-0 7)) (if *display-profile* (draw-bars! *profile-array* s3-0 a2-0) diff --git a/test/decompiler/reference/jak2/engine/game/task/task-arrow_REF.gc b/test/decompiler/reference/jak2/engine/game/task/task-arrow_REF.gc index 4b024ba223..cdc81318ce 100644 --- a/test/decompiler/reference/jak2/engine/game/task/task-arrow_REF.gc +++ b/test/decompiler/reference/jak2/engine/game/task/task-arrow_REF.gc @@ -91,6 +91,7 @@ or collectable items on the ground (jetboard / weapon upgrades / etc)" ;; definition for method 10 of type task-arrow ;; WARN: Return type mismatch int vs none. (defmethod deactivate ((this task-arrow)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (send-event (handle->process (-> this hud-dist)) 'hide-and-die) ((method-of-type process-drawable deactivate) this) 0 diff --git a/test/decompiler/reference/jak2/engine/game/task/task-control_REF.gc b/test/decompiler/reference/jak2/engine/game/task/task-control_REF.gc index cf786a7e32..d386a108ad 100644 --- a/test/decompiler/reference/jak2/engine/game/task/task-control_REF.gc +++ b/test/decompiler/reference/jak2/engine/game/task/task-control_REF.gc @@ -1442,6 +1442,7 @@ ;; definition for method 12 of type fail-mission (defmethod run-logic? ((this fail-mission)) + "Should this process be run? Checked by execute-process-tree." #t ) @@ -1640,6 +1641,7 @@ ;; definition for method 10 of type fail-mission (defmethod deactivate ((this fail-mission)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (set-filter-color! 1.0 1.0 1.0) (sound-group-continue (sound-group sfx music dialog sog3 ambient dialog2 sog6 sog7)) (update-rates! (-> *display* bg-clock) 1.0) @@ -1928,6 +1930,7 @@ ;; definition for method 10 of type task-manager (defmethod deactivate ((this task-manager)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (with-pp (let ((s5-0 pp)) (set! pp this) diff --git a/test/decompiler/reference/jak2/engine/geometry/bounding-box_REF.gc b/test/decompiler/reference/jak2/engine/geometry/bounding-box_REF.gc index b07f48c2e8..8ebe16a5ec 100644 --- a/test/decompiler/reference/jak2/engine/geometry/bounding-box_REF.gc +++ b/test/decompiler/reference/jak2/engine/geometry/bounding-box_REF.gc @@ -3,6 +3,7 @@ ;; definition for method 19 of type bounding-box (defmethod inside-xyz? ((this bounding-box) (arg0 vector)) + "Is the point in the box?" (and (< (-> this min x) (-> arg0 x)) (< (-> this min y) (-> arg0 y)) (< (-> this min z) (-> arg0 z)) @@ -14,6 +15,7 @@ ;; definition for method 20 of type bounding-box (defmethod inside-xz? ((this bounding-box) (arg0 vector)) + "Is the point in the box? Check xz only." (and (< (-> this min x) (-> arg0 x)) (< (-> this min z) (-> arg0 z)) (< (-> arg0 x) (-> this max x)) @@ -23,6 +25,7 @@ ;; definition for function box-vector-enside? (defun box-vector-enside? ((arg0 bounding-box) (arg1 vector)) + "Is the point in the box? On the edge doesn't count." (and (< (-> arg0 min x) (-> arg1 x)) (< (-> arg0 min y) (-> arg1 y)) (< (-> arg0 min z) (-> arg1 z)) @@ -34,6 +37,7 @@ ;; definition for function box-vector-inside? (defun box-vector-inside? ((arg0 bounding-box) (arg1 vector)) + "Is the point in the box? On the edge counts." (and (>= (-> arg1 x) (-> arg0 min x)) (>= (-> arg1 y) (-> arg0 min y)) (>= (-> arg1 z) (-> arg0 min z)) @@ -46,6 +50,7 @@ ;; definition for method 13 of type bounding-box ;; WARN: Return type mismatch int vs none. (defmethod set-from-point-offset! ((this bounding-box) (arg0 vector) (arg1 vector)) + "Set to the smallest box containing arg0, (arg0 + arg1)" (rlet ((vf0 :class vf) (vf1 :class vf) (vf2 :class vf) @@ -71,6 +76,7 @@ ;; definition for method 11 of type bounding-box ;; WARN: Return type mismatch int vs none. (defmethod add-point! ((this bounding-box) (arg0 vector)) + "Expand the box as needed to contain the given point." (rlet ((vf1 :class vf) (vf2 :class vf) (vf3 :class vf) @@ -89,6 +95,7 @@ ;; definition for method 10 of type bounding-box (defmethod add-box! ((this bounding-box) (arg0 bounding-box)) + "Expand the box as needed to contain the given box." (rlet ((vf1 :class vf) (vf2 :class vf) (vf3 :class vf) @@ -110,6 +117,7 @@ ;; INFO: Used lq/sq ;; WARN: Return type mismatch int vs none. (defmethod set-to-point! ((this bounding-box) (arg0 vector)) + "Set the box to be a single point." (set! (-> this min quad) (-> arg0 quad)) (set! (-> this max quad) (-> arg0 quad)) 0 @@ -118,6 +126,7 @@ ;; definition for method 14 of type bounding-box (defmethod set-from-point-offset-pad! ((this bounding-box) (arg0 vector) (arg1 vector) (arg2 float)) + "Set the box to contain arg0, arg0 + offset, with some padding." (rlet ((vf0 :class vf) (vf1 :class vf) (vf2 :class vf) @@ -146,6 +155,7 @@ ;; definition for method 16 of type bounding-box ;; WARN: Return type mismatch int vs none. (defmethod set-from-sphere! ((this bounding-box) (arg0 sphere)) + "Set the box to contain a single sphere." (rlet ((vf0 :class vf) (vf1 :class vf) (vf2 :class vf) @@ -172,6 +182,7 @@ ;; definition for method 18 of type bounding-box (defmethod get-bounding-sphere ((this bounding-box) (arg0 vector)) + "Get a bounding sphere for a bounding box." (let* ((a1-2 (vector-! (new 'stack-no-clear 'vector) (-> this max) (-> this min))) (a0-3 (vector-float*! (new 'stack-no-clear 'vector) a1-2 0.5)) ) @@ -203,6 +214,7 @@ ;; definition for function liang-barsky-line-clipt (defun liang-barsky-line-clipt ((arg0 liang-barsky-line-clip-params) (arg1 float) (arg2 float)) + "Clip test in 1 dimension. Is arg1 in arg2?" (cond ((< 0.0 arg1) (let ((f0-2 (/ arg2 arg1))) @@ -236,6 +248,8 @@ ;; definition for method 12 of type bounding-box ;; WARN: disable def twice: 23. This may happen when a cond (no else) is nested inside of another conditional, but it should be rare. (defmethod intersects-line-segment? ((this bounding-box) (arg0 vector) (arg1 vector)) + "Check intersection in xz plane, using liang-barsky. Not sure if this actually +a useful check or not..." (let ((f28-0 (- (-> arg1 x) (-> arg0 x))) (f30-0 (- (-> arg1 z) (-> arg0 z))) ) diff --git a/test/decompiler/reference/jak2/engine/geometry/geometry_REF.gc b/test/decompiler/reference/jak2/engine/geometry/geometry_REF.gc index 305ec453b0..5aaae676cb 100644 --- a/test/decompiler/reference/jak2/engine/geometry/geometry_REF.gc +++ b/test/decompiler/reference/jak2/engine/geometry/geometry_REF.gc @@ -3,6 +3,8 @@ ;; definition for function vector-flatten! (defun vector-flatten! ((arg0 vector) (arg1 vector) (arg2 vector)) + "Get the projection of src onto a plane with the given normal +The normal should have magnitude 1.0." (rlet ((acc :class vf) (vf0 :class vf) (vf1 :class vf) @@ -24,6 +26,7 @@ ;; definition for function vector-reflect! (defun vector-reflect! ((arg0 vector) (arg1 vector) (arg2 vector)) + "Reflect a vector off of a plane." (rlet ((acc :class vf) (vf0 :class vf) (vf1 :class vf) @@ -47,6 +50,12 @@ ;; definition for function vector-reflect-flat! (defun vector-reflect-flat! ((arg0 vector) (arg1 vector) (arg2 vector)) + "This is a weird one. It doesn't care about the value of src dot normal +and it effectively replaces the component of src normal to the plane with +the plane's normal. I think this requires src/normal to both be unit vectors +in order to make sense. +NOTE: src should point from positive halfspace to negative otherwise it +doesn't work." (rlet ((acc :class vf) (vf0 :class vf) (vf1 :class vf) @@ -69,6 +78,7 @@ ;; definition for function vector-reflect-flat-above! (defun vector-reflect-flat-above! ((arg0 vector) (arg1 vector) (arg2 vector)) + "Not really a reflect. Same as flatten." (rlet ((acc :class vf) (vf0 :class vf) (vf1 :class vf) @@ -119,6 +129,9 @@ ;; definition for function vector-segment-distance-point! (defun vector-segment-distance-point! ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 vector)) + "Compute the distance from a point to the closest point on the line segment. +arg0 is the point. arg1/arg2 are the endpoints of the line segment. +arg3 is an optional output closest point." (local-vars (v0-0 float) (v1-0 float) (v1-1 float)) (rlet ((acc :class vf) (Q :class vf) @@ -190,6 +203,8 @@ ;; definition for function vector-line-distance ;; INFO: Used lq/sq (defun vector-line-distance ((arg0 vector) (arg1 vector) (arg2 vector)) + "Weird function: given a point arg1, and an infinite line connecting arg2 and arg1, compute the distance +from arg0 to that line." (let* ((a1-3 (vector-normalize! (vector-! (new-stack-vector0) arg2 arg1) 1.0)) (gp-1 (vector-! (new-stack-vector0) arg0 arg1)) (f0-1 (vector-dot a1-3 gp-1)) @@ -202,6 +217,7 @@ ;; definition for function vector-line-distance-point! ;; INFO: Used lq/sq (defun vector-line-distance-point! ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 vector)) + "Same as above function, but returns the point on arg2/arg1 in arg3 (ignored if #f)" (let* ((a1-3 (vector-normalize! (vector-! (new-stack-vector0) arg2 arg1) 1.0)) (s4-1 (vector-! (new-stack-vector0) arg0 arg1)) (f0-1 (vector-dot a1-3 s4-1)) @@ -216,6 +232,7 @@ ;; definition for function vector-segment-overlap (defun vector-segment-overlap ((arg0 vector) (arg1 vector) (arg2 vector)) + "Seems to compute (v1 - v0).dot(v2 - v1), but in a weird way." (let* ((gp-1 (vector-! (new 'stack-no-clear 'vector) arg1 arg2)) (s5-0 (vector-normalize-copy! (new 'stack-no-clear 'vector) gp-1 1.0)) ) @@ -228,6 +245,7 @@ ;; definition for function line-sphere-intersection? (defun line-sphere-intersection? ((arg0 vector) (arg1 vector) (arg2 vector)) + "Does [arg1, arg2] intersect sphere arg0?" (let ((s5-0 (new 'stack-no-clear 'vector))) (let ((s3-0 (new 'stack-no-clear 'vector)) (f30-0 0.0) @@ -257,6 +275,7 @@ ;; definition for function vector-orient-by-quat! (defun vector-orient-by-quat! ((arg0 vector) (arg1 vector) (arg2 quaternion)) + "Rotate a vector by a quaternion." (rlet ((acc :class vf) (vf0 :class vf) (vf1 :class vf) @@ -303,6 +322,7 @@ ;; definition for function vector-inv-orient-by-quat! ;; ERROR: Bad vector register dependency: vf7 (defun vector-inv-orient-by-quat! ((arg0 vector) (arg1 vector) (arg2 quaternion)) + "Rotate a vector by the inverse rotation." (rlet ((acc :class vf) (vf0 :class vf) (vf1 :class vf) @@ -384,12 +404,16 @@ ;; definition for function forward-up->inv-matrix (defun forward-up->inv-matrix ((arg0 matrix) (arg1 vector) (arg2 vector)) + "Create a matrix representing an inverse transform where arg1 is forward (+z) +and arg2 is up (+y). Will use the pitch of forward." (forward-down->inv-matrix arg0 arg1 (vector-negate! (new 'stack-no-clear 'vector) arg2)) ) ;; definition for function forward-up-nopitch->inv-matrix ;; INFO: Used lq/sq (defun forward-up-nopitch->inv-matrix ((arg0 matrix) (arg1 vector) (arg2 vector)) + "Create a matrix representing an inverse transform where arg1 is forward (+z) +and arg2 is up (+y). Will not use the pitch of forward." (forward-down-nopitch->inv-matrix arg0 arg1 (vector-negate! (new-stack-vector0) arg2)) ) @@ -411,6 +435,7 @@ ;; definition for function quaternion-from-two-vectors! ;; INFO: Used lq/sq (defun quaternion-from-two-vectors! ((arg0 quaternion) (arg1 vector) (arg2 vector)) + "Create a quaternion representing the rotation between two vectors." (let* ((s5-0 (vector-cross! (new-stack-vector0) arg1 arg2)) (f1-0 (vector-length s5-0)) (f0-1 (vector-dot arg1 arg2)) @@ -428,6 +453,8 @@ ;; definition for function quaternion-from-two-vectors-partial! ;; INFO: Used lq/sq (defun quaternion-from-two-vectors-partial! ((arg0 quaternion) (arg1 vector) (arg2 vector) (arg3 float)) + "Create a quaternion representing the rotation between two vectors, +doing arg3 fraction of the total rotation." (let* ((s5-0 (vector-cross! (new-stack-vector0) arg1 arg2)) (f0-0 (vector-length s5-0)) (f1-1 (+ 1.0 (* arg3 (+ -1.0 (vector-dot arg1 arg2))))) @@ -501,6 +528,7 @@ ;; definition for function matrix-from-two-vectors! ;; INFO: Used lq/sq (defun matrix-from-two-vectors! ((arg0 matrix) (arg1 vector) (arg2 vector)) + "Create a rotation matrix representing the rotation between two vectors." (let* ((a1-3 (vector-normalize! (vector-cross! (new-stack-vector0) arg2 arg1) 1.0)) (f0-1 (vector-dot arg1 arg2)) (f1-0 1.0) @@ -514,6 +542,8 @@ ;; definition for function matrix-from-two-vectors-max-angle! ;; INFO: Used lq/sq (defun matrix-from-two-vectors-max-angle! ((arg0 matrix) (arg1 vector) (arg2 vector) (arg3 float)) + "Create a rotation matrix representing the rotation between two vectors, +allowing at most a rotation of arg3 degrees." (let ((s4-1 (vector-normalize! (vector-cross! (new-stack-vector0) arg2 arg1) 1.0)) (f30-0 (vector-dot arg1 arg2)) (f28-0 (cos arg3)) @@ -538,6 +568,11 @@ ;; definition for function matrix-from-two-vectors-smooth! (defun matrix-from-two-vectors-smooth! ((arg0 matrix) (arg1 vector) (arg2 vector) (arg3 float) (arg4 int)) + "This function can help smoothly rotate from a current heading vector to a target one. +It returns a rotation to move arg1 closer to arg2, subject to two different speed limits. +arg3 is a rotations-per-frame rate. This limit takes frame rate into account (when lagging, the rotation is larger) +arg4 is a 'slow down when getting close to the end' limit. +This is used in rotate-toward-orientation, which is much improved from jak 1." (let* ((s5-1 (vector-normalize! (vector-cross! (new 'stack-no-clear 'vector) arg2 arg1) 1.0)) (f0-1 (vector-dot arg1 arg2)) (f0-2 (acos f0-1)) @@ -551,6 +586,8 @@ ;; definition for function matrix-from-two-vectors-the-long-way-smooth! (defun matrix-from-two-vectors-the-long-way-smooth! ((arg0 matrix) (arg1 vector) (arg2 vector) (arg3 float) (arg4 int)) + "Same as above, but rotates you away from the target. +Note that the 'near the end' smoothing will apply when you're near the target." (let* ((s5-1 (vector-normalize! (vector-cross! (new 'stack-no-clear 'vector) arg2 arg1) 1.0)) (f0-1 (vector-dot arg1 arg2)) (f0-3 (- (acos f0-1))) @@ -564,6 +601,7 @@ ;; definition for function quaternion-from-two-vectors-smooth! (defun quaternion-from-two-vectors-smooth! ((arg0 quaternion) (arg1 vector) (arg2 vector) (arg3 float) (arg4 int)) + "Same as above, but returns a quaternion." (let ((a1-1 (matrix-from-two-vectors-smooth! (new 'stack-no-clear 'matrix) arg1 arg2 arg3 arg4))) (matrix->quaternion arg0 a1-1) ) @@ -571,6 +609,8 @@ ;; definition for function matrix-from-two-vectors-max-angle-partial! (defun matrix-from-two-vectors-max-angle-partial! ((arg0 matrix) (arg1 vector) (arg2 vector) (arg3 float) (arg4 float)) + "Create a rotation matrix representing the given fraction of the rotation between two heading vectors, +rotating by at most the given angle." (let* ((s4-1 (vector-normalize! (vector-cross! (new 'stack-no-clear 'vector) arg2 arg1) 1.0)) (f28-0 (vector-dot arg1 arg2)) (f30-0 (cos arg3)) @@ -597,6 +637,7 @@ ;; definition for function matrix-from-two-vectors-partial-linear! ;; INFO: Used lq/sq (defun matrix-from-two-vectors-partial-linear! ((arg0 matrix) (arg1 vector) (arg2 vector) (arg3 float)) + "Create a rotation matrix representing doing arg3 fraction of the rotation between two vectors." (let ((gp-1 (vector-normalize! (vector-cross! (new-stack-vector0) arg2 arg1) 1.0)) (f0-1 (vector-dot arg1 arg2)) ) @@ -648,6 +689,7 @@ ;; definition for function matrix-rot-diff! ;; INFO: Used lq/sq (defun matrix-rot-diff! ((arg0 vector) (arg1 matrix) (arg2 matrix)) + "Get the difference of rotation between two matrices, expressed as a quaternion." (let ((s3-0 (new-stack-quaternion0)) (s2-0 (new-stack-quaternion0)) (s5-0 (new-stack-quaternion0)) @@ -675,6 +717,7 @@ ;; definition for function quaternion-seek ;; INFO: Used lq/sq (defun quaternion-seek ((arg0 quaternion) (arg1 quaternion) (arg2 quaternion) (arg3 float) (arg4 float)) + "Strange quaternion rotate toward function. arg3 is ignored. arg4 is the max seek amount." (let ((s5-0 (new-stack-matrix0)) (s4-0 (new-stack-matrix0)) ) @@ -690,6 +733,7 @@ ;; definition for function vector-deg-seek ;; INFO: Used lq/sq (defun vector-deg-seek ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 float)) + "Make one vector closer to another, doing at most a rotation by arg3 degrees." (let ((s4-0 (new-stack-matrix0))) (matrix-from-two-vectors-max-angle! s4-0 arg1 arg2 arg3) (vector-matrix*! arg0 arg1 s4-0) @@ -699,6 +743,7 @@ ;; definition for function vector-deg-slerp ;; INFO: Used lq/sq (defun vector-deg-slerp ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 float)) + "Slerp for vectors. (imagine that they are the z axis of two frames)" (cond ((>= 0.0 arg3) (set! (-> arg0 quad) (-> arg1 quad)) @@ -724,6 +769,7 @@ ;; definition for function vector-vector-deg-slerp! ;; INFO: Used lq/sq (defun vector-vector-deg-slerp! ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 float) (arg4 vector)) + "Unused. No clue what this does." (local-vars (sv-112 (function float float float float))) (cond ((>= 0.0 arg3) @@ -756,6 +802,7 @@ ;; definition for function normal-of-plane (defun normal-of-plane ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 vector)) + "Given three points on a plane, compute the plane's normal." (rlet ((acc :class vf) (Q :class vf) (vf0 :class vf) @@ -789,6 +836,7 @@ ;; definition for function vector-3pt-cross! (defun vector-3pt-cross! ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 vector)) + "Cross product of 2 - 1 and 3 - 1. (will give a normal to the plane, but not of magnitude 1)" (rlet ((acc :class vf) (vf0 :class vf) (vf1 :class vf) @@ -814,6 +862,7 @@ ;; INFO: Used lq/sq ;; WARN: Return type mismatch int vs none. (defun closest-pt-in-triangle ((arg0 vector) (arg1 vector) (arg2 matrix) (arg3 vector)) + "arg2 is the vertices of the triangle, arg3 is the normal, arg1 is the input point, arg0 is the output." (local-vars (v1-0 float) (v1-4 uint) @@ -948,6 +997,7 @@ ;; WARN: Using logior on floats ;; WARN: Using logior on floats (defun point-in-triangle-cross ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 vector) (arg4 vector)) + "Check if point is in the triangle using cross product check (so you have to get the order of points right)." (local-vars (v1-0 float) (a0-1 float) (a1-1 float)) (rlet ((acc :class vf) (vf1 :class vf) @@ -998,6 +1048,9 @@ ;; definition for function point-in-plane-<-point+normal! (defun point-in-plane-<-point+normal! ((arg0 vector) (arg1 vector) (arg2 vector)) + "Very strange function. Takes a plane, in point-normal form, then returns some other point on that plane. +It will move 1m in two of {x, y, z} directions. The direction not moved in is the one which is closest to point-in-triangle-cross +in the same direction of the normal (this prevent moving huge distances for nearly vertical planes for example)." (let ((f0-3 (+ (* (-> arg2 x) (-> arg1 x)) (* (-> arg2 y) (-> arg1 y)) (* (-> arg2 z) (-> arg1 z))))) (set! (-> arg0 w) 1.0) (let ((f1-7 (fabs (-> arg2 x))) @@ -1045,6 +1098,7 @@ ;; ERROR: Unsupported inline assembly instruction kind - [mula.s f3, f3] ;; ERROR: Unsupported inline assembly instruction kind - [msub.s f5, f6, f5] (defun circle-circle-xz-intersect ((arg0 sphere) (arg1 sphere) (arg2 vector) (arg3 vector)) + "This function is unused and really complicated, so not implementing it for now." (local-vars (v0-0 uint) (f3-1 float) (f4-5 float) (f5-5 float) (f5-15 float) (f6-0 float) (f8-1 float)) (let ((f3-0 (-> arg0 x)) (f4-0 (-> arg0 z)) @@ -1239,6 +1293,7 @@ ;; INFO: Used lq/sq ;; WARN: Return type mismatch object vs none. (defun circle-test () + "Test the circle-circle-xz-intersect function." (let ((s4-0 (new 'stack 'sphere)) (a1-2 (new 'stack 'sphere)) (s5-0 (new-stack-vector0)) @@ -1269,6 +1324,7 @@ ;; INFO: Used lq/sq ;; WARN: Return type mismatch int vs none. (defun vector-circle-tangent-new ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 vector)) + "Unused." (rlet ((Q :class vf) (vf0 :class vf) (vf1 :class vf) @@ -1308,6 +1364,7 @@ ;; definition for function vector-circle-tangent ;; WARN: Return type mismatch int vs none. (defun vector-circle-tangent ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 vector)) + "Also unused." (let* ((s3-1 (vector-! (the-as vector (new 'stack-no-clear 'sphere)) arg1 arg0)) (f0-0 (vector-xz-length s3-1)) (f28-0 (acos (/ (-> arg1 w) f0-0))) @@ -1347,6 +1404,7 @@ ;; definition for function find-knot-span (defun find-knot-span ((arg0 int) (arg1 int) (arg2 float) (arg3 (inline-array vector))) + "Binary serach over knots to find which contains the value float in (arg0 arg1). Unused." (local-vars (v0-0 int)) (b! (= arg2 (-> (&-> arg3 0 data (+ arg0 1)) 0)) cfg-11 :delay (set! v0-0 arg0)) (let ((v1-3 (the int arg2))) @@ -1388,6 +1446,7 @@ ;; ERROR: Unsupported inline assembly instruction kind - [sll v1, a1, 2] ;; ERROR: Unsupported inline assembly instruction kind - [addu v1, a3, v1] (defun calculate-basis-functions-vector! ((arg0 vector) (arg1 int) (arg2 float) (arg3 (pointer float))) + "Calculate polynomial basis for a given control point." (local-vars (v1-0 int) (v1-1 object)) (.sll v1-0 arg1 2) (let ((a1-1 1.0) @@ -1449,6 +1508,13 @@ ;; ERROR: Unsupported inline assembly instruction kind - [addiu v1, s3, -3] ;; ERROR: Unsupported inline assembly instruction kind - [sll v1, v1, 4] (defun curve-evaluate! ((arg0 vector) (arg1 float) (arg2 (inline-array vector)) (arg3 int) (arg4 (pointer float)) (arg5 int)) + "Evaluate a curve. +arg0 is the output +arg1 is the input. +arg2 is control vertices. +arg3 is the number of control vertices. +arg4 is the knot points. +arg5 is the number of knots." (local-vars (v1-7 int) (v1-8 int) (v1-10 float) (s3-0 int)) (rlet ((acc :class vf) (vf0 :class vf) @@ -1550,12 +1616,14 @@ ;; definition for function curve-get-pos! (defun curve-get-pos! ((arg0 vector) (arg1 float) (arg2 curve)) + "Get the position on the curve at the given input." (curve-evaluate! arg0 arg1 (-> arg2 cverts) (-> arg2 num-cverts) (-> arg2 knots) (-> arg2 num-knots)) ) ;; definition for function curve-length ;; INFO: Used lq/sq (defun curve-length ((arg0 curve)) + "Compute the approximate curve length as the sum of distances between knots." (let ((s5-0 (new 'stack-no-clear 'vector)) (s4-0 (new 'stack-no-clear 'vector)) (s3-0 (* 3 (-> arg0 num-cverts))) @@ -1589,6 +1657,7 @@ ;; definition for function curve-copy! (defun curve-copy! ((arg0 curve) (arg1 curve)) + "Shallow copy a curve." (set! (-> arg0 cverts) (-> arg1 cverts)) (set! (-> arg0 num-cverts) (-> arg1 num-cverts)) (set! (-> arg0 knots) (-> arg1 knots)) @@ -1606,6 +1675,7 @@ ;; WARN: Stack slot offset 48 signed mismatch ;; WARN: Stack slot offset 48 signed mismatch (defun curve-closest-point ((arg0 curve) (arg1 vector) (arg2 float) (arg3 float) (arg4 int) (arg5 float)) + "Get the input value for the point on the curve. Approximate! And is O(n_knots)." (local-vars (sv-48 float)) (set! sv-48 arg3) (let ((s3-0 arg4) @@ -1668,11 +1738,13 @@ ;; definition for function vector-plane-distance (defun vector-plane-distance ((arg0 vector) (arg1 plane) (arg2 vector)) + "Unused." (vector-dot (vector-! (new 'stack-no-clear 'vector) arg0 (the-as vector (&-> arg1 x))) arg2) ) ;; definition for function intersect-ray-plane (defun intersect-ray-plane ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 vector)) + "arg1 is ray direction, arg3 is plane normal, others don't really make sense to me." (let ((f0-1 (vector-dot arg3 arg1))) (if (= f0-1 0.0) -1.0 diff --git a/test/decompiler/reference/jak2/engine/geometry/path-h_REF.gc b/test/decompiler/reference/jak2/engine/geometry/path-h_REF.gc index bdf97d22b3..19ee8e7ddb 100644 --- a/test/decompiler/reference/jak2/engine/geometry/path-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/geometry/path-h_REF.gc @@ -3,10 +3,11 @@ ;; definition of type path-control (deftype path-control (basic) - "An abstraction around a [[curve]], providing tools such as: -- debug drawing -- conveniant vertex accessing -- vertex finding/searching algorithms" + "The path-control is a reference a path data, which is just a list of points. +Although it contains a `curve`, the knot part is not populated, so it's just treated as +a bunch of line segments from the control points. +The child class curve-control does fill out the knot data and is a proper b-spline. +These path-controls are typically allocated on a process heap." ((flags path-control-flag) (name symbol) (process process-drawable) @@ -57,7 +58,7 @@ ;; definition of type curve-control (deftype curve-control (path-control) - "Identical in terms of data to a [[path-control]] but has different implementation" + "A curve-control is like a path control, but it has both control points and knot points." () (:methods (new (symbol type process symbol float) _type_) @@ -88,21 +89,22 @@ ;; WARN: Return type mismatch object vs path-control. (defmethod new path-control ((allocation symbol) (type-to-make type) - (arg0 process) - (arg1 symbol) - (arg2 float) - (arg3 entity) - (arg4 symbol) + (proc process) + (lump-name symbol) + (lump-time float) + (lump-actor entity) + (must-exist symbol) ) + "Allocate a new path-control, set up the curve to point to the specified lump data." (local-vars (v0-3 object) (sv-16 res-tag) (sv-32 float)) - (set! sv-32 arg2) - (let ((s0-0 arg3) - (s1-0 arg4) + (set! sv-32 lump-time) + (let ((s0-0 lump-actor) + (s1-0 must-exist) ) (if (not s0-0) - (set! s0-0 (-> arg0 entity)) + (set! s0-0 (-> proc entity)) ) - (when (= arg1 'path) + (when (= lump-name 'path) (let ((v0-0 (entity-actor-lookup s0-0 'path-actor 0))) (if v0-0 (set! s0-0 v0-0) @@ -112,7 +114,7 @@ (let ((s2-0 (the-as object 0))) (set! sv-16 (new 'static 'res-tag)) (let* ((t9-1 (method-of-type res-lump get-property-data)) - (a1-2 arg1) + (a1-2 lump-name) (a2-2 'interp) (t0-1 #f) (t1-1 (the-as (pointer res-tag) (& sv-16))) @@ -124,8 +126,8 @@ (set! s2-0 (object-new allocation type-to-make (the-as int (-> type-to-make size)))) (set! v0-3 (cond ((nonzero? (the-as path-control s2-0)) - (set! (-> (the-as path-control s2-0) process) (the-as process-drawable arg0)) - (set! (-> (the-as path-control s2-0) name) arg1) + (set! (-> (the-as path-control s2-0) process) (the-as process-drawable proc)) + (set! (-> (the-as path-control s2-0) name) lump-name) (set! (-> (the-as path-control s2-0) curve cverts) (the-as (inline-array vector) s0-1)) (set! v0-3 (-> sv-16 elt-count)) (set! (-> (the-as path-control s2-0) curve num-cverts) (the-as int v0-3)) @@ -143,8 +145,8 @@ (cond ((nonzero? (the-as path-control s2-0)) (logior! (-> (the-as path-control s2-0) flags) (path-control-flag not-found)) - (set! (-> (the-as path-control s2-0) process) (the-as process-drawable arg0)) - (set! (-> (the-as path-control s2-0) name) arg1) + (set! (-> (the-as path-control s2-0) process) (the-as process-drawable proc)) + (set! (-> (the-as path-control s2-0) name) lump-name) (set! (-> (the-as path-control s2-0) curve cverts) (the-as (inline-array vector) #f)) (set! (-> (the-as path-control s2-0) curve num-cverts) 0) 0 diff --git a/test/decompiler/reference/jak2/engine/gfx/background/background-h_REF.gc b/test/decompiler/reference/jak2/engine/gfx/background/background-h_REF.gc index 1b1415fe00..d451f64cb9 100644 --- a/test/decompiler/reference/jak2/engine/gfx/background/background-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/background/background-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type background-work (deftype background-work (basic) + "List of all things for the background renderer to draw." ((tfrag-tree-count int32) (tfrag-trees drawable-tree-tfrag 8) (tfrag-levels level 8) diff --git a/test/decompiler/reference/jak2/engine/gfx/background/prototype_REF.gc b/test/decompiler/reference/jak2/engine/gfx/background/prototype_REF.gc index 92e6455691..992f82b5d2 100644 --- a/test/decompiler/reference/jak2/engine/gfx/background/prototype_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/background/prototype_REF.gc @@ -3,6 +3,7 @@ ;; definition for method 9 of type prototype-inline-array-shrub (defmethod login ((this prototype-inline-array-shrub)) + "Initialize the object after it is loaded." (let ((bsp-header (-> *level* level *level-index* bsp))) (dotimes (shrub-idx (-> this length)) (let ((shrub (-> this data shrub-idx))) diff --git a/test/decompiler/reference/jak2/engine/gfx/background/subdivide-h_REF.gc b/test/decompiler/reference/jak2/engine/gfx/background/subdivide-h_REF.gc index be36f0d894..55323dac99 100644 --- a/test/decompiler/reference/jak2/engine/gfx/background/subdivide-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/background/subdivide-h_REF.gc @@ -3,6 +3,8 @@ ;; definition of type subdivide-settings (deftype subdivide-settings (basic) + "Input settings for distances for switching mesh level of details. +These are set by the level code and read by rendering code." ((dist float 5) (meters float 5) (close float 8) @@ -41,6 +43,7 @@ ;; definition of type subdivide-dists (deftype subdivide-dists (structure) + "Unused subdivide distances. Internally, tfrag/tie figure these out instead." ((data uint32 32) (vector vector 8 :inline :overlay-at (-> data 0)) (k0s uint128 4 :overlay-at (-> data 0)) @@ -65,6 +68,7 @@ ;; definition of type terrain-stats (deftype terrain-stats (structure) + "Desptie the name `terrain-stats`, these are more general triangle stats for all renderers." ((pris tr-stat :inline) (tie-generic tr-stat :inline) (tie-vanish tr-stat :inline) @@ -175,6 +179,9 @@ ;; definition of type background-area (deftype background-area (structure) + "Scratchpad memory layout for most background rendering +This uses the full scratchpad so it should only be used when the stack isn't on the scratchpad (rendering code). +Interestingly, dma-area went from a union of all the -dma types to a plain array of bytes in jak 3." ((dma-area dma-area :inline) (vis-list uint8 2048) ) @@ -195,6 +202,7 @@ ;; definition of type foreground-area (deftype foreground-area (structure) + "Scratchpad memory layout for most foreground rendering." ((generic-work generic-work :inline) (foreground-work foreground-work :inline :overlay-at (-> generic-work saves ptr-dma)) (joint-work joint-work :inline :overlay-at (-> generic-work saves ptr-dma)) @@ -221,6 +229,7 @@ ;; definition of type region-prim-area (deftype region-prim-area (structure) + "Scratchpad memory layout for regions." ((region-prim-list region-prim-list :inline) (pos vector :inline) (unknown-vector-uiyb1 vector :inline) @@ -275,6 +284,7 @@ ;; definition of type sprite-area (deftype sprite-area (structure) + "Scratchpad memory layout for sprites." ((clock-data vector 13 :inline) (buffer uint8 :dynamic) ) @@ -295,6 +305,7 @@ ;; definition of type work-area (deftype work-area (structure) + "All scratchpad memory layouts." ((background background-area :inline) (foreground foreground-area :inline :overlay-at (-> background dma-area ocean-vertex 0)) (region-prim region-prim-area :inline :overlay-at (-> background dma-area ocean-vertex 0)) @@ -319,6 +330,7 @@ ;; definition of type terrain-context (deftype terrain-context (structure) + "Useless wrapper around work-area. (this added some stuff in jak 1)" ((work work-area :inline) ) ) diff --git a/test/decompiler/reference/jak2/engine/gfx/background/tfrag/tfrag-h_REF.gc b/test/decompiler/reference/jak2/engine/gfx/background/tfrag/tfrag-h_REF.gc index bb865e83aa..e80fc7f292 100644 --- a/test/decompiler/reference/jak2/engine/gfx/background/tfrag/tfrag-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/background/tfrag/tfrag-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type tfragment-stats (deftype tfragment-stats (structure) + "Triangle and vertex stats for a single tfragment." ((num-tris uint16 4) (num-dverts uint16 4) ) @@ -23,6 +24,7 @@ ;; definition of type tfragment-debug-data (deftype tfragment-debug-data (structure) + "Optional debug information (stats, lines) for a tfragment." ((stats tfragment-stats :inline) (debug-lines (array vector-array)) ) @@ -43,6 +45,7 @@ ;; definition of type generic-tfragment (deftype generic-tfragment (structure) + "Unused. Could have been a way to render tfrag's through generic." ((dummy int32) ) ) @@ -61,6 +64,7 @@ ;; definition of type tfragment (deftype tfragment (drawable) + "A tfrag mesh fragment. This is just references to DMA data, plus some metadata." ((color-index uint16 :offset 6) (debug-data tfragment-debug-data :offset 8) (color-indices uint32 :offset 12) @@ -140,6 +144,7 @@ ;; definition of type drawable-tree-tfrag (deftype drawable-tree-tfrag (drawable-tree) + "top level tfrag tree." ((time-of-day-pal time-of-day-palette :offset 12) (arrays drawable-inline-array :dynamic :offset 32) ) @@ -157,6 +162,7 @@ ;; definition of type tfrag-dists (deftype tfrag-dists (structure) + "Distances for mesh level-of-detail blending for use on VU1." ((data uint32 16) (vector vector 4 :inline :overlay-at (-> data 0)) (k0s vector 2 :inline :overlay-at (-> data 0)) @@ -181,6 +187,7 @@ ;; definition of type tfrag-data (deftype tfrag-data (structure) + "Constants for VU1 data memory for tfrag rendering." ((data uint32 56 :offset 0) (vector vector 14 :inline :overlay-at (-> data 0)) (fog vector :inline :overlay-at (-> vector 0)) @@ -227,6 +234,7 @@ ;; definition of type tfrag-control (deftype tfrag-control (structure) + "VU1 'control' data containing address and counters." ((num-base-points uint32) (num-shared-base-points uint32) (num-level0-points uint32) @@ -283,6 +291,7 @@ ;; definition of type tfrag-stats (deftype tfrag-stats (structure) + "TFRAG statistics computed on EE." ((from int32) (to int32) (cnt int32) @@ -349,6 +358,7 @@ ;; definition of type tfrag-work (deftype tfrag-work (structure) + "Scratch space for generating TFRAG DMA." ((base-tmpl dma-packet :inline) (level-0-tmpl dma-packet :inline) (common-tmpl dma-packet :inline) @@ -415,6 +425,7 @@ ;; definition of type tfrag-dma (deftype tfrag-dma (structure) + "Memory layout for to/from scratchpad for tfrag." ((banka tfragment 16 :inline) (bankb tfragment 16 :inline) (outa uint128 128) diff --git a/test/decompiler/reference/jak2/engine/gfx/background/tie/tie-h_REF.gc b/test/decompiler/reference/jak2/engine/gfx/background/tie/tie-h_REF.gc index 968fd52abd..da2ce25d82 100644 --- a/test/decompiler/reference/jak2/engine/gfx/background/tie/tie-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/background/tie/tie-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type tie-fragment-debug (deftype tie-fragment-debug (structure) + "Optional debug information about a tie-fragment." ((num-tris uint16) (num-dverts uint16) (debug-lines (array vector-array)) @@ -25,6 +26,7 @@ ;; definition of type tie-fragment (deftype tie-fragment (drawable) + "A mesh fragment of a TIE. This is a chunk of mesh that is rendered by VU1, stored as DMA chains." ((gif-ref (inline-array adgif-shader) :overlay-at id) (point-ref uint32 :offset 8) (color-index uint16 :offset 12) @@ -73,6 +75,7 @@ ;; definition of type instance-tie (deftype instance-tie (instance) + "A TIE model instance." ((color-indices uint32 :offset 8) (bucket-ptr prototype-bucket-tie :offset 12) (max-scale uint16 :overlay-at (-> origin data 3)) @@ -110,6 +113,7 @@ ;; definition of type drawable-tree-instance-tie (deftype drawable-tree-instance-tie (drawable-tree) + "Top-level drawable-tree for TIEs" ((prototypes proxy-prototype-array-tie :offset 8) ) ) @@ -142,6 +146,7 @@ ;; definition of type tie-matrix (deftype tie-matrix (structure) + "Per-instance matrix for TIE VU1 rendering." ((mat matrix :inline) (morph qword :inline) (fog qword :inline) @@ -174,6 +179,7 @@ ;; definition of type instance-tie-work (deftype instance-tie-work (structure) + "workspace for TIE instance DMA generation" ((wind-const vector :inline) (hmge-d vector :inline) (hvdf-offset vector :inline) @@ -282,6 +288,7 @@ ;; definition of type instance-tie-dma (deftype instance-tie-dma (structure) + "Scratchpad memory layout for TIE instance DMA generation." ((banka instance-tie 32 :inline) (bankb instance-tie 32 :inline) (outa uint128 256) @@ -308,6 +315,7 @@ ;; definition of type prototype-tie-work (deftype prototype-tie-work (structure) + "workspace for TIE protype DMA generation." ((upload-flushe dma-packet :inline) (upload-palette dma-packet :inline) (upload-model-0 dma-packet :inline) diff --git a/test/decompiler/reference/jak2/engine/gfx/background/tie/tie_REF.gc b/test/decompiler/reference/jak2/engine/gfx/background/tie/tie_REF.gc index 7ef10e354d..32dd341ece 100644 --- a/test/decompiler/reference/jak2/engine/gfx/background/tie/tie_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/background/tie/tie_REF.gc @@ -3,6 +3,7 @@ ;; definition for method 9 of type tie-fragment (defmethod login ((this tie-fragment)) + "Initialize the object after it is loaded." (let ((s5-0 (the-as adgif-shader (-> this gif-ref))) (s4-0 (/ (-> this tex-count) (the-as uint 5))) ) @@ -54,12 +55,14 @@ ;; definition for method 9 of type drawable-tree-instance-tie ;; INFO: this function exists in multiple non-identical object files (defmethod login ((this drawable-tree-instance-tie)) + "Initialize the object after it is loaded." this ) ;; definition for method 9 of type drawable-tree-instance-tie ;; INFO: this function exists in multiple non-identical object files (defmethod login ((this drawable-tree-instance-tie)) + "Initialize the object after it is loaded." (dotimes (s5-0 (-> this length)) (login (-> this data s5-0)) ) @@ -79,6 +82,7 @@ ;; definition for method 9 of type prototype-tie (defmethod login ((this prototype-tie)) + "Initialize the object after it is loaded." (dotimes (s5-0 (-> this length)) (login (-> this data s5-0)) ) diff --git a/test/decompiler/reference/jak2/engine/gfx/foreground/eye-h_REF.gc b/test/decompiler/reference/jak2/engine/gfx/foreground/eye-h_REF.gc index 520972cd2c..e116d9e09d 100644 --- a/test/decompiler/reference/jak2/engine/gfx/foreground/eye-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/foreground/eye-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type eye (deftype eye (structure) + "Data for a single eye." ((data vector 2 :inline) (x float :overlay-at (-> data 0 data 0)) (y float :overlay-at (-> data 0 data 1)) @@ -33,6 +34,7 @@ ;; definition of type eye-control (deftype eye-control (structure) + "Information about the state of both eyes of a [[process-drawable]]." ((process handle) (draw-flag symbol) (different-eyes symbol) @@ -67,6 +69,7 @@ ;; definition of type eye-control-array (deftype eye-control-array (basic) + "An array of [[eye-control]]s." ((data eye-control 16 :inline) ) ) @@ -104,6 +107,7 @@ ;; definition of type eye-work (deftype eye-work (structure) + "Eye renderer DMA data." ((sprite-tmpl dma-gif-packet :inline) (sprite-tmpl2 dma-gif-packet :inline) (adgif-tmpl dma-gif-packet :inline) diff --git a/test/decompiler/reference/jak2/engine/gfx/foreground/foreground-h_REF.gc b/test/decompiler/reference/jak2/engine/gfx/foreground/foreground-h_REF.gc index 4571631a96..da969c3e62 100644 --- a/test/decompiler/reference/jak2/engine/gfx/foreground/foreground-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/foreground/foreground-h_REF.gc @@ -3,6 +3,8 @@ ;; definition of type mercneric-chain (deftype mercneric-chain (structure) + "A DMA chain for drawing with mercneric, and metadata needed to append. +This chain is assumed to run with a specific tpage from a specific level available." ((first uint32) (next uint32) (state generic-bucket-state :inline) @@ -28,6 +30,8 @@ ;; definition of type merc-chain (deftype merc-chain (structure) + "A DMA chain for drawing with merc. +This chain is assumed to run with a specific tpage from a specific level available." ((first dma-packet) (patch dma-packet) (vu1-bucket bucket-id) @@ -51,6 +55,7 @@ ;; definition of type foreground-bucket (deftype foreground-bucket (structure) + "A foreground bucket is merc, emerc, and mercneric chain for a given texture mode." ((merc merc-chain :inline) (emerc merc-chain :inline) (mercneric mercneric-chain :inline) @@ -73,6 +78,9 @@ ;; definition of type foreground-level-buckets (deftype foreground-level-buckets (structure) + "Collection of buckets for a single level. +Each bucket has a different texture. The order is: +tfrag, pris, shrub, alpha, water, pris, pris2" ((data foreground-bucket 7 :inline) ) ) @@ -91,6 +99,7 @@ ;; definition of type foreground-bucket-grid (deftype foreground-bucket-grid (structure) + "Array of buckets for each level, plus the single warp chain shared between everybody." ((level-buckets foreground-level-buckets 7 :inline) (warp-chain mercneric-chain :inline) ) @@ -111,6 +120,8 @@ ;; definition of type foreground-regs (deftype foreground-regs (structure) + "Frequently accessed foreground values. These are in scratchpad for fast access +during foreground processing." ((dist float) (merc-used uint32) (emerc-used uint32) @@ -155,6 +166,9 @@ ;; definition of type foreground-work (deftype foreground-work (structure) + "Memory map for scratchpad during foreground processing. +This is not used by the renderers, bone matrix, or joint code - just the code +that assigns stuff to buckets and prepares DMA for merc (or requests for generic merc)." ((regs foreground-regs :inline) (draw-index-map uint8 7 :offset 64) (grid foreground-bucket-grid :inline) @@ -197,6 +211,7 @@ ;; definition of type texscroll-globals (deftype texscroll-globals (structure) + "List of all merc-effects that need texscroll applied." ((requests int32) (effects merc-effect 32) ) @@ -217,6 +232,8 @@ ;; definition of type merc-effect-bucket-info (deftype merc-effect-bucket-info (structure) + "Scratch info computed per-merc-effect by the foreground code, then later read by merc +DMA generation. This is only for the currently-processing merc model's effects." ((color-fade rgba) (alpha uint8 :offset 3) (merc-path uint8) @@ -245,6 +262,7 @@ ;; definition of type merc-bucket-info (deftype merc-bucket-info (structure) + "Scratch info for the current merc-ctrl. Written by the foreground code, read by merc DMA generation." ((light vu-lights :inline) (needs-clip int32) (need-mercprime-if-merc int32) @@ -271,6 +289,7 @@ ;; definition of type foreground-globals (deftype foreground-globals (structure) + "The foreground renderer state: all DMA chains, settings for the current merc-ctrl, texscroll list." ((foreground-grid foreground-bucket-grid :inline) (merc-bucket-info merc-bucket-info :inline) (texscroll texscroll-globals :inline) @@ -296,6 +315,7 @@ ;; definition of type shadow-dma-packet (deftype shadow-dma-packet (structure) + "DMA tag for submitting shadow data." ((tag generic-merc-tag :inline) (settings shadow-settings :inline) (geo-ref dma-packet :inline) diff --git a/test/decompiler/reference/jak2/engine/gfx/foreground/merc/merc-h_REF.gc b/test/decompiler/reference/jak2/engine/gfx/foreground/merc/merc-h_REF.gc index 24877ebe82..218d174951 100644 --- a/test/decompiler/reference/jak2/engine/gfx/foreground/merc/merc-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/foreground/merc/merc-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type ripple-merc-query (deftype ripple-merc-query (inline-array-class) + "Information about which merc vertices to apply the 'ripple' effect to." ((start-vertex int32) (vertex-skip int32) (vertex-count int32) @@ -34,6 +35,7 @@ ;; definition of type merc-byte-header (deftype merc-byte-header (structure) + "Header for a single [[merc-fragment]] uploaded to the VU." ((srcdest-off uint8) (rgba-off uint8) (lump-off uint8) @@ -78,6 +80,7 @@ ;; definition of type merc-fragment (deftype merc-fragment (structure) + "A single merc fragment that fits into VU memory." ((header merc-byte-header :inline) (rest uint8 1) ) @@ -101,6 +104,7 @@ ;; definition of type merc-vtx (deftype merc-vtx (structure) + "A packed merc vertex." ((mat-0 uint8) (mat-1 uint8) (nrm-x uint8) @@ -141,6 +145,7 @@ ;; definition of type merc-fp-header (deftype merc-fp-header (structure) + "Merc header for a [[merc-fragment]]'s floating point data." ((x-add float) (y-add float) (z-add float) @@ -171,12 +176,13 @@ ;; definition for function merc-fragment-fp-data ;; WARN: Return type mismatch int vs merc-fp-header. -(defun merc-fragment-fp-data ((arg0 merc-fragment)) - (the-as merc-fp-header (+ (the-as uint arg0) (* (-> arg0 header mm-quadword-fp-off) 16))) +(defun merc-fragment-fp-data ((frag merc-fragment)) + (the-as merc-fp-header (+ (the-as uint frag) (* (-> frag header mm-quadword-fp-off) 16))) ) ;; definition of type merc-mat-dest (deftype merc-mat-dest (structure) + "Metadata for a merc matrix upload." ((matrix-number uint8) (matrix-dest uint8) ) @@ -198,6 +204,7 @@ ;; definition of type merc-fragment-control (deftype merc-fragment-control (structure) + "Data about a [[merc-fragment]] needed for merc DMA generation." ((unsigned-four-count uint8) (lump-four-count uint8) (fp-qwc uint8) @@ -224,6 +231,7 @@ ;; definition of type merc-blend-data (deftype merc-blend-data (structure) + "Packed BLERC data." ((int8-data int8 :dynamic) ) ) @@ -242,6 +250,7 @@ ;; definition of type merc-blend-ctrl (deftype merc-blend-ctrl (structure) + "Information about the vertices of a model modified by BLERC." ((blend-vtx-count uint8) (nonzero-index-count uint8) (bt-index uint8 :dynamic) @@ -264,6 +273,7 @@ ;; definition of type mei-envmap-tint (deftype mei-envmap-tint (structure) + "Data for the extra 'envmap tint' effect." ((fade0 float) (fade1 float) (tint rgba) @@ -288,6 +298,7 @@ ;; definition of type mei-texture-scroll (deftype mei-texture-scroll (structure) + "Data for the extra 'texscroll' effect." ((max-dist float) (st-int-scale uint8) (time-factor uint8) @@ -318,6 +329,7 @@ ;; definition of type mei-ripple (deftype mei-ripple (structure) + "Data for the extra 'ripple' effect." ((x-base float) (z-base float) (grid-size float) @@ -342,6 +354,7 @@ ;; definition of type merc-extra-info (deftype merc-extra-info (structure) + "Info for merc extra effects." ((envmap-tint-offset uint8) (shader-offset uint8) (texture-scroll-offset uint8) @@ -368,6 +381,7 @@ ;; definition of type merc-effect (deftype merc-effect (structure) + "A collection of [[merc-fragment]]s with data for any extra effects." ((frag-geo merc-fragment) (frag-ctrl merc-fragment-control) (blend-data merc-blend-data) @@ -413,6 +427,7 @@ ;; definition of type merc-eye-ctrl (deftype merc-eye-ctrl (structure) + "Eye info for both eyes of a merc model." ((eye-slot int8) (shader-offset int8) (shader-count int8) @@ -449,6 +464,7 @@ ;; definition of type merc-eye-anim-frame (deftype merc-eye-anim-frame (structure) + "A single frame of a merc eye animation." ((pupil-trans-x int8) (pupil-trans-y int8) (blink int8) @@ -480,6 +496,7 @@ ;; definition of type merc-eye-anim-block (deftype merc-eye-anim-block (structure) + "A list of eye animation frames." ((max-frame int16) (data merc-eye-anim-frame :inline :dynamic) ) @@ -518,6 +535,8 @@ ;; definition of type merc-ctrl-header (deftype merc-ctrl-header (structure) + "The header for a [[merc-ctrl]], +containing metadata about the model used for drawing." ((xyz-scale float) (st-magic uint32) (st-out-a uint32) @@ -628,6 +647,8 @@ ;; definition of type merc-ctrl (deftype merc-ctrl (art-element) + "The merc data for a single model as it's stored in an art group. +Consists of a header and a list of [[merc-effect]]s." ((num-joints int32 :overlay-at (-> pad 0)) (seg-table (array uint64) :overlay-at (-> pad 4)) (header merc-ctrl-header :inline) diff --git a/test/decompiler/reference/jak2/engine/gfx/generic/generic-h_REF.gc b/test/decompiler/reference/jak2/engine/gfx/generic/generic-h_REF.gc index 1e2efc4c5a..0608c155f1 100644 --- a/test/decompiler/reference/jak2/engine/gfx/generic/generic-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/generic/generic-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type gsf-vertex (deftype gsf-vertex (structure) + "Vertex used by generic. GSF = generic stripped fragment?" ((data uint32 8) (byte uint8 32 :overlay-at (-> data 0)) (quad uint128 2 :overlay-at (-> data 0)) @@ -60,6 +61,8 @@ ;; definition of type gsf-fx-vertex (deftype gsf-fx-vertex (structure) + "Color/texture data only. Possibly used to share with a gsf-vertex with +the same position/normal." ((clr vector4ub :inline) (tex vector2uh :inline) ) @@ -98,6 +101,7 @@ ;; definition of type gsf-header (deftype gsf-header (structure) + "Header for generic data." ((num-strips uint8) (num-new-vtxs uint8) (num-dps uint16) diff --git a/test/decompiler/reference/jak2/engine/gfx/generic/generic-vu1-h_REF.gc b/test/decompiler/reference/jak2/engine/gfx/generic/generic-vu1-h_REF.gc index cc4cc06e04..52b1064baf 100644 --- a/test/decompiler/reference/jak2/engine/gfx/generic/generic-vu1-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/generic/generic-vu1-h_REF.gc @@ -3,6 +3,9 @@ ;; definition of type pris-mtx (deftype pris-mtx (structure) + "Matrix for merc rendering. Named after the earlier 'pris' renderer. +Contains a transformation matrix for vertices, one for normals, and a scale. +This matrix is likely not used by generic VU1, but is used by the merc -> generic converter." ((data float 32) (vector vector 8 :overlay-at (-> data 0)) (t-mtx matrix :inline :overlay-at (-> data 0)) @@ -51,6 +54,7 @@ ;; definition of type generic-constants (deftype generic-constants (structure) + "Constant data sent to VU1 for generic rendering." ((fog vector :inline) (adgif gs-gif-tag :inline) (hvdf-offset vector :inline) diff --git a/test/decompiler/reference/jak2/engine/gfx/hw/display_REF.gc b/test/decompiler/reference/jak2/engine/gfx/hw/display_REF.gc index 02eb314ef9..9fd74f8327 100644 --- a/test/decompiler/reference/jak2/engine/gfx/hw/display_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/hw/display_REF.gc @@ -3,11 +3,13 @@ ;; definition for function get-current-time (defun get-current-time () + "Get the base-clock time." (-> *display* base-clock frame-counter) ) ;; definition for function get-integral-current-time (defun get-integral-current-time () + "Get the number of frames that have happened." (-> *display* base-clock integral-frame-counter) ) @@ -27,6 +29,7 @@ ;; definition for function set-display (defun set-display ((arg0 display)) + "Allocate and initialize clocks for the display." (dotimes (s5-0 13) (set! (-> arg0 clock s5-0) (new 'global 'clock s5-0)) ) @@ -55,6 +58,7 @@ ;; definition for function allocate-dma-buffers (defun allocate-dma-buffers ((arg0 display)) + "Allocate the main, debug, and calc dma buffers." (when (zero? (-> arg0 frames 0 calc-buf)) (set! (-> arg0 frames 0 calc-buf) (new 'global 'dma-buffer 10000)) (set! (-> arg0 frames 1 calc-buf) (new 'global 'dma-buffer 10000)) @@ -76,6 +80,7 @@ ;; definition for function draw-sprite2d-xy ;; WARN: Return type mismatch pointer vs none. (defun draw-sprite2d-xy ((arg0 dma-buffer) (arg1 int) (arg2 int) (arg3 int) (arg4 int) (arg5 rgba)) + "Draw a sprite primitive with the given color and dimensions." (let* ((t2-1 (new 'stack 'draw-context arg1 arg2 arg3 arg4 arg5)) (a1-3 (max 1792 (min 2304 (+ (-> t2-1 orgx) 1792)))) (a0-5 (max 1840 (min 2256 (+ (-> t2-1 orgy) 1840)))) @@ -134,6 +139,7 @@ ;; definition for function draw-sprite2d-xy-absolute ;; WARN: Return type mismatch pointer vs none. (defun draw-sprite2d-xy-absolute ((arg0 dma-buffer) (arg1 int) (arg2 int) (arg3 int) (arg4 int) (arg5 rgba)) + "Draw a sprite primitive, setting the gs-xzyf register to exactly the values specified (no offset/clamp)." (let ((t2-0 (+ arg1 1792)) (a1-1 (+ arg2 1840)) (v1-0 (-> arg0 base)) @@ -188,6 +194,7 @@ ;; definition for function draw-quad2d ;; WARN: Return type mismatch pointer vs none. (defun draw-quad2d ((arg0 dma-buffer) (arg1 draw-context)) + "Draw a quad that fills the entire context." (let ((a3-1 (max 1792 (min 2304 (+ (-> arg1 orgx) 1792)))) (a2-3 (max 1840 (min 2256 (+ (-> arg1 orgy) 1840)))) (t3-0 (-> arg1 width)) @@ -265,6 +272,7 @@ ;; definition for function screen-gradient (defun screen-gradient ((arg0 dma-buffer) (arg1 rgba) (arg2 rgba) (arg3 rgba) (arg4 rgba)) + "Fill the screen with a sprite with the given colors." (let ((a1-2 (new 'stack 'draw-context 0 0 512 416 (new 'static 'rgba)))) (set! (-> a1-2 color 0) arg1) (set! (-> a1-2 color 1) arg2) diff --git a/test/decompiler/reference/jak2/engine/gfx/hw/gs_REF.gc b/test/decompiler/reference/jak2/engine/gfx/hw/gs_REF.gc index 687454421c..ef63304202 100644 --- a/test/decompiler/reference/jak2/engine/gfx/hw/gs_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/hw/gs_REF.gc @@ -23,6 +23,7 @@ ;; definition for function psm-size (defun psm-size ((arg0 gs-psm)) + "Convert texture format to some type of size." (cond ((= arg0 (gs-psm mt8)) 64 @@ -41,6 +42,7 @@ ;; definition for function psm-page-height (defun psm-page-height ((arg0 gs-psm)) + "Convert texture format to some type of page height." (cond ((= arg0 (gs-psm mt8)) 64 @@ -59,6 +61,7 @@ ;; definition for function psm->string (defun psm->string ((arg0 gs-psm)) + "Get the name of a texture format." (case arg0 (((gs-psm ct24)) "ct24" @@ -163,6 +166,8 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition of type gs-bank (deftype gs-bank (structure) + "Memory layout of the GS's privileged registers (mapped to EE memory). +It is missing the SIGLBLID/LABELID register at 4224 (useless anyway?)" ((pmode gs-pmode) (smode2 gs-smode2 :offset 32) (dspfb1 gs-display-fb :offset 112) @@ -214,6 +219,7 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition of type gs-zbuf (deftype gs-zbuf (uint64) + "The GS's ZBUF registers make various settings regarding Z buffer." ((zbp uint16 :offset 0 :size 9) (psm gs-psm :offset 24 :size 4) (zmsk uint8 :offset 32 :size 1) @@ -222,6 +228,8 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition of type gs-xy-offset (deftype gs-xy-offset (uint64) + "The GS's XYOFFSET registers set the offset value for converting from the primitive coordinate +system to the window coordinate system." ((ofx uint16 :offset 0 :size 16) (ofy uint16 :offset 32 :size 16) ) @@ -229,6 +237,9 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition of type gs-scissor (deftype gs-scissor (uint64) + "The GS's SCISSOR registers specify the scissoring area. The coordinate values for +the upper-left/lower-right points of the enabled drawing area are specified by the window +coordinate system." ((scax0 uint16 :offset 0 :size 11) (scax1 uint16 :offset 16 :size 11) (scay0 uint16 :offset 32 :size 11) @@ -238,24 +249,30 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition of type gs-prmode-cont (deftype gs-prmode-cont (uint64) + "The GS's PRMODECONT register sets whether to use primitive attributes (IIP, TME, FGE, ABE, +AA1, FST, CTXT, FIX) specified by the PRMODE register or the PRIM register." ((ac uint8 :offset 0 :size 1) ) ) ;; definition of type gs-color-clamp (deftype gs-color-clamp (uint64) + "The GS's COLCLAMP register stores settings as to whether clamping for the RGB value of the +pixel is performed." ((clamp uint8 :offset 0 :size 1) ) ) ;; definition of type gs-dthe (deftype gs-dthe (uint64) + "The GS's DTHE register stores settings for dithering (performed/not performed)." ((dthe uint8 :offset 0 :size 1) ) ) ;; definition of type gs-test (deftype gs-test (uint64) + "The GS's TEST register performs settings related to the pixel test." ((ate uint8 :offset 0 :size 1) (atst gs-atest :offset 1 :size 3) (aref uint8 :offset 4 :size 8) @@ -283,6 +300,8 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition of type gs-rgbaq (deftype gs-rgbaq (uint64) + "The GS's RGBAQ register sets the RGBA value of the vertex and the Q value of the normalized +texture coordinates." ((r uint8 :offset 0 :size 8) (g uint8 :offset 8 :size 8) (b uint8 :offset 16 :size 8) @@ -301,6 +320,7 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition of type gs-uv (deftype gs-uv (uint64) + "The GS's UV register specifies the texel coordinate (UV) values of the vertex." ((u uint16 :offset 0 :size 16) (v uint16 :offset 16 :size 16) ) @@ -308,6 +328,8 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition of type gs-st (deftype gs-st (uint64) + "The GS's ST register sets the S and T values of the vertex texture coordinates. +The value Q is specified by the RGBAQ register." ((s float :offset 0 :size 32) (t float :offset 32 :size 32) ) @@ -359,6 +381,9 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition of type gs-trxpos (deftype gs-trxpos (uint64) + "The GS's TRXPOS register specifies the position and +scanning direction of the rectangular area +in each buffer where buffer transmission is performed." ((ssax uint16 :offset 0 :size 11) (ssay uint16 :offset 16 :size 11) (dsax uint16 :offset 32 :size 11) @@ -369,6 +394,9 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition of type gs-trxreg (deftype gs-trxreg (uint64) + "The GS's TRXREG register specifies the size of the rectangular area, where the transmission +between buffers is implemented, in units of pixels. +The pixel mode must be the one set by the BITBLTBUF register." ((rrw uint16 :offset 0 :size 12) (rrh uint16 :offset 32 :size 12) ) @@ -376,12 +404,18 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition of type gs-trxdir (deftype gs-trxdir (uint64) + "The GS's TRXDIR register specifies the transmission direction in the transmission between +buffers, and activates transmission. +Appropriate settings must be made by the BITBLTBUF/TRXPOS/TRXREG before activating +the transmission." ((xdir uint8 :offset 0 :size 2) ) ) ;; definition of type gs-bitbltbuf (deftype gs-bitbltbuf (uint64) + "The GS's BITBLTBUF register stores buffer-related settings for transmission source and +destination during transmission between buffers." ((sbp uint16 :offset 0 :size 14) (sbw uint8 :offset 16 :size 6) (spsm uint8 :offset 24 :size 6) @@ -393,6 +427,7 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition of type gs-tex0 (deftype gs-tex0 (uint64) + "The GS's TEX0 registers set various kinds of information regarding the textures to be used." ((tbp0 uint16 :offset 0 :size 14) (tbw uint8 :offset 14 :size 6) (psm uint8 :offset 20 :size 6) @@ -410,6 +445,7 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition of type gs-tex1 (deftype gs-tex1 (uint64) + "The GS's TEX1 registers set information on the sampling method of the textures." ((lcm uint8 :offset 0 :size 1) (mxl uint8 :offset 2 :size 3) (mmag uint8 :offset 5 :size 1) @@ -422,6 +458,8 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition of type gs-texa (deftype gs-texa (uint64) + "The GS's TEXA register sets the Alpha value to be referred to when the Alpha value of the +texture is not an 8-bit value." ((ta0 uint8 :offset 0 :size 8) (aem uint8 :offset 15 :size 1) (ta1 uint8 :offset 32 :size 8) @@ -430,6 +468,8 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition of type gs-texclut (deftype gs-texclut (uint64) + "The GS's TEXCLUT register specifies the CLUT position in the buffer when the CLUT storage mode +is CSM=1 (CSM2 mode)." ((cbw uint8 :offset 0 :size 6) (cou uint8 :offset 6 :size 6) (cov uint16 :offset 12 :size 10) @@ -438,6 +478,8 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition of type gs-miptbp (deftype gs-miptbp (uint64) + "the GS's MIPTBP registers set the buffer pointer and buffer width of textures when performing +MIPMAP. MIPTBP1 sets levels 1 to 3, MIPTBP2 sets levels 4 to 6." ((tbp1 uint16 :offset 0 :size 14) (tbw1 uint8 :offset 14 :size 6) (tbp2 uint16 :offset 20 :size 14) @@ -729,6 +771,7 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition of type gif-packet (deftype gif-packet (basic) + "Unused type for building a dynamically sized gif packet." ((reg-count int32) (gif-tag gs-gif-tag :inline) (gif-tag0 uint128 :overlay-at (-> gif-tag qword)) @@ -761,6 +804,7 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition for function open-gif-packet (defun open-gif-packet ((arg0 gif-packet)) + "Initialize an existing gif-packet for 0 registers." (set! (-> arg0 reg-count) 0) (set! (-> arg0 gif-tag regs) (new 'static 'gif-tag-regs)) arg0 @@ -769,6 +813,7 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition for function add-reg-gif-packet ;; WARN: Return type mismatch gif-packet vs none. (defun add-reg-gif-packet ((arg0 gif-packet) (arg1 int) (arg2 int)) + "Add a register + value to the packet." (let ((v1-0 (-> arg0 gif-tag))) (logior! (-> v1-0 regs) (ash arg1 (* (-> arg0 reg-count) 4))) ) @@ -779,6 +824,7 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition for function close-gif-packet (defun close-gif-packet ((arg0 gif-packet) (arg1 int)) + "Finish adding registers." (set! (-> arg0 gif-tag tag) (new 'static 'gif-tag64 :nloop #x1 :flg (gif-flag reg-list) :eop arg1 :nreg (-> arg0 reg-count)) ) @@ -832,6 +878,7 @@ bits 5 and 6 (0x20 and 0x40) should be zero" ;; definition for function draw-context-set-xy ;; WARN: Return type mismatch int vs none. (defun draw-context-set-xy ((arg0 draw-context) (arg1 int) (arg2 int)) + "Set the origin of the draw context." (set! (-> arg0 orgx) arg1) (set! (-> arg0 orgy) arg2) (none) diff --git a/test/decompiler/reference/jak2/engine/gfx/hw/video-h_REF.gc b/test/decompiler/reference/jak2/engine/gfx/hw/video-h_REF.gc index 45995bc48c..6eb5996c33 100644 --- a/test/decompiler/reference/jak2/engine/gfx/hw/video-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/hw/video-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type video-params (deftype video-params (structure) + "Parameters for the framebuffer." ((set-video-mode symbol) (reset-video-mode symbol) (display-fbp int32) diff --git a/test/decompiler/reference/jak2/engine/gfx/math-camera-h_REF.gc b/test/decompiler/reference/jak2/engine/gfx/math-camera-h_REF.gc index 3e46e4bd08..c3a6c396ce 100644 --- a/test/decompiler/reference/jak2/engine/gfx/math-camera-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/math-camera-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type vis-gif-tag (deftype vis-gif-tag (structure) + "Unused." ((fog0 uint32) (strip uint32) (regs uint32) @@ -27,6 +28,7 @@ ;; definition of type cull-info (deftype cull-info (structure) + "Also seems unused." ((x-fact float) (y-fact float) (z-fact float) diff --git a/test/decompiler/reference/jak2/engine/gfx/math-camera_REF.gc b/test/decompiler/reference/jak2/engine/gfx/math-camera_REF.gc index a88777eaf7..928d668b5d 100644 --- a/test/decompiler/reference/jak2/engine/gfx/math-camera_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/math-camera_REF.gc @@ -3,6 +3,14 @@ ;; definition of type fog-corrector (deftype fog-corrector (structure) + "The math-camera matrices are used to compute fogging values, which are a per-vertex uint8 that +tells the GS how 'foggy' the color should be. This should be proportional to how far away the vertex +is. There is a scaling factor applied so the fog intensity isn't affected by the field of view angle. + +The fog-corrector stores a fog-end fog-start value that is corrected for the field of view. +The actual correction factor is computed in cam-update.gc. +Without this corrector, the fogginess of the world would change as the FOV changes +(for example, when Jak gets on the zoomer, the FOV changes slightly)." ((fog-end float) (fog-start float) ) @@ -24,6 +32,7 @@ ;; definition for function fog-corrector-setup ;; WARN: Return type mismatch float vs none. (defun fog-corrector-setup ((arg0 fog-corrector) (arg1 math-camera)) + "Set the fog corrector based on the supplied math-camera." (set! (-> arg0 fog-end) (* (-> arg1 fog-end) (-> arg1 fov-correction-factor))) (set! (-> arg0 fog-start) (* (-> arg1 fog-start) (-> arg1 fov-correction-factor))) (none) @@ -43,6 +52,8 @@ ;; ERROR: Failed store: (s.w! (+ a0-43 8) a1-10) at op 463 ;; ERROR: Failed store: (s.w! (+ a0-43 12) a1-11) at op 465 (defun update-math-camera ((arg0 math-camera) (arg1 symbol) (arg2 symbol) (arg3 float)) + "Compute some one-time camera constants. +These should only change when changing aspect ratio." (local-vars (sv-16 float)) (set! (-> arg0 x-ratio) (tan (* 0.5 arg3))) (if (= arg2 'aspect4x3) @@ -264,6 +275,7 @@ ;; definition for function math-cam-start-smoothing (defun math-cam-start-smoothing ((arg0 float) (arg1 float)) + "Unused camera smoothing." (set! (-> *math-camera* smooth-step) (/ 1.0 arg0)) (set! (-> *math-camera* smooth-t) arg1) (matrix->quaternion (-> *math-camera* inv-camera-rot-smooth-from) (-> *math-camera* inv-camera-rot-smooth)) @@ -272,6 +284,9 @@ ;; definition for function move-target-from-pad ;; INFO: Used lq/sq (defun move-target-from-pad ((arg0 transform) (arg1 int)) + "Unused function to adjust trans based on inputs from the pad. +This function must be extremely old because it takes a non-quaternion transform, +and all [[target]] stuff uses quaternions." (let ((s4-0 (new-stack-vector0))) (set! (-> s4-0 x) (cond ((cpad-hold? arg1 circle) @@ -334,6 +349,9 @@ ;; ERROR: Inline assembly instruction marked with TODO - [TODO.VCLIP] ;; ERROR: Unsupported inline assembly instruction kind - [cfc2.i v1, Clipping] (defun transform-point-vector! ((arg0 vector) (arg1 vector)) + "Apply camera transformation to a point. Return true if it is visible or not. +This returns the point in GS coords, but as float instead of int, so it's +not really useful. See [[transform-point-qword!]] for more details." (local-vars (v1-2 int)) (rlet ((acc :class vf) (Q :class vf) @@ -382,6 +400,8 @@ ;; ERROR: Inline assembly instruction marked with TODO - [TODO.VCLIP] ;; ERROR: Unsupported inline assembly instruction kind - [cfc2.i v1, Clipping] (defun transform-point-qword! ((arg0 vector4w) (arg1 vector)) + "Apply camera transformation to point, returning fixed point 28.4 position +that can be given to the GS directly." (local-vars (v1-2 int)) (rlet ((acc :class vf) (Q :class vf) @@ -431,6 +451,7 @@ ;; ERROR: Inline assembly instruction marked with TODO - [TODO.VCLIP] ;; ERROR: Unsupported inline assembly instruction kind - [cfc2.i v1, Clipping] (defun transform-point-vector-scale! ((arg0 vector) (arg1 vector)) + "Similar to transform-point-qword! but returns the scale factor instead." (local-vars (v0-0 float) (v1-2 int)) (rlet ((acc :class vf) (Q :class vf) @@ -480,6 +501,7 @@ ;; definition for function reverse-transform-point! ;; WARN: Return type mismatch vector vs none. (defun reverse-transform-point! ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 vector)) + "Likely transform arg3 from screen space to world coords, using arg1/arg2 for... something." (let* ((v1-1 (-> *math-camera* perspective)) (s2-0 (-> *math-camera* camera-rot)) (f30-0 (* (/ (-> v1-1 vector 2 w) (-> v1-1 vector 0 x)) (-> *math-camera* hmge-scale w))) @@ -509,6 +531,9 @@ ;; INFO: Used lq/sq ;; WARN: Return type mismatch symbol vs none. (defun init-for-transform ((arg0 matrix)) + "Sets up VU0 registers with camera info. +This is probably a very old function and it's only used by camera debug. +It stashes some data in vector float registers that must be there before calling transform-float-point." (local-vars (v1-14 float)) (rlet ((vf1 :class vf) (vf17 :class vf) diff --git a/test/decompiler/reference/jak2/engine/gfx/mood/time-of-day-h_REF.gc b/test/decompiler/reference/jak2/engine/gfx/mood/time-of-day-h_REF.gc index 03ad068c08..27883f1dc8 100644 --- a/test/decompiler/reference/jak2/engine/gfx/mood/time-of-day-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/mood/time-of-day-h_REF.gc @@ -3,6 +3,8 @@ ;; definition of type palette-fade-control (deftype palette-fade-control (structure) + "Unused interface to the time-of-day control. Was used in jak 1 as an interface between level code, +and the code in mood.gc, which set the actual fade values for time-of-day." ((trans vector :inline) (fade float) (actor-dist float) @@ -25,6 +27,8 @@ ;; definition of type palette-fade-controls (deftype palette-fade-controls (basic) + "Unused interface to the time-of-day control. Was used in jak 1 as an interface between level code, +and the code in mood.gc, which set the actual fade values for time-of-day." ((control palette-fade-control 8 :inline) ) (:methods @@ -50,6 +54,7 @@ ;; definition of type time-of-day-proc (deftype time-of-day-proc (process) + "Process for running things that change with the time-of-day, like lighting, sun/stars/moon, etc." ((hours int32) (minutes int32) (seconds int32) @@ -103,6 +108,9 @@ ;; definition of type time-of-day-palette (deftype time-of-day-palette (basic) + "Pre-baked lighting values used by rendering code. The exact meaning of this data can vary, +but in all cases, the time-of-day system can do linear interpolation of two palettes to +blend between them." ((width int32) (height int32) (pad int32) @@ -127,6 +135,7 @@ ;; definition of type time-of-day-context (deftype time-of-day-context (basic) + "A mix of inputs/outputs to the time-of-day system." ((interp float 6) (current-fog mood-fog :inline) (current-sky-color vector :inline) @@ -193,6 +202,7 @@ ;; definition of type time-of-day-dma (deftype time-of-day-dma (structure) + "Memory layout for the time-of-day interpolation functions." ((outa uint32 256) (outb uint32 256) (banka uint32 256) diff --git a/test/decompiler/reference/jak2/engine/gfx/mood/time-of-day_REF.gc b/test/decompiler/reference/jak2/engine/gfx/mood/time-of-day_REF.gc index 8add50c706..b2b21c735a 100644 --- a/test/decompiler/reference/jak2/engine/gfx/mood/time-of-day_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/mood/time-of-day_REF.gc @@ -9,6 +9,7 @@ ;; definition for method 10 of type time-of-day-proc (defmethod deactivate ((this time-of-day-proc)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this sun)) (kill-and-free-particles (-> this sun)) ) diff --git a/test/decompiler/reference/jak2/engine/gfx/shrub/shrubbery-h_REF.gc b/test/decompiler/reference/jak2/engine/gfx/shrub/shrubbery-h_REF.gc index 73c868dd59..d01656ab33 100644 --- a/test/decompiler/reference/jak2/engine/gfx/shrub/shrubbery-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/shrub/shrubbery-h_REF.gc @@ -3,6 +3,8 @@ ;; definition of type billboard (deftype billboard (drawable) + "A billboard for shrubbery in the distance. This is simple a quad that faces the camera. +The only data needed is the texture/mode. The location is determined by bsphere." ((flat adgif-shader :inline) ) ) @@ -23,6 +25,7 @@ ;; definition of type shrub-view-data (deftype shrub-view-data (structure) + "Camera and general settings for shrubbery VU1 program." ((data uint128 3) (texture-giftag gs-gif-tag :inline :overlay-at (-> data 0)) (consts vector :inline :overlay-at (-> data 1)) @@ -63,6 +66,8 @@ ;; definition of type shrubbery (deftype shrubbery (drawable) + "Prototype (mesh/geometry) for a shrub. not _really_ a drawable in any way, as it +overwrites all the normal drawable fields." ((textures (inline-array adgif-shader) :overlay-at id) (header qword :offset 8) (obj-qwc uint8 :offset 12) @@ -101,6 +106,7 @@ ;; definition of type instance-shrubbery (deftype instance-shrubbery (instance) + "Instance of a shrub." ((flat-normal vector :inline) (flat-hwidth float :overlay-at (-> flat-normal data 3)) (color uint32 :offset 8) @@ -129,6 +135,7 @@ ;; definition of type drawable-inline-array-instance-shrub (deftype drawable-inline-array-instance-shrub (drawable-inline-array) + "Array of shrub instances stored in the level data." ((data instance-shrubbery 1 :inline) (pad uint32) ) @@ -136,6 +143,7 @@ ;; definition of type drawable-tree-instance-shrub (deftype drawable-tree-instance-shrub (drawable-tree) + "Drawable-tree for the shrubs." ((info prototype-array-shrub-info :offset 8) (colors-added time-of-day-palette :offset 12) ) @@ -143,6 +151,9 @@ ;; definition of type generic-shrub-fragment (deftype generic-shrub-fragment (drawable) + "Shrub data, converted into the format for generic. +The shrub renderer doesn't support clipping, so it falls back to generic. +This requires storing the data for all shrubs prototype twice!" ((textures (inline-array adgif-shader) :overlay-at id) (vtx-cnt uint32 :offset 8) (cnt-qwc uint8 :offset 12) @@ -188,6 +199,7 @@ ;; definition of type prototype-trans-shrubbery (deftype prototype-trans-shrubbery (prototype-shrubbery) + "Array of transparent shrub prototypes." () ) @@ -198,6 +210,7 @@ ;; definition of type shrubbery-matrix (deftype shrubbery-matrix (structure) + "Instance matrix for a shrub, contains interpolated color." ((mat matrix :inline) (color qword :inline) ) @@ -220,6 +233,7 @@ ;; INFO: Used lq/sq ;; WARN: Return type mismatch symbol vs none. (defun shrubbery-login-post-texture ((arg0 shrubbery)) + "Do some weird fix-up to the shrubbery textures. this is likely to present normal-looking adgifs to the texture system, but then we scramble them up for easier consumption by VU1." (let* ((v1-1 (-> arg0 header data 0)) (a1-1 (the-as object (+ (the-as uint (-> arg0 header)) (* (+ (-> arg0 header data 1) 1) 16)))) (a2-5 (the-as object (+ (the-as int a1-1) (* v1-1 64)))) @@ -255,6 +269,7 @@ ;; definition of type shrub-near-packet (deftype shrub-near-packet (structure) + "DMA templates for generic rendering of shrubs." ((matrix-tmpl dma-packet :inline) (header-tmpl dma-packet :inline) (stq-tmpl dma-packet :inline) @@ -287,6 +302,7 @@ ;; definition of type instance-shrub-work (deftype instance-shrub-work (structure) + "Scratchpad layout for generating shrub DMA." ((dummy qword 3 :inline) (chaina qword 8 :inline) (chainb qword 8 :inline) diff --git a/test/decompiler/reference/jak2/engine/gfx/shrub/shrubbery_REF.gc b/test/decompiler/reference/jak2/engine/gfx/shrub/shrubbery_REF.gc index da37740759..7faabc916b 100644 --- a/test/decompiler/reference/jak2/engine/gfx/shrub/shrubbery_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/shrub/shrubbery_REF.gc @@ -3,6 +3,7 @@ ;; definition for method 9 of type billboard (defmethod login ((this billboard)) + "Initialize the object after it is loaded." (adgif-shader-login (-> this flat)) this ) @@ -82,6 +83,7 @@ ;; definition for method 9 of type generic-shrub-fragment (defmethod login ((this generic-shrub-fragment)) + "Initialize the object after it is loaded." (let ((s5-0 (/ (-> this cnt-qwc) (the-as uint 5)))) (dotimes (s4-0 (the-as int s5-0)) (adgif-shader-login-no-remap (-> this textures s4-0)) @@ -136,6 +138,7 @@ ;; definition for method 9 of type prototype-shrubbery (defmethod login ((this prototype-shrubbery)) + "Initialize the object after it is loaded." (dotimes (s5-0 (-> this length)) (login (-> this data s5-0)) ) @@ -150,6 +153,7 @@ ;; definition for method 9 of type prototype-generic-shrub (defmethod login ((this prototype-generic-shrub)) + "Initialize the object after it is loaded." (dotimes (s5-0 (-> this length)) (login (-> this data s5-0)) ) @@ -158,6 +162,7 @@ ;; definition for method 9 of type shrubbery (defmethod login ((this shrubbery)) + "Initialize the object after it is loaded." (let ((s5-0 (* (-> this header data 0) 2))) (dotimes (s4-0 (the-as int s5-0)) (let ((v1-3 (adgif-shader-login-no-remap (-> this textures s4-0)))) @@ -224,6 +229,7 @@ ;; definition for method 9 of type drawable-tree-instance-shrub (defmethod login ((this drawable-tree-instance-shrub)) + "Initialize the object after it is loaded." (if (nonzero? (-> this info prototype-inline-array-shrub)) (login (-> this info prototype-inline-array-shrub)) ) diff --git a/test/decompiler/reference/jak2/engine/gfx/sprite/particles/sparticle-h_REF.gc b/test/decompiler/reference/jak2/engine/gfx/sprite/particles/sparticle-h_REF.gc index a7732ca611..4bacb5e67f 100644 --- a/test/decompiler/reference/jak2/engine/gfx/sprite/particles/sparticle-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/sprite/particles/sparticle-h_REF.gc @@ -6,6 +6,7 @@ ;; definition of type sparticle-cpuinfo (deftype sparticle-cpuinfo (structure) + "The per-particle information. This stays on the CPU, and isn't uploaded to the VU." ((sprite sprite-vec-data-2d) (adgif adgif-shader) (radius float) @@ -94,6 +95,7 @@ ;; definition of type sparticle-launchinfo (deftype sparticle-launchinfo (structure) + "Settings for launching a particle. These are a temporary thing consumed by the assembly particle code, and modified by particle callbacks." ((launchrot vector :inline) (conerot vector :inline) (rotate-x float) @@ -136,6 +138,8 @@ ;; definition of type sparticle-system (deftype sparticle-system (basic) + "An entire particle 'system', which is a pipeline for spawning, updating, and generating sprite-renderer DMA data. +There are separate systems for different modes of sprite rendering: 2D/billboard, full 3D, and screen-space (HUD)" ((blocks int32 2) (length int32 2) (num-alloc int32 2) diff --git a/test/decompiler/reference/jak2/engine/gfx/sprite/particles/sparticle-launcher-h_REF.gc b/test/decompiler/reference/jak2/engine/gfx/sprite/particles/sparticle-launcher-h_REF.gc index f72bec8043..06ac7ebb53 100644 --- a/test/decompiler/reference/jak2/engine/gfx/sprite/particles/sparticle-launcher-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/sprite/particles/sparticle-launcher-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type sparticle-birthinfo (deftype sparticle-birthinfo (structure) + "Used internally by the sparticle code." ((sprite uint32) (anim int32) (anim-speed float) @@ -37,6 +38,7 @@ ;; definition of type sp-field-init-spec (deftype sp-field-init-spec (structure) + "Part of a particle definition - how to initialize a field of a particle." ((field sp-field-id) (flags sp-flag) (initial-valuef float) @@ -81,6 +83,7 @@ ;; definition of type sparticle-launcher (deftype sparticle-launcher (basic) + "A definition of a single particle, as a list of init specs." ((birthaccum float) (soundaccum float) (init-specs (inline-array sp-field-init-spec)) @@ -107,6 +110,7 @@ ;; definition of type sparticle-group-item (deftype sparticle-group-item (structure) + "A reference to a single sparticle-launcher (by ID) and some parameters for using it." ((launcher uint32) (fade-after meters) (falloff-to meters) @@ -141,6 +145,7 @@ ;; definition of type sparticle-launch-state (deftype sparticle-launch-state (structure) + "The state associated with a launcher of a given sparticle." ((group-item sparticle-group-item) (flags sp-launch-state-flags) (randomize uint16) @@ -187,6 +192,7 @@ ;; definition of type sparticle-launch-group (deftype sparticle-launch-group (basic) + "Definition of multiple a particle-group, which is a collection of particle effects." ((length int16) (duration uint16) (linger-duration uint16) @@ -235,6 +241,10 @@ ;; definition of type sparticle-launch-control (deftype sparticle-launch-control (inline-array-class) + "Top-level type containing all the state needed to launch a particle group. +These are typically owned by a process, and allocated on the process heap. +These refer to static particle definitions, and then spawn particles that are tracked by the +particle system itself. This type just holds the launching-related state." ((group sparticle-launch-group) (proc process-drawable) (local-clock int32) diff --git a/test/decompiler/reference/jak2/engine/gfx/texture/texture-h_REF.gc b/test/decompiler/reference/jak2/engine/gfx/texture/texture-h_REF.gc index 21cda91f0e..745f4d67cf 100644 --- a/test/decompiler/reference/jak2/engine/gfx/texture/texture-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/texture/texture-h_REF.gc @@ -3,6 +3,8 @@ ;; definition of type texture-id (deftype texture-id (uint32) + "Unique identifier for a texture +as the tpage number and index of the texture within the tpage." ((index uint16 :offset 8 :size 12) (page uint16 :offset 20 :size 12) ) @@ -23,6 +25,7 @@ ;; definition of type texture-pool-segment (deftype texture-pool-segment (structure) + "A chunk of VRAM." ((dest uint32) (size uint32) ) @@ -45,6 +48,7 @@ ;; definition of type texture-pool (deftype texture-pool (basic) + "The manager for the VRAM." ((top int32) (cur int32) (allocate-func (function texture-pool texture-page kheap int texture-page)) @@ -109,6 +113,9 @@ ;; definition of type texture-mask (deftype texture-mask (structure) + "Mask where each bit indicates if some part of a tpage is used, by a texture. +Additionally, the w component holds a minimum distance. The texture is only needed +if the distance to the object is smaller than this." ((mask vector4w :inline) (dist float :overlay-at (-> mask data 3)) (long uint64 2 :overlay-at (-> mask data 0)) @@ -134,6 +141,8 @@ ;; definition of type texture-masks (deftype texture-masks (structure) + "Grouping of three masks, corresponding to the 3 segments of the texture. +So mask 0 is needed if segment 0 of the texture is needed, etc..." ((data texture-mask 3 :inline) ) ) @@ -152,6 +161,7 @@ ;; definition of type texture-masks-array (deftype texture-masks-array (inline-array-class) + "Group of all texture-masks for a given tpage." ((data texture-masks :inline :dynamic) ) ) @@ -181,6 +191,7 @@ ;; definition of type texture (deftype texture (basic) + "Metadata for a texture." ((w int16) (h int16) (num-mips uint8) @@ -227,6 +238,8 @@ ;; definition of type texture-page-segment (deftype texture-page-segment (structure) + "Metadata for a 'segment' of a texture page. +Each texture page has 3 segments - smaller number segments have higher detail mips." ((block-data pointer) (size uint32) (dest uint32) @@ -251,6 +264,9 @@ ;; definition for function texture-mip->segment (defun texture-mip->segment ((arg0 int) (arg1 int)) + "Figure out which segment of a tpage a given mip level of a texture will be in. +arg0 is the mip level, arg1 is the total number of mips. +Higher mip level is lower detail." (if (>= 2 arg1) (+ (- -1 arg0) arg1) (max 0 (- 2 arg0)) @@ -259,6 +275,11 @@ ;; definition of type texture-page (deftype texture-page (basic) + "A collection of textures. There is a tpage per category per level. +These tpages are loaded from the DVD. +e.g.: prison tfrag is its own tpage. +The tpage has multiple textures, and 3 segments. +Lower number segments are larger and have hi-res versions of textures." ((info file-info) (name string) (id uint32) @@ -303,6 +324,8 @@ ;; definition of type shader-ptr (deftype shader-ptr (uint32) + "A pointer to an adgif-shader, stored in bits 8-32. This allows them to fit into +an adgif shader easily." ((first-8 uint8 :offset 0 :size 8) (shader uint32 :offset 8 :size 24) ) @@ -310,6 +333,8 @@ ;; definition of type texture-link (deftype texture-link (structure) + "An overlay structure containing a shader-ptr that points to the next adgif-shader +in a linked list." ((next shader-ptr 1) ) ) @@ -328,6 +353,10 @@ ;; definition of type texture-page-dir-entry (deftype texture-page-dir-entry (structure) + "An entry for a texture in the texture-page-dir. +The texture-page-dir contains an entry for each tpage. +Each entry contains a reference to the tpage, and a linked list of shaders +using it." ((length int16) (status uint16) (page texture-page) @@ -354,6 +383,8 @@ ;; definition of type texture-page-dir (deftype texture-page-dir (basic) + "The list of all texture pages. +This is static data loaded from the DVD at boot." ((length int32) (entries texture-page-dir-entry 1 :inline) ) @@ -365,6 +396,8 @@ ;; definition of type texture-relocate-later (deftype texture-relocate-later (basic) + "Unused in Jak 2, but metadata for postponing tpage copies until a second frame, +to have a smaller impact on frame times when loading." ((memcpy symbol) (dest uint32) (source uint32) @@ -402,6 +435,10 @@ ;; definition of type adgif-shader (deftype adgif-shader (structure) + "GS texturing/blending settings, called adgif-shader. +These are used by many different renderers and partially managed by the texture system. +For example, the texture system will automatically update tbp to point to the location +of the texture." ((quad qword 5 :inline) (prims gs-reg64 10 :overlay-at quad) (reg-0 uint8 :overlay-at (-> quad 0 data 2)) @@ -475,6 +512,8 @@ ;; definition of type texture-base (deftype texture-base (structure) + "Metadata about an area of VRAM set aside for fancy dynamic texture effects +(sky, eye, etc)." ((vram-page uint32) (vram-block uint32) (vram-word uint32) diff --git a/test/decompiler/reference/jak2/engine/gfx/texture/texture_REF.gc b/test/decompiler/reference/jak2/engine/gfx/texture/texture_REF.gc index 331421858f..fa3d9d424a 100644 --- a/test/decompiler/reference/jak2/engine/gfx/texture/texture_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/texture/texture_REF.gc @@ -44,8 +44,9 @@ ) ;; definition for function texture-bpp -(defun texture-bpp ((tex-fmt gs-psm)) - (case tex-fmt +(defun texture-bpp ((tex-format gs-psm)) + "Get the bits-per-pixel in the given texture format" + (case tex-format (((gs-psm mt8)) 8 ) @@ -62,20 +63,27 @@ ) ;; definition for function texture-qwc -(defun texture-qwc ((width int) (height int) (tex-fmt gs-psm)) - (let ((v1-0 (texture-bpp tex-fmt))) - (/ (+ (* (* width height) v1-0) 127) 128) +(defun texture-qwc ((w int) (h int) (tex-format gs-psm)) + "Get the number of quadwords needed for a given texture size and format. +Does not consider weird PS2 memory layout stuff." + (let ((v1-0 (texture-bpp tex-format))) + (/ (+ (* (* w h) v1-0) 127) 128) ) ) ;; definition for function physical-address -(defun physical-address ((ptr pointer)) - (logand #xfffffff ptr) +(defun physical-address ((addr pointer)) + "Strip off high 8-bits of a pointer, to bypass the uncached memory mappings. +This gives an address suitable for DMAing from main memory." + (logand #xfffffff addr) ) ;; definition for function dma-buffer-add-ref-texture ;; WARN: Return type mismatch symbol vs none. (defun dma-buffer-add-ref-texture ((dma-buf dma-buffer) (tex-data-ptr pointer) (width int) (height int) (tex-fmt gs-psm)) + "Upload a texture, by reference. Doesn't copy the texture into the DMA buffer - just a reference, +so it is up to the user to make sure the texture is valid during DMA time. +Doesn't set up GIF for receiving textures." (let ((padr (physical-address tex-data-ptr)) (qwc-remaining (texture-qwc width height tex-fmt)) ) @@ -148,36 +156,37 @@ ) ;; definition for function gs-find-block -(defun gs-find-block ((bx int) (by int) (fmt gs-psm)) +(defun gs-find-block ((bx int) (by int) (tex-format gs-psm)) + "Lookup offset of block in PS2's swizzled VRAM, as a block index." (cond - ((= fmt (gs-psm ct32)) + ((= tex-format (gs-psm ct32)) (-> ct32-24-block-table (+ bx (* by 8))) ) - ((= fmt (gs-psm ct24)) + ((= tex-format (gs-psm ct24)) (-> ct32-24-block-table (+ bx (* by 8))) ) - ((= fmt (gs-psm ct16)) + ((= tex-format (gs-psm ct16)) (-> ct16-block-table (+ bx (* by 4))) ) - ((= fmt (gs-psm ct16s)) + ((= tex-format (gs-psm ct16s)) (-> ct16s-block-table (+ bx (* by 4))) ) - ((= fmt (gs-psm mz32)) + ((= tex-format (gs-psm mz32)) (-> mz32-24-block-table (+ bx (* by 8))) ) - ((= fmt (gs-psm mz24)) + ((= tex-format (gs-psm mz24)) (-> mz32-24-block-table (+ bx (* by 8))) ) - ((= fmt (gs-psm mz16)) + ((= tex-format (gs-psm mz16)) (-> mz16-block-table (+ bx (* by 4))) ) - ((= fmt (gs-psm mz16s)) + ((= tex-format (gs-psm mz16s)) (-> mz16s-block-table (+ bx (* by 4))) ) - ((= fmt (gs-psm mt8)) + ((= tex-format (gs-psm mt8)) (-> mt8-block-table (+ bx (* by 8))) ) - ((= fmt (gs-psm mt4)) + ((= tex-format (gs-psm mt4)) (-> mt4-block-table (+ bx (* by 4))) ) (else @@ -187,8 +196,9 @@ ) ;; definition for function gs-page-width -(defun gs-page-width ((arg0 gs-psm)) - (case arg0 +(defun gs-page-width ((tex-format gs-psm)) + "Get the width of a page, in pixels, for the given texture format." + (case tex-format (((gs-psm ct32) (gs-psm ct24) (gs-psm ct16) (gs-psm ct16s)) 64 ) @@ -196,15 +206,16 @@ 128 ) (else - (format #t "Warning: Unknown block width for psm ~D~%" arg0) + (format #t "Warning: Unknown block width for psm ~D~%" tex-format) 1 ) ) ) ;; definition for function gs-page-height -(defun gs-page-height ((arg0 gs-psm)) - (case arg0 +(defun gs-page-height ((tex-format gs-psm)) + "Get the height of a page, in pixels, for the given texture format." + (case tex-format (((gs-psm ct32) (gs-psm ct24)) 32 ) @@ -218,15 +229,16 @@ 128 ) (else - (format #t "Warning: Unknown block width for psm ~D~%" arg0) + (format #t "Warning: Unknown block width for psm ~D~%" tex-format) 1 ) ) ) ;; definition for function gs-block-width -(defun gs-block-width ((arg0 gs-psm)) - (case arg0 +(defun gs-block-width ((tex-format gs-psm)) + "Get the width of a block, in pixels, for the texture format." + (case tex-format (((gs-psm ct32) (gs-psm ct24)) 8 ) @@ -237,15 +249,16 @@ 32 ) (else - (format #t "Warning: Unknown block width for psm ~D~%" arg0) + (format #t "Warning: Unknown block width for psm ~D~%" tex-format) 1 ) ) ) ;; definition for function gs-block-height -(defun gs-block-height ((arg0 gs-psm)) - (case arg0 +(defun gs-block-height ((tex-format gs-psm)) + "Get the height of a block, in pixels, for the texture format." + (case tex-format (((gs-psm ct32) (gs-psm ct24) (gs-psm ct16) (gs-psm ct16s)) 8 ) @@ -253,25 +266,26 @@ 16 ) (else - (format #t "Warning: Unknown block width for psm ~D~%" arg0) + (format #t "Warning: Unknown block width for psm ~D~%" tex-format) 1 ) ) ) ;; definition for function gs-largest-block -(defun gs-largest-block ((arg0 int) (arg1 int) (arg2 gs-psm)) - (let* ((s5-0 (gs-block-width arg2)) - (v1-0 (gs-block-height arg2)) - (a0-6 (* (/ (+ s5-0 -1 arg0) s5-0) s5-0)) - (a1-4 (* (/ (+ v1-0 -1 arg1) v1-0) v1-0)) +(defun gs-largest-block ((w int) (h int) (tex-format gs-psm)) + "Get the highest block index used by a texture." + (let* ((s5-0 (gs-block-width tex-format)) + (v1-0 (gs-block-height tex-format)) + (a0-6 (* (/ (+ s5-0 -1 w) s5-0) s5-0)) + (a1-4 (* (/ (+ v1-0 -1 h) v1-0) v1-0)) (s5-1 (/ a0-6 s5-0)) (s3-1 (/ a1-4 v1-0)) (s4-1 0) ) (dotimes (s2-0 s5-1) (dotimes (s1-0 s3-1) - (set! s4-1 (max s4-1 (gs-find-block s2-0 s1-0 arg2))) + (set! s4-1 (max s4-1 (gs-find-block s2-0 s1-0 tex-format))) ) ) s4-1 @@ -279,18 +293,22 @@ ) ;; definition for function gs-blocks-used -(defun gs-blocks-used ((arg0 int) (arg1 int) (arg2 gs-psm)) - (let* ((s4-0 (gs-page-width arg2)) - (v1-0 (gs-page-height arg2)) - (a0-6 (* (/ (+ s4-0 -1 arg0) s4-0) s4-0)) - (a1-4 (* (/ (+ v1-0 -1 arg1) v1-0) v1-0)) +(defun gs-blocks-used ((w int) (h int) (tex-format gs-psm)) + "Get the number of blocks used by a texture. +If the texture isn't an even number of pages, the partially completed +page will be counted as the largest used block. +(gaps in this page are counted as used)" + (let* ((s4-0 (gs-page-width tex-format)) + (v1-0 (gs-page-height tex-format)) + (a0-6 (* (/ (+ s4-0 -1 w) s4-0) s4-0)) + (a1-4 (* (/ (+ v1-0 -1 h) v1-0) v1-0)) (s3-0 (/ a0-6 s4-0)) (s1-0 (/ a1-4 v1-0)) - (a0-9 (- arg0 (* (+ s3-0 -1) s4-0))) - (a1-7 (- arg1 (* (+ s1-0 -1) v1-0))) + (a0-9 (- w (* (+ s3-0 -1) s4-0))) + (a1-7 (- h (* (+ s1-0 -1) v1-0))) ) (if (or (< a0-9 s4-0) (< a1-7 v1-0)) - (+ (gs-largest-block a0-9 a1-7 arg2) 1 (* (+ (* s3-0 s1-0) -1) 32)) + (+ (gs-largest-block a0-9 a1-7 tex-format) 1 (* (+ (* s3-0 s1-0) -1) 32)) (* (* s1-0 s3-0) 32) ) ) @@ -298,13 +316,15 @@ ;; definition for method 0 of type texture-pool (defmethod new texture-pool ((allocation symbol) (type-to-make type)) + "Allocate and initialize a texture pool." (initialize! (object-new allocation type-to-make (the-as int (-> type-to-make size)))) ) ;; definition for method 15 of type texture-pool -(defmethod allocate-vram-words! ((this texture-pool) (arg0 int)) +(defmethod allocate-vram-words! ((this texture-pool) (size int)) + "Increment the bump allocator to allocate vram, by words." (let ((v0-0 (-> this cur))) - (+! (-> this cur) arg0) + (+! (-> this cur) size) v0-0 ) ) @@ -326,6 +346,7 @@ ;; definition for method 9 of type texture-pool (defmethod initialize! ((this texture-pool)) + "Set up a texture-pool and do the initial division of VRAM." (set! (-> this cur) 0) (set! (-> this top) (-> this cur)) (set! (-> this allocate-func) texture-page-default-allocate) @@ -349,6 +370,7 @@ ;; definition for method 10 of type texture-page (defmethod get-leftover-block-count ((this texture-page) (num-segments int) (upload-offset int)) + "Unused - statistics for how much unused memory we have" (let ((offset upload-offset)) (dotimes (i num-segments) (+! offset (-> this segment i size)) @@ -373,15 +395,17 @@ ) ;; definition for method 16 of type texture-pool -(defmethod allocate-segment ((this texture-pool) (seg texture-pool-segment) (num-words int)) - (set! (-> seg size) (the-as uint num-words)) - (set! (-> seg dest) (the-as uint (allocate-vram-words! this num-words))) - seg +(defmethod allocate-segment ((this texture-pool) (segment texture-pool-segment) (size int)) + "Allocate VRAM for a texture-pool-segment" + (set! (-> segment size) (the-as uint size)) + (set! (-> segment dest) (the-as uint (allocate-vram-words! this size))) + segment ) ;; definition for method 12 of type texture-pool ;; WARN: Return type mismatch int vs none. (defmethod allocate-defaults ((this texture-pool)) + "Allocate the common segment and set up dynamic texture addresses" (format #t "texture start #x~x~%" (/ (-> this cur) 64)) (allocate-segment this (-> this segment-common) #x3e000) (format #t "texture end #x~x~%" (/ (-> this cur) 64)) @@ -410,12 +434,17 @@ ;; definition for method 9 of type texture-page (defmethod remove-data-from-heap ((this texture-page) (heap kheap)) + "Bump the kheap pointer to discard this texture data. All metadata is kept. +This is only safe to use if the last thing on the kheap is this texture." (set! (-> heap current) (-> this segment 0 block-data)) this ) ;; definition for function texture-page-default-allocate (defun texture-page-default-allocate ((pool texture-pool) (tpage texture-page) (heap kheap) (tpage-id int)) + "Texture allocation function for textures that permanently live in VRAM. +The texture data is immediately uploaded, then discarded from the heap. +This should only be called during startup." (dotimes (seg 3) (let ((vram-loc (allocate-vram-words! pool (the-as int (-> tpage segment seg size))))) (relocate-dests! tpage vram-loc seg) @@ -439,19 +468,25 @@ ) ;; definition for function texture-page-common-allocate -(defun texture-page-common-allocate ((pool texture-pool) (tpage texture-page) (heap kheap) (tpage-id int)) - (let ((vram-loc (-> pool segment-common dest))) - (dotimes (seg 3) - (relocate-dests! tpage (the-as int vram-loc) seg) - (+! vram-loc (-> tpage segment seg size)) +(defun texture-page-common-allocate ((pool texture-pool) (page texture-page) (heap kheap) (page-id int)) + "Texture allocation function for textures that share the common segment. +The texture remains in RAM, and is uploaded to VRAM as needed as part +of the main drawing DMA chain." + (let ((s5-0 (-> pool segment-common dest))) + (dotimes (s4-0 3) + (relocate-dests! page (the-as int s5-0) s4-0) + (+! s5-0 (-> page segment s4-0 size)) ) ) - (set! (-> tpage dram-size) (-> tpage size)) - tpage + (set! (-> page dram-size) (-> page size)) + page ) ;; definition for function texture-page-font-allocate (defun texture-page-font-allocate ((pool texture-pool) (tpage texture-page) (heap kheap) (tpage-id int)) + "Texture allocation function for font. This temporarily stores them in the common segment, +removes them from RAM. This is a bit of hack. Later font setup code expects the font texture +to be in common, and they will eventually be moved into the upper 8-bits of the depth buffer." (texture-page-common-allocate pool tpage heap tpage-id) (upload-now! tpage (tex-upload-mode seg0-1-2)) (remove-data-from-heap tpage heap) @@ -473,6 +508,7 @@ ;; definition for method 22 of type texture-pool ;; WARN: Return type mismatch int vs none. (defmethod lay-out-sprite-tex ((this texture-pool)) + "Lay out VRAM addresses for sprite rendering, which is done in one pass for all levels." (let ((vram-loc 0)) (countdown (level-idx 7) (let ((lev (-> *level* level level-idx))) @@ -504,6 +540,7 @@ ;; definition for method 23 of type texture-pool ;; WARN: Return type mismatch int vs none. (defmethod lay-out-hud-tex ((this texture-pool)) + "Lay out VRAM addresses for HUD rendering, which is done all at one for all levels." (let ((level-idx 0)) (countdown (vram-loc 7) (let ((lev (-> *level* level vram-loc))) @@ -535,6 +572,7 @@ ;; definition for method 24 of type texture-pool ;; WARN: Return type mismatch int vs none. (defmethod lay-out-warp-tex ((this texture-pool)) + "Lay out VRAM addresses for WARP texture rendering, and update adgifs to point to the new address." (let ((vram-loc 0)) (countdown (level-idx 7) (let ((lev (-> *level* level level-idx))) @@ -589,6 +627,7 @@ ;; definition for method 25 of type texture-pool ;; WARN: Return type mismatch int vs none. (defmethod clear-ids ((this texture-pool)) + "Reset all cached texture upload IDs. This must be done whenever a texture has its vram address changed." (dotimes (v1-0 128) (set! (-> this ids v1-0) (the-as uint 0)) ) @@ -599,6 +638,7 @@ ;; definition for method 20 of type texture-pool ;; WARN: Return type mismatch symbol vs none. (defmethod update-sprites ((this texture-pool)) + "Redo sprite texture addresses with the current set of loaded levels." (lay-out-sprite-tex this) (clear-ids this) (set! (-> this update-sprites-flag) #f) @@ -608,6 +648,7 @@ ;; definition for method 19 of type texture-pool ;; WARN: Return type mismatch symbol vs none. (defmethod update-warp-and-hud ((this texture-pool)) + "Redo warp and hud textures with the current set of loaded levels." (lay-out-hud-tex this) (lay-out-warp-tex this) (clear-ids this) @@ -618,6 +659,7 @@ ;; definition for method 21 of type texture-pool ;; WARN: Return type mismatch symbol vs none. (defmethod mark-hud-warp-sprite-dirty ((this texture-pool)) + "Set update flags for hud/sprite/warp. Needed after level load or unload." (set! (-> this update-sprites-flag) #t) (set! (-> this update-flag) #t) (none) @@ -625,6 +667,8 @@ ;; definition for function texture-page-common-boot-allocate (defun texture-page-common-boot-allocate ((pool texture-pool) (tpage texture-page) (heap kheap) (tpage-id int)) + "Allocator function for texture loaded at startup time. +For jak 3, this seems to always do default-allocate (permanently in vram?)" (let ((common-page-slot-id (get-common-page-slot-by-id pool tpage-id))) (cond ((>= common-page-slot-id 0) @@ -683,6 +727,7 @@ ;; definition for function upload-vram-data ;; WARN: Return type mismatch symbol vs none. (defun upload-vram-data ((buf dma-buffer) (dest int) (data pointer) (height int) (width int)) + "Add DMA to later upload a texture, by reference. Sets up the GIF for receiving the texture." (while (> height 0) (let ((height-this-time (min 2048 height))) (dma-buffer-add-gs-set buf @@ -707,6 +752,10 @@ (mode tex-upload-mode) (bucket bucket-id) ) + "Add DMA to upload a texture page. Will only upload the portion of data that is not already present in VRAM. +This is the old Jak 1 background texture uploading system, which had this near/far concept +for different mip levels. By jak 2, the background system switched to masks and uses +the -pris variant of this function." (local-vars (data-ptr pointer) (vram-ptr uint) @@ -793,14 +842,15 @@ ) ;; definition for function update-vram-pages -(defun update-vram-pages ((pool texture-pool) (dest-seg texture-pool-segment) (tpage texture-page) (mode tex-upload-mode)) - (-> tpage segment 0 block-data) - (let ((vram-ptr (shr (-> tpage segment 0 dest) 12)) - (tpage-num-chunks (-> tpage segment 0 size)) - (chunks-pending 0) +(defun update-vram-pages ((pool texture-pool) (pool-segment texture-pool-segment) (page texture-page) (mode tex-upload-mode)) + "Likely a debug function for checking the logic of upload-vram-pages. Unused" + (-> page segment 0 block-data) + (let ((t1-0 (shr (-> page segment 0 dest) 12)) + (t2-0 (-> page segment 0 size)) + (v1-2 0) ) 0 - (let ((tpage-id (-> tpage id))) + (let ((t0-1 (-> page id))) (cond ((= mode (tex-upload-mode none)) (return 0) @@ -808,33 +858,33 @@ ((= mode (tex-upload-mode seg0)) ) ((= mode (tex-upload-mode seg0-1)) - (+! tpage-num-chunks (-> tpage segment 1 size)) + (+! t2-0 (-> page segment 1 size)) ) ((= mode (tex-upload-mode seg0-1-2)) - (set! tpage-num-chunks (-> tpage size)) + (set! t2-0 (-> page size)) ) ((= mode (tex-upload-mode seg2)) - (-> tpage segment 2 block-data) - (set! vram-ptr (shr (-> tpage segment 2 dest) 12)) - (set! tpage-num-chunks (-> tpage segment 2 size)) + (-> page segment 2 block-data) + (set! t1-0 (shr (-> page segment 2 dest) 12)) + (set! t2-0 (-> page segment 2 size)) ) ) - (let ((adjusted-num-chunks (shr (min (the-as int (-> dest-seg size)) (the-as int (+ tpage-num-chunks 4095))) 12))) - (dotimes (chunk-idx adjusted-num-chunks) - (let ((chunk-ptr (+ vram-ptr chunk-idx))) + (let ((a1-4 (shr (min (the-as int (-> pool-segment size)) (the-as int (+ t2-0 4095))) 12))) + (dotimes (a2-3 a1-4) + (let ((a3-8 (+ t1-0 a2-3))) (cond - ((zero? chunks-pending) - (when (!= (-> pool ids chunk-ptr) tpage-id) - (set! (-> pool ids chunk-ptr) tpage-id) - (+! chunks-pending 1) + ((zero? v1-2) + (when (!= (-> pool ids a3-8) t0-1) + (set! (-> pool ids a3-8) t0-1) + (+! v1-2 1) ) ) - ((= (-> pool ids chunk-ptr) tpage-id) - (set! chunks-pending 0) + ((= (-> pool ids a3-8) t0-1) + (set! v1-2 0) ) (else - (set! (-> pool ids chunk-ptr) tpage-id) - (+! chunks-pending 1) + (set! (-> pool ids a3-8) t0-1) + (+! v1-2 1) ) ) ) @@ -852,6 +902,11 @@ (bucket bucket-id) (arg4 (pointer int32)) ) + "Similar to upload-vram-pages, but skips the near/far mode and instead uses masks. +The foreground/background renderers will generate masks telling us which textures are used. +This lets us skip uploading entire textures, or mip levels that won't need. +(side note: this optimization is what causes many of the texturing issues in pcsx2, +where the ps2 and pcsx2 disagree on the mip level to use.)" (local-vars (data-ptr pointer) (vram-ptr uint) @@ -924,26 +979,28 @@ ) ;; definition for function texture-page-level-allocate -(defun texture-page-level-allocate ((pool texture-pool) (tpage texture-page) (heap kheap) (tpage-id int)) +(defun texture-page-level-allocate ((pool texture-pool) (page texture-page) (heap kheap) (page-id int)) + "Allocation function for level textures." (if (zero? (-> *level* loading-level code-memory-end)) - (set! (-> *level* loading-level code-memory-end) (the-as pointer tpage)) + (set! (-> *level* loading-level code-memory-end) (the-as pointer page)) ) - (let ((common-page-slot-id (get-common-page-slot-by-id pool tpage-id))) + (let ((s2-0 (get-common-page-slot-by-id pool page-id))) (cond - ((>= common-page-slot-id 0) - (texture-page-common-allocate pool tpage heap tpage-id) - (set! (-> pool common-page common-page-slot-id) tpage) + ((>= s2-0 0) + (texture-page-common-allocate pool page heap page-id) + (set! (-> pool common-page s2-0) page) ) (else - (texture-page-common-allocate pool tpage heap tpage-id) + (texture-page-common-allocate pool page heap page-id) ) ) ) - tpage + page ) ;; definition for function texture-page-size-check (defun texture-page-size-check ((pool texture-pool) (lev level) (silent symbol)) + "Check the size of level textures." (let ((gp-0 0)) (let ((v1-0 (-> lev texture-page 0))) (when v1-0 @@ -1075,6 +1132,7 @@ ;; definition for method 13 of type texture-pool ;; WARN: Return type mismatch int vs none. (defmethod login-level-textures ((pool texture-pool) (lev level) (num-tpage-ids int) (tpage-ids (pointer texture-id))) + "Login all textures for the given level." (dotimes (v1-0 18) (set! (-> lev texture-page v1-0) #f) ) @@ -1110,6 +1168,7 @@ ;; INFO: Used lq/sq ;; WARN: Return type mismatch int vs none. (defmethod add-level-tpage-dma ((pool texture-pool) (lev level) (cat tpage-category) (bucket bucket-id)) + "Set up DMA to upload all textures needed to draw this level on this frame." (with-pp (let ((tpage (-> lev texture-page cat))) (-> lev closest-object-array cat) @@ -1306,6 +1365,7 @@ ;; INFO: Used lq/sq ;; WARN: Return type mismatch uint128 vs none. (defun set-skull-gem-masks () + "Turn on masks for skull gem textures, so they will be uploaded." (local-vars (v0-3 uint128) (v1-2 uint128) (v1-3 uint128)) (let ((gp-0 (-> *level* default-level texture-mask))) (let* ((s5-0 (lookup-texture-by-id (new 'static 'texture-id :index #x28 :page #x395))) @@ -1329,6 +1389,7 @@ ;; INFO: Used lq/sq ;; WARN: Return type mismatch int vs none. (defun upload-textures ((arg0 texture-pool)) + "Set up DMA for all texture uploads for this frame." (cond ((not (-> *blit-displays-work* screen-copied)) (set-skull-gem-masks) @@ -1409,6 +1470,7 @@ ;; definition for method 13 of type texture-page ;; WARN: Return type mismatch int vs none. (defmethod upload-now! ((this texture-page) (arg0 tex-upload-mode)) + "Upload a texture to VRAM immediately, wait for DMA to finish." (let ((gp-0 *txt-dma-list*)) (let ((v1-0 gp-0)) (set! (-> v1-0 base) (-> v1-0 data)) @@ -1430,37 +1492,39 @@ ) ;; definition for method 12 of type texture-page -(defmethod add-to-dma-buffer ((this texture-page) (arg0 dma-buffer) (arg1 tex-upload-mode)) +(defmethod add-to-dma-buffer ((page texture-page) (buf dma-buffer) (mode tex-upload-mode)) + "Add upload DMA to a DMA buffer. Wrapper for upload-vram-data." (local-vars (sv-16 int)) - (let ((v1-0 arg1)) + (let ((v1-0 mode)) (set! sv-16 (cond ((= v1-0 (tex-upload-mode none)) 0 ) ((= v1-0 (tex-upload-mode seg0-1)) - (the-as int (+ (-> this segment 0 size) (-> this segment 1 size))) + (the-as int (+ (-> page segment 0 size) (-> page segment 1 size))) ) ((= v1-0 (tex-upload-mode seg0-1-2)) - (the-as int (-> this size)) + (the-as int (-> page size)) ) (else - (the-as int (-> this segment (the-as int arg1) size)) + (the-as int (-> page segment (the-as int mode) size)) ) ) ) ) - (let* ((v1-7 (max 0 (the-as int arg1))) + (let* ((v1-7 (max 0 (the-as int mode))) (a3-4 (* (/ (+ (/ sv-16 64) 63) 64) 32)) - (t1-0 (shr (-> this segment v1-7 dest) 6)) - (a2-10 (-> this segment v1-7 block-data)) + (t1-0 (shr (-> page segment v1-7 dest) 6)) + (a2-10 (-> page segment v1-7 block-data)) ) - (upload-vram-data arg0 (the-as int t1-0) a2-10 a3-4 128) + (upload-vram-data buf (the-as int t1-0) a2-10 a3-4 128) ) sv-16 ) ;; definition for function texture-relocate (defun texture-relocate ((dma-buff dma-buffer) (tex texture) (dest-loc int) (dest-fmt gs-psm) (clut-dst int)) + "Move a texture in VRAM." (dotimes (v1-0 (the-as int (-> tex num-mips))) (let ((t1-1 (ash (-> tex w) (- v1-0))) (t2-3 (ash (-> tex h) (- v1-0))) @@ -1549,6 +1613,9 @@ ;; WARN: Stack slot offset 16 signed mismatch ;; WARN: Return type mismatch int vs none. (defmethod setup-font-texture ((this texture-pool)) + "Set up the font texture. In normal use, the font texture is allocated, and currently uploaded to, the common segment. +This function copies that to the unused upper 8-bits of the depth buffer, and sets up the font +renderer to point to that address." (local-vars (sv-16 int) (sv-20 int)) (let ((s3-0 (-> this font-palette))) (set! sv-16 (-> this cur)) @@ -1656,36 +1723,37 @@ ;; definition for method 11 of type texture-page ;; WARN: Return type mismatch texture-page vs none. -(defmethod relocate-dests! ((this texture-page) (new-dest int) (segs int)) - (let ((new-tbp (shr new-dest 6)) - (old-tbp (shr (-> this segment segs dest) 6)) +(defmethod relocate-dests! ((this texture-page) (new-dest int) (seg-id int)) + "Update the metadata of this texture so it points to a new vram address." + (let ((v1-0 (shr new-dest 6)) + (a3-4 (shr (-> this segment seg-id dest) 6)) ) - (when (!= new-tbp old-tbp) - (dotimes (tex-idx (-> this length)) - (when (-> this data tex-idx) - (let* ((tex (-> this data tex-idx)) - (num-mips (-> tex num-mips)) + (when (!= v1-0 a3-4) + (dotimes (t0-1 (-> this length)) + (when (-> this data t0-1) + (let* ((t1-6 (-> this data t0-1)) + (t2-0 (-> t1-6 num-mips)) ) - (if (zero? segs) - (set! (-> tex clutdest) (+ (- (-> tex clutdest) old-tbp) new-tbp)) + (if (zero? seg-id) + (set! (-> t1-6 clutdest) (+ (- (-> t1-6 clutdest) a3-4) v1-0)) ) - (dotimes (mip-idx (the-as int num-mips)) - (let ((t4-0 mip-idx) - (t5-0 num-mips) + (dotimes (t3-4 (the-as int t2-0)) + (let ((t4-0 t3-4) + (t5-0 t2-0) ) - (if (= segs (if (>= (the-as uint 2) t5-0) - (+ (- -1 t4-0) t5-0) - (max 0 (- 2 t4-0)) - ) + (if (= seg-id (if (>= (the-as uint 2) t5-0) + (+ (- -1 t4-0) t5-0) + (max 0 (- 2 t4-0)) + ) ) - (set! (-> tex dest mip-idx) (+ (- (-> tex dest mip-idx) old-tbp) new-tbp)) + (set! (-> t1-6 dest t3-4) (+ (- (-> t1-6 dest t3-4) a3-4) v1-0)) ) ) ) ) ) ) - (set! (-> this segment segs dest) (the-as uint new-dest)) + (set! (-> this segment seg-id dest) (the-as uint new-dest)) ) ) (none) @@ -1693,6 +1761,10 @@ ;; definition for method 7 of type texture-page (defmethod relocate ((this texture-page) (loading-heap kheap) (name (pointer uint8))) + "Handle a texture page that has been loaded by the linker. +This must run in the linker, since we sometimes kick out textures from the loading heap, which +requires no more allocations made after the texture, and the only time is right after the linker +does the allocation for this GOAL object file." (cond ((or (not this) (not (file-info-correct-version? (-> this info) (file-kind tpage) 0))) (the-as texture-page #f) @@ -1738,6 +1810,10 @@ ;; definition for function relocate-later (defun relocate-later () + "Unused in jak 2 and likely unsed in jak 3. Feature to postpone some texture copying until +a later frame. This is only used in cases when texture data must be memcpy'd in RAM, to patch up a hole left +by some data that is now permanently in VRAM, and no longer needed. +Note that Jak2/Jak3 don't have this problem since level textures are now never permanent" (let ((gp-0 *texture-relocate-later*)) (let ((s5-0 (-> gp-0 entry)) (s4-0 (-> gp-0 page)) @@ -1756,64 +1832,71 @@ ) ;; definition for function texture-page-login -(defun texture-page-login ((tex-id texture-id) (alloc-func (function texture-pool texture-page kheap int texture-page)) (heap kheap)) - (when (and (nonzero? (-> tex-id page)) (< (-> tex-id page) (the-as uint (-> *texture-page-dir* length)))) - (let ((dir-entry (-> *texture-page-dir* entries (-> tex-id page)))) - (when (not (-> dir-entry page)) - (let ((old-alloc-func (-> *texture-pool* allocate-func))) +(defun texture-page-login ((id texture-id) (alloc-func (function texture-pool texture-page kheap int texture-page)) (heap kheap)) + "'Login' (initialize) a texture page with the pool. +This has a trick - it doesn't actually require you to pass a texture-page object - instead you pass an ID. +If the texture was loaded at all, it will already be known to the texture pool, and this function will do nothing. +However, if the texture is not present, it will be loaded through a call to `loado`, for use in development." + (when (and (nonzero? (-> id page)) (< (-> id page) (the-as uint (-> *texture-page-dir* length)))) + (let ((s5-0 (-> *texture-page-dir* entries (-> id page)))) + (when (not (-> s5-0 page)) + (let ((s4-0 (-> *texture-pool* allocate-func))) (set! (-> *texture-pool* allocate-func) alloc-func) - (let* ((name (make-file-name (file-kind tpage) (the-as string (* (-> tex-id page) 8)) 0 #f)) - (loaded-tpage (the-as texture-page (loado name heap))) + (let* ((s3-0 (make-file-name (file-kind tpage) (the-as string (* (-> id page) 8)) 0 #f)) + (s2-0 (the-as texture-page (loado s3-0 heap))) ) - (if loaded-tpage - (relocate loaded-tpage heap (charp-basename (-> name data))) + (if s2-0 + (relocate s2-0 heap (charp-basename (-> s3-0 data))) ) ) - (set! (-> *texture-pool* allocate-func) old-alloc-func) + (set! (-> *texture-pool* allocate-func) s4-0) ) ) - dir-entry + s5-0 ) ) ) ;; definition for function lookup-texture-by-id -(defun lookup-texture-by-id ((arg0 texture-id)) - (let ((a0-2 (texture-page-login arg0 texture-page-default-allocate loading-level)) +(defun lookup-texture-by-id ((id texture-id)) + "Get a texture by ID, loading it if needed (for debugging only)." + (let ((a0-2 (texture-page-login id texture-page-default-allocate loading-level)) (v1-0 (the-as texture-page #f)) ) - (if (and a0-2 (begin (set! v1-0 (-> a0-2 page)) v1-0) (< (-> arg0 index) (the-as uint (-> v1-0 length)))) - (-> v1-0 data (-> arg0 index)) + (if (and a0-2 (begin (set! v1-0 (-> a0-2 page)) v1-0) (< (-> id index) (the-as uint (-> v1-0 length)))) + (-> v1-0 data (-> id index)) ) ) ) ;; definition for function lookup-texture-by-id-fast -(defun lookup-texture-by-id-fast ((arg0 texture-id)) - (let ((a1-2 (if (and (nonzero? (-> arg0 page)) (< (-> arg0 page) (the-as uint (-> *texture-page-dir* length)))) - (-> *texture-page-dir* entries (-> arg0 page)) +(defun lookup-texture-by-id-fast ((id texture-id)) + "Get a texture by ID. #f if it does not exist." + (let ((a1-2 (if (and (nonzero? (-> id page)) (< (-> id page) (the-as uint (-> *texture-page-dir* length)))) + (-> *texture-page-dir* entries (-> id page)) ) ) (v1-6 (the-as texture-page #f)) ) - (if (and a1-2 (begin (set! v1-6 (-> a1-2 page)) v1-6) (< (-> arg0 index) (the-as uint (-> v1-6 length)))) - (-> v1-6 data (-> arg0 index)) + (if (and a1-2 (begin (set! v1-6 (-> a1-2 page)) v1-6) (< (-> id index) (the-as uint (-> v1-6 length)))) + (-> v1-6 data (-> id index)) ) ) ) ;; definition for function lookup-texture-by-name -(defun lookup-texture-by-name ((arg0 string) (arg1 string) (arg2 (pointer texture-page))) +(defun lookup-texture-by-name ((tex-name string) (page-name string) (page-out (pointer texture-page))) + "Get a loaded texture by name. Slow." (local-vars (sv-16 texture-page-dir)) (set! sv-16 *texture-page-dir*) (dotimes (s3-0 (-> sv-16 length)) (let ((s2-0 (-> sv-16 entries s3-0 page))) - (when (and s2-0 (or (not arg1) (string= (-> s2-0 name) arg1))) + (when (and s2-0 (or (not page-name) (string= (-> s2-0 name) page-name))) (dotimes (s1-0 (-> s2-0 length)) (let ((s0-0 (-> s2-0 data s1-0))) - (when (and s0-0 (string= (-> s0-0 name) arg0)) - (if arg2 - (set! (-> arg2 0) s2-0) + (when (and s0-0 (string= (-> s0-0 name) tex-name)) + (if page-out + (set! (-> page-out 0) s2-0) ) (return s0-0) ) @@ -1827,15 +1910,16 @@ ;; definition for function lookup-texture-id-by-name ;; WARN: Return type mismatch int vs texture-id. -(defun lookup-texture-id-by-name ((arg0 string) (arg1 string)) +(defun lookup-texture-id-by-name ((tex-name string) (page-name string)) + "Get the ID of a loaded texture by name. Slow." (local-vars (sv-16 texture-page-dir)) (set! sv-16 *texture-page-dir*) (dotimes (gp-0 (-> sv-16 length)) (let ((s3-0 (-> sv-16 entries gp-0 page))) - (when (and s3-0 (or (not arg1) (string= (-> s3-0 name) arg1))) + (when (and s3-0 (or (not page-name) (string= (-> s3-0 name) page-name))) (dotimes (s2-0 (-> s3-0 length)) (let ((v1-7 (-> s3-0 data s2-0))) - (if (and v1-7 (string= (-> v1-7 name) arg0)) + (if (and v1-7 (string= (-> v1-7 name) tex-name)) (return (new 'static 'texture-id :page gp-0 :index s2-0)) ) ) @@ -1848,6 +1932,7 @@ ;; definition for function lookup-level-texture-by-name (defun lookup-level-texture-by-name ((arg0 string) (arg1 level) (arg2 (pointer texture-page))) + "Get a texture from a given level, by name." (dotimes (s3-0 18) (let ((s2-0 (-> arg1 texture-page s3-0))) (when (and s2-0 (nonzero? s2-0)) @@ -1869,11 +1954,12 @@ ;; definition for method 17 of type texture-pool ;; WARN: Return type mismatch int vs none. -(defmethod unload-page ((this texture-pool) (arg0 texture-page)) +(defmethod unload-page ((this texture-pool) (page texture-page)) + "Remove a page from the texture pool." (local-vars (a0-2 int)) (let ((v1-0 *texture-page-dir*)) (dotimes (a0-1 (-> v1-0 length)) - (when (= arg0 (-> v1-0 entries a0-1 page)) + (when (= page (-> v1-0 entries a0-1 page)) (set! a0-2 a0-1) (goto cfg-7) ) @@ -1896,15 +1982,17 @@ (define *edit-shader* (new 'static 'texture-id)) ;; definition for function link-texture-by-id -(defun link-texture-by-id ((arg0 texture-id) (arg1 adgif-shader)) - (when (not (or (zero? (-> arg0 page)) (>= (-> arg0 page) (the-as uint (-> *texture-page-dir* length))))) - (let ((s4-0 (-> *texture-page-dir* entries (-> arg0 page)))) +(defun link-texture-by-id ((id texture-id) (shader adgif-shader)) + "Add this adgif shader to the linked list of shaders associated with the given texture ID. +Will allocate the link array if it's not already." + (when (not (or (zero? (-> id page)) (>= (-> id page) (the-as uint (-> *texture-page-dir* length))))) + (let ((s4-0 (-> *texture-page-dir* entries (-> id page)))) (if (not (-> s4-0 link)) (set! (-> s4-0 link) (the-as texture-link (malloc 'loading-level (* (-> s4-0 length) 4)))) ) - (when (< (-> arg0 index) (the-as uint (-> s4-0 length))) - (set! (-> arg1 next shader) (-> s4-0 link next (-> arg0 index) shader)) - (set! (-> s4-0 link next (-> arg0 index) shader) (shr (the-as int arg1) 4)) + (when (< (-> id index) (the-as uint (-> s4-0 length))) + (set! (-> shader next shader) (-> s4-0 link next (-> id index) shader)) + (set! (-> s4-0 link next (-> id index) shader) (shr (the-as int shader) 4)) ) s4-0 ) @@ -1913,6 +2001,7 @@ ;; definition for method 9 of type texture-page-dir (defmethod unlink-shaders-in-heap ((this texture-page-dir) (heap kheap)) + "Iterate through all adgifs, splicing out ones that are in the given heap." (local-vars (dist-past-end uint)) (let ((mem-start (-> heap base)) (mem-end (-> heap top-base)) @@ -1963,14 +2052,15 @@ ;; definition for function adgif-shader-update! ;; WARN: Return type mismatch gs-tex1 vs none. -(defun adgif-shader-update! ((arg0 adgif-shader) (arg1 texture)) - (let ((s5-0 (the int (/ 256.0 (-> arg1 uv-dist))))) - (case (-> arg0 tex1 l) +(defun adgif-shader-update! ((shader adgif-shader) (tex texture)) + "Update k based on uv-dist" + (let ((s5-0 (the int (/ 256.0 (-> tex uv-dist))))) + (case (-> shader tex1 l) ((1) - (set! (-> arg0 tex1 k) (+ (logand (ash s5-0 (- 5 (log2 s5-0))) 31) -350 (* (log2 s5-0) 32))) + (set! (-> shader tex1 k) (+ (logand (ash s5-0 (- 5 (log2 s5-0))) 31) -350 (* (log2 s5-0) 32))) ) (else - (set! (-> arg0 tex1 k) (+ (logand (ash s5-0 (- 4 (log2 s5-0))) 15) -175 (* (log2 s5-0) 16))) + (set! (-> shader tex1 k) (+ (logand (ash s5-0 (- 4 (log2 s5-0))) 15) -175 (* (log2 s5-0) 16))) ) ) ) @@ -1982,38 +2072,42 @@ (def-mips2c adgif-shader<-texture-with-update! (function adgif-shader texture adgif-shader)) ;; definition for function hack-texture -(defun hack-texture ((arg0 texture)) - (set! (-> arg0 uv-dist) 1000000.0) - (+! (-> arg0 masks data 0 dist) 40960000.0) - (set! (-> arg0 masks data 1 dist) (+ 40960000.0 (-> arg0 masks data 1 dist))) +(defun hack-texture ((tex texture)) + "adjust some values of a texture, likely for debug." + (set! (-> tex uv-dist) 1000000.0) + (+! (-> tex masks data 0 dist) 40960000.0) + (set! (-> tex masks data 1 dist) (+ 40960000.0 (-> tex masks data 1 dist))) ) ;; definition for function adgif-shader-login -(defun adgif-shader-login ((arg0 adgif-shader)) - (when (logtest? (-> arg0 link-test) (link-test-flags needs-log-in)) - (logclear! (-> arg0 link-test) (link-test-flags needs-log-in bit-9)) - (set! (-> arg0 texture-id) (level-remap-texture (-> arg0 texture-id))) - (when (= (-> arg0 texture-id page) 2797) +(defun adgif-shader-login ((shader adgif-shader)) + "set up an adgif shader with the texture-pool, so it points to the right vram address. +Will remap textures through the level remap table. +If texture is missing, will load it on debug hardware." + (when (logtest? (-> shader link-test) (link-test-flags needs-log-in)) + (logclear! (-> shader link-test) (link-test-flags needs-log-in bit-9)) + (set! (-> shader texture-id) (level-remap-texture (-> shader texture-id))) + (when (= (-> shader texture-id page) 2797) (nop!) (nop!) 0 ) - (link-texture-by-id (-> arg0 texture-id) arg0) - (let ((s5-0 (lookup-texture-by-id (-> arg0 texture-id)))) + (link-texture-by-id (-> shader texture-id) shader) + (let ((s5-0 (lookup-texture-by-id (-> shader texture-id)))) (cond (s5-0 (if (and *debug-segment* (-> *screen-shot-work* highres-enable)) (hack-texture s5-0) ) - (adgif-shader<-texture-with-update! arg0 s5-0) + (adgif-shader<-texture-with-update! shader s5-0) ) (else (format 0 "login<1> could not find texture ~X in obj ~A shader ~X~%" - (-> arg0 texture-id) + (-> shader texture-id) (-> *kernel-context* login-object) - arg0 + shader ) ) ) @@ -2023,25 +2117,27 @@ ) ;; definition for function adgif-shader-login-no-remap -(defun adgif-shader-login-no-remap ((arg0 adgif-shader)) - (when (logtest? (-> arg0 link-test) (link-test-flags needs-log-in)) - (logclear! (-> arg0 link-test) (link-test-flags needs-log-in bit-9)) - (link-texture-by-id (-> arg0 texture-id) arg0) - (let ((s5-0 (lookup-texture-by-id (-> arg0 texture-id)))) +(defun adgif-shader-login-no-remap ((shader adgif-shader)) + "Set up an adgif shader with the texture-pool, so it points to the right vram adress. +This does not do level tpage remapping, so the texture should be one that's not loaded in a combine level tpage." + (when (logtest? (-> shader link-test) (link-test-flags needs-log-in)) + (logclear! (-> shader link-test) (link-test-flags needs-log-in bit-9)) + (link-texture-by-id (-> shader texture-id) shader) + (let ((s5-0 (lookup-texture-by-id (-> shader texture-id)))) (cond (s5-0 (if (and *debug-segment* (-> *screen-shot-work* highres-enable)) (hack-texture s5-0) ) - (adgif-shader<-texture-with-update! arg0 s5-0) + (adgif-shader<-texture-with-update! shader s5-0) ) (else (format 0 "login<2> could not find texture ~X in obj ~A shader ~X~%" - (-> arg0 texture-id) + (-> shader texture-id) (-> *kernel-context* login-object) - arg0 + shader ) ) ) @@ -2051,16 +2147,20 @@ ) ;; definition for function adgif-shader-login-fast -(defun adgif-shader-login-fast ((arg0 adgif-shader)) - (when (logtest? (-> arg0 link-test) (link-test-flags needs-log-in)) - (logclear! (-> arg0 link-test) (link-test-flags needs-log-in bit-9)) - (set! (-> arg0 texture-id) (level-remap-texture (-> arg0 texture-id))) - (let ((v1-4 (-> arg0 texture-id))) +(defun adgif-shader-login-fast ((shader adgif-shader)) + "Set up an adgif shader with the texture-pool, so it points to the right vram address. +Will remap through the level table, so can be used to refer to textures inside 'squashed' +level tpages. +Will not load texture if it is missing." + (when (logtest? (-> shader link-test) (link-test-flags needs-log-in)) + (logclear! (-> shader link-test) (link-test-flags needs-log-in bit-9)) + (set! (-> shader texture-id) (level-remap-texture (-> shader texture-id))) + (let ((v1-4 (-> shader texture-id))) (when (and (nonzero? (-> v1-4 page)) (< (-> v1-4 page) (the-as uint (-> *texture-page-dir* length)))) (let ((a0-9 (-> *texture-page-dir* entries (-> v1-4 page)))) (when (and (< (-> v1-4 index) (the-as uint (-> a0-9 length))) (-> a0-9 link)) - (set! (-> arg0 next shader) (-> a0-9 link next (-> v1-4 index) shader)) - (set! (-> a0-9 link next (-> v1-4 index) shader) (shr (the-as int arg0) 4)) + (set! (-> shader next shader) (-> a0-9 link next (-> v1-4 index) shader)) + (set! (-> a0-9 link next (-> v1-4 index) shader) (shr (the-as int shader) 4)) ) (when (and (-> a0-9 page) (< (-> v1-4 index) (the-as uint (-> a0-9 page length)))) (let ((s5-0 (-> a0-9 page data (-> v1-4 index)))) @@ -2068,7 +2168,7 @@ (if (and *debug-segment* (-> *screen-shot-work* highres-enable)) (hack-texture s5-0) ) - (adgif-shader<-texture-with-update! arg0 s5-0) + (adgif-shader<-texture-with-update! shader s5-0) ) s5-0 ) @@ -2080,15 +2180,18 @@ ) ;; definition for function adgif-shader-login-no-remap-fast -(defun adgif-shader-login-no-remap-fast ((arg0 adgif-shader)) - (when (logtest? (-> arg0 link-test) (link-test-flags needs-log-in)) - (logclear! (-> arg0 link-test) (link-test-flags needs-log-in bit-9)) - (let ((v1-4 (-> arg0 texture-id))) +(defun adgif-shader-login-no-remap-fast ((shader adgif-shader)) + "Set up an adgif shader with the texture-pool, so it points to the right vram address. +Will not remap through the level tpage table. +Will not load texture if it is missing." + (when (logtest? (-> shader link-test) (link-test-flags needs-log-in)) + (logclear! (-> shader link-test) (link-test-flags needs-log-in bit-9)) + (let ((v1-4 (-> shader texture-id))) (when (and (nonzero? (-> v1-4 page)) (< (-> v1-4 page) (the-as uint (-> *texture-page-dir* length)))) (let ((a0-8 (-> *texture-page-dir* entries (-> v1-4 page)))) (when (and (< (-> v1-4 index) (the-as uint (-> a0-8 length))) (-> a0-8 link)) - (set! (-> arg0 next shader) (-> a0-8 link next (-> v1-4 index) shader)) - (set! (-> a0-8 link next (-> v1-4 index) shader) (shr (the-as int arg0) 4)) + (set! (-> shader next shader) (-> a0-8 link next (-> v1-4 index) shader)) + (set! (-> a0-8 link next (-> v1-4 index) shader) (shr (the-as int shader) 4)) ) (when (and (-> a0-8 page) (< (-> v1-4 index) (the-as uint (-> a0-8 page length)))) (let ((s5-0 (-> a0-8 page data (-> v1-4 index)))) @@ -2096,7 +2199,7 @@ (if (and *debug-segment* (-> *screen-shot-work* highres-enable)) (hack-texture s5-0) ) - (adgif-shader<-texture-with-update! arg0 s5-0) + (adgif-shader<-texture-with-update! shader s5-0) ) s5-0 ) @@ -2114,28 +2217,30 @@ ) ;; definition for function adgif-shader<-texture-simple! -(defun adgif-shader<-texture-simple! ((arg0 adgif-shader) (arg1 texture)) - (set! (-> arg0 tex1) (new 'static 'gs-tex1 :mmag #x1 :mmin #x1)) - (set! (-> arg0 tex0 tfx) 0) - (if arg1 - (adgif-shader<-texture! arg0 arg1) +(defun adgif-shader<-texture-simple! ((shader adgif-shader) (tex texture)) + "Simple adgif-shader to texture, just sets vram address and format stuff. +Intended for use with fancy texture stuff that will later set the other regs." + (set! (-> shader tex1) (new 'static 'gs-tex1 :mmag #x1 :mmin #x1)) + (set! (-> shader tex0 tfx) 0) + (if tex + (adgif-shader<-texture! shader tex) ) - (set! (-> arg0 clamp) (new 'static 'gs-clamp :wms (gs-tex-wrap-mode clamp) :wmt (gs-tex-wrap-mode clamp))) - (set! (-> arg0 alpha) (new 'static 'gs-alpha :b #x1 :d #x1)) - (set! (-> arg0 prims 1) (gs-reg64 tex0-1)) - (set! (-> arg0 prims 3) (gs-reg64 tex1-1)) - (set! (-> arg0 prims 5) (gs-reg64 miptbp1-1)) - (set! (-> arg0 clamp-reg) (gs-reg64 clamp-1)) - (set! (-> arg0 prims 9) (gs-reg64 alpha-1)) - arg0 + (set! (-> shader clamp) (new 'static 'gs-clamp :wms (gs-tex-wrap-mode clamp) :wmt (gs-tex-wrap-mode clamp))) + (set! (-> shader alpha) (new 'static 'gs-alpha :b #x1 :d #x1)) + (set! (-> shader prims 1) (gs-reg64 tex0-1)) + (set! (-> shader prims 3) (gs-reg64 tex1-1)) + (set! (-> shader prims 5) (gs-reg64 miptbp1-1)) + (set! (-> shader clamp-reg) (gs-reg64 clamp-1)) + (set! (-> shader prims 9) (gs-reg64 alpha-1)) + shader ) ;; definition for function set-dirty-mask! ;; WARN: Return type mismatch int vs none. -(defun set-dirty-mask! ((arg0 level) (arg1 int) (arg2 int) (arg3 int)) - (let ((s4-0 (sar (+ arg2 #x3fff) 14)) - (s5-0 (sar (+ arg3 #x3fff) 14)) - (gp-0 (-> arg0 texture-dirty-masks arg1)) +(defun set-dirty-mask! ((lev level) (mask-idx int) (m0 int) (m1 int)) + (let ((s4-0 (sar (+ m0 #x3fff) 14)) + (s5-0 (sar (+ m1 #x3fff) 14)) + (gp-0 (-> lev texture-dirty-masks mask-idx)) (v1-5 (new 'stack 'texture-mask)) ) (cond diff --git a/test/decompiler/reference/jak2/engine/gfx/vu1-user-h_REF.gc b/test/decompiler/reference/jak2/engine/gfx/vu1-user-h_REF.gc index 798a439e30..9454888990 100644 --- a/test/decompiler/reference/jak2/engine/gfx/vu1-user-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/gfx/vu1-user-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type dma-foreground-sink (deftype dma-foreground-sink (basic) + "A specification for where a foreground renderer should output its DMA data." ((bucket bucket-id) (foreground-texture-page tpage-category) (foreground-texture-level int8) @@ -27,6 +28,9 @@ ;; definition of type generic-bucket-state (deftype generic-bucket-state (structure) + "The state of buffers for the generic renderer. +When generating generic DMA data, you must know the previous state +of the VU's memory to properly double-buffer the input and output data." ((gifbuf-adr uint32) (inbuf-adr uint32) ) @@ -48,6 +52,8 @@ ;; definition of type generic-dma-foreground-sink (deftype generic-dma-foreground-sink (dma-foreground-sink) + "A specification for where a foreground generic renderer should output DMA data, +and the state of the VU memory buffers at the end of the bucket." ((state generic-bucket-state :inline) ) ) diff --git a/test/decompiler/reference/jak2/engine/level/bsp-h_REF.gc b/test/decompiler/reference/jak2/engine/level/bsp-h_REF.gc index d856db8cfd..3173f22dcd 100644 --- a/test/decompiler/reference/jak2/engine/level/bsp-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/level/bsp-h_REF.gc @@ -3,6 +3,8 @@ ;; definition of type bsp-node (deftype bsp-node (structure) + "A node in the 'BSP' tree. This is really a bounding volume tree, where each volume is an axis-aligned box, containing 2 child boxes. +This is used for precomputed visibility, based on the camera position. This is not used for collision." ((front int16) (back int16) (front-box-min vector4b :inline) @@ -32,6 +34,8 @@ ;; definition of type bsp-header (deftype bsp-header (drawable) + "The bsp-header is really an entire level. +This probably started as a very simple structure, but now it is extremely complicated." ((info file-info :overlay-at id) (all-visible-list (pointer uint16)) (visible-list-length int16) @@ -97,6 +101,7 @@ ;; definition of type game-level (deftype game-level (basic) + "Unused in Jak 1, 2, and 3!" ((master-bsp basic) ) ) @@ -115,6 +120,9 @@ ;; definition of type view-frustum (deftype view-frustum (structure) + "A view frustum, expressed as corners. +This representation is not very useful, and is used in only one spot to generate camera planes +in a very inefficient way." ((hither-top-left vector :inline) (hither-top-right vector :inline) (hither-bottom-left vector :inline) @@ -160,6 +168,7 @@ ;; definition (debug) for function inspect-bsp-tree ;; WARN: Return type mismatch bsp-header vs none. (defun-debug inspect-bsp-tree ((arg0 bsp-header) (arg1 bsp-node)) + "Attempt to print a bsp-tree, but it is actually broken since the jak 2 bsp format change" (cond ((zero? arg1) ) @@ -186,6 +195,7 @@ ;; definition for function map-bsp-tree ;; WARN: Return type mismatch bsp-header vs none. (defun map-bsp-tree ((arg0 (function bsp-node none)) (arg1 bsp-header) (arg2 bsp-node)) + "Attempt to call a function on all bsp-tree nodes, but it is actually broken since the jak 2 bsp format" (cond ((zero? arg2) ) @@ -205,6 +215,8 @@ ;; definition of type collide-stats (deftype collide-stats (structure) + "Very strange collide stats type. It has been somewhat broken in all versions of the game. +The final stopwatch is cut off. For jak 3, I just fixed it." ((calls uint32) (spheres uint32) (nodes uint32) diff --git a/test/decompiler/reference/jak2/engine/level/bsp_REF.gc b/test/decompiler/reference/jak2/engine/level/bsp_REF.gc index f8b0978599..3819761f78 100644 --- a/test/decompiler/reference/jak2/engine/level/bsp_REF.gc +++ b/test/decompiler/reference/jak2/engine/level/bsp_REF.gc @@ -127,6 +127,7 @@ ;; definition for method 9 of type bsp-header (defmethod login ((this bsp-header)) + "Initialize the object after it is loaded." (if (nonzero? (-> this drawable-trees)) (login (-> this drawable-trees)) ) diff --git a/test/decompiler/reference/jak2/engine/level/region-h_REF.gc b/test/decompiler/reference/jak2/engine/level/region-h_REF.gc index 257a1751d6..5875c878ef 100644 --- a/test/decompiler/reference/jak2/engine/level/region-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/level/region-h_REF.gc @@ -3,13 +3,17 @@ ;; definition of type region (deftype region (structure) + "A region is a closed volume that you can, enter, exit, and be inside. +This stores a unique, and script functions for a single region. +These are stored separately from the actual geometry to allow the geometry to be smaller +and fit in scratchpad/cache better." ((id uint32) (on-enter pair) (on-inside pair) (on-exit pair) ) (:methods - (region-method-9 (_type_ vector) symbol) + (point-in-region-debug! (_type_ vector) symbol) ) ) @@ -30,6 +34,7 @@ ;; definition of type region-array (deftype region-array (inline-array-class) + "Array of region." ((data region :inline :dynamic) ) ) @@ -53,6 +58,8 @@ ;; definition of type drawable-region-prim (deftype drawable-region-prim (drawable) + "Base class for a region + geometry. +Note that all child classes of this must be 32-bytes." ((region region :offset 8) ) (:methods @@ -78,6 +85,7 @@ ;; definition of type drawable-tree-region-prim (deftype drawable-tree-region-prim (drawable-tree) + "Top-level container for all regions of a level." ((name basic :offset 8) (data2 drawable-inline-array :dynamic :offset 32) ) @@ -108,6 +116,8 @@ ;; definition of type drawable-inline-array-region-prim (deftype drawable-inline-array-region-prim (drawable-inline-array) + "Inline array of drawable-region-prim. This actually stores child classes, but they are +exactly the same size as the parent, so it's okay." ((data drawable-region-prim 1 :inline) (pad uint8 4) ) @@ -115,6 +125,7 @@ ;; definition of type drawable-region-sphere (deftype drawable-region-sphere (drawable-region-prim) + "Region where the bsphere of the drawable is the volume." () ) @@ -134,6 +145,7 @@ ;; definition of type region-face-data (deftype region-face-data (structure) + "Data to store a single planar face, as a normal and list of vertices." ((normal vector :inline) (normal-offset float :overlay-at (-> normal data 3)) (num-points uint32) @@ -158,6 +170,7 @@ ;; definition of type drawable-region-face (deftype drawable-region-face (drawable-region-prim) + "A drawable-region which is just a face. Unclear if `on-inside` is used." ((data region-face-data :offset 12) ) ) @@ -179,6 +192,7 @@ ;; definition of type region-face-array (deftype region-face-array (inline-array-class) + "An array of faces that hopefully make a closed volume." ((data drawable-region-face :inline :dynamic :offset 16) (pad0 uint8 4) ) @@ -203,6 +217,7 @@ ;; definition of type drawable-region-volume (deftype drawable-region-volume (drawable-region-prim) + "A drawable-region which is a bunch of faces that represent a closed volume." ((faces region-face-array :offset 12) ) ) @@ -224,6 +239,7 @@ ;; definition of type region-prim-list (deftype region-prim-list (structure) + "A list of drawable-region-prim. This is the return type of queries like `which regions contain this point?`" ((num-items int32) (items drawable-region-prim 320) ) diff --git a/test/decompiler/reference/jak2/engine/level/region_REF.gc b/test/decompiler/reference/jak2/engine/level/region_REF.gc index dfeaf248ed..eefc115b56 100644 --- a/test/decompiler/reference/jak2/engine/level/region_REF.gc +++ b/test/decompiler/reference/jak2/engine/level/region_REF.gc @@ -485,7 +485,8 @@ otherwise, add the [[drawable-region-sphere]] to `region-start-prim-list` and in ;; definition for method 9 of type region ;; INFO: Used lq/sq ;; WARN: Return type mismatch int vs symbol. -(defmethod region-method-9 ((this region) (arg0 vector)) +(defmethod point-in-region-debug! ((this region) (arg0 vector)) + "Debug check to see if point is in region. This is not efficient, since it has to find the parent geometry of this region." (local-vars (sv-16 int) (sv-32 int)) (sphere<-vector+r! (the-as sphere (-> (the-as region-prim-area #x70000000) pos)) arg0 0.0) (dotimes (s5-0 (-> *level* length)) diff --git a/test/decompiler/reference/jak2/engine/load/decomp-h_REF.gc b/test/decompiler/reference/jak2/engine/load/decomp-h_REF.gc index f77c19fce5..439a898c9f 100644 --- a/test/decompiler/reference/jak2/engine/load/decomp-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/load/decomp-h_REF.gc @@ -3,6 +3,8 @@ ;; definition of type decomp-work (deftype decomp-work (structure) + "Temporary storage for visibility data decompression. +This is stored on the scratchpad." ((buffer0 uint8 2048) (buffer1 uint8 2048) (indices uint16 2048) diff --git a/test/decompiler/reference/jak2/engine/load/file-io_REF.gc b/test/decompiler/reference/jak2/engine/load/file-io_REF.gc index 92f910d4af..c6d1ddaf8c 100644 --- a/test/decompiler/reference/jak2/engine/load/file-io_REF.gc +++ b/test/decompiler/reference/jak2/engine/load/file-io_REF.gc @@ -29,9 +29,9 @@ ) ;; definition for method 0 of type file-stream -(defmethod new file-stream ((allocation symbol) (type-to-make type) (arg0 string) (arg1 symbol)) - (let ((a0-1 (object-new allocation type-to-make (the-as int (-> type-to-make size))))) - (file-stream-open a0-1 arg0 arg1) +(defmethod new file-stream ((obj symbol) (arg1 type) (file-name string) (mode symbol)) + (let ((a0-1 (object-new obj arg1 (the-as int (-> arg1 size))))) + (file-stream-open a0-1 file-name mode) ) ) @@ -39,10 +39,12 @@ (set! (-> file-stream method-table 4) file-stream-length) ;; definition for function file-stream-read-string -(defun file-stream-read-string ((arg0 file-stream) (arg1 string)) - (clear arg1) - (file-stream-read arg0 (-> arg1 data) (length arg0)) - arg1 +(defun file-stream-read-string ((fs file-stream) (str string)) + "Fill a string with data from a file stream. +Note: this function does not work." + (clear str) + (file-stream-read fs (-> str data) (length fs)) + str ) ;; definition of type file-info @@ -94,6 +96,14 @@ ;; definition for function make-file-name (defun make-file-name ((arg0 file-kind) (arg1 string) (arg2 int) (arg3 symbol)) + "Get a file name to open a file with the given kind and name. +The art-group-version argument can be used to override the version +of the art-group. Set it to 0 or less to use the default version. +Similar to MakeFileName in C. +Note: file type enum is different between C and GOAL. +File versions should match those in versions.h. +Uses a single *file-temp-string* buffer, shared with make-vfile-name. +arg3 is unused." (clear *file-temp-string*) (cond ((= arg0 (file-kind dir-tpage)) @@ -138,14 +148,16 @@ ) ;; definition for function make-vfile-name -(defun make-vfile-name ((arg0 file-kind) (arg1 string)) +(defun make-vfile-name ((kind file-kind) (name string)) + "Make virtual? file name. This makes a name that the kernel knows how to +handle in a specific way. This function is not used." (clear *file-temp-string*) (cond - ((= arg0 (file-kind level-bt)) - (format *file-temp-string* "$LEVEL/~S" arg1) + ((= kind (file-kind level-bt)) + (format *file-temp-string* "$LEVEL/~S" name) ) - ((= arg0 (file-kind art-group)) - (format *file-temp-string* "$ART_GROUP/~S" arg1) + ((= kind (file-kind art-group)) + (format *file-temp-string* "$ART_GROUP/~S" name) ) ) *file-temp-string* @@ -153,6 +165,8 @@ ;; definition for function file-info-correct-version? (defun file-info-correct-version? ((arg0 file-info) (arg1 file-kind) (arg2 int)) + "Check if the version and kind in the info is valid. The `version-override` can specify a +non-default version, or set to 0 for the default version." (let* ((s5-0 (cond ((zero? arg2) (case arg1 diff --git a/test/decompiler/reference/jak2/engine/load/load-dgo_REF.gc b/test/decompiler/reference/jak2/engine/load/load-dgo_REF.gc index a66b0865d2..f9920b189c 100644 --- a/test/decompiler/reference/jak2/engine/load/load-dgo_REF.gc +++ b/test/decompiler/reference/jak2/engine/load/load-dgo_REF.gc @@ -3,6 +3,7 @@ ;; definition of type load-dgo-msg (deftype load-dgo-msg (structure) + "IOP RPC message for loading a dgo." ((rsvd uint16) (result load-msg-result) (b1 pointer) @@ -34,6 +35,7 @@ ;; definition of type load-chunk-msg (deftype load-chunk-msg (structure) + "IOP RPC message for loading a chunk of a chunked animation" ((rsvd uint16) (result load-msg-result) (address pointer) @@ -64,6 +66,7 @@ ;; definition of type play-chunk-msg (deftype play-chunk-msg (structure) + "IOP RPC message for playing some streamed audio." ((rsvd uint16) (result uint16) (address pointer) @@ -123,16 +126,17 @@ ) ;; definition for function str-load -(defun str-load ((arg0 string) (arg1 int) (arg2 pointer) (arg3 int)) +(defun str-load ((name string) (chunk-idx int) (dest-addr pointer) (max-len int)) + "Send a message to the IOP to start loading a chunk of a .STR file to the EE." (if (or (check-busy *load-str-rpc*) *load-str-lock*) (return #f) ) (let ((s2-0 (the-as load-chunk-msg (add-element *load-str-rpc*)))) (set! (-> s2-0 result) (load-msg-result invalid)) - (set! (-> s2-0 address) arg2) - (set! (-> s2-0 section) (the-as uint arg1)) - (set! (-> s2-0 maxlen) (the-as uint arg3)) - (copyn-charp<-string (the-as (pointer uint8) (-> s2-0 basename)) arg0 48) + (set! (-> s2-0 address) dest-addr) + (set! (-> s2-0 section) (the-as uint chunk-idx)) + (set! (-> s2-0 maxlen) (the-as uint max-len)) + (copyn-charp<-string (the-as (pointer uint8) (-> s2-0 basename)) name 48) (call *load-str-rpc* (the-as uint 0) (the-as pointer s2-0) (the-as uint 32)) ) (set! *load-str-lock* #t) @@ -141,7 +145,10 @@ ) ;; definition for function str-load-status -(defun str-load-status ((arg0 (pointer int32))) +(defun str-load-status ((maxlen-out (pointer int32))) + "Get the status of the most recent load. +Return 'busy if in progress, 'error if failed, or 'complete. +If 'complete, returns the maxlen value from the IOP." (if (check-busy *load-str-rpc*) (return 'busy) ) @@ -151,7 +158,7 @@ (if (= (-> v1-7 result) (load-msg-result error)) (return 'error) ) - (set! (-> arg0 0) (the-as int (-> v1-7 maxlen))) + (set! (-> maxlen-out 0) (the-as int (-> v1-7 maxlen))) ) 'complete ) @@ -159,6 +166,7 @@ ;; definition for function str-load-cancel ;; WARN: Return type mismatch int vs none. (defun str-load-cancel () + "Cancel a streaming load. Note that this does not actually stop the transfer, so the IOP may continue writing to the buffer." (set! *load-str-lock* #f) (set! *que-str-lock* #t) 0 @@ -168,6 +176,7 @@ ;; definition for function str-play-async ;; WARN: Return type mismatch int vs none. (defun str-play-async ((arg0 string) (arg1 sound-id)) + "Start playing a streaming audio." (set! *que-str-lock* #t) (let ((s4-0 (the-as play-chunk-msg (add-element *play-str-rpc*)))) (copyn-charp<-string (the-as (pointer uint8) (-> s4-0 basename)) arg0 48) @@ -187,14 +196,15 @@ ;; definition for function str-play-stop ;; WARN: Return type mismatch int vs none. -(defun str-play-stop ((arg0 string) (arg1 sound-id)) +(defun str-play-stop ((name string) (id sound-id)) + "Stop playing streaming audio." (set! *que-str-lock* #t) (let ((s4-0 (the-as play-chunk-msg (add-element *play-str-rpc*)))) - (copyn-charp<-string (the-as (pointer uint8) (-> s4-0 basename)) arg0 48) + (copyn-charp<-string (the-as (pointer uint8) (-> s4-0 basename)) name 48) (copyn-charp<-string (the-as (pointer uint8) (-> s4-0 basename 1)) "" 48) (copyn-charp<-string (the-as (pointer uint8) (-> s4-0 basename 2)) "" 48) (copyn-charp<-string (the-as (pointer uint8) (-> s4-0 basename 3)) "" 48) - (set! (-> s4-0 id 0) (the-as uint arg1)) + (set! (-> s4-0 id 0) (the-as uint id)) (set! (-> s4-0 id 1) (the-as uint 0)) (set! (-> s4-0 id 2) (the-as uint 0)) (set! (-> s4-0 id 3) (the-as uint 0)) @@ -207,6 +217,7 @@ ;; definition for function str-play-queue ;; WARN: Return type mismatch int vs none. (defun str-play-queue ((arg0 string) (arg1 string) (arg2 string) (arg3 string) (arg4 (pointer uint32)) (arg5 pointer)) + "Queue up streaming data, allowing it to start playing without delay." (when (and (not (check-busy *play-str-rpc*)) (not *load-str-lock*) (not *que-str-lock*)) (let ((s4-0 (the-as play-chunk-msg (add-element *play-str-rpc*)))) (if arg0 @@ -240,6 +251,7 @@ ;; definition for function str-ambient-play ;; WARN: Return type mismatch int vs none. (defun str-ambient-play ((arg0 string)) + "Start playing ambient (unused?)." (set! *que-str-lock* #t) (let ((s5-0 (the-as load-chunk-msg (add-element *play-str-rpc*)))) (set! (-> s5-0 basename name 0) (the-as uint 36)) @@ -254,6 +266,7 @@ ;; definition for function str-ambient-stop ;; WARN: Return type mismatch int vs none. (defun str-ambient-stop ((arg0 string)) + "Stop playing ambient (unused?)." (set! *que-str-lock* #t) (let ((s5-0 (the-as load-chunk-msg (add-element *play-str-rpc*)))) (set! (-> s5-0 basename name 0) (the-as uint 36)) @@ -267,6 +280,7 @@ ;; definition for function str-play-kick ;; WARN: Return type mismatch int vs none. (defun str-play-kick () + "Do an empty RPC on play so the IOP code runs and can update buffers." (cond ((check-busy *play-str-rpc*) ) @@ -284,6 +298,7 @@ ;; definition for function dgo-load-begin ;; INFO: Used lq/sq (defun dgo-load-begin ((arg0 string) (arg1 pointer) (arg2 pointer) (arg3 pointer)) + "Start a DGO load!" (set! *dgo-time* (the-as time-frame (-> *display* real-clock integral-frame-counter))) (format 0 "Starting level load clock~%") (sync *load-dgo-rpc* #t) @@ -300,6 +315,7 @@ ;; definition for function dgo-load-get-next (defun dgo-load-get-next ((arg0 (pointer symbol))) + "Get the address of the most recently loaded object. #f is there is none. Returns if this is the last by arg0." (set! (-> arg0 0) #f) (let ((gp-0 (the-as pointer #f))) (when (not (check-busy *load-dgo-rpc*)) @@ -328,12 +344,13 @@ ;; definition for function dgo-load-continue ;; INFO: Used lq/sq -(defun dgo-load-continue ((arg0 pointer) (arg1 pointer) (arg2 pointer)) +(defun dgo-load-continue ((buffer1 pointer) (buffer2 pointer) (buffer-top pointer)) + "Inform the IOP that it is safe to start loading the next object." (let ((gp-0 (the-as load-dgo-msg (add-element *load-dgo-rpc*)))) (set! (-> gp-0 result) (load-msg-result invalid)) - (set! (-> gp-0 b1) arg0) - (set! (-> gp-0 b2) arg1) - (set! (-> gp-0 bt) arg2) + (set! (-> gp-0 b1) buffer1) + (set! (-> gp-0 b2) buffer2) + (set! (-> gp-0 bt) buffer-top) (set! (-> gp-0 name) (the-as uint128 0)) (call *load-dgo-rpc* (the-as uint 1) (the-as pointer gp-0) (the-as uint 32)) gp-0 @@ -343,6 +360,7 @@ ;; definition for function dgo-load-cancel ;; WARN: Return type mismatch int vs none. (defun dgo-load-cancel () + "Abort a DGO load." (sync *load-dgo-rpc* #t) (let ((a2-0 (add-element *load-dgo-rpc*))) (call *load-dgo-rpc* (the-as uint 2) a2-0 (the-as uint 32)) @@ -352,8 +370,10 @@ ) ;; definition for function find-temp-buffer -(defun find-temp-buffer ((arg0 int)) - (let ((gp-0 (+ (/ arg0 16) 2))) +(defun find-temp-buffer ((size int)) + "Unused function to find some temporary leftover space in DMA buffer. +Unused since jak 1, and checks the same buffer twice??" + (let ((gp-0 (+ (/ size 16) 2))) (cond ((< (the-as uint gp-0) (the-as uint (dma-buffer-free (-> *display* frames (-> *display* on-screen) global-buf))) @@ -371,6 +391,7 @@ ;; definition for function dgo-load-link (defun dgo-load-link ((arg0 dgo-header) (arg1 kheap) (arg2 uint) (arg3 symbol) (arg4 symbol)) + "Start the async linker on a GOAL object file that was just loaded." (let ((s4-0 (the-as object (&+ arg0 64)))) (let ((v1-0 arg2)) (cond @@ -426,10 +447,11 @@ ;; definition for function destroy-mem ;; WARN: Return type mismatch int vs none. -(defun destroy-mem ((arg0 (pointer uint32)) (arg1 (pointer uint32))) - (while (< (the-as int arg0) (the-as int arg1)) - (set! (-> arg0 0) (the-as uint #xffffffff)) - (set! arg0 (&-> arg0 1)) +(defun destroy-mem ((start (pointer uint32)) (end (pointer uint32))) + "Overwrite memory with #xffffffff for debugging." + (while (< (the-as int start) (the-as int end)) + (set! (-> start 0) (the-as uint #xffffffff)) + (set! start (&-> start 1)) ) 0 (none) diff --git a/test/decompiler/reference/jak2/engine/load/loader-h_REF.gc b/test/decompiler/reference/jak2/engine/load/loader-h_REF.gc index e8364d2ac7..552ca7a30f 100644 --- a/test/decompiler/reference/jak2/engine/load/loader-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/load/loader-h_REF.gc @@ -16,6 +16,7 @@ ;; definition of type load-dir-art-group (deftype load-dir-art-group (load-dir) + "Specialization of load-dir for `art-group`s." ((art-group-array (array art-group) :overlay-at data-array) ) (:methods @@ -48,6 +49,7 @@ ;; definition of type external-art-buffer (deftype external-art-buffer (basic) + "An `external-art-buffer` is a buffer that streamed files use." ((index int32) (other external-art-buffer) (status symbol) @@ -136,6 +138,8 @@ ;; definition of type spool-anim (deftype spool-anim (basic) + "A `spool-anim` is metadata for an animation that will be loaded in chunks +to a pair of external-art-buffers." ((name string :offset 16) (anim-name basic) (buffer external-art-buffer :overlay-at anim-name) @@ -167,6 +171,7 @@ ;; definition of type external-art-control (deftype external-art-control (basic) + "The `external-art-control` manages loading chunks from `spool-anim`s to `external-art-buffer`." ((buffer external-art-buffer 2) (rec spool-anim 3 :inline) (spool-lock handle) diff --git a/test/decompiler/reference/jak2/engine/load/ramdisk_REF.gc b/test/decompiler/reference/jak2/engine/load/ramdisk_REF.gc index 1138d77026..7fe2240c5c 100644 --- a/test/decompiler/reference/jak2/engine/load/ramdisk_REF.gc +++ b/test/decompiler/reference/jak2/engine/load/ramdisk_REF.gc @@ -3,6 +3,7 @@ ;; definition of type ramdisk-rpc-fill (deftype ramdisk-rpc-fill (structure) + "Unused RAMDISK rpc to load files from DVD to the IOP RAM." ((rsvd1 int32) (ee-id int32) (rsvd2 int32 2) @@ -28,6 +29,7 @@ ;; definition of type ramdisk-rpc-load (deftype ramdisk-rpc-load (structure) + "Unused RAMDISK rpc to load files from DVD to the IOP RAM." ((rsvd int32) (ee-id int32) (offset uint32) @@ -52,6 +54,7 @@ ;; definition of type ramdisk-rpc-load-to-ee (deftype ramdisk-rpc-load-to-ee (structure) + "Unused RAMDISK rpc to load files from DVD to the IOP RAM." ((rsvd int32) (addr int32) (offset int32) diff --git a/test/decompiler/reference/jak2/engine/math/euler-h_REF.gc b/test/decompiler/reference/jak2/engine/math/euler-h_REF.gc index 6d6d5b96eb..b8b0d754ab 100644 --- a/test/decompiler/reference/jak2/engine/math/euler-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/math/euler-h_REF.gc @@ -2,13 +2,21 @@ (in-package goal) ;; definition for symbol EulSafe, type (array int32) -(define EulSafe (new 'static 'boxed-array :type int32 0 1 2 0)) +(define EulSafe + "Maybe euler angle storage orders? +What is this naming convention?" + (new 'static 'boxed-array :type int32 0 1 2 0) + ) ;; definition for symbol EulNext, type (array int32) (define EulNext (new 'static 'boxed-array :type int32 1 2 0 1)) ;; definition of type euler-angles (deftype euler-angles (vector) + "Just uses the same xyzw and data array as vector. +The `w` stores an integer that seems to have +bitfields for... something? Like maybe the order? +Euler angles are mostly unused, and the code is a bit of disaster." () ) diff --git a/test/decompiler/reference/jak2/engine/math/euler_REF.gc b/test/decompiler/reference/jak2/engine/math/euler_REF.gc index 537e56ba1b..ee061a6362 100644 --- a/test/decompiler/reference/jak2/engine/math/euler_REF.gc +++ b/test/decompiler/reference/jak2/engine/math/euler_REF.gc @@ -3,6 +3,7 @@ ;; definition for function set-eul! (defun set-eul! ((arg0 euler-angles) (arg1 float) (arg2 float) (arg3 float) (arg4 int)) + "Set euler angles and the flag bits." (set! (-> arg0 x) arg1) (set! (-> arg0 y) arg2) (set! (-> arg0 z) arg3) @@ -13,6 +14,7 @@ ;; definition for function eul->matrix ;; INFO: Used lq/sq (defun eul->matrix ((arg0 matrix) (arg1 euler-angles)) + "Convert from euler angles to 4x4 matrix." (matrix-identity! arg0) (let ((s5-0 (new 'stack-no-clear 'vector))) (set! (-> s5-0 quad) (-> arg1 quad)) @@ -94,6 +96,8 @@ ;; definition for function matrix->eul (defun matrix->eul ((arg0 euler-angles) (arg1 matrix) (arg2 int)) + "Convert matrix to euler angles with given order flag. +Not clear how this works if the matrix has more than just a rotation." 0 0 0 @@ -192,6 +196,7 @@ ;; definition for function eul->quat (defun eul->quat ((arg0 quaternion) (arg1 euler-angles)) + "Convert euler angles to quaternion, not very efficient." (let ((s5-0 (new 'stack-no-clear 'matrix))) (eul->matrix s5-0 arg1) (matrix->quaternion arg0 s5-0) @@ -201,13 +206,10 @@ ;; definition for function quat->eul (defun quat->eul ((arg0 euler-angles) (arg1 quaternion) (arg2 int)) + "Convert quaternion to euler angles with given order, not very efficient." (let ((s5-0 (new 'stack-no-clear 'matrix))) (quaternion->matrix s5-0 arg1) (matrix->eul arg0 s5-0 arg2) ) arg0 ) - - - - diff --git a/test/decompiler/reference/jak2/engine/math/math_REF.gc b/test/decompiler/reference/jak2/engine/math/math_REF.gc index 74e37719ba..789db0943c 100644 --- a/test/decompiler/reference/jak2/engine/math/math_REF.gc +++ b/test/decompiler/reference/jak2/engine/math/math_REF.gc @@ -3,11 +3,14 @@ ;; definition for function truncate (defun truncate ((arg0 float)) + "Round (toward zero) to an integer. +@param arg0 float to truncate" (the float (the int arg0)) ) ;; definition for function floor (defun floor ((arg0 float)) + "Round (down) to an integer" (let ((f0-3 (the float (the int arg0)))) (if (or (>= arg0 0.0) (= arg0 f0-3)) f0-3 @@ -18,6 +21,7 @@ ;; definition for function ceil (defun ceil ((arg0 float)) + "Round (up) to an integer" (let ((f0-3 (the float (the int arg0)))) (if (or (>= 0.0 arg0) (= arg0 f0-3)) f0-3 @@ -28,16 +32,19 @@ ;; definition for function integral? (defun integral? ((arg0 float)) + "Is this number an integer?" (= (the float (the int arg0)) arg0) ) ;; definition for function fractional-part (defun fractional-part ((arg0 float)) + "Get the fractional part of a float." (- arg0 (the float (the int arg0))) ) ;; definition for function sawtooth-wave (defun sawtooth-wave ((arg0 float)) + "Sample a sawtooth with period 1. In range (0, 1)" (let ((f0-2 (- arg0 (the float (the int arg0))))) (if (< f0-2 0.0) (set! f0-2 (+ 1.0 f0-2)) @@ -48,6 +55,7 @@ ;; definition for function triangle-wave (defun triangle-wave ((arg0 float)) + "Sample a triangle wave. Period is 4, in range (-1, 1) (so slope is 1 or -1)." (let* ((f0-1 (* 0.25 (+ -1.0 arg0))) (f0-3 (- f0-1 (the float (the int f0-1)))) ) @@ -60,6 +68,7 @@ ;; definition for function log-x-plus-1-order9 (defun log-x-plus-1-order9 ((arg0 float)) + "Fast approximation of ln(x + 1). Probably only accurate for x in [0, 1]." (* arg0 (+ 1.0 (* arg0 @@ -81,6 +90,7 @@ ;; definition for function logf (defun logf ((arg0 float)) + "Natural log." (let ((v1-1 (the-as int (+ (shr (the-as int arg0) 23) -126))) (a0-2 (the-as number (logior #x3f000000 (logand (the-as uint #x807fffff) (the-as uint arg0))))) ) @@ -114,6 +124,7 @@ ;; definition for function log2f (defun log2f ((arg0 float)) + "Log base 2." (let ((v1-1 (the-as int (+ (shr (the-as int arg0) 23) -126))) (a0-2 (the-as number (logior #x3f000000 (logand (the-as uint #x807fffff) (the-as uint arg0))))) ) @@ -231,12 +242,14 @@ ;; definition for function pow (defun pow ((arg0 float) (arg1 float)) + "Compute arg0^arg1" (exp (* arg1 (logf arg0))) ) ;; definition for function print-exp ;; WARN: Return type mismatch int vs none. (defun print-exp ((arg0 float)) + "Print in the format AeB where A is in the range (1, 10)" (let* ((f30-1 (floor (/ (logf (fabs arg0)) (logf 10.0)))) (f0-4 (pow 10.0 f30-1)) ) @@ -292,6 +305,7 @@ ;; definition for function seek (defun seek ((arg0 float) (arg1 float) (arg2 float)) + "Move arg0 toward arg1 by at most arg2." (let ((f2-0 (- arg1 arg0))) (cond ((>= arg2 (fabs f2-0)) @@ -309,6 +323,9 @@ ;; definition for function seek-ease (defun seek-ease ((arg0 float) (arg1 float) (arg2 float) (arg3 float) (arg4 float)) + "Move arg0 toward arg1, and slow down before reaching the end. +When farther than arg3 away, move by at most arg2. +When closer than arg3, linearly ramp down the movement amount from arg2 to 0 but no lower than arg4." (let ((f2-0 (- arg1 arg0))) (when (>= arg3 (fabs f2-0)) (set! arg2 (* arg2 (- 1.0 (/ (- arg3 (fabs f2-0)) arg3)))) @@ -332,6 +349,10 @@ ;; definition for function seek-ease-in-out (defun seek-ease-in-out ((arg0 float) (arg1 float) (arg2 float) (arg3 float) (arg4 float) (arg5 float) (arg6 float)) + "Move arg0 toward arg2, and slow down at the start and end. +When within arg4 of arg1 (at the beginning of movement), ramp up speed, with a minimum speed of arg6 +When within arg5 of arg2 (at the end of movement), ramp down speed, with a minimum speed of arg5 +Normally, move at most arg3" (let ((f2-0 (- arg2 arg0))) (let ((f4-1 (- arg0 arg1))) (when (>= arg4 (fabs f4-1)) @@ -363,11 +384,14 @@ ;; definition for function lerp (defun lerp ((arg0 float) (arg1 float) (arg2 float)) + "Linearly interpolate between arg0 and arg1." (+ arg0 (* arg2 (- arg1 arg0))) ) ;; definition (debug) for function lerp-scale-old (defun-debug lerp-scale-old ((arg0 float) (arg1 float) (arg2 float) (arg3 float) (arg4 float)) + "Linearly remap arg2 in [arg3, arg4] to [arg0, arg1]. +This is the jak 1 implementation, which I claimed was a bad implementation..." (let ((f0-1 (fmax 0.0 (fmin 1.0 (/ (- arg2 arg3) (- arg4 arg3)))))) (+ (* (- 1.0 f0-1) arg0) (* f0-1 arg1)) ) @@ -397,6 +421,7 @@ ;; definition for function lerp-clamp (defun lerp-clamp ((arg0 float) (arg1 float) (arg2 float)) + "Linearly interpolate between arg0 and arg1. arg2 is clamped to [0, 1]" (cond ((>= 0.0 arg2) arg0 @@ -412,6 +437,7 @@ ;; definition for function seekl (defun seekl ((arg0 int) (arg1 int) (arg2 int)) + "Move arg0 toward arg1, by at most arg2." (let* ((v1-0 (- arg1 arg0)) (a3-0 (abs v1-0)) ) @@ -434,6 +460,7 @@ ;; ERROR: Unsupported inline assembly instruction kind - [ctc2.i vi_R, a0] ;; ERROR: Unsupported inline assembly instruction kind - [cfc2.i v0, vi_R] (defun rand-vu-init ((arg0 float)) + "Initialize the VU0 random generator." (local-vars (v0-0 int)) (.ctc2.i vi_R arg0) (.cfc2.i v0-0 vi_R) @@ -469,6 +496,9 @@ ;; definition for function rand-vu-nostep ;; ERROR: Inline assembly instruction marked with TODO - [TODO.VRGET] (defun rand-vu-nostep () + "Get the number currently in the random generator. +This will be equal to the last call of (rand-vu). +This will not update the random generator." (local-vars (v0-0 float)) (rlet ((vf0 :class vf) (vf1 :class vf) @@ -483,16 +513,19 @@ ;; definition for function rand-vu-float-range (defun rand-vu-float-range ((arg0 float) (arg1 float)) + "Get a random float in between arg0 and arg1." (+ arg0 (* (rand-vu) (- arg1 arg0))) ) ;; definition for function rand-vu-percent? (defun rand-vu-percent? ((arg0 float)) + "Get a boolean that's true with the given probability (in 0, 1)." (>= arg0 (rand-vu)) ) ;; definition for function rand-vu-int-range (defun rand-vu-int-range ((arg0 int) (arg1 int)) + "Get an integer in the given range (inclusive)." (if (< arg0 arg1) (set! arg1 (+ arg1 1)) (set! arg0 (+ arg0 1)) @@ -507,12 +540,15 @@ ;; definition for function rand-vu-int-count (defun rand-vu-int-count ((arg0 int)) + "Get an integer in the range [0, max)." (the int (* (rand-vu) (the float arg0))) ) ;; definition for function rand-vu-int-count-excluding ;; WARN: new jak 2 until loop case, check carefully (defun rand-vu-int-count-excluding ((arg0 int) (arg1 int)) + "Get an integer in the range [0, arg0). +If bit n is set in arg1, exclude this value from being returned." (let ((s4-0 0) (s5-0 0) ) @@ -554,6 +590,8 @@ ;; definition for function rand-vu-int-range-exclude ;; WARN: new jak 2 until loop case, check carefully (defun rand-vu-int-range-exclude ((arg0 int) (arg1 int) (arg2 int)) + "Get an integer in the range [0, arg0), excluding arg2. +Note that this doesn't use bits like rand-vu-int-count-excluding." (until #f (let ((v1-0 (rand-vu-int-range arg0 arg1))) (if (!= v1-0 arg2) @@ -593,6 +631,7 @@ ;; definition for function cube-root (defun cube-root ((arg0 float)) + "Cube root with cool trick that I don't understand." (cond ((!= arg0 0.0) (let* ((v1-0 arg0) @@ -625,6 +664,7 @@ ;; definition for function int-noise (defun int-noise ((arg0 int)) + "Generate random-ish floats in range -1, 1." (let ((v1-1 (logxor (shl arg0 13) arg0))) (- 1.0 (* 0.0000000009313226 (the float (logand #x7fffffff (+ #x5208dd0d (* v1-1 (+ #xc0ae5 (* (* #x3d73 v1-1) v1-1)))))) @@ -635,6 +675,8 @@ ;; definition for function smooth-step (defun smooth-step ((arg0 float)) + "Interpolate between 0, 1 with a cubic polynomial. +These are picked so f(0) = 0, f(1) = 1, f'(0) = f'(1) = 0." (cond ((>= 0.0 arg0) 0.0 @@ -650,5 +692,10 @@ ;; definition for function smooth-interp (defun smooth-interp ((arg0 float) (arg1 float) (arg2 float) (arg3 float) (arg4 float)) + "Remap arg2 from (arg3, arg4) to (arg0, arg1), using cubic interpolation. +Satisfies: +- f(arg3) = arg0 +- f(arg4) = arg1 +- f'(arg3) = f'(arg4) = 0" (+ arg0 (* (- arg1 arg0) (smooth-step (/ (- arg2 arg3) (- arg4 arg3))))) ) diff --git a/test/decompiler/reference/jak2/engine/math/matrix-h_REF.gc b/test/decompiler/reference/jak2/engine/math/matrix-h_REF.gc index 82e20ba359..1efe571fde 100644 --- a/test/decompiler/reference/jak2/engine/math/matrix-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/math/matrix-h_REF.gc @@ -3,6 +3,9 @@ ;; definition of type matrix (deftype matrix (structure) + "A 4x4 matrix, stored in row-major order. +some, but not all, functions assume that a matrix is an affine transform. +others assume that the rotation has no scale or shear (and that its inverse is its transpose)." ((data float 16) (vector vector 4 :inline :overlay-at (-> data 0)) (quad uint128 4 :overlay-at (-> data 0)) @@ -31,6 +34,10 @@ ;; definition of type matrix3 (deftype matrix3 (structure) + "A 3x3 matrix, stored in row-major order. +NOTE: the rows each have an extra 4-bytes of padding, +so this is really a 3x4 matrix. +This type is rarely used." ((data float 12) (vector vector 3 :inline :overlay-at (-> data 0)) (quad uint128 3 :overlay-at (-> data 0)) @@ -54,6 +61,11 @@ ;; definition of type matrix4h (deftype matrix4h (structure) + "A matrix stored using 16-bit integers. +Note that these usually have different scaling for the 4th row which +contains the translation in an affine transform. +So you generally should not unpack these to floats without knowing where they came from +and how they were originally packed (for example, in tie/shrub)." ((data int16 16) (vector4h vector4h 4 :inline :overlay-at (-> data 0)) (long int64 4 :overlay-at (-> data 0)) @@ -77,6 +89,7 @@ ;; definition for function matrix-copy! ;; INFO: Used lq/sq (defun matrix-copy! ((arg0 matrix) (arg1 matrix)) + "Copy arg1 to arg0" (let ((v1-0 (-> arg1 quad 0)) (a2-0 (-> arg1 quad 1)) (a3-0 (-> arg1 quad 2)) diff --git a/test/decompiler/reference/jak2/engine/math/matrix_REF.gc b/test/decompiler/reference/jak2/engine/math/matrix_REF.gc index 98728c9753..5253f69a1b 100644 --- a/test/decompiler/reference/jak2/engine/math/matrix_REF.gc +++ b/test/decompiler/reference/jak2/engine/math/matrix_REF.gc @@ -46,6 +46,7 @@ ;; definition for function matrix-identity! ;; INFO: Used lq/sq (defun matrix-identity! ((arg0 matrix)) + "Set dst to the identity matrix." (set! (-> arg0 quad 0) (the-as uint128 0)) (set! (-> arg0 quad 1) (the-as uint128 0)) (set! (-> arg0 quad 2) (the-as uint128 0)) @@ -74,6 +75,8 @@ ;; definition for function matrix+! (defun matrix+! ((arg0 matrix) (arg1 matrix) (arg2 matrix)) + "Set dst = src1 + src2. It is okay for any arguments to be the same data. +This is not an efficient implementation." (dotimes (v1-0 16) (set! (-> arg0 data v1-0) (+ (-> arg1 data v1-0) (-> arg2 data v1-0))) ) @@ -82,6 +85,8 @@ ;; definition for function matrix-! (defun matrix-! ((arg0 matrix) (arg1 matrix) (arg2 matrix)) + "Set dst = src1 - src1. It is okay for any arugments to be the same data. +This is not an efficient implementation." (dotimes (v1-0 16) (set! (-> arg0 data v1-0) (- (-> arg1 data v1-0) (-> arg2 data v1-0))) ) @@ -90,6 +95,8 @@ ;; definition for function matrix*! (defun matrix*! ((arg0 matrix) (arg1 matrix) (arg2 matrix)) + "Set dst = src1 * src2. It is okay for any arguments to be the same data. +This is a moderately efficient implementation." (rlet ((acc :class vf) (vf10 :class vf) (vf11 :class vf) @@ -139,6 +146,9 @@ ;; definition for function matrixp*! ;; INFO: Used lq/sq (defun matrixp*! ((arg0 matrix) (arg1 matrix) (arg2 matrix)) + "Set dst = src1 * src2. NOTE: this function is a wrapper around matrix*! +that adds no additional functionality. It seems to be a leftover from +a time when matrix*! wasn't safe to use in place. This is unused." (let ((s5-0 (new-stack-matrix0))) (matrix*! s5-0 arg1 arg2) (set! (-> arg0 quad 0) (-> s5-0 quad 0)) @@ -151,6 +161,7 @@ ;; definition for function vector-matrix*! (defun vector-matrix*! ((arg0 vector) (arg1 vector) (arg2 matrix)) + "Set dst = vec * mat. dst may be equal to src." (rlet ((acc :class vf) (vf1 :class vf) (vf2 :class vf) @@ -203,6 +214,8 @@ ;; definition for function vector3s-matrix*! ;; INFO: Used lq/sq (defun vector3s-matrix*! ((arg0 vector3s) (arg1 vector3s) (arg2 matrix)) + "Set dst to be ([src 1.0] * mat).xyz. Doesn't touch the w of dst. +dst and vec can be the same memory" (let ((s5-0 (new-stack-vector0))) (set-vector! s5-0 (-> arg1 x) (-> arg1 y) (-> arg1 z) 1.0) (vector-matrix*! s5-0 s5-0 arg2) @@ -216,6 +229,8 @@ ;; definition for function vector3s-rotate*! ;; INFO: Used lq/sq (defun vector3s-rotate*! ((arg0 vector3s) (arg1 vector3s) (arg2 matrix)) + "Set dst to vec rotated by the rotation in the homogeneous transform mat. +mat should not have a scale/shear (the upper 3x3 should be a pure rotation)." (let ((s5-0 (new-stack-vector0))) (set-vector! s5-0 (-> arg1 x) (-> arg1 y) (-> arg1 z) 1.0) (vector-rotate*! s5-0 s5-0 arg2) @@ -229,6 +244,7 @@ ;; definition for function matrix-transpose! ;; INFO: Used lq/sq (defun matrix-transpose! ((arg0 matrix) (arg1 matrix)) + "Set dst = src^T. src and dst can be the same." (local-vars (v1-0 uint128) (v1-1 uint128) (v1-2 uint128) (a1-1 uint128) (a2-1 uint128) (t0-1 uint128)) (nop!) (nop!) @@ -266,6 +282,8 @@ ;; definition for function matrix-inverse-of-rot-trans! (defun matrix-inverse-of-rot-trans! ((arg0 matrix) (arg1 matrix)) + "Set dst = src^-1, assuming src is a homogeneous tranform with only rotation/translation. +NOTE: THIS FUNCTION REQUIRES dst != src" (rlet ((acc :class vf) (vf0 :class vf) (vf1 :class vf) @@ -301,6 +319,8 @@ ;; ERROR: Bad vector register dependency: vf4 ;; ERROR: Bad vector register dependency: vf5 (defun matrix-4x4-inverse! ((arg0 matrix) (arg1 matrix)) + "Invert a 4x4 matrix. This assumes that the input is a homogeneous transform. +Src and dst can be the same." (rlet ((acc :class vf) (Q :class vf) (vf0 :class vf) @@ -452,6 +472,7 @@ ;; definition for function matrix-translate! (defun matrix-translate! ((arg0 matrix) (arg1 vector)) + "Set dst to a homogeneous transform with only a translation of trans." (matrix-identity! arg0) (set! (-> arg0 trans x) (-> arg1 x)) (set! (-> arg0 trans y) (-> arg1 y)) @@ -462,6 +483,8 @@ ;; definition for function matrix-translate+! ;; INFO: Used lq/sq (defun matrix-translate+! ((arg0 matrix) (arg1 matrix) (arg2 vector)) + "Add the given translation to the translation of homogenous transform mat src +and store in dst. It is okay for dst = src." (set! (-> arg0 trans x) (+ (-> arg1 trans x) (-> arg2 x))) (set! (-> arg0 trans y) (+ (-> arg1 trans y) (-> arg2 y))) (set! (-> arg0 trans z) (+ (-> arg1 trans z) (-> arg2 z))) @@ -476,6 +499,8 @@ ;; definition for function matrix-scale! ;; INFO: Used lq/sq (defun matrix-scale! ((arg0 matrix) (arg1 vector)) + "Set dst to a homogenous transform with only a scale. The x,y,z components +of scale become the x,y,z scaling factors" (set! (-> arg0 quad 0) (the-as uint128 0)) (set! (-> arg0 quad 1) (the-as uint128 0)) (set! (-> arg0 quad 2) (the-as uint128 0)) @@ -489,6 +514,9 @@ ;; definition for function scale-matrix! (defun scale-matrix! ((arg0 matrix) (arg1 vector) (arg2 matrix)) + "Scale an existing matrix. Okay for dst = src. The scaling is applied per row. +This means the x component of scale is used to scale the first row of src. +The w component of scale is used." (rlet ((vf4 :class vf) (vf5 :class vf) (vf6 :class vf) @@ -515,6 +543,8 @@ ;; definition for function matrix-inv-scale! ;; INFO: Used lq/sq (defun matrix-inv-scale! ((arg0 matrix) (arg1 vector)) + "Set dst to a homogeneous transform with only a scale. +The x,y,z components of scale are inverted and used as the x,y,z scaling factors" (set! (-> arg0 quad 0) (the-as uint128 0)) (set! (-> arg0 quad 1) (the-as uint128 0)) (set! (-> arg0 quad 2) (the-as uint128 0)) @@ -528,6 +558,8 @@ ;; definition for function column-scale-matrix! (defun column-scale-matrix! ((arg0 matrix) (arg1 vector) (arg2 matrix)) + "Scale an existing matrix. Okay for dst = src. The scaling is applied column-wise. +Meaning the x component of scale will scale the first column of src." (rlet ((vf4 :class vf) (vf5 :class vf) (vf6 :class vf) @@ -554,6 +586,7 @@ ;; definition for function matrix-rotate-x! ;; INFO: Used lq/sq (defun matrix-rotate-x! ((arg0 matrix) (arg1 float)) + "Set dst to a homogeneous transform matrix for a rotation around the x-axis (degrees)." (let ((f30-0 (sin arg1)) (f0-0 (cos arg1)) ) @@ -574,6 +607,7 @@ ;; definition for function matrix-rotate-y! ;; INFO: Used lq/sq (defun matrix-rotate-y! ((arg0 matrix) (arg1 float)) + "Set dst to a homoegeneous transform matrix for a rotation around the y axis (degrees)." (let ((f30-0 (sin arg1)) (f0-0 (cos arg1)) ) @@ -594,6 +628,7 @@ ;; definition for function matrix-rotate-z! ;; INFO: Used lq/sq (defun matrix-rotate-z! ((arg0 matrix) (arg1 float)) + "Set dst to a homogeneous transform matrix for a rotation around the z-axis (degrees)." (let ((f30-0 (sin arg1)) (f0-0 (cos arg1)) ) @@ -614,6 +649,7 @@ ;; definition for function matrix-rotate-zyx! ;; INFO: Used lq/sq (defun matrix-rotate-zyx! ((arg0 matrix) (arg1 vector)) + "Rotate in z,y,x order." (let ((gp-0 (new-stack-matrix0)) (s5-0 (new-stack-matrix0)) ) @@ -628,6 +664,7 @@ ;; definition (debug) for function matrix-rotate-xyz-2! (defun-debug matrix-rotate-xyz-2! ((arg0 matrix) (arg1 vector)) + "Jak 1 version of matrix-rotate-xyz. Slower than the one below." (let ((gp-0 (new 'stack-no-clear 'matrix)) (s5-0 (new 'stack-no-clear 'matrix)) ) @@ -642,6 +679,7 @@ ;; definition for function matrix-rotate-xyz! (defun matrix-rotate-xyz! ((arg0 matrix) (arg1 vector)) + "Rotate in x,y,z order." (rlet ((vf0 :class vf)) (init-vf0-vector) (let ((s4-0 (new 'stack-no-clear 'vector)) @@ -682,6 +720,7 @@ ;; definition for function matrix-rotate-zxy! ;; INFO: Used lq/sq (defun matrix-rotate-zxy! ((arg0 matrix) (arg1 vector)) + "Rotate in z,x,y order." (let ((gp-0 (new-stack-matrix0)) (s5-0 (new-stack-matrix0)) ) @@ -697,6 +736,7 @@ ;; definition for function matrix-rotate-yxz! ;; INFO: Used lq/sq (defun matrix-rotate-yxz! ((arg0 matrix) (arg1 vector)) + "Rotate in y,x,z order." (let ((gp-0 (new-stack-matrix0)) (s5-0 (new-stack-matrix0)) ) @@ -712,6 +752,7 @@ ;; definition for function matrix-rotate-yzx! ;; INFO: Used lq/sq (defun matrix-rotate-yzx! ((arg0 matrix) (arg1 vector)) + "Rotate in y,z,x order." (let ((gp-0 (new-stack-matrix0)) (s5-0 (new-stack-matrix0)) ) @@ -726,6 +767,8 @@ ;; definition for function matrix-rotate-yxy! (defun matrix-rotate-yxy! ((arg0 matrix) (arg1 vector)) + "Rotate. I believe in yxy order? Compared to the other rotations, this one +is quite a bit more optimized and avoid repeated trig operations." (let ((a2-0 (new 'stack-no-clear 'vector)) (s5-0 (new 'stack-no-clear 'vector)) (s4-0 (new 'stack-no-clear 'vector)) @@ -763,6 +806,7 @@ ;; definition for function matrix-rotate-yx! ;; INFO: Used lq/sq (defun matrix-rotate-yx! ((arg0 matrix) (arg1 float) (arg2 float)) + "Rotate by y then x." (matrix-rotate-y! arg0 arg1) (let ((a1-2 (matrix-rotate-x! (new-stack-matrix0) arg2))) (matrix*! arg0 a1-2 arg0) @@ -776,7 +820,7 @@ ;; ERROR: Unsupported inline assembly instruction kind - [prot3w a1, v1] ;; ERROR: Unsupported inline assembly instruction kind - [prot3w a2, a1] (defun matrix-axis-sin-cos-vu! ((arg0 matrix) (arg1 vector) (arg2 float) (arg3 float)) - "@unused" + "Create an axis-angle rotation matrix. But given the sin/cos of the angle. Uses the VU." (local-vars (a1-2 uint128) (a2-1 uint128) (a3-1 uint128) (a3-2 uint128)) (rlet ((vf0 :class vf) (vf1 :class vf) @@ -886,6 +930,7 @@ ;; ERROR: Unsupported inline assembly instruction kind - [prot3w a0, v1] ;; ERROR: Unsupported inline assembly instruction kind - [prot3w a1, a0] (defun matrix-axis-sin-cos! ((arg0 matrix) (arg1 vector) (arg2 float) (arg3 float)) + "Create an axis-angle rotation matrix. But given the sin/cos of the angle." (local-vars (a0-4 uint128) (a1-2 uint128) (a1-3 uint128) (a1-4 uint128)) (rlet ((vf0 :class vf) (vf1 :class vf) @@ -1003,11 +1048,13 @@ ;; definition for function matrix-axis-angle! (defun matrix-axis-angle! ((arg0 matrix) (arg1 vector) (arg2 float)) + "Create an axis-angle rotation matrix." (matrix-axis-sin-cos! arg0 arg1 (sin arg2) (cos arg2)) ) ;; definition for function matrix-lerp! (defun matrix-lerp! ((arg0 matrix) (arg1 matrix) (arg2 matrix) (arg3 float)) + "Lerp an entire matrix, coefficient-wise." (rlet ((vf1 :class vf) (vf2 :class vf) (vf3 :class vf) @@ -1049,6 +1096,7 @@ ;; definition for function matrix-3x3-determinant (defun matrix-3x3-determinant ((arg0 matrix)) + "Compute the determinant of a 3x3 matrix." (let ((f8-0 (-> arg0 vector 0 x)) (f1-0 (-> arg0 vector 0 y)) (f4-0 (-> arg0 vector 0 z)) @@ -1067,6 +1115,7 @@ ;; definition for function matrix3-determinant (defun matrix3-determinant ((arg0 matrix)) + "Unused. Not sure if this has limitations compared to the above version." (local-vars (v0-0 float)) (rlet ((acc :class vf) (vf10 :class vf) @@ -1089,6 +1138,8 @@ ;; definition for function matrix-3x3-inverse! (defun matrix-3x3-inverse! ((arg0 matrix) (arg1 matrix)) + "Compute the inverse of a 3x3 matrix. Not very efficient. +Requires src != dst." (let ((f0-0 (matrix-3x3-determinant arg1))) (set! (-> arg0 vector 0 x) (/ (- (* (-> arg1 vector 1 y) (-> arg1 vector 2 z)) (* (-> arg1 vector 1 z) (-> arg1 vector 2 y))) f0-0) @@ -1123,6 +1174,8 @@ ;; definition for function matrix-3x3-inverse-transpose! (defun matrix-3x3-inverse-transpose! ((arg0 matrix) (arg1 matrix)) + "Invert and transpose. +Requires dst != src." (let ((f0-0 (matrix-3x3-determinant arg1))) (set! (-> arg0 vector 0 x) (/ (- (* (-> arg1 vector 1 y) (-> arg1 vector 2 z)) (* (-> arg1 vector 1 z) (-> arg1 vector 2 y))) f0-0) @@ -1157,6 +1210,7 @@ ;; definition for function matrix3-inverse-transpose! (defun matrix3-inverse-transpose! ((arg0 matrix) (arg1 matrix)) + "Unused. Not sure if this has limitations compared to other version." (rlet ((acc :class vf) (Q :class vf) (vf0 :class vf) @@ -1208,6 +1262,7 @@ ;; ERROR: Unsupported inline assembly instruction kind - [madd.s f0, f1, f1] ;; ERROR: Unsupported inline assembly instruction kind - [rsqrt.s f0, f2, f0] (defun matrix-3x3-normalize! ((arg0 matrix) (arg1 matrix)) + "Unused." (local-vars (f0-1 float) (f0-2 float)) (rlet ((acc :class vf) (Q :class vf) @@ -1265,6 +1320,7 @@ ;; definition for function matrix-4x4-determinant (defun matrix-4x4-determinant ((arg0 matrix)) + "Take the determinant of a 4x4 matrix, but this is wrong." (let ((f15-0 (-> arg0 vector 0 x)) (f14-0 (-> arg0 vector 0 y)) (f10-0 (-> arg0 vector 0 z)) @@ -1314,6 +1370,8 @@ ;; definition for function matrix-4x4-inverse-transpose! (defun matrix-4x4-inverse-transpose! ((arg0 matrix) (arg1 matrix)) + "Invert and transpose an entire 4x4. I think has no restrictions, other than dst != src. Unused. +The answer is wrong. The determinant function is wrong." (let ((f0-0 (matrix-4x4-determinant arg1))) (let ((f9-0 (-> arg1 vector 1 y)) (f2-0 (-> arg1 vector 1 z)) @@ -1601,6 +1659,7 @@ ;; definition for function matrix-y-angle (defun matrix-y-angle ((arg0 matrix)) + "If mat has its upper 3x3 as a rotation, gets the y axis rotation." (let ((v1-0 (-> arg0 vector 2))) (atan (-> v1-0 x) (-> v1-0 z)) ) @@ -1608,6 +1667,7 @@ ;; definition for function matrix->trans (defun matrix->trans ((arg0 matrix) (arg1 vector)) + "Multiply xyz by 1/w." (rlet ((Q :class vf) (vf0 :class vf) (vf2 :class vf) @@ -1628,12 +1688,14 @@ ;; definition for function matrix<-trans ;; INFO: Used lq/sq (defun matrix<-trans ((arg0 matrix) (arg1 vector)) + "Set the translation." (set! (-> arg0 trans quad) (-> arg1 quad)) arg0 ) ;; definition for function matrix->scale (defun matrix->scale ((arg0 matrix) (arg1 vector)) + "Get the scale of a matrix." (set! (-> arg1 x) (vector-length (the-as vector (-> arg0 vector)))) (set! (-> arg1 y) (vector-length (-> arg0 vector 1))) (set! (-> arg1 z) (vector-length (-> arg0 vector 2))) @@ -1643,6 +1705,7 @@ ;; definition for function matrix<-scale (defun matrix<-scale ((arg0 matrix) (arg1 vector)) + "Set the scale of a matrix by rescaling." (vector-normalize! (the-as vector (-> arg0 vector)) (-> arg1 x)) (vector-normalize! (-> arg0 vector 1) (-> arg1 y)) (vector-normalize! (-> arg0 vector 2) (-> arg1 z)) @@ -1652,6 +1715,8 @@ ;; definition for function matrix->quat ;; INFO: Used lq/sq (defun matrix->quat ((arg0 matrix) (arg1 quaternion)) + "Convert matrix to quaternion, works for matrix with scale. +unlike matrix->quaternion." (let ((s5-0 (new 'stack-no-clear 'matrix))) (let* ((a2-0 arg0) (v1-0 (-> a2-0 quad 0)) @@ -1674,6 +1739,7 @@ ;; definition for function matrix<-quat (defun matrix<-quat ((arg0 matrix) (arg1 quaternion)) + "Modify the rotation part of a transform." (let ((s5-0 (matrix->scale arg0 (new 'stack-no-clear 'vector))) (s4-1 (quaternion->matrix (new 'stack-no-clear 'matrix) arg1)) ) @@ -1690,6 +1756,7 @@ ;; definition for function matrix->transformq ;; INFO: Used lq/sq (defun matrix->transformq ((arg0 transformq) (arg1 matrix)) + "Create a transformq from a matrix. Allowing scale, etc." (rlet ((Q :class vf) (vf0 :class vf) (vf2 :class vf) @@ -1738,6 +1805,7 @@ ;; definition for function matrix-mirror! (defun matrix-mirror! ((arg0 matrix) (arg1 vector) (arg2 vector)) + "Make a matrix that mirrors. Arguments are unclear." (let ((f10-0 -2.0) (f0-0 1.0) ) diff --git a/test/decompiler/reference/jak2/engine/math/quaternion-h_REF.gc b/test/decompiler/reference/jak2/engine/math/quaternion-h_REF.gc index 9b588740c2..fc0c8b9a8b 100644 --- a/test/decompiler/reference/jak2/engine/math/quaternion-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/math/quaternion-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type quaternion (deftype quaternion (structure) + "Quaternion. Stored in xyzw order." ((data float 4) (x float :overlay-at (-> data 0)) (y float :overlay-at (-> data 1)) diff --git a/test/decompiler/reference/jak2/engine/math/quaternion_REF.gc b/test/decompiler/reference/jak2/engine/math/quaternion_REF.gc index a331615db2..af7b756bed 100644 --- a/test/decompiler/reference/jak2/engine/math/quaternion_REF.gc +++ b/test/decompiler/reference/jak2/engine/math/quaternion_REF.gc @@ -18,6 +18,7 @@ ;; definition for function quaternion-axis-angle! (defun quaternion-axis-angle! ((arg0 quaternion) (arg1 float) (arg2 float) (arg3 float) (arg4 float)) + "Construct a quaternion from an axis and angle. The axis should be normalized." (let ((s5-0 (new 'stack-no-clear 'vector))) (sincos! s5-0 (* 0.5 arg4)) (let ((f0-2 (-> s5-0 x))) @@ -32,6 +33,7 @@ ;; definition for function quaternion-vector-angle! (defun quaternion-vector-angle! ((arg0 quaternion) (arg1 vector) (arg2 float)) + "Construct a quaternion from an axis and angle. The axis should be normalized." (let ((s5-0 (new 'stack-no-clear 'vector))) (sincos! s5-0 (* 0.5 arg2)) (let ((f0-2 (-> s5-0 x))) @@ -46,6 +48,7 @@ ;; definition for function vector-angle<-quaternion! (defun vector-angle<-quaternion! ((arg0 vector) (arg1 quaternion)) + "Convert the quaternion arg1 to axis-angle form and store in arg0 (angle goes in w)" (let* ((f0-0 1.0) (f1-0 1.0) (f2-0 (-> arg1 w)) @@ -63,6 +66,7 @@ ;; definition for function quaternion-look-at! ;; INFO: Used lq/sq (defun quaternion-look-at! ((arg0 quaternion) (arg1 vector) (arg2 vector)) + "Look along arg1, with arg2 as up." (let ((s5-0 (new 'stack-no-clear 'matrix))) (vector-cross! (the-as vector (-> s5-0 vector)) arg2 arg1) (vector-cross! (-> s5-0 vector 1) arg1 (the-as vector (-> s5-0 vector))) @@ -74,6 +78,7 @@ ;; definition for function quaternion-zero! ;; INFO: Used lq/sq (defun quaternion-zero! ((arg0 quaternion)) + "Set quaternion to all 0's." (set! (-> arg0 quad) (the-as uint128 0)) arg0 ) @@ -81,6 +86,7 @@ ;; definition for function quaternion-identity! ;; INFO: Used lq/sq (defun quaternion-identity! ((arg0 quaternion)) + "Set quaternion to 0,0,0,1 (identity)." (set! (-> arg0 quad) (the-as uint128 0)) (set! (-> arg0 w) 1.0) arg0 @@ -89,6 +95,7 @@ ;; definition for function quaternion-i! ;; INFO: Used lq/sq (defun quaternion-i! ((arg0 quaternion)) + "Create unit i quaternion." (set! (-> arg0 quad) (the-as uint128 0)) (set! (-> arg0 x) 1.0) arg0 @@ -97,6 +104,7 @@ ;; definition for function quaternion-j! ;; INFO: Used lq/sq (defun quaternion-j! ((arg0 quaternion)) + "Create unit j quaternion." (set! (-> arg0 quad) (the-as uint128 0)) (set! (-> arg0 y) 1.0) arg0 @@ -105,6 +113,7 @@ ;; definition for function quaternion-k! ;; INFO: Used lq/sq (defun quaternion-k! ((arg0 quaternion)) + "Create unit k quaternion." (set! (-> arg0 quad) (the-as uint128 0)) (set! (-> arg0 z) 1.0) arg0 @@ -113,12 +122,14 @@ ;; definition for function quaternion-copy! ;; INFO: Used lq/sq (defun quaternion-copy! ((arg0 quaternion) (arg1 quaternion)) + "Set arg0 = arg1." (set! (-> arg0 quad) (-> arg1 quad)) arg0 ) ;; definition for function quaternion-set! (defun quaternion-set! ((arg0 quaternion) (arg1 float) (arg2 float) (arg3 float) (arg4 float)) + "Set arg0 = [arg1, arg2, arg3, arg4]." (set! (-> arg0 x) arg1) (set! (-> arg0 y) arg2) (set! (-> arg0 z) arg3) @@ -128,6 +139,7 @@ ;; definition for function quaternion+! (defun quaternion+! ((arg0 quaternion) (arg1 quaternion) (arg2 quaternion)) + "Add quaternions as vectors." (rlet ((vf1 :class vf) (vf2 :class vf) ) @@ -141,6 +153,7 @@ ;; definition for function quaternion-! (defun quaternion-! ((arg0 quaternion) (arg1 quaternion) (arg2 quaternion)) + "Subtract quaternions as vectors." (rlet ((vf1 :class vf) (vf2 :class vf) ) @@ -155,6 +168,7 @@ ;; definition for function quaternion-negate! ;; ERROR: Bad vector register dependency: vf2 (defun quaternion-negate! ((arg0 quaternion) (arg1 quaternion)) + "Set arg0 = -arg1." (rlet ((vf1 :class vf) (vf2 :class vf) ) @@ -169,6 +183,9 @@ ;; definition for function quaternion-conjugate! ;; ERROR: Bad vector register dependency: vf2 (defun quaternion-conjugate! ((arg0 quaternion) (arg1 quaternion)) + "Set arg0 to the conjugate of arg1 (negate only ijk). +If arg1 is normalized, this is equivalent to the inverse +NOTE: this gives you the inverse rotation." (rlet ((vf1 :class vf) (vf2 :class vf) ) @@ -183,6 +200,7 @@ ;; definition for function quaternion-float*! (defun quaternion-float*! ((arg0 quaternion) (arg1 quaternion) (arg2 float)) + "Multiply each element." (rlet ((vf1 :class vf) (vf2 :class vf) ) @@ -196,6 +214,7 @@ ;; definition for function quaternion-float/! (defun quaternion-float/! ((arg0 quaternion) (arg1 quaternion) (arg2 float)) + "Divide each element." (let ((f0-1 (/ 1.0 arg2))) (quaternion-float*! arg0 arg1 f0-1) ) @@ -204,6 +223,7 @@ ;; definition for function quaternion-norm2 (defun quaternion-norm2 ((arg0 quaternion)) + "Get the squared norm of a quaternion." (local-vars (v0-0 float)) (rlet ((acc :class vf) (vf0 :class vf) @@ -223,6 +243,7 @@ ;; definition for function quaternion-norm (defun quaternion-norm ((arg0 quaternion)) + "Get the norm of a quaternion." (local-vars (v1-1 float)) (rlet ((acc :class vf) (vf0 :class vf) @@ -242,6 +263,7 @@ ;; definition for function quaternion-normalize! (defun quaternion-normalize! ((arg0 quaternion)) + "Normalize a quaternion." (rlet ((acc :class vf) (Q :class vf) (vf0 :class vf) @@ -267,6 +289,8 @@ ;; definition for function quaternion-inverse! ;; ERROR: Bad vector register dependency: vf3 (defun quaternion-inverse! ((arg0 quaternion) (arg1 quaternion)) + "Invert a quaternion. The inverse will satisfy q * q^-1 = identity, even if q is not normalized. +If your quaternion is normalized, it is faster/more accurate to do quaternion-conjugate!" (rlet ((acc :class vf) (Q :class vf) (vf0 :class vf) @@ -295,6 +319,7 @@ ;; definition for function quaternion-dot (defun quaternion-dot ((arg0 quaternion) (arg1 quaternion)) + "Treat quaternions as vectors and take the dot product." (local-vars (v0-0 float)) (rlet ((acc :class vf) (vf0 :class vf) @@ -316,6 +341,7 @@ ;; definition for function quaternion*! (defun quaternion*! ((arg0 quaternion) (arg1 quaternion) (arg2 quaternion)) + "Real quaternion multiplication." (rlet ((acc :class vf) (vf0 :class vf) (vf1 :class vf) @@ -344,6 +370,10 @@ ;; definition for function quaternion-right-mult-matrix! (defun quaternion-right-mult-matrix! ((arg0 matrix) (arg1 quaternion)) + "Place quaternion coefficients into a matrix. +You can convert a quaternion to a matrix by taking the product of this +right-mult and left-mult matrix, but this method is not used. +Instead, quaternion->matrix is a more efficient implementation." (let ((f3-0 (-> arg1 x)) (f2-0 (-> arg1 y)) (f1-0 (-> arg1 z)) @@ -371,6 +401,7 @@ ;; definition for function quaternion-left-mult-matrix! (defun quaternion-left-mult-matrix! ((arg0 matrix) (arg1 quaternion)) + "Place quaternion coefficients into a matrix. Unused." (let ((f2-0 (-> arg1 x)) (f1-0 (-> arg1 y)) (f0-0 (-> arg1 z)) @@ -399,6 +430,7 @@ ;; definition for function quaternion->matrix (defun quaternion->matrix ((arg0 matrix) (arg1 quaternion)) + "Convert quaternion to matrix." (rlet ((acc :class vf) (vf0 :class vf) (vf1 :class vf) @@ -444,6 +476,7 @@ ;; definition for function matrix->quaternion (defun matrix->quaternion ((arg0 quaternion) (arg1 matrix)) + "Convert a rotation matrix to a quaternion." (let ((f0-2 (+ (-> arg1 vector 0 x) (-> arg1 vector 1 y) (-> arg1 vector 2 z)))) (cond ((< 0.0 f0-2) @@ -519,6 +552,7 @@ ;; definition for function matrix-with-scale->quaternion ;; INFO: Used lq/sq (defun matrix-with-scale->quaternion ((arg0 quaternion) (arg1 matrix)) + "Convert a matrix with a rotation and scale into a quaternion (just the rotation)." (local-vars (a1-4 float)) (rlet ((vf1 :class vf) (vf2 :class vf) @@ -565,6 +599,7 @@ ;; definition for function quaternion-vector-len (defun quaternion-vector-len ((arg0 quaternion)) + "Assuming quaternion is normalized, get the length of the xyz part." (let ((f0-0 1.0) (f1-0 (-> arg0 w)) ) @@ -574,6 +609,7 @@ ;; definition for function quaternion-log! (defun quaternion-log! ((arg0 quaternion) (arg1 quaternion)) + "Take the log of a quaternion. Unused." (cond ((= (-> arg1 w) 0.0) (set! (-> arg0 x) (* 1.5707963 (-> arg1 x))) @@ -595,6 +631,7 @@ ;; definition for function quaternion-exp! (defun quaternion-exp! ((arg0 quaternion) (arg1 quaternion)) + "Quaternion exponentiation. Unused." (let ((f30-0 (vector-length (the-as vector arg1)))) (cond ((= f30-0 0.0) @@ -621,6 +658,8 @@ ;; definition for function quaternion-slerp! (defun quaternion-slerp! ((arg0 quaternion) (arg1 quaternion) (arg2 quaternion) (arg3 float)) + "Real quaternion slerp. Spherical-linear interpolation is a nice way to interpolate +between quaternions." (local-vars (v1-15 float)) (rlet ((acc :class vf) (vf1 :class vf) @@ -685,6 +724,9 @@ ;; definition for function quaternion-pseudo-slerp! (defun quaternion-pseudo-slerp! ((arg0 quaternion) (arg1 quaternion) (arg2 quaternion) (arg3 float)) + "This is a bad interpolation between quaternions. It lerps then normalizes. +It will behave extremely poorly for 180 rotations. +It is unused." (rlet ((acc :class vf) (vf1 :class vf) (vf2 :class vf) @@ -717,6 +759,8 @@ ;; definition for function quaternion-pseudo-seek (defun quaternion-pseudo-seek ((arg0 quaternion) (arg1 quaternion) (arg2 quaternion) (arg3 float)) + "Seek one quaternion toward another. Not using real slerp, so this is only good if the quaternions +are pretty similar." (let ((s3-0 (new 'stack-no-clear 'quaternion))) (let ((s5-0 (new 'stack-no-clear 'quaternion))) (quaternion-copy! s3-0 arg2) @@ -740,6 +784,7 @@ ;; definition for function quaternion-smooth-seek! (defun quaternion-smooth-seek! ((arg0 quaternion) (arg1 quaternion) (arg2 quaternion) (arg3 float)) + "Another hacky rotation interpolation." (let ((gp-0 (new 'stack-no-clear 'inline-array 'quaternion 2))) (quaternion-copy! (-> gp-0 0) arg2) (if (< (quaternion-dot (-> gp-0 0) arg1) 0.0) @@ -755,6 +800,7 @@ ;; definition for function quaternion-zxy! (defun quaternion-zxy! ((arg0 quaternion) (arg1 vector)) + "Make a quaternion from a sequence of z, x, y axis rotations." (rlet ((acc :class vf) (vf0 :class vf) (vf1 :class vf) @@ -796,6 +842,7 @@ ;; definition for function vector-x-quaternion! ;; INFO: Used lq/sq (defun vector-x-quaternion! ((arg0 vector) (arg1 quaternion)) + "Get the first row of the rotation matrix for this quaternion." (let ((s5-0 (new-stack-matrix0))) (quaternion->matrix s5-0 arg1) (set! (-> arg0 quad) (-> (the-as (pointer uint128) (-> s5-0 vector)) 0)) @@ -806,6 +853,7 @@ ;; definition for function vector-y-quaternion! ;; INFO: Used lq/sq (defun vector-y-quaternion! ((arg0 vector) (arg1 quaternion)) + "Get the second row of the rotation matrix for this quaternion." (let ((s5-0 (new-stack-matrix0))) (quaternion->matrix s5-0 arg1) (set! (-> arg0 quad) (-> (the-as (pointer uint128) (-> s5-0 vector 1)) 0)) @@ -816,6 +864,7 @@ ;; definition for function vector-z-quaternion! ;; INFO: Used lq/sq (defun vector-z-quaternion! ((arg0 vector) (arg1 quaternion)) + "Get the third row of the rotation matrix for this quaternion." (let ((s5-0 (new-stack-matrix0))) (quaternion->matrix s5-0 arg1) (set! (-> arg0 quad) (-> (the-as (pointer uint128) (-> s5-0 vector 2)) 0)) @@ -825,6 +874,7 @@ ;; definition for function quaternion-x-angle (defun quaternion-x-angle ((arg0 quaternion)) + "Get the x rotation angle. Not very efficient." (let ((v1-1 (vector-y-quaternion! (new 'stack-no-clear 'vector) arg0))) (atan (-> v1-1 z) (-> v1-1 y)) ) @@ -832,6 +882,7 @@ ;; definition for function quaternion-y-angle (defun quaternion-y-angle ((arg0 quaternion)) + "Get the y rotation angle. Not very efficient." (let ((v1-1 (vector-z-quaternion! (new 'stack-no-clear 'vector) arg0))) (atan (-> v1-1 x) (-> v1-1 z)) ) @@ -839,6 +890,7 @@ ;; definition for function quaternion-z-angle (defun quaternion-z-angle ((arg0 quaternion)) + "Get the z rotation angle. Not very efficient." (let ((v1-1 (vector-y-quaternion! (new 'stack-no-clear 'vector) arg0))) (atan (-> v1-1 x) (-> v1-1 y)) ) @@ -846,6 +898,7 @@ ;; definition for function quaternion-vector-y-angle (defun quaternion-vector-y-angle ((arg0 quaternion) (arg1 vector)) + "Not sure. Angle between quaternion and axis, projected in xz plane?" (let ((f30-0 (quaternion-y-angle arg0)) (f0-2 (atan (-> arg1 x) (-> arg1 z))) ) @@ -856,6 +909,7 @@ ;; definition for function quaternion-rotate-local-x! ;; INFO: Used lq/sq (defun quaternion-rotate-local-x! ((arg0 quaternion) (arg1 quaternion) (arg2 float)) + "Rotate existing quaternion along x axis." (let ((a2-1 (quaternion-vector-angle! (new-stack-quaternion0) (new 'static 'vector :x 1.0 :w 1.0) arg2))) (quaternion-normalize! (quaternion*! arg0 arg1 a2-1)) ) @@ -864,6 +918,7 @@ ;; definition for function quaternion-rotate-local-y! ;; INFO: Used lq/sq (defun quaternion-rotate-local-y! ((arg0 quaternion) (arg1 quaternion) (arg2 float)) + "Rotate existing quaternion along y axis." (let ((a2-1 (quaternion-vector-angle! (new-stack-quaternion0) (new 'static 'vector :y 1.0 :w 1.0) arg2))) (quaternion-normalize! (quaternion*! arg0 arg1 a2-1)) ) @@ -872,6 +927,7 @@ ;; definition for function quaternion-rotate-local-z! ;; INFO: Used lq/sq (defun quaternion-rotate-local-z! ((arg0 quaternion) (arg1 quaternion) (arg2 float)) + "Rotate existing quaternion along z axis." (let ((a2-1 (quaternion-vector-angle! (new-stack-quaternion0) (new 'static 'vector :z 1.0 :w 1.0) arg2))) (quaternion-normalize! (quaternion*! arg0 arg1 a2-1)) ) @@ -880,6 +936,7 @@ ;; definition for function quaternion-rotate-y! ;; INFO: Used lq/sq (defun quaternion-rotate-y! ((arg0 quaternion) (arg1 quaternion) (arg2 float)) + "Rotate existing quaternion along y axis (right multiply)." (let ((a1-2 (quaternion-vector-angle! (new-stack-quaternion0) (new 'static 'vector :y 1.0 :w 1.0) arg2))) (quaternion-normalize! (quaternion*! arg0 a1-2 arg1)) ) @@ -888,6 +945,7 @@ ;; definition for function quaternion-rotate-x! ;; INFO: Used lq/sq (defun quaternion-rotate-x! ((arg0 quaternion) (arg1 quaternion) (arg2 float)) + "Rotate existing quaternion along x axis (right multiply)." (let ((a1-3 (quaternion-vector-angle! (new-stack-quaternion0) (vector-x-quaternion! (new-stack-vector0) arg1) arg2)) ) (quaternion-normalize! (quaternion*! arg0 a1-3 arg1)) @@ -897,6 +955,7 @@ ;; definition for function quaternion-rotate-z! ;; INFO: Used lq/sq (defun quaternion-rotate-z! ((arg0 quaternion) (arg1 quaternion) (arg2 float)) + "Rotate existing quaternion along z axis (right multiply)." (let ((a1-3 (quaternion-vector-angle! (new-stack-quaternion0) (vector-z-quaternion! (new-stack-vector0) arg1) arg2)) ) (quaternion-normalize! (quaternion*! arg0 a1-3 arg1)) @@ -905,6 +964,7 @@ ;; definition for function quaternion-delta-y (defun quaternion-delta-y ((arg0 quaternion) (arg1 quaternion)) + "Difference in yaw between two quaternions." (acos (vector-dot (vector-z-quaternion! (new 'stack-no-clear 'vector) arg0) (vector-z-quaternion! (new 'stack-no-clear 'vector) arg1) @@ -937,6 +997,7 @@ ;; definition for function vector-rotate-x! (defun vector-rotate-x! ((arg0 vector) (arg1 vector) (arg2 float)) + "Rotate vector along x axis." (let ((a1-2 (quaternion-vector-angle! (new 'stack-no-clear 'quaternion) (new 'static 'vector :x 1.0 :w 1.0) arg2)) (s4-0 (new 'stack-no-clear 'matrix)) ) @@ -947,6 +1008,7 @@ ;; definition for function vector-rotate-y! (defun vector-rotate-y! ((arg0 vector) (arg1 vector) (arg2 float)) + "Rotate vector along y axis." (let ((a1-2 (quaternion-vector-angle! (new 'stack-no-clear 'quaternion) (new 'static 'vector :y 1.0 :w 1.0) arg2)) (s4-0 (new 'stack-no-clear 'matrix)) ) @@ -957,6 +1019,7 @@ ;; definition for function vector-rotate-z! (defun vector-rotate-z! ((arg0 vector) (arg1 vector) (arg2 float)) + "Rotate vector along z axis." (let ((a1-2 (quaternion-vector-angle! (new 'stack-no-clear 'quaternion) (new 'static 'vector :z 1.0 :w 1.0) arg2)) (s4-0 (new 'stack-no-clear 'matrix)) ) @@ -967,22 +1030,26 @@ ;; definition for function vector-y-angle (defun vector-y-angle ((arg0 vector)) + "Get the yaw angle of a vector." (atan (-> arg0 x) (-> arg0 z)) ) ;; definition for function vector-x-angle (defun vector-x-angle ((arg0 vector)) + "Get the pitch angle of a vector." (atan (-> arg0 y) (vector-xz-length arg0)) ) ;; definition for function quaternion<-rotate-y-vector (defun quaternion<-rotate-y-vector ((arg0 quaternion) (arg1 vector)) + "Create a quaternion representing only the yaw of the given vector." (quaternion-vector-angle! arg0 (new 'static 'vector :y 1.0 :w 1.0) (vector-y-angle arg1)) ) ;; definition (debug) for function quaternion-validate ;; WARN: Return type mismatch int vs none. (defun-debug quaternion-validate ((arg0 quaternion)) + "Verify that a quaternion is valid, print an error if the length is off by more than 1%.." (with-pp (let ((f0-0 (quaternion-norm arg0))) (when (or (< 1.01 f0-0) (< f0-0 0.99)) @@ -1000,6 +1067,7 @@ ;; definition for function quaternion-xz-angle (defun quaternion-xz-angle ((arg0 quaternion)) + "Yet another function to compute the yaw of a quaternion. This is a particularly inefficient version." (let ((gp-0 (new 'stack-no-clear 'matrix)) (s5-0 (new 'stack-no-clear 'vector)) ) diff --git a/test/decompiler/reference/jak2/engine/math/transform-h_REF.gc b/test/decompiler/reference/jak2/engine/math/transform-h_REF.gc index 3bd0410a60..c54bcbaa0d 100644 --- a/test/decompiler/reference/jak2/engine/math/transform-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/math/transform-h_REF.gc @@ -3,6 +3,10 @@ ;; definition of type transform (deftype transform (structure) + "Transformation. w components of vectors should be 1.0 +This can represent any rotation, translation, and scaling. +Note that the scaling is applied before rotation +(meaning it scales along the axes of the pre-transformed frame)." ((trans vector :inline) (rot vector :inline) (scale vector :inline) @@ -25,6 +29,9 @@ ;; definition of type trs (deftype trs (basic) + "Like transform, but it's a basic. +Note that the trsq child type overrides this rotation with a quaternion. +usage of the plain trs is very limited, at least in Jak 1." ((trans vector :inline) (rot vector :inline) (scale vector :inline) diff --git a/test/decompiler/reference/jak2/engine/math/transform_REF.gc b/test/decompiler/reference/jak2/engine/math/transform_REF.gc index 75d21c7624..288540efcd 100644 --- a/test/decompiler/reference/jak2/engine/math/transform_REF.gc +++ b/test/decompiler/reference/jak2/engine/math/transform_REF.gc @@ -23,6 +23,7 @@ ;; definition for function transform-matrix-calc! ;; INFO: Used lq/sq (defun transform-matrix-calc! ((arg0 transform) (arg1 matrix)) + "Convert a transform to matrix. Not efficient, and the output is the second arg." (let ((s4-0 (new-stack-matrix0)) (s3-0 (new-stack-matrix0)) ) @@ -42,6 +43,7 @@ ;; definition for function transform-matrix-parent-calc! ;; INFO: Used lq/sq (defun transform-matrix-parent-calc! ((arg0 transform) (arg1 matrix) (arg2 vector)) + "Convert a transform to a matrix, applying an inverse scaling." (let ((s4-0 (new-stack-matrix0)) (s3-0 (new-stack-matrix0)) ) @@ -62,5 +64,6 @@ ;; definition for function trs-matrix-calc! (defun trs-matrix-calc! ((arg0 trs) (arg1 matrix)) + "Convert a trs to a matrix." (transform-matrix-calc! (the-as transform (-> arg0 trans)) arg1) ) diff --git a/test/decompiler/reference/jak2/engine/math/transformq-h_REF.gc b/test/decompiler/reference/jak2/engine/math/transformq-h_REF.gc index dc367a9fd2..17fd8dd063 100644 --- a/test/decompiler/reference/jak2/engine/math/transformq-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/math/transformq-h_REF.gc @@ -45,6 +45,15 @@ ;; definition of type trsqv (deftype trsqv (trsq) + "A transform with: +- type information (child of [[basic]]) +- rotation stored as quaternion +- velocity information. +This is a very commonly used type to represent the position of an in-game object. +The `root` of a process-drawable (the parent 'in-game object' type) is a [[trsqv]]. +Additionally, the collision system uses [[trsqv]] as the parent type for foreground +collision objects ([[collide-shape]], [[collide-shape-moving]]). +As a result, this type has a lot of weird methods and extra stuff hidden in it." ((pause-adjust-distance meters :offset 4) (nav-radius meters :offset 8) (transv vector :inline) @@ -102,11 +111,15 @@ ;; definition for method 23 of type trsqv (defmethod global-y-angle-to-point ((this trsqv) (arg0 vector)) + "Get the angle in the xz plane from the position of this trsqv to the point arg0 +(ignores our current yaw)." (vector-y-angle (vector-! (new 'stack-no-clear 'vector) arg0 (-> this trans))) ) ;; definition for method 24 of type trsqv (defmethod relative-y-angle-to-point ((this trsqv) (arg0 vector)) + "Get the y angle between the current orientation and arg0 +(how much we'd have to yaw to point at arg0)." (deg-diff (y-angle this) (vector-y-angle (vector-! (new 'stack-no-clear 'vector) arg0 (-> this trans)))) ) diff --git a/test/decompiler/reference/jak2/engine/math/trigonometry_REF.gc b/test/decompiler/reference/jak2/engine/math/trigonometry_REF.gc index 9c4a26703e..776bf5166e 100644 --- a/test/decompiler/reference/jak2/engine/math/trigonometry_REF.gc +++ b/test/decompiler/reference/jak2/engine/math/trigonometry_REF.gc @@ -3,6 +3,7 @@ ;; definition for function radmod (defun radmod ((arg0 float)) + "Wrap arg0 to be within (-pi, pi)." (let ((f0-1 (+ 3.1415925 arg0))) (if (< 0.0 f0-1) (+ -3.1415925 (- f0-1 (* (the float (the int (/ f0-1 6.283185))) 6.283185))) @@ -13,16 +14,20 @@ ;; definition for function deg- (defun deg- ((arg0 float) (arg1 float)) + "Compute arg0-arg1, unwrapped, using rotation units. +Result should be in the range (-180, 180)" (the float (sar (- (shl (the int arg0) 48) (shl (the int arg1) 48)) 48)) ) ;; definition for function deg-diff (defun deg-diff ((arg0 float) (arg1 float)) + "Very similar to the function above, but computes arg1 - arg0 instead." (the float (sar (- (shl (the int arg1) 48) (shl (the int arg0) 48)) 48)) ) ;; definition for function deg-seek (defun deg-seek ((arg0 float) (arg1 float) (arg2 float)) + "Move in toward target by at most max-diff, using rotation units" (let ((v1-1 (shl (the int arg0) 48)) (a0-2 (shl (the int arg1) 48)) ) @@ -53,6 +58,7 @@ ;; definition for function deg-seek-smooth (defun deg-seek-smooth ((arg0 float) (arg1 float) (arg2 float) (arg3 float)) + "Step amount of the way from in to target, by at most max-diff, using rotation units" (let ((f0-1 (* (deg- arg1 arg0) arg3))) (if (< arg2 (fabs f0-1)) (set! f0-1 (if (>= f0-1 0.0) @@ -67,6 +73,7 @@ ;; definition for function deg-lerp-clamp (defun deg-lerp-clamp ((arg0 float) (arg1 float) (arg2 float)) + "Map [0, 1] to min-val, max-val, handling wrapping and saturating, using rotation units." (cond ((>= 0.0 arg2) arg0 @@ -156,6 +163,7 @@ ;; definition for function sin (defun sin ((arg0 float)) + "Compute the sine of an angle in rotation units. Unwraps it." (let ((f2-0 (* 0.000095873795 (the float (sar (shl (the int arg0) 48) 48))))) f2-0 (let* ((f1-4 (* 0.999998 f2-0)) @@ -186,6 +194,10 @@ ;; definition for function vector-sin-rad! (defun vector-sin-rad! ((arg0 vector) (arg1 vector)) + "Taylor series approximation of sine on all 4 elements in a vector. +Inputs should be in radians, in -pi to pi. +Somehow their coefficients are a little bit off. +Like the first coefficient, which should obviously be 1, is not quite 1." (rlet ((acc :class vf) (vf1 :class vf) (vf10 :class vf) @@ -226,6 +238,8 @@ ;; definition for function vector-cos-rad! ;; ERROR: Bad vector register dependency: vf2 (defun vector-cos-rad! ((arg0 vector) (arg1 vector)) + "Compute the cosine of all 4 vector elements. +Radians, with no wrapping. Uses taylor series with 4 coefficients." (rlet ((acc :class vf) (vf0 :class vf) (vf1 :class vf) @@ -257,6 +271,9 @@ ;; definition for function vector-sincos-rad! ;; ERROR: Bad vector register dependency: vf14 (defun vector-sincos-rad! ((arg0 vector) (arg1 vector) (arg2 vector)) + "Compute the sine and cosine of each element of src, storing it in dst-sin and dst-cos. +This is more efficient than separate calls to sin and cos. +Inputs should be radians in -pi to pi." (rlet ((acc :class vf) (vf0 :class vf) (vf1 :class vf) @@ -312,13 +329,15 @@ ;; definition for function vector-rad<-vector-deg! ;; WARN: Return type mismatch float vs none. -(defun vector-rad<-vector-deg! ((arg0 vector) (arg1 vector)) +(defun vector-rad<-vector-deg! ((out vector) (in vector)) + "Convert a vector in rotation units to radians, and unwrap. +Input can be anything, output will be -2pi to pi." (local-vars (v0-0 float) (v1-1 uint128) (v1-2 uint128) (v1-3 uint128)) (rlet ((vf1 :class vf) (vf2 :class vf) ) (let ((v1-0 #x38c90fda)) - (.lvf vf1 (&-> arg1 quad)) + (.lvf vf1 (&-> in quad)) (.ftoi.vf vf1 vf1) (.mov vf2 v1-0) ) @@ -328,7 +347,7 @@ (.mov vf1 v1-3) (.itof.vf vf1 vf1) (.mul.x.vf vf1 vf1 vf2) - (.svf (&-> arg0 quad) vf1) + (.svf (&-> out quad) vf1) (.mov v0-0 vf1) (none) ) @@ -336,14 +355,16 @@ ;; definition for function vector-rad<-vector-deg/2! ;; WARN: Return type mismatch float vs int. -(defun vector-rad<-vector-deg/2! ((arg0 vector) (arg1 vector)) +(defun vector-rad<-vector-deg/2! ((out vector) (in vector)) + "Divide the input by two, and then convert from rotation units to radians, unwrapping. +Not sure why this really needs to be separate the from previous function..." (local-vars (v0-0 float) (v1-1 uint128) (v1-2 uint128) (v1-3 uint128)) (rlet ((vf1 :class vf) (vf2 :class vf) ) (let ((v1-0 #x38c90fda)) (let ((a2-0 #x3f000000)) - (.lvf vf1 (&-> arg1 quad)) + (.lvf vf1 (&-> in quad)) (.mov vf2 a2-0) ) (.mul.x.vf vf1 vf1 vf2) @@ -356,7 +377,7 @@ (.mov vf1 v1-3) (.itof.vf vf1 vf1) (.mul.x.vf vf1 vf1 vf2) - (.svf (&-> arg0 quad) vf1) + (.svf (&-> out quad) vf1) (.mov v0-0 vf1) (the-as int v0-0) ) @@ -364,6 +385,7 @@ ;; definition for function vector-sincos! (defun vector-sincos! ((arg0 vector) (arg1 vector) (arg2 vector)) + "Compute sine and cosine of each element in a vector, in rotation units" (let ((s4-0 (new 'stack-no-clear 'vector))) (vector-rad<-vector-deg! s4-0 arg2) (vector-sincos-rad! arg0 arg1 s4-0) @@ -372,16 +394,19 @@ ;; definition for function tan-rad (defun tan-rad ((arg0 float)) + "This function appears to be named wrong and actually operates on rotation units." (/ (sin arg0) (cos arg0)) ) ;; definition for function cos (defun cos ((arg0 float)) + "Cosine of rotation units." (sin (+ 16384.0 arg0)) ) ;; definition for function tan (defun tan ((arg0 float)) + "Correctly named tangent of rotation units." (/ (sin arg0) (cos arg0)) ) @@ -393,11 +418,13 @@ ;; definition for function atan-rad (defun atan-rad ((arg0 float)) + "Inverse tangent in radians." (atan-series-rad (/ (+ -1.0 arg0) (+ 1.0 arg0))) ) ;; definition for function sign-bit (defun sign-bit ((arg0 int)) + "Return 1 if bit 31 is set, otherwise 0." (local-vars (v1-1 int)) (let ((v1-0 arg0)) (shift-arith-right-32 v1-1 v1-0 31) @@ -410,6 +437,8 @@ ;; definition for function sign (defun sign ((arg0 float)) + "Similar to above, but returns 0 if input is 0. +But is more complicated." (cond ((< 0.0 arg0) 1.0 @@ -425,6 +454,7 @@ ;; definition for function atan2-rad (defun atan2-rad ((arg0 float) (arg1 float)) + "Atan for radians." (cond ((= arg1 0.0) (* 1.5707963 (sign arg0)) @@ -458,6 +488,7 @@ ;; definition for function atan (defun atan ((arg0 float) (arg1 float)) + "Atan for rotation units. Signs behave like atan.." (cond ((and (= arg1 0.0) (= arg0 0.0)) 0.0 @@ -479,6 +510,7 @@ ;; definition for function asin (defun asin ((arg0 float)) + "Inverse sine, rotation units." (let ((gp-0 #f)) 0.0 (when (< arg0 0.0) @@ -510,11 +542,13 @@ ;; definition for function acos (defun acos ((arg0 float)) + "Inverse cosine. Returns rotation units." (- 16384.0 (asin arg0)) ) ;; definition for function acos-rad (defun acos-rad ((arg0 float)) + "Inverse cosine, radians." (cond ((>= arg0 0.0) (let* ((f0-1 1.0) @@ -539,11 +573,13 @@ ;; definition for function sinerp (defun sinerp ((arg0 float) (arg1 float) (arg2 float)) + "Map amount to min,max using sine. Kinda weird, usually people use cosine." (lerp arg0 arg1 (sin (* 16384.0 arg2))) ) ;; definition for function sinerp-clamp (defun sinerp-clamp ((arg0 float) (arg1 float) (arg2 float)) + "Like sinerp, but clamp to min,max." (cond ((>= 0.0 arg2) arg0 @@ -559,11 +595,13 @@ ;; definition for function coserp (defun coserp ((arg0 float) (arg1 float) (arg2 float)) + "Weird lerp with cosine (over 90 degrees?)." (lerp arg0 arg1 (- 1.0 (cos (* 16384.0 arg2)))) ) ;; definition for function coserp-clamp (defun coserp-clamp ((arg0 float) (arg1 float) (arg2 float)) + "Weird 90 degree lerp with cosine, clamped to min,max." (cond ((>= 0.0 arg2) arg0 @@ -579,11 +617,13 @@ ;; definition for function coserp180 (defun coserp180 ((arg0 float) (arg1 float) (arg2 float)) + "Classic lerp with cosine." (lerp arg0 arg1 (* 0.5 (- 1.0 (cos (* 32768.0 arg2))))) ) ;; definition for function coserp180-clamp (defun coserp180-clamp ((arg0 float) (arg1 float) (arg2 float)) + "Classic coserp with saturation." (cond ((>= 0.0 arg2) arg0 @@ -599,6 +639,7 @@ ;; definition for function ease-in-out (defun ease-in-out ((arg0 int) (arg1 int)) + "Weird coserp like mapping from 0 to 1 as progress goes from 0 to total." (local-vars (v1-0 int)) (cond ((>= arg1 arg0) diff --git a/test/decompiler/reference/jak2/engine/math/vector-h_REF.gc b/test/decompiler/reference/jak2/engine/math/vector-h_REF.gc index 1043423021..71d741923a 100644 --- a/test/decompiler/reference/jak2/engine/math/vector-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/math/vector-h_REF.gc @@ -32,6 +32,7 @@ ;; definition for method 0 of type bit-array (defmethod new bit-array ((allocation symbol) (type-to-make type) (arg0 int)) + "Allocate a new bit-array with room arg0 bits." (let ((v0-0 (object-new allocation type-to-make (+ (/ (logand -8 (+ arg0 7)) 8) -1 (-> type-to-make size))))) (set! (-> v0-0 length) arg0) (set! (-> v0-0 allocated-length) arg0) @@ -52,6 +53,7 @@ ;; definition for method 9 of type bit-array (defmethod get-bit ((this bit-array) (arg0 int)) + "Get the nth bit as a boolean." (let ((v1-2 (-> this bytes (/ arg0 8)))) (logtest? v1-2 (ash 1 (logand arg0 7))) ) @@ -59,18 +61,21 @@ ;; definition for method 10 of type bit-array (defmethod clear-bit ((this bit-array) (arg0 int)) + "Set the nth bit to 0." (logclear! (-> this bytes (/ arg0 8)) (ash 1 (logand arg0 7))) 0 ) ;; definition for method 11 of type bit-array (defmethod set-bit ((this bit-array) (arg0 int)) + "Set the nth bit to 1." (logior! (-> this bytes (/ arg0 8)) (ash 1 (logand arg0 7))) 0 ) ;; definition for method 12 of type bit-array (defmethod clear-all! ((this bit-array)) + "Set all bits to 0." (countdown (v1-2 (/ (logand -8 (+ (-> this allocated-length) 7)) 8)) (nop!) (nop!) @@ -972,11 +977,15 @@ ;; definition for function vector-dot (defun vector-dot ((arg0 vector) (arg1 vector)) + "Take the dot product of two vectors. +Only does the x, y, z compoments. +Originally handwritten assembly to space out loads and use FPU accumulator" (vector-dot arg0 arg1) ) ;; definition for function vector-dot-vu (defun vector-dot-vu ((arg0 vector) (arg1 vector)) + "Take the dot product (xyz only). Using VU0." (local-vars (v0-0 float)) (rlet ((vf1 :class vf) (vf2 :class vf) @@ -993,11 +1002,14 @@ ;; definition for function vector4-dot (defun vector4-dot ((arg0 vector) (arg1 vector)) + "Take the dot product of two vectors. +Does the x, y, z, and w compoments" (vector4-dot arg0 arg1) ) ;; definition for function vector4-dot-vu (defun vector4-dot-vu ((arg0 vector) (arg1 vector)) + "Take the dot product (xyzw). Using VU0." (local-vars (v0-0 float)) (rlet ((acc :class vf) (vf0 :class vf) @@ -1021,23 +1033,27 @@ ;; definition for function vector+! (defun vector+! ((arg0 vector) (arg1 vector) (arg2 vector)) + "Set dst = a + b. The w component of dst is set to 0." (vector+! arg0 arg1 arg2) ) ;; definition for function vector-! (defun vector-! ((arg0 vector) (arg1 vector) (arg2 vector)) + "Set dst = a - b. The w componenent of dst is set to 0." (vector-! arg0 arg1 arg2) ) ;; definition for function vector-zero! ;; INFO: Used lq/sq (defun vector-zero! ((arg0 vector)) + "Set xyzw to 0." (set! (-> arg0 quad) (the-as uint128 0)) arg0 ) ;; definition for function vector-reset! (defun vector-reset! ((arg0 vector)) + "Set vector to <0,0,0,1>." (rlet ((vf0 :class vf)) (init-vf0-vector) (.svf (&-> arg0 quad) vf0) @@ -1048,6 +1064,7 @@ ;; definition for function vector-copy! ;; INFO: Used lq/sq (defun vector-copy! ((arg0 vector) (arg1 vector)) + "Copy arg1 to arg0." (set! (-> arg0 quad) (-> arg1 quad)) arg0 ) diff --git a/test/decompiler/reference/jak2/engine/math/vector_REF.gc b/test/decompiler/reference/jak2/engine/math/vector_REF.gc index 3936dab413..03edad80da 100644 --- a/test/decompiler/reference/jak2/engine/math/vector_REF.gc +++ b/test/decompiler/reference/jak2/engine/math/vector_REF.gc @@ -3,11 +3,13 @@ ;; definition for function vector-cross! (defun vector-cross! ((arg0 vector) (arg1 vector) (arg2 vector)) + "Compute the cross product. The w component is set to junk." (vector-cross! arg0 arg1 arg2) ) ;; definition for function vector-xz-cross! (defun vector-xz-cross! ((arg0 vector) (arg1 vector) (arg2 vector)) + "Compute the cross product of the xz components of inputs." (rlet ((acc :class vf) (vf0 :class vf) (vf1 :class vf) @@ -28,6 +30,7 @@ ;; definition for function vector+float! (defun vector+float! ((arg0 vector) (arg1 vector) (arg2 float)) + "Add float to each component of vector. The w component is set to 1" (rlet ((vf0 :class vf) (vf4 :class vf) (vf5 :class vf) @@ -45,6 +48,7 @@ ;; definition for function vector*! (defun vector*! ((arg0 vector) (arg1 vector) (arg2 vector)) + "Elementwise product. Set w = 1." (rlet ((vf0 :class vf) (vf4 :class vf) (vf5 :class vf) @@ -62,6 +66,7 @@ ;; definition for function vector+*! (defun vector+*! ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 float)) + "set arg0 = arg1 + (arg3 * arg2). The w component will be set to 1." (rlet ((acc :class vf) (vf0 :class vf) (vf4 :class vf) @@ -83,6 +88,7 @@ ;; definition for function vector-*! (defun vector-*! ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 float)) + "Set arg0 = arg1 - (arg3 * arg2). The w component will be set to 1." (rlet ((acc :class vf) (vf0 :class vf) (vf4 :class vf) @@ -104,6 +110,8 @@ ;; definition for function vector/! (defun vector/! ((arg0 vector) (arg1 vector) (arg2 vector)) + "Set arg0 = arg1 / arg2. The w component will be set to 1. +The implementation is kind of crazy." (rlet ((Q :class vf) (vf0 :class vf) (vf4 :class vf) @@ -136,6 +144,7 @@ ;; definition for function vector-float*! (defun vector-float*! ((arg0 vector) (arg1 vector) (arg2 float)) + "Multiply all values in a vector by arg2. Set w to 1." (rlet ((vf0 :class vf) (vf1 :class vf) (vf2 :class vf) @@ -152,6 +161,7 @@ ;; definition for function vector-average! (defun vector-average! ((arg0 vector) (arg1 vector) (arg2 vector)) + "Set arg0 to the average of arg1 and arg2. Set w to 1." (rlet ((acc :class vf) (vf0 :class vf) (vf1 :class vf) @@ -175,6 +185,7 @@ ;; definition for function vector+float*! (defun vector+float*! ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 float)) + "arg0 = arg1 + arg2 * arg3." (rlet ((acc :class vf) (vf0 :class vf) (vf1 :class vf) @@ -196,6 +207,8 @@ ;; definition for function vector--float*! (defun vector--float*! ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 float)) + "Set arg0 = arg1 - (arg2 * arg3). The w component will be set to 1. +Is this different from vector-*!" (rlet ((acc :class vf) (vf0 :class vf) (vf1 :class vf) @@ -217,6 +230,7 @@ ;; definition for function vector-float/! (defun vector-float/! ((arg0 vector) (arg1 vector) (arg2 float)) + "Divide all components by arg2. The w component will be set to 1." (rlet ((Q :class vf) (vf0 :class vf) (vf1 :class vf) @@ -239,6 +253,7 @@ ;; definition for function vector-negate! (defun vector-negate! ((arg0 vector) (arg1 vector)) + "Negate xyz, set w to 1." (rlet ((vf0 :class vf) (vf1 :class vf) (vf4 :class vf) @@ -254,6 +269,7 @@ ;; definition for function vector-negate-in-place! (defun vector-negate-in-place! ((arg0 vector)) + "Negate xyz. Doesn't touch w." (rlet ((vf0 :class vf) (vf1 :class vf) ) @@ -270,6 +286,7 @@ ;; definition for function vector-delta (defun vector-delta ((arg0 vector) (arg1 vector)) + "Sum of the elementwise absolute value of differences." (local-vars (v0-0 float)) (rlet ((acc :class vf) (vf0 :class vf) @@ -293,6 +310,8 @@ ;; definition for function vector-seek! (defun vector-seek! ((arg0 vector) (arg1 vector) (arg2 float)) + "Seek arg0 toward arg1. The arg0 is both read and written. +arg2 is saturated to (0, 1)" (rlet ((vf0 :class vf) (vf1 :class vf) (vf2 :class vf) @@ -317,6 +336,10 @@ ;; definition for function vector-smooth-seek! (defun vector-smooth-seek! ((arg0 vector) (arg1 vector) (arg2 float)) + "Smoothly seek vec toward target. +The step always points toward the target and has length (dist * alpha). +If the step is longer than max-step, the step is projected onto a _square_ with side length arg2. +Note that this doesn't project to a circle like the function below..." (rlet ((acc :class vf) (vf0 :class vf) (vf4 :class vf) @@ -345,6 +368,10 @@ ;; definition for function vector-seek-2d-xz-smooth! (defun vector-seek-2d-xz-smooth! ((arg0 vector) (arg1 vector) (arg2 float) (arg3 float)) + "Smoothly seek vec's x and z components toward target. +The step always points toward the target and has length (dist * alpha). +If the step is longer than max-step, the step is projected onto a circle of radius max-step. +Doesn't touch y or w." (let ((f0-1 (- (-> arg1 x) (-> arg0 x))) (f2-1 (- (-> arg1 z) (-> arg0 z))) ) @@ -373,6 +400,10 @@ ;; definition for function vector-seek-2d-yz-smooth! (defun vector-seek-2d-yz-smooth! ((arg0 vector) (arg1 vector) (arg2 float) (arg3 float)) + "Smoothly seek vec's y and z components toward target. +The step always points toward the target and has length (dist * alpha). +If the step is longer than max-step, the step is projected onto a circle of radius max-step. +Doesn't touch x or w." (let ((f0-1 (- (-> arg1 y) (-> arg0 y))) (f2-1 (- (-> arg1 z) (-> arg0 z))) ) @@ -401,6 +432,10 @@ ;; definition for function vector-seek-3d-smooth! (defun vector-seek-3d-smooth! ((arg0 vector) (arg1 vector) (arg2 float) (arg3 float)) + "Smoothly seek vec's x, y, and z components toward target. +The step always points toward the target and has length (dist * alpha). +If the step is longer than max-step, the step is projected onto a circle of radius max-step. +Doesn't touch w." (let ((f0-1 (- (-> arg1 x) (-> arg0 x))) (f1-2 (- (-> arg1 y) (-> arg0 y))) (f3-1 (- (-> arg1 z) (-> arg0 z))) @@ -433,6 +468,9 @@ ;; definition for function seek-with-smooth (defun seek-with-smooth ((arg0 float) (arg1 float) (arg2 float) (arg3 float) (arg4 float)) + "Move value closer to target. +If we are within deadband, just go straight to target. +If not, try to go alpha*err. If that is a larger step than max-step, limit to max-step" (let ((f0-1 (- arg1 arg0))) (cond ((>= arg4 (fabs f0-1)) @@ -459,6 +497,7 @@ ;; definition for function vector-identity! (defun vector-identity! ((arg0 vector)) + "Set arg0 to 1, 1, 1, 1." (set! (-> arg0 x) 1.0) (set! (-> arg0 y) 1.0) (set! (-> arg0 z) 1.0) @@ -468,6 +507,7 @@ ;; definition for function vector-seconds (defun vector-seconds ((arg0 vector) (arg1 vector)) + "Convert from actual seconds to the seconds unit." (set! (-> arg0 x) (* 300.0 (-> arg1 x))) (set! (-> arg0 y) (* 300.0 (-> arg1 y))) (set! (-> arg0 z) (* 300.0 (-> arg1 z))) @@ -476,6 +516,7 @@ ;; definition for function vector-seconds! (defun vector-seconds! ((arg0 vector)) + "Convert from actual seconds to seconds, in place." (set! (-> arg0 x) (* 300.0 (-> arg0 x))) (set! (-> arg0 y) (* 300.0 (-> arg0 y))) (set! (-> arg0 z) (* 300.0 (-> arg0 z))) @@ -484,41 +525,49 @@ ;; definition for function vector-v! (defun vector-v! ((arg0 vector)) + "Convert a velocity to a displacement per frame. The velocity should be in X/actual_second. +Uses the current process clock." (vector-float*! arg0 arg0 (seconds-per-frame)) arg0 ) ;; definition for function vector-v+! (defun vector-v+! ((arg0 vector) (arg1 vector) (arg2 vector)) + "Euler forward step, using the current display time settings." (vector+float*! arg0 arg1 arg2 (seconds-per-frame)) arg0 ) ;; definition for function vector-v*float+! (defun vector-v*float+! ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 float)) + "Euler forward step, scaling velocity by velocity-scale." (vector+float*! arg0 arg1 arg2 (* arg3 (seconds-per-frame))) arg0 ) ;; definition for function vector-v++! (defun vector-v++! ((arg0 vector) (arg1 vector)) + "Update position in place, using display's current timing." (vector+float*! arg0 arg0 arg1 (seconds-per-frame)) arg0 ) ;; definition for function vector-v*float! (defun vector-v*float! ((arg0 vector) (arg1 vector) (arg2 float)) + "Go from velocity to delta-p per frame, scaling by scale." (vector-float*! arg0 arg1 (* arg2 (seconds-per-frame))) ) ;; definition for function vector-v*float++! (defun vector-v*float++! ((arg0 vector) (arg1 vector) (arg2 float)) + "Update position with given velocity, scaled by scale." (vector+float*! arg0 arg0 arg1 (* arg2 (seconds-per-frame))) arg0 ) ;; definition for function vector-to-ups! (defun vector-to-ups! ((arg0 vector) (arg1 vector)) + "Go from units per frame to units per second?" (local-vars (at-0 int)) (with-pp (rlet ((vf0 :class vf) @@ -541,6 +590,7 @@ ;; definition for function vector-from-ups! (defun vector-from-ups! ((arg0 vector) (arg1 vector)) + "Go from units per second to units per frame?" (local-vars (at-0 int)) (rlet ((vf0 :class vf) (vf1 :class vf) @@ -561,11 +611,13 @@ ;; definition for function vector-length (defun vector-length ((arg0 vector)) + "Get the length of the xyz part." (vector-length arg0) ) ;; definition for function vector-length-squared (defun vector-length-squared ((arg0 vector)) + "Get the squared length of the xyz part." (local-vars (v0-0 float)) (rlet ((acc :class vf) (vf0 :class vf) @@ -586,16 +638,19 @@ ;; definition for function vector-xz-length-squared (defun vector-xz-length-squared ((arg0 vector)) + "Get the length of the xz part, squared." (+ (* (-> arg0 x) (-> arg0 x)) (* (-> arg0 z) (-> arg0 z))) ) ;; definition for function vector-xz-length (defun vector-xz-length ((arg0 vector)) + "Get the length of the xz part." (sqrtf (+ (* (-> arg0 x) (-> arg0 x)) (* (-> arg0 z) (-> arg0 z)))) ) ;; definition for function vector-vector-distance (defun vector-vector-distance ((arg0 vector) (arg1 vector)) + "Subtract the xyz parts and get the norm." (local-vars (v0-0 float)) (rlet ((acc :class vf) (Q :class vf) @@ -625,6 +680,7 @@ ;; definition for function vector-vector-distance-squared (defun vector-vector-distance-squared ((arg0 vector) (arg1 vector)) + "Squared norm of the difference of the xyz parts." (local-vars (v0-0 float)) (rlet ((vf1 :class vf) (vf2 :class vf) @@ -643,6 +699,7 @@ ;; definition for function vector-vector-xz-distance (defun vector-vector-xz-distance ((arg0 vector) (arg1 vector)) + "Distance on the xz plane." (local-vars (v0-0 float)) (rlet ((acc :class vf) (Q :class vf) @@ -671,6 +728,7 @@ ;; definition for function vector-vector-xy-distance (defun vector-vector-xy-distance ((arg0 vector) (arg1 vector)) + "distance on the xy plane." (local-vars (v0-0 float)) (rlet ((acc :class vf) (Q :class vf) @@ -699,6 +757,7 @@ ;; definition for function vector-vector-xz-distance-squared (defun vector-vector-xz-distance-squared ((arg0 vector) (arg1 vector)) + "Distance on the xz plane squared." (local-vars (v0-0 float)) (rlet ((vf1 :class vf) (vf2 :class vf) @@ -716,6 +775,7 @@ ;; definition for function vector-normalize! (defun vector-normalize! ((arg0 vector) (arg1 float)) + "Modify arg0 in place to have length arg1 for its xyz components. The w part is not changed." (rlet ((acc :class vf) (Q :class vf) (vf0 :class vf) @@ -745,6 +805,8 @@ ;; definition for function vector-normalize-ret-len! (defun vector-normalize-ret-len! ((arg0 vector) (arg1 float)) + "Modify arg0 in place to have length arg1 for its xyz components. +The w part isn't changed and the _original_ length is returned." (local-vars (v1-1 float)) (rlet ((acc :class vf) (Q :class vf) @@ -780,6 +842,9 @@ ;; definition for function vector-normalize-copy! ;; INFO: Used lq/sq (defun vector-normalize-copy! ((arg0 vector) (arg1 vector) (arg2 float)) + "Normalize, but not in place. +This implementation is very good compared to the vector-normalize! one. +The w component is set to 1." (let ((f0-0 (vector-length arg1))) (cond ((= f0-0 0.0) @@ -799,23 +864,25 @@ ) ;; definition for function vector-xz-normalize! -(defun vector-xz-normalize! ((arg0 vector) (arg1 float)) - (let* ((v1-0 arg0) +(defun vector-xz-normalize! ((vec vector) (arg1 float)) + "Normalize, xz components only." + (let* ((v1-0 vec) (f0-4 (sqrtf (+ (* (-> v1-0 x) (-> v1-0 x)) (* (-> v1-0 z) (-> v1-0 z))))) ) (when (!= f0-4 0.0) (let ((v1-3 (/ arg1 f0-4))) - (set! (-> arg0 x) (* (-> arg0 x) v1-3)) - (set! (-> arg0 z) (* (-> arg0 z) v1-3)) + (set! (-> vec x) (* (-> vec x) v1-3)) + (set! (-> vec z) (* (-> vec z) v1-3)) ) ) ) - arg0 + vec ) ;; definition for function vector-xz-normalize-copy! ;; INFO: Used lq/sq (defun vector-xz-normalize-copy! ((arg0 vector) (arg1 vector) (arg2 float)) + "Normalize, xz components only." (let* ((v1-0 arg1) (f0-4 (sqrtf (+ (* (-> v1-0 x) (-> v1-0 x)) (* (-> v1-0 z) (-> v1-0 z))))) ) @@ -838,6 +905,9 @@ ;; definition for function vector-length-max! (defun vector-length-max! ((arg0 vector) (arg1 float)) + "Make vector at most arg1 length (xyz only). +If it is larger, project onto sphere. +Doesn't touch w" (let ((f0-0 (vector-length arg0))) (when (not (or (= f0-0 0.0) (< f0-0 arg1))) (let ((f0-1 (/ f0-0 arg1))) @@ -854,6 +924,9 @@ ;; definition for function vector-xz-length-max! (defun vector-xz-length-max! ((arg0 vector) (arg1 float)) + "Make vector at most arg1 length (xz only). +It it is larger, project onto circle. +Doesn't touch w or y." (let* ((v1-0 arg0) (f0-4 (sqrtf (+ (* (-> v1-0 x) (-> v1-0 x)) (* (-> v1-0 z) (-> v1-0 z))))) ) @@ -872,6 +945,7 @@ ;; definition for function vector-rotate-around-x! ;; INFO: Used lq/sq (defun vector-rotate-around-x! ((arg0 vector) (arg1 vector) (arg2 float)) + "Rotate a vector around the x axis." (let* ((f28-0 (- arg2)) (f30-0 (cos f28-0)) (f1-0 (sin f28-0)) @@ -888,6 +962,7 @@ ;; definition for function vector-rotate-around-y! ;; INFO: Used lq/sq (defun vector-rotate-around-y! ((arg0 vector) (arg1 vector) (arg2 float)) + "Rotate a vector around the y axis." (let ((f26-0 (-> arg1 z)) (f30-0 (-> arg1 x)) (f28-0 (cos arg2)) @@ -903,6 +978,7 @@ ;; definition for function vector-rotate90-around-y! ;; INFO: Used lq/sq (defun vector-rotate90-around-y! ((arg0 vector) (arg1 vector)) + "Rotate a vector 90 degrees around y." (set! (-> arg0 quad) (-> arg1 quad)) (let ((f0-0 (-> arg0 x))) (set! (-> arg0 x) (- (-> arg1 z))) @@ -914,6 +990,7 @@ ;; definition for function vector-rotate-around-z! ;; INFO: Used lq/sq (defun vector-rotate-around-z! ((arg0 vector) (arg1 vector) (arg2 float)) + "Rotate a vector around the z axis." (let ((f26-0 (-> arg1 x)) (f30-0 (-> arg1 y)) (f28-0 (cos arg2)) @@ -934,16 +1011,19 @@ ;; definition for function rotate-x<-vector+vector (defun rotate-x<-vector+vector ((arg0 vector) (arg1 vector)) + "Get the x rotation between vectors. These should have the same length." (atan (- (-> arg1 y) (-> arg0 y)) (- (-> arg1 z) (-> arg0 z))) ) ;; definition for function rotate-z<-vector+vector (defun rotate-z<-vector+vector ((arg0 vector) (arg1 vector)) + "Get the z rotation between vectors. These should have the same length." (atan (- (-> arg1 x) (-> arg0 x)) (- (-> arg1 y) (-> arg0 y))) ) ;; definition for function vector-cvt.w.s! (defun vector-cvt.w.s! ((arg0 vector) (arg1 vector)) + "Convert float to int32. Truncate." (rlet ((vf1 :class vf)) (.lvf vf1 (&-> arg1 quad)) (.ftoi.vf vf1 vf1) @@ -954,6 +1034,7 @@ ;; definition for function vector-cvt.s.w! (defun vector-cvt.s.w! ((arg0 vector) (arg1 vector)) + "Convert float to int32." (rlet ((vf1 :class vf)) (.lvf vf1 (&-> arg1 quad)) (.itof.vf vf1 vf1) @@ -964,6 +1045,8 @@ ;; definition for function rot-zxy-from-vector! (defun rot-zxy-from-vector! ((arg0 vector) (arg1 vector)) + "I think this gives you a vector of euler angles to rotate some unit vector +to arg1." (let* ((f28-0 (-> arg1 z)) (f30-0 (-> arg1 x)) (f0-0 (atan f30-0 f28-0)) @@ -981,6 +1064,8 @@ ;; definition for function rot-zyx-from-vector! (defun rot-zyx-from-vector! ((arg0 vector) (arg1 vector)) + "I think this gives you a vector of euler angles to rotate some unit vector +to arg1." (let* ((f28-0 (-> arg1 z)) (f30-0 (- (-> arg1 y))) (f0-1 (atan f30-0 f28-0)) @@ -998,6 +1083,8 @@ ;; definition for function vector-lerp! (defun vector-lerp! ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 float)) + "Linearly interpolate between two vectors. Alpha isn't clamped. +w will be set to 1." (rlet ((vf0 :class vf) (vf1 :class vf) (vf2 :class vf) @@ -1020,6 +1107,8 @@ ;; definition for function vector-lerp-clamp! ;; INFO: Used lq/sq (defun vector-lerp-clamp! ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 float)) + "Linearly interpolate between two vectors, clamping alpha to 0, 1. +w will be set to 1." (rlet ((vf0 :class vf) (vf1 :class vf) (vf2 :class vf) @@ -1057,6 +1146,7 @@ ;; definition for function vector4-lerp! (defun vector4-lerp! ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 float)) + "Interpolate all 4 elements of a vector. Alpha is not clamped." (rlet ((vf1 :class vf) (vf2 :class vf) (vf3 :class vf) @@ -1076,6 +1166,7 @@ ;; definition for function vector4-lerp-clamp! ;; INFO: Used lq/sq (defun vector4-lerp-clamp! ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 float)) + "Interpolate all 4 elements of a vector. Alpha is clamped to [0, 1]." (rlet ((vf1 :class vf) (vf2 :class vf) (vf3 :class vf) @@ -1111,6 +1202,10 @@ ;; definition for function vector-degi ;; INFO: Used lq/sq (defun vector-degi ((arg0 vector) (arg1 vector)) + "Convert a vector (in _rotations_) to degrees units, stored in an int. +Truncates to the nearest _rotation_. +Neither the input or output is a commonly used form. +Unsurprisingly, this strange function is never used." (local-vars (v1-0 uint128) (v1-1 uint128)) (rlet ((vf1 :class vf)) (.lvf vf1 (&-> arg1 quad)) @@ -1125,6 +1220,9 @@ ;; definition for function vector-degf ;; INFO: Used lq/sq (defun vector-degf ((arg0 vector) (arg1 vector)) + "Convert a vector (in integer degree units) to floating point rotations. +Truncates to the nearest _rotation_. +Like the previous function, this is stupid and unused." (local-vars (v1-1 uint128)) (rlet ((vf1 :class vf)) (let ((v1-0 (-> arg1 quad))) @@ -1139,6 +1237,8 @@ ;; definition for function vector-degmod (defun vector-degmod ((arg0 vector) (arg1 vector)) + "This one is actually right. Wraps degrees units (in floats, like they should be) +to +/- half a rotation." (local-vars (v1-0 uint128) (v1-1 uint128) (v1-2 uint128)) (rlet ((vf1 :class vf)) (.lvf vf1 (&-> arg1 quad)) @@ -1156,6 +1256,7 @@ ;; definition for function vector-deg-diff ;; WARN: Return type mismatch float vs none. (defun vector-deg-diff ((arg0 vector) (arg1 vector) (arg2 vector)) + "Wrapped difference, degrees units. Will have the usual 16-bit accuracy issue." (local-vars (v0-0 float) (v1-0 uint128) @@ -1189,6 +1290,7 @@ ;; definition for function vector-deg-lerp-clamp! ;; INFO: Used lq/sq (defun vector-deg-lerp-clamp! ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 float)) + "Apply deg-lerp-clamp to the xyz components of a vector. Sets w = 1." (cond ((>= 0.0 arg3) (set! (-> arg0 quad) (-> arg1 quad)) @@ -1245,6 +1347,7 @@ ;; definition for function vector4-add! ;; WARN: Return type mismatch float vs none. (defun vector4-add! ((arg0 vector4) (arg1 vector4) (arg2 vector4)) + "Add 2 vector4s." (local-vars (v0-0 float)) (rlet ((vf4 :class vf) (vf5 :class vf) @@ -1262,6 +1365,7 @@ ;; definition for function vector4-sub! ;; WARN: Return type mismatch float vs none. (defun vector4-sub! ((arg0 vector4) (arg1 vector4) (arg2 vector4)) + "Subtract 2 vector4s." (local-vars (v0-0 float)) (rlet ((vf4 :class vf) (vf5 :class vf) @@ -1279,6 +1383,7 @@ ;; definition for function vector4-mul! ;; WARN: Return type mismatch float vs none. (defun vector4-mul! ((arg0 vector4) (arg1 vector4) (arg2 vector4)) + "Multiple 2 vector4s." (local-vars (v0-0 float)) (rlet ((vf4 :class vf) (vf5 :class vf) @@ -1296,6 +1401,7 @@ ;; definition for function vector4-scale! ;; WARN: Return type mismatch float vs none. (defun vector4-scale! ((arg0 vector4) (arg1 vector4) (arg2 float)) + "arg0 = arg1 * arg2." (local-vars (v0-0 float)) (rlet ((vf4 :class vf) (vf5 :class vf) @@ -1313,6 +1419,7 @@ ;; definition for function vector4-madd! ;; WARN: Return type mismatch float vs none. (defun vector4-madd! ((arg0 vector4) (arg1 vector4) (arg2 vector4) (arg3 float)) + "arg0 = arg1 + arg2 * arg3." (local-vars (v0-0 float)) (rlet ((acc :class vf) (vf0 :class vf) @@ -1336,6 +1443,7 @@ ;; definition for function vector4-msub! ;; WARN: Return type mismatch float vs none. (defun vector4-msub! ((arg0 vector4) (arg1 vector4) (arg2 vector4) (arg3 float)) + "arg0 = arg1 - arg2 * arg3." (local-vars (v0-0 float)) (rlet ((acc :class vf) (vf0 :class vf) @@ -1359,6 +1467,7 @@ ;; definition for function vector4-array-add! ;; WARN: Return type mismatch symbol vs none. (defun vector4-array-add! ((arg0 (inline-array vector4)) (arg1 (inline-array vector4)) (arg2 (inline-array vector4)) (arg3 int)) + "Apply vector4-add! to all arrays." (dotimes (s2-0 arg3) (vector4-add! (the-as vector4 arg0) (the-as vector4 arg1) (the-as vector4 arg2)) (set! arg1 (the-as (inline-array vector4) (-> arg1 1))) @@ -1371,6 +1480,7 @@ ;; definition for function vector4-array-sub! ;; WARN: Return type mismatch symbol vs none. (defun vector4-array-sub! ((arg0 (inline-array vector4)) (arg1 (inline-array vector4)) (arg2 (inline-array vector4)) (arg3 int)) + "Apply vector4-sub! to all arrays." (dotimes (s2-0 arg3) (vector4-sub! (the-as vector4 arg0) (the-as vector4 arg1) (the-as vector4 arg2)) (set! arg1 (the-as (inline-array vector4) (-> arg1 1))) @@ -1383,6 +1493,7 @@ ;; definition for function vector4-array-mul! ;; WARN: Return type mismatch symbol vs none. (defun vector4-array-mul! ((arg0 (inline-array vector4)) (arg1 (inline-array vector4)) (arg2 (inline-array vector4)) (arg3 int)) + "Apply vector4-mul! to all arrays." (dotimes (s2-0 arg3) (vector4-mul! (the-as vector4 arg0) (the-as vector4 arg1) (the-as vector4 arg2)) (set! arg1 (the-as (inline-array vector4) (-> arg1 1))) @@ -1395,6 +1506,7 @@ ;; definition for function vector4-array-scale! ;; WARN: Return type mismatch symbol vs none. (defun vector4-array-scale! ((arg0 (inline-array vector4)) (arg1 (inline-array vector4)) (arg2 float) (arg3 int)) + "Apply vector4-scale! to all arrays." (dotimes (s2-0 arg3) (vector4-scale! (the-as vector4 arg0) (the-as vector4 arg1) arg2) (set! arg1 (the-as (inline-array vector4) (-> arg1 1))) @@ -1411,6 +1523,7 @@ (arg3 float) (arg4 int) ) + "Apply vector4-madd! to all arrays." (dotimes (s1-0 arg4) (vector4-madd! (the-as vector4 arg0) (the-as vector4 arg1) (the-as vector4 arg2) arg3) (set! arg1 (the-as (inline-array vector4) (-> arg1 1))) @@ -1428,6 +1541,7 @@ (arg3 float) (arg4 int) ) + "Apply vector4-msub! to all arrays." (dotimes (s1-0 arg4) (vector4-msub! (the-as vector4 arg0) (the-as vector4 arg1) (the-as vector4 arg2) arg3) (set! arg1 (the-as (inline-array vector4) (-> arg1 1))) @@ -1444,6 +1558,7 @@ (arg3 float) (arg4 int) ) + "Apply vector4-lerp! to all arrays." (dotimes (s1-0 arg4) (vector4-lerp! (the-as vector arg0) (the-as vector arg1) (the-as vector arg2) arg3) (set! arg1 (the-as (inline-array vector4) (-> arg1 1))) @@ -1455,6 +1570,7 @@ ;; definition for function spheres-overlap? (defun spheres-overlap? ((arg0 sphere) (arg1 sphere)) + "Do the spheres overlap?" (local-vars (v1-0 float) (a0-1 float)) (rlet ((vf0 :class vf) (vf1 :class vf) @@ -1481,6 +1597,7 @@ ;; definition for function sphere<-vector! ;; INFO: Used lq/sq (defun sphere<-vector! ((arg0 sphere) (arg1 vector)) + "Set the position of the sphere to arg1. Does not change the radius." (let ((f0-0 (-> arg0 r))) (set! (-> arg0 quad) (-> arg1 quad)) (set! (-> arg0 r) f0-0) @@ -1491,6 +1608,7 @@ ;; definition for function sphere<-vector+r! ;; INFO: Used lq/sq (defun sphere<-vector+r! ((arg0 sphere) (arg1 vector) (arg2 float)) + "Set the position of the sphere from arg1 and the radius from arg2." (set! (-> arg0 quad) (-> arg1 quad)) (set! (-> arg0 r) arg2) arg0 @@ -1498,6 +1616,8 @@ ;; definition for function rand-vu-sphere-point! (defun rand-vu-sphere-point! ((arg0 vector) (arg1 float)) + "Get a random point on the sphere at the origin with radius arg1. +The point is on the surface of the sphere." (set-vector! arg0 (rand-vu-float-range -1.0 1.0) @@ -1516,6 +1636,7 @@ ;; definition for function vector-vector-angle-safe (defun vector-vector-angle-safe ((arg0 vector) (arg1 vector)) + "Get the angle between two vectors, with some 'safety' applied..." (let ((f0-1 (vector-dot (vector-normalize-copy! (new 'stack-no-clear 'vector) arg0 1.0) (vector-normalize-copy! (new 'stack-no-clear 'vector) arg1 1.0) diff --git a/test/decompiler/reference/jak2/engine/nav/nav-mesh-h_REF.gc b/test/decompiler/reference/jak2/engine/nav/nav-mesh-h_REF.gc index 05f74a28ff..74b0cce3b1 100644 --- a/test/decompiler/reference/jak2/engine/nav/nav-mesh-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/nav/nav-mesh-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type nav-mesh-work-debug (deftype nav-mesh-work-debug (structure) + "Debug outputs for the nav-mesh assembly functions" ((debug-vec1 vector :inline) (debug-vec2 vector :inline) (debug-vec3 vector :inline) @@ -45,6 +46,7 @@ ;; definition of type nav-mesh-work (deftype nav-mesh-work (structure) + "Workspace for nav-mesh processing functions." ((vert0-table int8 4) (vert1-table int8 4) (edge-mask-table uint8 3) @@ -97,6 +99,7 @@ ;; definition of type nav-mesh-link (deftype nav-mesh-link (structure) + "Link between two different meshes" ((id uint32) (dest-mesh-id uint32) (src-link-poly-id uint8) @@ -127,6 +130,8 @@ ;; definition of type nav-poly (deftype nav-poly (structure) + "Polygon within a nav-mesh. Can be a tri or quad. +Based on the implementation of point-poly-intersection?, these should likely be convex." ((data uint8 64) (vertex vector 4 :inline :overlay-at (-> data 0)) (vertex0 vector :inline :overlay-at (-> data 0)) @@ -352,6 +357,7 @@ and declared out of order (cannot use forward declared structures in inline arra ;; definition of type nav-mesh (deftype nav-mesh (basic) + "Mesh used for creature/enemy navigation." ((work nav-mesh-work) (poly-array (inline-array nav-poly)) (static-sphere-count uint8) @@ -462,6 +468,7 @@ and declared out of order (cannot use forward declared structures in inline arra ;; definition for function vector-normalize-unity! (defun vector-normalize-unity! ((arg0 vector)) + "Normalize a vector (xyz only) in place." (rlet ((acc :class vf) (Q :class vf) (vf0 :class vf) @@ -496,6 +503,7 @@ and declared out of order (cannot use forward declared structures in inline arra ;; definition for function vector-normalize-unity-copy! ;; INFO: Used lq/sq (defun vector-normalize-unity-copy! ((arg0 vector) (arg1 vector)) + "Normalize a vector (xyz only)" (rlet ((acc :class vf) (Q :class vf) (vf0 :class vf) @@ -530,12 +538,14 @@ and declared out of order (cannot use forward declared structures in inline arra ;; definition (debug) for function debug-validate-current-poly (defun-debug debug-validate-current-poly () + "Not implemented." #f ) ;; definition for function init-ray ;; WARN: Return type mismatch int vs none. (defun init-ray ((arg0 nav-ray)) + "Set up a nav-ray. Assumes that dest-pos and current-pos are set." (rlet ((acc :class vf) (Q :class vf) (vf0 :class vf) @@ -579,17 +589,18 @@ and declared out of order (cannot use forward declared structures in inline arra ) ;; definition for function point-poly-intersection? -(defun point-poly-intersection? ((arg0 nav-mesh) (arg1 vector) (arg2 int) (arg3 (inline-array vector))) - (let ((v1-1 (-> arg0 work vert0-table)) - (a0-2 (-> arg0 work vert1-table)) +(defun point-poly-intersection? ((mesh nav-mesh) (pt vector) (num-verts int) (verts (inline-array vector))) + "Check if a point is inside a poly." + (let ((v1-1 (-> mesh work vert0-table)) + (a0-2 (-> mesh work vert1-table)) ) - (dotimes (t0-0 arg2) - (let* ((t1-3 (-> arg3 (-> v1-1 t0-0))) - (t2-3 (-> arg3 (-> a0-2 t0-0))) + (dotimes (t0-0 num-verts) + (let* ((t1-3 (-> verts (-> v1-1 t0-0))) + (t2-3 (-> verts (-> a0-2 t0-0))) (f0-1 (- (-> t1-3 z) (-> t2-3 z))) (f1-2 (- (-> t2-3 x) (-> t1-3 x))) - (f2-2 (- (-> arg1 x) (-> t1-3 x))) - (f3-2 (- (-> arg1 z) (-> t1-3 z))) + (f2-2 (- (-> pt x) (-> t1-3 x))) + (f3-2 (- (-> pt z) (-> t1-3 z))) (f0-3 (+ (* f2-2 f0-1) (* f3-2 f1-2))) ) (if (< 0.0 f0-3) @@ -603,6 +614,7 @@ and declared out of order (cannot use forward declared structures in inline arra ;; definition for method 37 of type nav-mesh (defmethod point-in-poly? ((this nav-mesh) (arg0 nav-poly) (arg1 vector)) + "Check if a point is inside a poly of this mesh" (let* ((a3-0 this) (v1-0 arg1) (a0-1 (-> arg0 vertex-count)) @@ -636,6 +648,7 @@ and declared out of order (cannot use forward declared structures in inline arra ;; WARN: Stack slot offset 56 signed mismatch ;; WARN: Return type mismatch vector vs none. (defmethod closest-point-on-boundary ((this nav-mesh) (arg0 nav-poly) (arg1 vector) (arg2 vector)) + "Find the point on the polygon edge that is closest to the query point." (local-vars (sv-48 vector) (sv-52 vector) (sv-56 float)) (set! sv-48 (new 'stack-no-clear 'vector)) (set! sv-52 (new 'stack-no-clear 'vector)) @@ -665,6 +678,7 @@ and declared out of order (cannot use forward declared structures in inline arra ;; WARN: Stack slot offset 56 signed mismatch ;; WARN: Return type mismatch vector vs none. (defmethod project-point-into-poly-2d ((this nav-mesh) (arg0 nav-poly) (arg1 vector) (arg2 vector)) + "Find the point in the polygon closest to the query point." (local-vars (sv-48 vector) (sv-52 vector) (sv-56 float)) (cond ((point-in-poly? this arg0 arg2) @@ -833,6 +847,7 @@ and declared out of order (cannot use forward declared structures in inline arra ;; definition (debug) for function nav-sphere-from-cam ;; WARN: Return type mismatch int vs none. (defun-debug nav-sphere-from-cam () + "Print out a SPHEREM from the current camera position, possibly used by their level-building tool." (let ((v1-0 (camera-pos))) (format #t "SPHEREM(~4,,1M, ~4,,1M, ~4,,1M, 1.0)~%" (-> v1-0 x) (-> v1-0 y) (-> v1-0 z)) ) diff --git a/test/decompiler/reference/jak2/engine/process-drawable/focus_REF.gc b/test/decompiler/reference/jak2/engine/process-drawable/focus_REF.gc index 547bffcb3d..fc8acf58ee 100644 --- a/test/decompiler/reference/jak2/engine/process-drawable/focus_REF.gc +++ b/test/decompiler/reference/jak2/engine/process-drawable/focus_REF.gc @@ -3,6 +3,7 @@ ;; definition of type focus (deftype focus (structure) + "A structure that keeps a handle to a [[process-focusable]]." ((handle handle) (collide-with collide-spec) ) @@ -29,31 +30,35 @@ ;; definition for method 11 of type focus ;; WARN: Return type mismatch int vs none. -(defmethod reset-to-collide-spec ((this focus) (arg0 collide-spec)) - (set! (-> this collide-with) arg0) +(defmethod reset-to-collide-spec ((this focus) (cspec collide-spec)) + "Reset this focus with the given [[collide-spec]]." + (set! (-> this collide-with) cspec) (set! (-> this handle) (the-as handle #f)) 0 (none) ) ;; definition for method 10 of type focus -(defmethod collide-check? ((this focus) (arg0 process-focusable)) - (when (and arg0 (not (logtest? (-> arg0 focus-status) (focus-status disable dead)))) - (let* ((s5-0 (-> arg0 root)) - (v1-2 (if (type? s5-0 collide-shape) - s5-0 - ) - ) +(defmethod collide-check? ((this focus) (proc process-focusable)) + "If the focused process is not dead, +check that the [[collide-spec]] of the focus and the process match." + (when (and proc (not (logtest? (-> proc focus-status) (focus-status disable dead)))) + (let* ((root (-> proc root)) + (cshape (if (type? root collide-shape) + root + ) + ) ) - (and v1-2 (logtest? (-> this collide-with) (-> v1-2 root-prim prim-core collide-as))) + (and cshape (logtest? (-> this collide-with) (-> cshape root-prim prim-core collide-as))) ) ) ) ;; definition for method 12 of type focus -(defmethod try-update-focus ((this focus) (arg0 process-focusable)) - (when (!= (handle->process (-> this handle)) arg0) - (set! (-> this handle) (process->handle arg0)) +(defmethod try-update-focus ((this focus) (proc process-focusable)) + "Try to set the `handle` of this focus to the given process." + (when (!= (handle->process (-> this handle)) proc) + (set! (-> this handle) (process->handle proc)) #t ) ) @@ -61,6 +66,7 @@ ;; definition for method 9 of type focus ;; WARN: Return type mismatch int vs none. (defmethod clear-focused ((this focus)) + "Reset the focus' handle." (set! (-> this handle) (the-as handle #f)) 0 (none) diff --git a/test/decompiler/reference/jak2/engine/process-drawable/process-drawable-h_REF.gc b/test/decompiler/reference/jak2/engine/process-drawable/process-drawable-h_REF.gc index a6f2bb1468..c4b07f23e4 100644 --- a/test/decompiler/reference/jak2/engine/process-drawable/process-drawable-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/process-drawable/process-drawable-h_REF.gc @@ -3,16 +3,17 @@ ;; definition for function cspace-by-name-no-fail ;; WARN: Return type mismatch object vs cspace. -(defun cspace-by-name-no-fail ((arg0 process-drawable) (arg1 string)) - (let ((v0-0 (the-as object (cspace-by-name arg0 arg1)))) +(defun cspace-by-name-no-fail ((proc process-drawable) (name string)) + "Like [[cspace-by-name]], but prints an error if the [[cspace]] was not found and returns the `node-list`." + (let ((v0-0 (the-as object (cspace-by-name proc name)))) (the-as cspace (cond ((the-as cspace v0-0) (empty) v0-0 ) (else - (format 0 "no cspace (~A)~%" arg1) - (-> arg0 node-list data) + (format 0 "no cspace (~A)~%" name) + (-> proc node-list data) ) ) ) @@ -20,46 +21,47 @@ ) ;; definition for function cspace-index-by-name-no-fail -(defun cspace-index-by-name-no-fail ((arg0 process-drawable) (arg1 string)) - (let ((v0-0 (cspace-index-by-name arg0 arg1))) +(defun cspace-index-by-name-no-fail ((proc process-drawable) (name string)) + "Like [[cspace-index-by-name]], but prints an error if the [[cspace]] was not found and returns 0." + (let ((idx (cspace-index-by-name proc name))) (cond - ((< v0-0 0) - (format 0 "no cspace[ndx] (~A)~%" arg1) + ((< idx 0) + (format 0 "no cspace[ndx] (~A)~%" name) 0 ) (else (empty) - v0-0 + idx ) ) ) ) ;; definition for function num-func-none -(defbehavior num-func-none process ((arg0 joint-control-channel) (arg1 float) (arg2 float) (arg3 float)) - (-> arg0 frame-num) +(defbehavior num-func-none process ((chan joint-control-channel) (arg1 float) (arg2 float) (arg3 float)) + (-> chan frame-num) ) ;; definition for function num-func-+! -(defbehavior num-func-+! process ((arg0 joint-control-channel) (arg1 float) (arg2 float) (arg3 float)) - (set! (-> arg0 frame-num) - (+ (-> arg0 frame-num) (* arg1 (* (-> arg0 frame-group speed) (-> self clock time-adjust-ratio)))) +(defbehavior num-func-+! process ((chan joint-control-channel) (arg1 float) (arg2 float) (arg3 float)) + (set! (-> chan frame-num) + (+ (-> chan frame-num) (* arg1 (* (-> chan frame-group speed) (-> self clock time-adjust-ratio)))) ) ) ;; definition for function num-func--! -(defbehavior num-func--! process ((arg0 joint-control-channel) (arg1 float) (arg2 float) (arg3 float)) - (set! (-> arg0 frame-num) - (- (-> arg0 frame-num) (* arg1 (* (-> arg0 frame-group speed) (-> self clock time-adjust-ratio)))) +(defbehavior num-func--! process ((chan joint-control-channel) (arg1 float) (arg2 float) (arg3 float)) + (set! (-> chan frame-num) + (- (-> chan frame-num) (* arg1 (* (-> chan frame-group speed) (-> self clock time-adjust-ratio)))) ) ) ;; definition for function num-func-loop! -(defbehavior num-func-loop! process ((arg0 joint-control-channel) (arg1 float) (arg2 float) (arg3 float)) - (let* ((f0-1 (the float (+ (-> arg0 frame-group frames num-frames) -1))) - (f1-2 (+ (-> arg0 frame-num) f0-1 (* arg1 (* (-> arg0 frame-group speed) (-> self clock time-adjust-ratio))))) +(defbehavior num-func-loop! process ((chan joint-control-channel) (arg1 float) (arg2 float) (arg3 float)) + (let* ((f0-1 (the float (+ (-> chan frame-group frames num-frames) -1))) + (f1-2 (+ (-> chan frame-num) f0-1 (* arg1 (* (-> chan frame-group speed) (-> self clock time-adjust-ratio))))) ) - (set! (-> arg0 frame-num) (- f1-2 (* (the float (the int (/ f1-2 f0-1))) f0-1))) + (set! (-> chan frame-num) (- f1-2 (* (the float (the int (/ f1-2 f0-1))) f0-1))) ) ) @@ -73,9 +75,9 @@ ) ;; definition for function num-func-seek! -(defbehavior num-func-seek! process ((arg0 joint-control-channel) (arg1 float) (arg2 float) (arg3 float)) - (set! (-> arg0 frame-num) - (seek (-> arg0 frame-num) arg1 (* arg2 (* (-> arg0 frame-group speed) (-> self clock time-adjust-ratio)))) +(defbehavior num-func-seek! process ((chan joint-control-channel) (arg1 float) (arg2 float) (arg3 float)) + (set! (-> chan frame-num) + (seek (-> chan frame-num) arg1 (* arg2 (* (-> chan frame-group speed) (-> self clock time-adjust-ratio)))) ) ) @@ -173,8 +175,8 @@ ) ;; definition for function num-func-identity -(defbehavior num-func-identity process ((arg0 joint-control-channel) (arg1 float) (arg2 float) (arg3 float)) - (-> arg0 frame-num) +(defbehavior num-func-identity process ((chan joint-control-channel) (arg1 float) (arg2 float) (arg3 float)) + (-> chan frame-num) ) ;; failed to figure out what this is: diff --git a/test/decompiler/reference/jak2/engine/process-drawable/process-drawable_REF.gc b/test/decompiler/reference/jak2/engine/process-drawable/process-drawable_REF.gc index aa32ec6b44..978c582dde 100644 --- a/test/decompiler/reference/jak2/engine/process-drawable/process-drawable_REF.gc +++ b/test/decompiler/reference/jak2/engine/process-drawable/process-drawable_REF.gc @@ -526,6 +526,7 @@ ;; definition for method 10 of type process-drawable (defmethod deactivate ((this process-drawable)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this part)) (kill-and-free-particles (-> this part)) ) diff --git a/test/decompiler/reference/jak2/engine/process-drawable/process-taskable-h_REF.gc b/test/decompiler/reference/jak2/engine/process-drawable/process-taskable-h_REF.gc index d8f27624f9..e3ac8272a5 100644 --- a/test/decompiler/reference/jak2/engine/process-drawable/process-taskable-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/process-drawable/process-taskable-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type process-taskable (deftype process-taskable (process-focusable) + "The parent class for NPCs that can be talked to." ((task game-task-control) (ambient ambient-control :inline) (neck-joint-index int32) diff --git a/test/decompiler/reference/jak2/engine/process-drawable/simple-focus_REF.gc b/test/decompiler/reference/jak2/engine/process-drawable/simple-focus_REF.gc index 0b77d8bf30..c07801a1d2 100644 --- a/test/decompiler/reference/jak2/engine/process-drawable/simple-focus_REF.gc +++ b/test/decompiler/reference/jak2/engine/process-drawable/simple-focus_REF.gc @@ -32,6 +32,7 @@ ;; definition for method 12 of type simple-focus (defmethod run-logic? ((this simple-focus)) + "Should this process be run? Checked by execute-process-tree." (when (-> this first-time?) (set! (-> this first-time?) #f) #t diff --git a/test/decompiler/reference/jak2/engine/process-drawable/simple-nav-sphere_REF.gc b/test/decompiler/reference/jak2/engine/process-drawable/simple-nav-sphere_REF.gc index e544215702..46837d0c48 100644 --- a/test/decompiler/reference/jak2/engine/process-drawable/simple-nav-sphere_REF.gc +++ b/test/decompiler/reference/jak2/engine/process-drawable/simple-nav-sphere_REF.gc @@ -53,6 +53,7 @@ ;; definition for method 12 of type simple-nav-sphere (defmethod run-logic? ((this simple-nav-sphere)) + "Should this process be run? Checked by execute-process-tree." (cond (*display-nav-marks* #t diff --git a/test/decompiler/reference/jak2/engine/ps2/memcard-h_REF.gc b/test/decompiler/reference/jak2/engine/ps2/memcard-h_REF.gc index 46af633b70..930e6b28a5 100644 --- a/test/decompiler/reference/jak2/engine/ps2/memcard-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/ps2/memcard-h_REF.gc @@ -8,6 +8,7 @@ ;; definition of type mc-file-info (deftype mc-file-info (structure) + "Data stored in a save file." ((present int32) (blind-data float 16 :offset 4) (blind-data-int8 int8 64 :overlay-at (-> blind-data 0)) @@ -59,6 +60,7 @@ ;; definition of type mc-slot-info (deftype mc-slot-info (structure) + "Data about a memory card slot." ((handle int32) (known int32) (formatted int32) @@ -92,6 +94,7 @@ ;; definition for function mc-sync (defun mc-sync () + "Synchronize the memory card state." (let ((v0-0 0)) (while (zero? v0-0) (mc-run) @@ -103,49 +106,50 @@ ;; definition for function show-mc-info ;; WARN: Return type mismatch int vs none. -(defun show-mc-info ((arg0 dma-buffer)) - (let ((s5-0 (new 'stack-no-clear 'mc-slot-info))) - (dotimes (s4-0 2) - (mc-get-slot-info s4-0 s5-0) +(defun show-mc-info ((buf dma-buffer)) + "Display the memory card debug text." + (let ((slot (new 'stack-no-clear 'mc-slot-info))) + (dotimes (slot-idx 2) + (mc-get-slot-info slot-idx slot) (cond - ((zero? (-> s5-0 known)) - (format (clear *temp-string*) "SLOT ~D: EXAMINING SLOT~%" s4-0) + ((zero? (-> slot known)) + (format (clear *temp-string*) "SLOT ~D: EXAMINING SLOT~%" slot-idx) *temp-string* ) - ((zero? (-> s5-0 handle)) - (format (clear *temp-string*) "SLOT ~D: NO CARD~%" s4-0) + ((zero? (-> slot handle)) + (format (clear *temp-string*) "SLOT ~D: NO CARD~%" slot-idx) *temp-string* ) - ((zero? (-> s5-0 formatted)) - (format (clear *temp-string*) "SLOT ~D: CARD [~D] : NOT FORMATTED~%" s4-0 (-> s5-0 handle)) + ((zero? (-> slot formatted)) + (format (clear *temp-string*) "SLOT ~D: CARD [~D] : NOT FORMATTED~%" slot-idx (-> slot handle)) *temp-string* ) - ((zero? (-> s5-0 inited)) + ((zero? (-> slot inited)) (format (clear *temp-string*) "SLOT ~D: CARD [~D] : NO FILE [~D/~D]~%" - s4-0 - (-> s5-0 handle) - (-> s5-0 mem-required) - (-> s5-0 mem-actual) + slot-idx + (-> slot handle) + (-> slot mem-required) + (-> slot mem-actual) ) *temp-string* ) (else - (format (clear *temp-string*) "SLOT ~D: CARD [~D] : " s4-0 (-> s5-0 handle)) + (format (clear *temp-string*) "SLOT ~D: CARD [~D] : " slot-idx (-> slot handle)) *temp-string* (format *temp-string* "SAVES ~D ~D ~D ~D : LAST ~D~%" - (-> s5-0 file 0 present) - (-> s5-0 file 1 present) - (-> s5-0 file 2 present) - (-> s5-0 file 3 present) - (-> s5-0 last-file) + (-> slot file 0 present) + (-> slot file 1 present) + (-> slot file 2 present) + (-> slot file 3 present) + (-> slot last-file) ) ) ) - (draw-string-xy *temp-string* arg0 32 (+ (* 12 s4-0) 8) (font-color red) (font-flags shadow)) + (draw-string-xy *temp-string* buf 32 (+ (* 12 slot-idx) 8) (font-color red) (font-flags shadow)) ) ) 0 diff --git a/test/decompiler/reference/jak2/engine/ps2/pad_REF.gc b/test/decompiler/reference/jak2/engine/ps2/pad_REF.gc index f36c9a5722..6e25a6ebbd 100644 --- a/test/decompiler/reference/jak2/engine/ps2/pad_REF.gc +++ b/test/decompiler/reference/jak2/engine/ps2/pad_REF.gc @@ -38,6 +38,8 @@ ;; definition of type hw-cpad (deftype hw-cpad (basic) + "Data that comes directly from hardware. +It's 32 bytes + type tag (ignored by C kernel)." ((valid uint8) (status uint8) (button0 uint16) @@ -72,6 +74,7 @@ ;; definition of type cpad-info (deftype cpad-info (hw-cpad) + "Data from hardware + additional info calculated here." ((number int32) (cpad-file int32) (button0-abs pad-buttons 3) @@ -145,6 +148,7 @@ ;; definition for function cpad-invalid! (defun cpad-invalid! ((arg0 cpad-info)) + "Reset all data in a [[cpad-info]]." (logior! (-> arg0 valid) 128) (set! (-> arg0 button0) (the-as uint 0)) (set! (-> arg0 button0-abs 0) (pad-buttons)) @@ -182,6 +186,7 @@ ;; definition for method 0 of type cpad-info (defmethod new cpad-info ((allocation symbol) (type-to-make type) (arg0 int)) + "Allocate a new cpad-info and open the pad itself through the kernel." (let ((s5-0 (object-new allocation type-to-make (the-as int (-> type-to-make size))))) (set! (-> s5-0 number) arg0) (set! (-> s5-0 buzz) #f) @@ -192,6 +197,7 @@ ;; definition of type cpad-list (deftype cpad-list (basic) + "List of controllers. It always has two controllers." ((num-cpads int32) (cpads cpad-info 2) ) @@ -215,6 +221,8 @@ ;; definition for method 0 of type cpad-list (defmethod new cpad-list ((allocation symbol) (type-to-make type)) + "Create a cpad-list for 2 controllers. It's fine to do this even if one or both controllers +aren't connected yet." (let ((gp-0 (object-new allocation type-to-make (the-as int (-> type-to-make size))))) (set! (-> gp-0 num-cpads) 2) (set! (-> gp-0 cpads 0) (new 'global 'cpad-info 0)) @@ -225,6 +233,10 @@ ;; definition for function analog-input (defun analog-input ((arg0 int) (arg1 float) (arg2 float) (arg3 float) (arg4 float)) + "Convert integer input from pad into a float between -out-range and +out-range. +The offset is applied directly to the input. +The center val is the expected value for 0, after applying offset. +The max val is the expected value with the stick pushed all the way." (let* ((f1-1 (- (the float arg0) arg1)) (f0-3 (- (fabs f1-1) arg2)) (v1-0 (- arg3 arg2)) @@ -249,6 +261,7 @@ ;; definition for function cpad-set-buzz! ;; WARN: Return type mismatch int vs none. (defun cpad-set-buzz! ((arg0 cpad-info) (arg1 int) (arg2 int) (arg3 time-frame)) + "Turn on vibration motor `buzz-idx` for duration, at magnitude `buzz-amount`." (cond ((zero? arg2) (set! (-> arg0 buzz-val arg1) (the-as uint 0)) @@ -274,6 +287,7 @@ ;; definition for function service-cpads (defun service-cpads () + "Read from cpads and update vibration." (let ((pads *cpad-list*)) (dotimes (i (-> pads num-cpads)) (let ((pad (-> *cpad-list* cpads i))) @@ -515,6 +529,7 @@ ;; definition for function buzz-stop! ;; WARN: Return type mismatch int vs none. (defun buzz-stop! ((arg0 int)) + "Set the buzz to 0 on both vibration motors of the given cpad." (cpad-set-buzz! (-> *cpad-list* cpads arg0) 0 0 0) (cpad-set-buzz! (-> *cpad-list* cpads arg0) 1 0 0) 0 @@ -600,43 +615,48 @@ ;; INFO: Used lq/sq ;; WARN: Return type mismatch mouse-info vs none. (defun service-mouse () - (let ((gp-0 *mouse*)) - (mouse-get-data gp-0) - (set! (-> gp-0 pos 1 quad) (-> gp-0 pos 0 quad)) - (set! (-> gp-0 button0-abs 2) (-> gp-0 button0-abs 1)) - (set! (-> gp-0 button0-abs 1) (-> gp-0 button0-shadow-abs 0)) - (set! (-> gp-0 button0-rel 2) (-> gp-0 button0-rel 1)) - (set! (-> gp-0 button0-rel 1) (-> gp-0 button0-rel 0)) - (set! (-> gp-0 button0-rel 0) (mouse-buttons)) - (set! (-> gp-0 speedx) 0.0) - (set! (-> gp-0 speedy) 0.0) + "Update the mouse, and draw the cursor." + (let ((mouse *mouse*)) + (mouse-get-data mouse) + (set! (-> mouse pos 1 quad) (-> mouse pos 0 quad)) + (set! (-> mouse button0-abs 2) (-> mouse button0-abs 1)) + (set! (-> mouse button0-abs 1) (-> mouse button0-shadow-abs 0)) + (set! (-> mouse button0-rel 2) (-> mouse button0-rel 1)) + (set! (-> mouse button0-rel 1) (-> mouse button0-rel 0)) + (set! (-> mouse button0-rel 0) (mouse-buttons)) + (set! (-> mouse speedx) 0.0) + (set! (-> mouse speedy) 0.0) (cond - ((or (not (-> gp-0 valid)) (not (-> gp-0 active))) - (set! (-> gp-0 valid) #f) - (set! (-> gp-0 status) (the-as uint 0)) - (set! (-> gp-0 pos 0 quad) (the-as uint128 0)) - (set! (-> gp-0 pos 1 quad) (the-as uint128 0)) + ((or (not (-> mouse valid)) (not (-> mouse active))) + (set! (-> mouse valid) #f) + (set! (-> mouse status) (the-as uint 0)) + (set! (-> mouse pos 0 quad) (the-as uint128 0)) + (set! (-> mouse pos 1 quad) (the-as uint128 0)) ) - ((logtest? (-> gp-0 status) 1) - (set! (-> gp-0 change-time) (get-current-time)) - (set! (-> gp-0 speedx) (* (sign (the float (-> gp-0 deltax))) (pow (fabs (the float (-> gp-0 deltax))) 1.3))) - (set! (-> gp-0 speedy) (* (sign (the float (-> gp-0 deltay))) (pow (fabs (the float (-> gp-0 deltay))) 1.3))) - (set! (-> gp-0 posx) (fmax -256.0 (fmin 256.0 (+ (-> gp-0 posx) (-> gp-0 speedx))))) - (set! (-> gp-0 posy) (fmax -208.0 (fmin 208.0 (+ (-> gp-0 posy) (-> gp-0 speedy))))) - (let ((v1-22 (-> gp-0 button0))) - (set! (-> gp-0 button0-shadow-abs 0) (the-as mouse-buttons v1-22)) - (set! (-> gp-0 button0-abs 0) (the-as mouse-buttons v1-22)) + ((logtest? (-> mouse status) 1) + (set! (-> mouse change-time) (get-current-time)) + (set! (-> mouse speedx) + (* (sign (the float (-> mouse deltax))) (pow (fabs (the float (-> mouse deltax))) 1.3)) + ) + (set! (-> mouse speedy) + (* (sign (the float (-> mouse deltay))) (pow (fabs (the float (-> mouse deltay))) 1.3)) + ) + (set! (-> mouse posx) (fmax -256.0 (fmin 256.0 (+ (-> mouse posx) (-> mouse speedx))))) + (set! (-> mouse posy) (fmax -208.0 (fmin 208.0 (+ (-> mouse posy) (-> mouse speedy))))) + (let ((v1-22 (-> mouse button0))) + (set! (-> mouse button0-shadow-abs 0) (the-as mouse-buttons v1-22)) + (set! (-> mouse button0-abs 0) (the-as mouse-buttons v1-22)) ) - (set! (-> gp-0 button0-rel 0) (logclear (-> gp-0 button0-abs 0) (-> gp-0 button0-abs 1))) + (set! (-> mouse button0-rel 0) (logclear (-> mouse button0-abs 0) (-> mouse button0-abs 1))) ) ) - (if (and (-> gp-0 active) (-> gp-0 valid) (-> gp-0 cursor)) + (if (and (-> mouse active) (-> mouse valid) (-> mouse cursor)) (add-debug-cursor #t (bucket-id debug-no-zbuf2) - (+ (the int (-> gp-0 posx)) 256) - (+ (the int (-> gp-0 posy)) 208) - (-> gp-0 button0-abs 0) + (+ (the int (-> mouse posx)) 256) + (+ (the int (-> mouse posy)) 208) + (-> mouse button0-abs 0) ) ) ) diff --git a/test/decompiler/reference/jak2/engine/ps2/rpc-h_REF.gc b/test/decompiler/reference/jak2/engine/ps2/rpc-h_REF.gc index d971599f2a..0a5f0fbea7 100644 --- a/test/decompiler/reference/jak2/engine/ps2/rpc-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/ps2/rpc-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type rpc-buffer (deftype rpc-buffer (basic) + "Buffer for storing input/output data for a remote procedure call to the overlord driver on the IOP." ((elt-size uint32) (elt-count uint32) (elt-used uint32) @@ -48,6 +49,8 @@ ;; definition of type rpc-buffer-pair (deftype rpc-buffer-pair (basic) + "A double buffer of RPC buffers. This is used to let the game queue up data in one buffer while +the other is being read/written by overlord." ((buffer rpc-buffer 2) (current rpc-buffer) (last-recv-buffer pointer) @@ -93,6 +96,7 @@ ;; definition for method 12 of type rpc-buffer-pair (defmethod sync ((this rpc-buffer-pair) (arg0 symbol)) + "Wait for an in-progress rpc to finish." (let ((s5-0 (if (= (-> this current) (-> this buffer 0)) (-> this buffer 1) (-> this buffer 0) @@ -125,6 +129,7 @@ ;; definition for method 13 of type rpc-buffer-pair (defmethod check-busy ((this rpc-buffer-pair)) + "Check to see if an rpc is in progress." (let ((gp-0 (if (= (-> this current) (-> this buffer 0)) (-> this buffer 1) (-> this buffer 0) @@ -145,6 +150,7 @@ ;; definition for method 9 of type rpc-buffer-pair (defmethod call ((this rpc-buffer-pair) (arg0 uint) (arg1 pointer) (arg2 uint)) + "Start an async RPC call. If there is already one in progress, stall and wait for it to finish." (when (nonzero? (-> this current elt-used)) (let ((s2-0 (if (= (-> this current) (-> this buffer 0)) (-> this buffer 1) @@ -191,6 +197,7 @@ ;; definition for method 14 of type rpc-buffer-pair (defmethod pop-last-received ((this rpc-buffer-pair)) + "Pop the response from the most recently completed rpc call." (let ((v0-0 (-> this last-recv-buffer))) (set! (-> this last-recv-buffer) (the-as pointer #f)) v0-0 @@ -199,6 +206,7 @@ ;; definition for method 10 of type rpc-buffer-pair (defmethod add-element ((this rpc-buffer-pair)) + "Add an element. If the buffer is full, flush it!" (let ((v1-0 (-> this current))) (when (= (-> v1-0 elt-used) (-> v1-0 elt-count)) (if (zero? (-> this rpc-port)) @@ -216,6 +224,7 @@ ;; definition for method 11 of type rpc-buffer-pair (defmethod decrement-elt-used ((this rpc-buffer-pair)) + "Remove the most recently queued element." (if (> (-> this current elt-used) 0) (+! (-> this current elt-used) -1) ) diff --git a/test/decompiler/reference/jak2/engine/ps2/timer-h_REF.gc b/test/decompiler/reference/jak2/engine/ps2/timer-h_REF.gc index dbfd4c0308..1f39733623 100644 --- a/test/decompiler/reference/jak2/engine/ps2/timer-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/ps2/timer-h_REF.gc @@ -3,6 +3,8 @@ ;; definition of type timer-mode (deftype timer-mode (uint32) + "This matches the Tn_MODE register structure of the ps2 EE timers. +Only the lower 32 bits of these registers are usable, and the upper 16 hardwired to zero." ((clks timer-clock-selection :offset 0 :size 2) (gate uint8 :offset 2 :size 1) (gats uint8 :offset 3 :size 1) @@ -18,6 +20,9 @@ ;; definition of type timer-bank (deftype timer-bank (structure) + "This matches an EE timer (without a HOLD register, timers 2 and 3). +Each register is 128-bits wide, but only the lower 32-bits are usable, and the upper +16-bits of that are hardwired to zero." ((count uint32) (mode timer-mode :offset 16) (comp uint32 :offset 32) @@ -40,6 +45,7 @@ ;; definition of type timer-hold-bank (deftype timer-hold-bank (timer-bank) + "This matches an EE timer (with a HOLD register, timers 0 and 1)." ((hold uint32 :offset 48) ) ) @@ -61,6 +67,9 @@ ;; definition of type stopwatch (deftype stopwatch (basic) + "Stopwatches are used to measure CPU clock cycles. +They don't use the timer above, but instead the Count COP0 register, +which counts CPU clock cycles directly." ((prev-time-elapsed time-frame) (start-time time-frame) (begin-level int32) @@ -86,6 +95,7 @@ ;; definition for function timer-init (defun timer-init ((arg0 timer-bank) (arg1 timer-mode)) + "Initiate a timer, start counting at a rate of 1 every 256 bus clocks (BUSCLK: ~147.456MHz)." (set! (-> arg0 mode) arg1) (set! (-> arg0 count) (the-as uint 0)) 0 diff --git a/test/decompiler/reference/jak2/engine/ps2/timer_REF.gc b/test/decompiler/reference/jak2/engine/ps2/timer_REF.gc index b2b82b16d8..d2d06d39d2 100644 --- a/test/decompiler/reference/jak2/engine/ps2/timer_REF.gc +++ b/test/decompiler/reference/jak2/engine/ps2/timer_REF.gc @@ -3,6 +3,7 @@ ;; definition for function timer-count (defun timer-count ((arg0 timer-bank)) + "Return a timer's counter value." (.sync.l) (let ((v0-0 (-> arg0 count))) (.sync.l) @@ -14,6 +15,7 @@ ;; WARN: Return type mismatch int vs none. ;; ERROR: Unsupported inline assembly instruction kind - [mfc0 v0, Status] (defun disable-irq () + "Disable all interrupts. Has no effect on PC Port." (local-vars (v0-0 int)) (let ((v1-0 (the-as uint #xfffffffe))) (.mfc0 v0-0 Status) @@ -30,6 +32,7 @@ ;; WARN: Return type mismatch int vs none. ;; ERROR: Unsupported inline assembly instruction kind - [mfc0 v0, Status] (defun enable-irq () + "Enable all interrupts. Has no effect on PC Port." (local-vars (v0-0 int)) (.mfc0 v0-0 Status) (let ((v0-1 (logior v0-0 1))) @@ -42,6 +45,7 @@ ;; definition for function stopwatch-init (defun stopwatch-init ((arg0 stopwatch)) + "Init a stopwatch." (set! (-> arg0 begin-level) 0) (set! (-> arg0 prev-time-elapsed) 0) 0 @@ -50,6 +54,7 @@ ;; definition for function stopwatch-reset ;; ERROR: Unsupported inline assembly instruction kind - [mfc0 v1, Count] (defun stopwatch-reset ((arg0 stopwatch)) + "Restart a stopwatch's times." (local-vars (v1-3 int)) (set! (-> arg0 prev-time-elapsed) 0) (when (> (-> arg0 begin-level) 0) @@ -63,6 +68,7 @@ ;; definition for function stopwatch-start ;; ERROR: Unsupported inline assembly instruction kind - [mfc0 v1, Count] (defun stopwatch-start ((arg0 stopwatch)) + "Start a stopwatch from scratch." (local-vars (v1-4 int)) (when (zero? (-> arg0 begin-level)) (set! (-> arg0 begin-level) 1) @@ -77,6 +83,7 @@ ;; WARN: Return type mismatch int vs none. ;; ERROR: Unsupported inline assembly instruction kind - [mfc0 a1, Count] (defun stopwatch-stop ((arg0 stopwatch)) + "Fully stop a stopwatch and save its elapsed time." (local-vars (a1-0 int)) (when (> (-> arg0 begin-level) 0) (set! (-> arg0 begin-level) 0) @@ -91,6 +98,7 @@ ;; definition for function stopwatch-begin ;; ERROR: Unsupported inline assembly instruction kind - [mfc0 v1, Count] (defun stopwatch-begin ((arg0 stopwatch)) + "Begin a stopwatch level, and starts it if it hasn't yet." (local-vars (v1-3 int)) (when (zero? (-> arg0 begin-level)) 0 @@ -105,6 +113,9 @@ ;; WARN: Return type mismatch int vs none. ;; ERROR: Unsupported inline assembly instruction kind - [mfc0 a1, Count] (defun stopwatch-end ((arg0 stopwatch)) + "End a stopwatch level. Stops the stopwatch if it's back to level zero. +There is no guard against ending a stopwatch too many times, and a negative level +will cause errors!" (local-vars (a1-0 int)) (+! (-> arg0 begin-level) -1) (when (zero? (-> arg0 begin-level)) @@ -119,6 +130,7 @@ ;; definition for function stopwatch-elapsed-ticks ;; ERROR: Unsupported inline assembly instruction kind - [mfc0 v1, Count] (defun stopwatch-elapsed-ticks ((arg0 stopwatch)) + "Returns the elapsed time so far (in clock cycles) of a stopwatch." (local-vars (v1-3 int)) (let ((v0-0 (-> arg0 prev-time-elapsed))) (when (> (-> arg0 begin-level) 0) @@ -132,6 +144,7 @@ ;; definition for function stopwatch-elapsed-seconds (defun stopwatch-elapsed-seconds ((arg0 stopwatch)) + "Returns the elapsed time so far (in seconds) of a stopwatch." (let ((v1-0 (stopwatch-elapsed-ticks arg0))) (* 0.0000000033333334 (the float v1-0)) ) @@ -139,6 +152,7 @@ ;; definition for method 9 of type clock (defmethod update-rates! ((this clock) (arg0 float)) + "Recompute all clock values for the given clock ratio (arg0)." (set! (-> this clock-ratio) arg0) (let ((f0-6 (if (nonzero? *display*) (* (-> *display* time-factor) (-> *display* dog-ratio) arg0) @@ -165,6 +179,8 @@ ;; definition for method 10 of type clock (defmethod advance-by! ((this clock) (arg0 float)) + "Advance the clock by arg0 timeframes (as a float). +Both counters keep a separate fractional and integer counter." (the int (+ arg0 (-> this accum))) (+! (-> this integral-accum) arg0) (set! (-> this old-integral-frame-counter) (-> this integral-frame-counter)) @@ -183,6 +199,7 @@ ;; definition for method 11 of type clock (defmethod tick! ((this clock)) + "Per-game-frame clock tick forward." (if (not (logtest? (-> this mask) (-> *kernel-context* prevent-from-run))) (advance-by! this (* (-> *display* time-factor) (-> *display* dog-ratio) (-> this clock-ratio))) (set! (-> this sparticle-data x) 0.0) @@ -193,6 +210,7 @@ ;; definition for method 14 of type clock ;; WARN: Return type mismatch int vs none. (defmethod reset! ((this clock)) + "Reset a clock to 1000s, rate of 1." (set! (-> this frame-counter) (seconds 1000)) (set! (-> this integral-frame-counter) (the-as uint #x493e0)) (set! (-> this accum) 0.0) @@ -205,6 +223,7 @@ ;; definition for method 12 of type clock (defmethod save! ((this clock) (arg0 (pointer uint64))) + "Save a clock's state to a buffer, return bytes used." (set! (-> arg0 0) (the-as uint (-> this frame-counter))) (set! (-> arg0 1) (-> this integral-frame-counter)) 16 @@ -212,6 +231,7 @@ ;; definition for method 13 of type clock (defmethod load! ((this clock) (arg0 (pointer uint64))) + "Load a clock's state from a buffer, return bytes used." (set! (-> this frame-counter) (the-as time-frame (-> arg0 0))) (set! (-> this integral-frame-counter) (-> arg0 1)) (set! (-> this accum) 0.0) diff --git a/test/decompiler/reference/jak2/engine/scene/scene_REF.gc b/test/decompiler/reference/jak2/engine/scene/scene_REF.gc index 039cf5cc52..1614d9b329 100644 --- a/test/decompiler/reference/jak2/engine/scene/scene_REF.gc +++ b/test/decompiler/reference/jak2/engine/scene/scene_REF.gc @@ -372,6 +372,7 @@ ;; definition for method 10 of type scene-player (defmethod deactivate ((this scene-player)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (set! *scene-player* (the-as (pointer scene-player) #f)) (kill-persister *setting-control* (the-as engine-pers 'blackout) 'bg-a-force) ((method-of-type process-drawable deactivate) this) diff --git a/test/decompiler/reference/jak2/engine/sound/gsound_REF.gc b/test/decompiler/reference/jak2/engine/sound/gsound_REF.gc index 45b5b8cf24..68cd124945 100644 --- a/test/decompiler/reference/jak2/engine/sound/gsound_REF.gc +++ b/test/decompiler/reference/jak2/engine/sound/gsound_REF.gc @@ -28,6 +28,7 @@ ;; definition for method 10 of type engine-sound-pers ;; WARN: Return type mismatch int vs none. (defmethod kill-callback ((this engine-sound-pers) (arg0 connection-pers)) + "Called when a connection is removed." (let ((v1-0 (the-as sound-rpc-set-param (get-sound-buffer-entry)))) (set! (-> v1-0 command) (sound-command set-param)) (set! (-> v1-0 id) (the-as sound-id (-> arg0 param-int64 0))) @@ -63,8 +64,9 @@ (kmemclose) ;; definition for function sound-name= -(defun sound-name= ((arg0 sound-name) (arg1 sound-name)) - (and (= (the-as uint arg0) (the-as uint arg1)) (= (-> arg0 hi) (-> arg1 hi))) +(defun sound-name= ((a sound-name) (b sound-name)) + "Are two sound names the same?" + (and (= (the-as uint a) (the-as uint b)) (= (-> a hi) (-> b hi))) ) ;; definition of type sound-iop-info @@ -145,6 +147,7 @@ ;; definition for function str-is-playing? (defun str-is-playing? () + "Is any streaming audio playing?" (countdown (v1-0 4) (if (and (>= (the-as uint (-> *sound-iop-info* stream-id v1-0)) 0) (logtest? (-> *sound-iop-info* stream-status v1-0) (stream-status ststatus-four)) @@ -157,6 +160,7 @@ ;; definition for function str-id-is-playing? (defun str-id-is-playing? ((arg0 int)) + "Is any streaming audio with the given ID playing?" (countdown (v1-0 4) (if (and (= arg0 (-> *sound-iop-info* stream-id v1-0)) (logtest? (-> *sound-iop-info* stream-status v1-0) (stream-status ststatus-one ststatus-six)) @@ -168,12 +172,13 @@ ) ;; definition for function current-str-pos -(defun current-str-pos ((arg0 sound-id)) +(defun current-str-pos ((id sound-id)) + "Get the current stream position of the given sound ID, or -1 if it is not playing." (if (>= (-> *setting-control* user-current movie-skip-frame) 0.0) (return (the int (* 34.133335 (-> *setting-control* user-current movie-skip-frame)))) ) (dotimes (v1-5 4) - (if (= arg0 (-> *sound-iop-info* stream-id v1-5)) + (if (= id (-> *sound-iop-info* stream-id v1-5)) (return (the-as int (-> *sound-iop-info* stream-position v1-5))) ) ) @@ -181,9 +186,10 @@ ) ;; definition for function is-ramdisk-loaded? -(defun is-ramdisk-loaded? ((arg0 symbol)) +(defun is-ramdisk-loaded? ((name symbol)) + "Check if the ramdisk-name is set to this (unused)." (let ((gp-0 (-> *sound-iop-info* ramdisk-name)) - (s5-0 (symbol->string arg0)) + (s5-0 (symbol->string name)) ) (and (charp-prefix= (-> s5-0 data) gp-0) (= (-> gp-0 (length s5-0)) 46)) ) @@ -191,11 +197,13 @@ ;; definition for function is-cd-in? (defun is-cd-in? () + "Is the CD/DVD in the ps2?" (zero? (-> *sound-iop-info* nocd)) ) ;; definition for function new-sound-id (defun new-sound-id () + "Allocate a new sound ID, used to identify a unique playback of a sound." (set! *current-sound-id* (+ *current-sound-id* 1)) (if (< (the-as int *current-sound-id*) #x10000) (set! *current-sound-id* (the-as sound-id #x10000)) @@ -205,6 +213,7 @@ ;; definition for function check-irx-version (defun check-irx-version () + "Confirm OVERLORD version is correct and set up the sound-iop-info address so the OVERLORD can report back to the EE." (let ((gp-0 (the-as sound-rpc-get-irx-version (add-element *sound-loader-rpc*)))) (set! (-> gp-0 command) (sound-command get-irx-version)) (set! (-> gp-0 ee-addr) (&-> *sound-iop-info* frame)) @@ -223,11 +232,12 @@ ;; definition for function sound-bank-iop-store ;; INFO: Used lq/sq -(defun sound-bank-iop-store ((arg0 sound-name)) +(defun sound-bank-iop-store ((name sound-name)) + "Send a iop-store RPC to loader with the given name" (let ((gp-0 (new-sound-id))) (let ((v1-1 (the-as sound-rpc-bank-cmd (add-element *sound-loader-rpc*)))) (set! (-> v1-1 command) (sound-command iop-store)) - (set! (-> v1-1 bank-name) arg0) + (set! (-> v1-1 bank-name) name) ) (call *sound-loader-rpc* (the-as uint 0) (the-as pointer 0) (the-as uint 0)) gp-0 @@ -236,11 +246,12 @@ ;; definition for function sound-bank-iop-free ;; INFO: Used lq/sq -(defun sound-bank-iop-free ((arg0 sound-name)) +(defun sound-bank-iop-free ((name sound-name)) + "Send a iop-free RPC to loader with the given name" (let ((gp-0 (new-sound-id))) (let ((v1-1 (the-as sound-rpc-bank-cmd (add-element *sound-loader-rpc*)))) (set! (-> v1-1 command) (sound-command iop-free)) - (set! (-> v1-1 bank-name) arg0) + (set! (-> v1-1 bank-name) name) ) (call *sound-loader-rpc* (the-as uint 0) (the-as pointer 0) (the-as uint 0)) gp-0 @@ -250,6 +261,7 @@ ;; definition for function sound-bank-load ;; INFO: Used lq/sq (defun sound-bank-load ((arg0 sound-name)) + "Send RPC to load a sound bank." (let ((gp-0 (new-sound-id))) (let ((v1-1 (the-as sound-rpc-load-bank (add-element *sound-loader-rpc*)))) (set! (-> v1-1 command) (sound-command load-bank)) @@ -262,11 +274,12 @@ ;; definition for function sound-bank-load-from-iop ;; INFO: Used lq/sq -(defun sound-bank-load-from-iop ((arg0 sound-name)) +(defun sound-bank-load-from-iop ((name sound-name)) + "Send load-bank-from-iop rpc to loader" (let ((gp-0 (new-sound-id))) (let ((v1-1 (the-as sound-rpc-load-bank (add-element *sound-loader-rpc*)))) (set! (-> v1-1 command) (sound-command load-bank-from-iop)) - (set! (-> v1-1 bank-name) arg0) + (set! (-> v1-1 bank-name) name) ) (call *sound-loader-rpc* (the-as uint 0) (the-as pointer 0) (the-as uint 0)) gp-0 @@ -275,12 +288,13 @@ ;; definition for function sound-bank-load-from-ee ;; INFO: Used lq/sq -(defun sound-bank-load-from-ee ((arg0 sound-name) (arg1 pointer)) +(defun sound-bank-load-from-ee ((name sound-name) (addr pointer)) + "Send load-bank-from-ee rpc to loader" (let ((gp-0 (new-sound-id))) (let ((v1-1 (the-as sound-rpc-load-bank (add-element *sound-loader-rpc*)))) (set! (-> v1-1 command) (sound-command load-bank-from-ee)) - (set! (-> v1-1 bank-name) arg0) - (set! (-> v1-1 ee-addr) arg1) + (set! (-> v1-1 bank-name) name) + (set! (-> v1-1 ee-addr) addr) ) (call *sound-loader-rpc* (the-as uint 0) (the-as pointer 0) (the-as uint 0)) gp-0 @@ -289,10 +303,11 @@ ;; definition for function sound-bank-unload ;; INFO: Used lq/sq -(defun sound-bank-unload ((arg0 sound-name)) +(defun sound-bank-unload ((name sound-name)) + "Send unload-bank rpc to loader" (let ((v1-1 (the-as sound-rpc-unload-bank (add-element *sound-loader-rpc*)))) (set! (-> v1-1 command) (sound-command unload-bank)) - (set! (-> v1-1 bank-name) arg0) + (set! (-> v1-1 bank-name) name) ) (call *sound-loader-rpc* (the-as uint 0) (the-as pointer 0) (the-as uint 0)) 0 @@ -300,10 +315,11 @@ ;; definition for function sound-music-load ;; INFO: Used lq/sq -(defun sound-music-load ((arg0 sound-name)) +(defun sound-music-load ((name sound-name)) + "Send load-music rpc to loader" (let ((v1-1 (the-as sound-rpc-load-music (add-element *sound-loader-rpc*)))) (set! (-> v1-1 command) (sound-command load-music)) - (set! (-> v1-1 bank-name) arg0) + (set! (-> v1-1 bank-name) name) ) (call *sound-loader-rpc* (the-as uint 0) (the-as pointer 0) (the-as uint 0)) 0 @@ -311,6 +327,7 @@ ;; definition for function sound-music-unload (defun sound-music-unload () + "Send unload-music rpc to loader." (let ((v1-1 (the-as sound-rpc-unload-music (add-element *sound-loader-rpc*)))) (set! (-> v1-1 command) (sound-command unload-music)) ) @@ -320,6 +337,7 @@ ;; definition for function set-language (defun set-language ((arg0 language-enum)) + "Send set-language rpc to loader. Note this is only for sound, no game text is changed." (kset-language arg0) (let ((v1-1 (the-as sound-rpc-set-language (add-element *sound-loader-rpc*)))) (set! (-> v1-1 command) (sound-command set-language)) @@ -332,6 +350,7 @@ ;; definition for function sound-set-stereo-mode ;; WARN: Return type mismatch int vs none. (defun sound-set-stereo-mode ((arg0 stereo-mode)) + "Send set-stereo-mode rpc to loader." (let ((v1-1 (the-as sound-rpc-set-stereo-mode (add-element *sound-loader-rpc*)))) (set! (-> v1-1 command) (sound-command set-stereo-mode)) (set! (-> v1-1 mode) (the-as int arg0)) @@ -344,6 +363,7 @@ ;; definition for function list-sounds ;; WARN: Return type mismatch int vs none. (defun list-sounds () + "Send list-sounds rpc to loader." (let ((v1-1 (the-as sound-rpc-list-sounds (add-element *sound-loader-rpc*)))) (set! (-> v1-1 command) (sound-command list-sounds)) ) @@ -354,8 +374,9 @@ ) ;; definition for function sound-command->string -(defun sound-command->string ((arg0 sound-command)) - (case arg0 +(defun sound-command->string ((cmd sound-command)) + "Convert sound-command enum to string." + (case cmd (((sound-command num-sectors)) "num-sectors" ) @@ -517,6 +538,7 @@ ;; definition for function sound-buffer-dump (defun sound-buffer-dump () + "Print out all sound-commands in the buffer." (let ((gp-0 (-> *sound-player-rpc* current elt-used)) (s5-0 (-> *sound-player-rpc* current elt-size)) ) @@ -543,6 +565,7 @@ ;; definition for function swap-sound-buffers (defun swap-sound-buffers ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 float)) + "Per-frame update of sound system - update loop-engine, update ear trans, send player RPC, check for missing/dirty CD." (run-pending-updates! *sound-loop-engine* (-> *display* base-clock frame-counter)) (cond ((check-busy *sound-player-rpc*) @@ -577,12 +600,14 @@ ;; definition for function get-sound-buffer-entry (defun get-sound-buffer-entry () + "Allocate a new entry in the player RPC queue, to be flushed on the next frame." (add-element *sound-player-rpc*) ) ;; definition for function free-last-sound-buffer-entry ;; WARN: Return type mismatch int vs none. (defun free-last-sound-buffer-entry () + "Remove the last thing added with get-sound-buffer-entry." (decrement-elt-used *sound-player-rpc*) 0 (none) @@ -591,6 +616,7 @@ ;; definition for function sound-basic-cb ;; WARN: Return type mismatch int vs none. (defun sound-basic-cb ((arg0 int) (arg1 (pointer int32))) + "Unknown and unused callback." (set! (-> arg1 0) arg0) 0 (none) @@ -598,6 +624,7 @@ ;; definition for function sound-trans-convert (defun sound-trans-convert ((arg0 vector3w) (arg1 vector)) + "Convert a GOAL translation (meters) to integer format for the IOP" (let ((v1-0 (if arg1 arg1 (ear-trans 0) @@ -612,8 +639,9 @@ ) ;; definition for function sound-angle-convert -(defun sound-angle-convert ((arg0 float)) - (let* ((f0-3 (the float (sar (shl (the int arg0) 48) 48))) +(defun sound-angle-convert ((float-angle float)) + "Convert a GOAL angle to integer format for the iop" + (let* ((f0-3 (the float (sar (shl (the int float-angle) 48) 48))) (v0-0 (the int (* 0.005493164 f0-3))) ) (if (< v0-0 0) @@ -630,6 +658,7 @@ ;; INFO: Used lq/sq ;; WARN: Return type mismatch uint128 vs sound-name. (defun string->sound-name ((arg0 string)) + "Create a sound-name from a string" (let ((v1-0 (new 'stack-no-clear 'qword))) (set! (-> v1-0 quad) (the-as uint128 0)) (let ((a1-0 (the-as (pointer uint8) v1-0)) @@ -647,6 +676,7 @@ ;; definition for function sound-set-volume (defun sound-set-volume ((arg0 sound-group) (arg1 float)) + "Send set-master-volume rpc." (let ((v1-0 (the-as sound-rpc-set-master-volume (get-sound-buffer-entry)))) (set! (-> v1-0 command) (sound-command set-master-volume)) (set! (-> v1-0 group) arg0) @@ -656,19 +686,21 @@ ) ;; definition for function sound-set-reverb -(defun sound-set-reverb ((arg0 int) (arg1 float) (arg2 float) (arg3 uint)) +(defun sound-set-reverb ((reverb int) (left float) (right float) (core uint)) + "Send set-reverb rpc" (let ((v1-0 (the-as sound-rpc-set-reverb (get-sound-buffer-entry)))) (set! (-> v1-0 command) (sound-command set-reverb)) - (set! (-> v1-0 core) arg3) - (set! (-> v1-0 reverb) arg0) - (set! (-> v1-0 left) (the-as uint (the int (* 32767.0 arg1)))) - (set! (-> v1-0 right) (the-as uint (the int (* 32767.0 arg2)))) + (set! (-> v1-0 core) core) + (set! (-> v1-0 reverb) reverb) + (set! (-> v1-0 left) (the-as uint (the int (* 32767.0 left)))) + (set! (-> v1-0 right) (the-as uint (the int (* 32767.0 right)))) ) 0 ) ;; definition for function sound-set-ear-trans (defun sound-set-ear-trans ((arg0 vector) (arg1 vector) (arg2 vector) (arg3 float)) + "Send set-ear-trans rpc" (let ((gp-0 (the-as sound-rpc-set-ear-trans (get-sound-buffer-entry)))) (set! (-> gp-0 command) (sound-command set-ear-trans)) (sound-trans-convert (the-as vector3w (-> gp-0 ear-trans0)) arg0) @@ -682,7 +714,8 @@ ;; definition for function sound-play-by-name ;; INFO: Used lq/sq (defbehavior sound-play-by-name process-drawable ((arg0 sound-name) (arg1 sound-id) (arg2 int) (arg3 int) (arg4 int) (arg5 sound-group) (arg6 object)) - "Last arg can by a symbol with value [[#t]], in which case it will pull `trans` [[vector]] off the current [[process-drawable]] + "Send play rpc to play a sound! +Last arg can by a symbol with value [[#t]], in which case it will pull `trans` [[vector]] off the current [[process-drawable]] otherwise, an explicit [[vector]] can be provided" (local-vars (sv-16 sound-group)) (set! sv-16 arg5) @@ -715,6 +748,7 @@ otherwise, an explicit [[vector]] can be provided" ;; definition for function sound-play-by-spec ;; INFO: Used lq/sq (defbehavior sound-play-by-spec process-drawable ((arg0 sound-spec) (arg1 sound-id) (arg2 vector)) + "Send play rpc to play a sound!" (when *sound-player-enable* (let ((s5-0 (the-as sound-rpc-play (get-sound-buffer-entry)))) (set! (-> s5-0 command) (sound-command play)) @@ -744,33 +778,36 @@ otherwise, an explicit [[vector]] can be provided" ) ;; definition for function sound-pause -(defun sound-pause ((arg0 sound-id)) - (when (nonzero? arg0) +(defun sound-pause ((id sound-id)) + "Send pause-sound rpc to pause by id" + (when (nonzero? id) (let ((v1-1 (the-as sound-rpc-pause-sound (get-sound-buffer-entry)))) (set! (-> v1-1 command) (sound-command pause-sound)) - (set! (-> v1-1 id) arg0) + (set! (-> v1-1 id) id) ) ) 0 ) ;; definition for function sound-stop -(defun sound-stop ((arg0 sound-id)) - (when (nonzero? arg0) +(defun sound-stop ((id sound-id)) + "Send stop-sound rpc to stop by id" + (when (nonzero? id) (let ((v1-1 (the-as sound-rpc-stop-sound (get-sound-buffer-entry)))) (set! (-> v1-1 command) (sound-command stop-sound)) - (set! (-> v1-1 id) arg0) + (set! (-> v1-1 id) id) ) ) 0 ) ;; definition for function sound-continue -(defun sound-continue ((arg0 sound-id)) - (when (nonzero? arg0) +(defun sound-continue ((id sound-id)) + "Send continue-sound rpc to continue by id" + (when (nonzero? id) (let ((v1-1 (the-as sound-rpc-continue-sound (get-sound-buffer-entry)))) (set! (-> v1-1 command) (sound-command continue-sound)) - (set! (-> v1-1 id) arg0) + (set! (-> v1-1 id) id) ) ) 0 @@ -778,6 +815,7 @@ otherwise, an explicit [[vector]] can be provided" ;; definition for function sound-group-pause (defun sound-group-pause ((arg0 sound-group)) + "Send pause-group rpc" (let ((v1-0 (the-as sound-rpc-pause-group (get-sound-buffer-entry)))) (set! (-> v1-0 command) (sound-command pause-group)) (set! (-> v1-0 group) arg0) @@ -787,6 +825,7 @@ otherwise, an explicit [[vector]] can be provided" ;; definition for function sound-group-stop (defun sound-group-stop ((arg0 sound-group)) + "Send stop-group rpc" (let ((v1-0 (the-as sound-rpc-stop-group (get-sound-buffer-entry)))) (set! (-> v1-0 command) (sound-command stop-group)) (set! (-> v1-0 group) arg0) @@ -796,6 +835,7 @@ otherwise, an explicit [[vector]] can be provided" ;; definition for function sound-group-continue (defun sound-group-continue ((arg0 sound-group)) + "Send continue-group rpc" (let ((v1-0 (the-as sound-rpc-continue-group (get-sound-buffer-entry)))) (set! (-> v1-0 command) (sound-command continue-group)) (set! (-> v1-0 group) arg0) @@ -804,36 +844,40 @@ otherwise, an explicit [[vector]] can be provided" ) ;; definition for function sound-set-flava -(defun sound-set-flava ((arg0 uint) (arg1 uint)) +(defun sound-set-flava ((flava uint) (excitement uint)) + "Send set-flava rpc" (let ((v1-0 (the-as sound-rpc-set-flava (get-sound-buffer-entry)))) (set! (-> v1-0 command) (sound-command set-flava)) - (set! (-> v1-0 flava) arg0) - (set! (-> v1-0 excitement) arg1) + (set! (-> v1-0 flava) flava) + (set! (-> v1-0 excitement) excitement) ) 0 ) ;; definition for function sound-set-midi-reg -(defun sound-set-midi-reg ((arg0 int) (arg1 int)) +(defun sound-set-midi-reg ((reg int) (val int)) + "Send set-midi-reg rpc" (let ((v1-0 (the-as sound-rpc-set-midi-reg (get-sound-buffer-entry)))) (set! (-> v1-0 command) (sound-command set-midi-reg)) - (set! (-> v1-0 reg) arg0) - (set! (-> v1-0 value) arg1) + (set! (-> v1-0 reg) reg) + (set! (-> v1-0 value) val) ) 0 ) ;; definition for function sound-set-fps -(defun sound-set-fps ((arg0 int)) +(defun sound-set-fps ((fps int)) + "Send set-fps rpc" (let ((v1-0 (the-as sound-rpc-set-fps (get-sound-buffer-entry)))) (set! (-> v1-0 command) (sound-command set-fps)) - (set! (-> v1-0 fps) (the-as uint arg0)) + (set! (-> v1-0 fps) (the-as uint fps)) ) 0 ) ;; definition for function sound-volume-off (defun sound-volume-off () + "Adjust settings to turn all sound volume off" (set-setting! 'music-volume 'abs 0.0 0) (set-setting! 'sfx-volume 'abs 0.0 0) (set-setting! 'ambient-volume 'abs 0.0 0) @@ -847,6 +891,7 @@ otherwise, an explicit [[vector]] can be provided" ;; INFO: Used lq/sq ;; WARN: Return type mismatch object vs ambient-sound. (defmethod new ambient-sound ((allocation symbol) (type-to-make type) (arg0 basic) (arg1 vector)) + "Set up ambient-sound. Can use an entity-actor (grabs from lump), sound-spec, or name as a string." (local-vars (sv-16 sound-spec) (sv-32 sound-name) @@ -954,6 +999,7 @@ otherwise, an explicit [[vector]] can be provided" ;; definition for method 9 of type ambient-sound ;; INFO: Used lq/sq (defmethod update! ((this ambient-sound)) + "Per-frame update of ambient sound." (with-pp (if (not *ambient-sound-class*) (return (the-as int #f)) @@ -1050,6 +1096,7 @@ otherwise, an explicit [[vector]] can be provided" ;; definition for method 11 of type ambient-sound ;; INFO: Used lq/sq (defmethod update-trans! ((this ambient-sound) (arg0 vector)) + "Change the trans of the sound." (with-pp (set! (-> this trans quad) (-> arg0 quad)) (when (nonzero? (-> this playing-id)) @@ -1077,6 +1124,7 @@ otherwise, an explicit [[vector]] can be provided" ;; definition for method 12 of type ambient-sound (defmethod update-vol! ((this ambient-sound) (arg0 float)) + "Change the volume of the sound." (when (nonzero? (-> this playing-id)) (when *sound-player-enable* (let ((v1-4 (the-as sound-rpc-set-param (get-sound-buffer-entry)))) @@ -1121,17 +1169,19 @@ otherwise, an explicit [[vector]] can be provided" ;; definition for method 10 of type ambient-sound ;; INFO: Used lq/sq -(defmethod change-sound! ((this ambient-sound) (arg0 sound-name)) - (when (not (and (= (the-as uint (-> this name)) (the-as uint arg0)) (= (-> arg0 hi) (-> this name hi)))) +(defmethod change-sound! ((this ambient-sound) (new-sound sound-name)) + "Change the sound being played." + (when (not (and (= (the-as uint (-> this name)) (the-as uint new-sound)) (= (-> new-sound hi) (-> this name hi)))) (stop! this) (set! (-> this playing-id) (new-sound-id)) - (set! (-> this name) arg0) + (set! (-> this name) new-sound) ) 0 ) ;; definition for function show-iop-info (defun show-iop-info ((arg0 dma-buffer)) + "Display iop info on screen." (dotimes (s5-0 24) (draw-string-xy (if (zero? (-> *sound-iop-info* chinfo s5-0)) @@ -1185,7 +1235,8 @@ otherwise, an explicit [[vector]] can be provided" ) ;; definition for function show-iop-memory -(defun show-iop-memory ((arg0 dma-buffer)) +(defun show-iop-memory ((dma dma-buffer)) + "Display iop memory stats on screen" (let ((s5-0 draw-string-xy)) (format (clear *temp-string*) @@ -1193,7 +1244,7 @@ otherwise, an explicit [[vector]] can be provided" (-> *sound-iop-info* freemem) (shr (-> *sound-iop-info* freemem) 10) ) - (s5-0 *temp-string* arg0 32 96 (font-color default) (font-flags shadow)) + (s5-0 *temp-string* dma 32 96 (font-color default) (font-flags shadow)) ) (let ((s5-1 draw-string-xy)) (format @@ -1202,13 +1253,14 @@ otherwise, an explicit [[vector]] can be provided" (-> *sound-iop-info* freemem2) (shr (-> *sound-iop-info* freemem2) 10) ) - (s5-1 *temp-string* arg0 32 64 (font-color default) (font-flags shadow)) + (s5-1 *temp-string* dma 32 64 (font-color default) (font-flags shadow)) ) 0 ) ;; definition for function ear-trans (defun ear-trans ((arg0 int)) + "Get the current location of the ear. Use 1 for the settings ear-handle, or 0 for the camera." (cond ((or (movie?) *external-cam-mode*) (math-camera-pos) @@ -1224,6 +1276,7 @@ otherwise, an explicit [[vector]] can be provided" ;; definition (debug) for function make-sqrt-table (defun-debug make-sqrt-table () + "Generate integer square-root table used in the IOP." (format #t "static int sqrt_table[256] =~%{~%") (dotimes (gp-0 256) (let* ((f0-2 (sqrtf (* 16777216.0 (the float gp-0)))) @@ -1262,11 +1315,12 @@ otherwise, an explicit [[vector]] can be provided" ;; definition for function loader-test-command ;; WARN: Return type mismatch int vs none. -(defun loader-test-command ((arg0 sound-command) (arg1 uint)) +(defun loader-test-command ((cmd sound-command) (param uint)) + "Send a command to loader by ID." (let ((v1-1 (the-as sound-rpc-test-cmd (add-element *sound-loader-rpc*)))) - (set! (-> v1-1 command) arg0) + (set! (-> v1-1 command) cmd) (set! (-> v1-1 ee-addr) (the-as pointer 0)) - (set! (-> v1-1 param0) arg1) + (set! (-> v1-1 param0) param) ) (call *sound-loader-rpc* (the-as uint 0) (the-as pointer 0) (the-as uint 0)) (sync *sound-loader-rpc* #f) @@ -1276,12 +1330,13 @@ otherwise, an explicit [[vector]] can be provided" ;; definition for function doppler-pitch-shift ;; INFO: Used lq/sq -(defun doppler-pitch-shift ((arg0 vector) (arg1 vector)) +(defun doppler-pitch-shift ((sound-pos vector) (sound-vel vector)) + "Compute pitch shift for the doppler effect. This is done assuming the listener is *target* and has *target*'s velocity." (let ((gp-0 (new 'stack-no-clear 'inline-array 'vector 2))) - (vector-! (-> gp-0 0) (target-pos 0) arg0) + (vector-! (-> gp-0 0) (target-pos 0) sound-pos) (if *target* - (vector-! (-> gp-0 1) arg1 (-> *target* control transv)) - (set! (-> gp-0 1 quad) (-> arg1 quad)) + (vector-! (-> gp-0 1) sound-vel (-> *target* control transv)) + (set! (-> gp-0 1 quad) (-> sound-vel quad)) ) (vector-normalize! (-> gp-0 0) 1.0) (let ((f0-1 (/ 1228800.0 (fmax 0.1 (- 1228800.0 (vector-dot (-> gp-0 0) (-> gp-0 1))))))) @@ -1293,6 +1348,7 @@ otherwise, an explicit [[vector]] can be provided" ;; definition for function sound-bank-reload ;; WARN: Return type mismatch int vs none. (defun sound-bank-reload () + "Start a background process to unload all sound banks, then load them again." (process-spawn-function process (lambda () diff --git a/test/decompiler/reference/jak2/engine/spatial-hash/collide-hash-h_REF.gc b/test/decompiler/reference/jak2/engine/spatial-hash/collide-hash-h_REF.gc index 807b7c9163..89ef7c4622 100644 --- a/test/decompiler/reference/jak2/engine/spatial-hash/collide-hash-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/spatial-hash/collide-hash-h_REF.gc @@ -18,6 +18,7 @@ ;; definition of type collide-hash-scratch (deftype collide-hash-scratch (structure) + "Scratchpad memory layout for collide-hash. Bitmask of things that have already been checked" ((collidable-bits uint128 128) (poly-bits uint64 2 :overlay-at (-> collidable-bits 0)) (id-bits uint32 512 :overlay-at (-> collidable-bits 0)) @@ -42,6 +43,9 @@ ;; definition of type collide-hash-bucket (deftype collide-hash-bucket (structure) + "A bucket is a reference to a list of items that intersect a grid cell. +For the broadphase, the items are collide-hash-item (wrapper of collide-hash-fragment). +For the narrowphase, the items are entries in the index list, which contains poly indices." ((index int16) (count int16) ) @@ -62,6 +66,8 @@ ;; definition of type collide-hash-item (deftype collide-hash-item (structure) + "Items that are 'hashed' in the broadphase. Contains unique ID for checking against already-visited-bitmask +and a pointer to the actual collide-hash-fragment, or possibly a TIE." ((id uint32) (collidable basic) ) @@ -83,6 +89,7 @@ ;; definition of type collide-hash-poly (deftype collide-hash-poly (structure) + "A polygon in the narrow-phase data. This is just indices into the vertex and PAT tables." ((data uint8 4) (vert-index0 uint8 :overlay-at (-> data 0)) (vert-index1 uint8 :overlay-at (-> data 1)) @@ -134,6 +141,8 @@ ;; definition of type collide-hash-fragment (deftype collide-hash-fragment (drawable) + "A mesh fragment for the Jak2/Jak3 collision system. This is a 'hash' of triangles into a grid +where the 'hash' function is just identity." ((num-buckets uint16 :overlay-at id) (num-indices uint16 :offset 6) (pat-array uint32 :offset 8) @@ -186,6 +195,8 @@ ;; definition of type collide-hash-fragment-array (deftype collide-hash-fragment-array (array) + "A collection of collide-hash-fragments. These are used by the instanced collision if a single instance +needs more than 1 collide-hash-fragment worth of triangles." ((fragments collide-hash-fragment :dynamic :offset 16) ) ) diff --git a/test/decompiler/reference/jak2/engine/spatial-hash/spatial-hash-h_REF.gc b/test/decompiler/reference/jak2/engine/spatial-hash/spatial-hash-h_REF.gc index 967e09fa6e..cb446e1d0b 100644 --- a/test/decompiler/reference/jak2/engine/spatial-hash/spatial-hash-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/spatial-hash/spatial-hash-h_REF.gc @@ -8,6 +8,7 @@ ;; definition of type grid-hash-box (deftype grid-hash-box (structure) + "Integer coordinate box for the spatial hash grid." ((min int8 3) (max int8 3) ) @@ -29,6 +30,9 @@ ;; definition of type grid-hash (deftype grid-hash (basic) + "The grid-hash is the basic 3D grid used in the spatial-hash, which is used for runtime +actor collision dectection by hashing actor spheres into grid cells, and avoiding the typical +O(n^2) 'check everybody against everybody' collision loop." ((work grid-hash-work) (search-box grid-hash-box :inline) (bucket-size int16) @@ -126,6 +130,7 @@ ;; definition of type sphere-hash (deftype sphere-hash (grid-hash) + "An extension of grid hash that holds spheres inside of the grid." ((sphere-array (inline-array sphere)) (max-object-count int16) (pad int16) @@ -199,6 +204,7 @@ ;; definition of type spatial-hash (deftype spatial-hash (sphere-hash) + "An extension of sphere-hash that associates an object with each sphere." ((object-array (inline-array hash-object-info)) (mem-object-array (inline-array hash-object-info)) (spr-object-array (inline-array hash-object-info)) diff --git a/test/decompiler/reference/jak2/engine/target/logic-target_REF.gc b/test/decompiler/reference/jak2/engine/target/logic-target_REF.gc index 11c81a4f8c..c44ee51d70 100644 --- a/test/decompiler/reference/jak2/engine/target/logic-target_REF.gc +++ b/test/decompiler/reference/jak2/engine/target/logic-target_REF.gc @@ -3360,6 +3360,7 @@ ;; definition for method 10 of type target (defmethod deactivate ((this target)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (kill-persister *setting-control* (the-as engine-pers 'bg-a-speed) 'bg-a-speed) (if (nonzero? (-> this darkjak)) (sound-stop (-> this darkjak tone)) diff --git a/test/decompiler/reference/jak2/engine/target/surface-h_REF.gc b/test/decompiler/reference/jak2/engine/target/surface-h_REF.gc index bfedc93a07..5076adc16f 100644 --- a/test/decompiler/reference/jak2/engine/target/surface-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/target/surface-h_REF.gc @@ -3,6 +3,9 @@ ;; definition of type surface (deftype surface (basic) + "Definition of a bunch of parameters for different types of surfaces. +Parameters include values such as max speed, friction, callback functions that run +on impact, during touch, on exit, etc." ((name symbol) (turnv float) (turnvv float) diff --git a/test/decompiler/reference/jak2/engine/target/target-turret_REF.gc b/test/decompiler/reference/jak2/engine/target/target-turret_REF.gc index 15bfb7a112..24ee9924ce 100644 --- a/test/decompiler/reference/jak2/engine/target/target-turret_REF.gc +++ b/test/decompiler/reference/jak2/engine/target/target-turret_REF.gc @@ -2212,6 +2212,7 @@ ;; definition for method 10 of type base-turret (defmethod deactivate ((this base-turret)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (valid? (-> this hud) (the-as type #f) "" #t 0) (send-event (handle->process (-> this hud)) 'hide-and-die) ) diff --git a/test/decompiler/reference/jak2/engine/ui/minimap_REF.gc b/test/decompiler/reference/jak2/engine/ui/minimap_REF.gc index da9aabcc73..2fb4a050f2 100644 --- a/test/decompiler/reference/jak2/engine/ui/minimap_REF.gc +++ b/test/decompiler/reference/jak2/engine/ui/minimap_REF.gc @@ -1176,6 +1176,10 @@ ;; definition for method 14 of type engine-minimap ;; WARN: Return type mismatch int vs none. (defmethod run-pending-updates! ((this engine-minimap) (arg0 time-frame)) + "Run updates if they scheduled. If something is found that has no pending update, kill it. +Note that we won't kill things on this call if they fail to update their `update-time`. +They will survive until the next call to `run-pending-updates`! +(or you can modify their `update-time` before that to prevent them from being killed.)" (let ((s2-0 (the-as (pointer connection-pers) (&-> this alive-list))) (s3-0 (-> this alive-list)) ) @@ -1287,6 +1291,7 @@ ;; definition for method 10 of type engine-minimap ;; WARN: Function (method 10 engine-minimap) has a return type of none, but the expression builder found a return statement. (defmethod kill-callback ((this engine-minimap) (arg0 connection-pers)) + "Called when a connection is removed." (if (not arg0) (return #f) ) diff --git a/test/decompiler/reference/jak2/engine/ui/progress/progress_REF.gc b/test/decompiler/reference/jak2/engine/ui/progress/progress_REF.gc index d770f2fe92..d7d0776160 100644 --- a/test/decompiler/reference/jak2/engine/ui/progress/progress_REF.gc +++ b/test/decompiler/reference/jak2/engine/ui/progress/progress_REF.gc @@ -536,6 +536,7 @@ ;; definition for method 10 of type progress (defmethod deactivate ((this progress)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (remove-setting-by-arg0 *setting-control* 'extra-bank) (disable-drawing *bigmap*) (set! (-> *blit-displays-work* menu-mode) #f) diff --git a/test/decompiler/reference/jak2/engine/util/profile-h_REF.gc b/test/decompiler/reference/jak2/engine/util/profile-h_REF.gc index 72973f0b1f..fc6c08a8d0 100644 --- a/test/decompiler/reference/jak2/engine/util/profile-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/util/profile-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type profile-segment (deftype profile-segment (structure) + "Confusingly, this has two uses. Either a single event, or a summary of all events within a category." ((name symbol) (start-time int16) (end-time int16) @@ -38,6 +39,7 @@ ;; definition of type profile-collapse (deftype profile-collapse (structure) + "An array of 'summaries'. Each entry in data is a summary of all events within a category." ((count int32) (data profile-segment 48 :inline) ) @@ -58,6 +60,7 @@ ;; definition of type profile-segment-array (deftype profile-segment-array (basic) + "All profiling data for a frame, stored as a tree of events. There is one for the VU, and one for the EE." ((count int16) (depth int8) (max-depth int8) @@ -92,10 +95,11 @@ ;; definition of type profile-array (deftype profile-array (structure) + "The EE and VU profilers, and the drawing code." ((data profile-segment-array 2) ) (:methods - (setup-categories! (_type_) none) + (postprocess-data! (_type_) none) (draw-bars! (_type_ dma-buffer int) none) (draw-text! (_type_) none) ) @@ -115,6 +119,7 @@ ;; definition for method 9 of type profile-segment-array (defmethod get-total-time ((this profile-segment-array)) + "Get the duration of the top-level event (typically, the whole frame)" (- (-> this data 0 end-time) (-> this data 0 start-time)) ) diff --git a/test/decompiler/reference/jak2/engine/util/profile_REF.gc b/test/decompiler/reference/jak2/engine/util/profile_REF.gc index a777f3c398..6e46d8d660 100644 --- a/test/decompiler/reference/jak2/engine/util/profile_REF.gc +++ b/test/decompiler/reference/jak2/engine/util/profile_REF.gc @@ -3,6 +3,7 @@ ;; definition of type profile-work (deftype profile-work (structure) + "DMA templates for profile drawing." ((sprite-tmpl dma-gif-packet :inline) (line-tmpl dma-gif-packet :inline) (last-index int32) @@ -75,6 +76,7 @@ ;; definition for method 10 of type profile-segment-array ;; WARN: Return type mismatch int vs none. (defmethod start-frame! ((this profile-segment-array)) + "Restart the profiler for the start of a frame." (set! (-> this count) 0) (set! (-> this depth) 0) (set! (-> this max-depth) 0) @@ -87,6 +89,7 @@ ;; definition for method 11 of type profile-segment-array ;; WARN: Return type mismatch int vs none. (defmethod start-segment! ((this profile-segment-array) (arg0 symbol) (arg1 rgba)) + "Start an event." (when (and *dproc* *debug-segment*) (let ((s4-0 (-> this data (-> this count)))) (let ((s3-0 (-> this base-time))) @@ -108,6 +111,7 @@ ;; definition for method 12 of type profile-segment-array ;; WARN: Return type mismatch int vs none. (defmethod end-segment! ((this profile-segment-array)) + "Stop the most recently started event." (when (and *dproc* *debug-segment*) (let* ((v1-4 (+ (-> this depth) -1)) (s5-0 (-> this segment v1-4)) @@ -399,7 +403,8 @@ ;; definition for method 9 of type profile-array ;; WARN: Return type mismatch int vs none. -(defmethod setup-categories! ((this profile-array)) +(defmethod postprocess-data! ((this profile-array)) + "Create the collapsed summary of the collected data." (dotimes (s5-0 2) (let ((s3-0 (-> *profile-array* data s5-0)) (s4-0 *profile-collapse*) @@ -559,6 +564,7 @@ ;; INFO: Used lq/sq ;; WARN: Return type mismatch int vs none. (defmethod draw-bars! ((this profile-array) (arg0 dma-buffer) (arg1 int)) + "Generate DMA data for drawing the profile bars." (local-vars (sv-16 (function _varargs_ object)) (sv-32 (function _varargs_ object))) (dma-buffer-add-gs-set arg0 (alpha-1 (new 'static 'gs-alpha :b #x1 :d #x1)) @@ -737,6 +743,7 @@ ;; definition for method 11 of type profile-array ;; WARN: Return type mismatch int vs none. (defmethod draw-text! ((this profile-array)) + "Generate DMA data for drawing the profile information screen." (let ((gp-0 *profile-collapse*)) (dotimes (s5-0 (-> gp-0 count)) (when (or (nonzero? (-> gp-0 data s5-0 count)) (nonzero? (-> gp-0 data s5-0 vu-count))) diff --git a/test/decompiler/reference/jak2/engine/util/smush-control-h_REF.gc b/test/decompiler/reference/jak2/engine/util/smush-control-h_REF.gc index 661de6399e..9db8845c5e 100644 --- a/test/decompiler/reference/jak2/engine/util/smush-control-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/util/smush-control-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type smush-control (deftype smush-control (structure) + "This holds information about the current state of an object's smush." ((start-time time-frame) (period float) (duration float) @@ -60,23 +61,23 @@ (defmethod update! ((this smush-control)) (cond ((!= (-> this amp) 0.0) - (let* ((f30-0 (the float (- (current-time) (-> this start-time)))) - (f0-2 (-> this period)) - (f28-0 (- f30-0 (* (the float (the int (/ f30-0 f0-2))) f0-2))) + (let* ((elapsed-time (the float (- (current-time) (-> this start-time)))) + (period (-> this period)) + (f28-0 (- elapsed-time (* (the float (the int (/ elapsed-time period))) period))) ) - (when (>= (- f30-0 (-> this ticks)) (-> this period)) + (when (>= (- elapsed-time (-> this ticks)) (-> this period)) (set! (-> this amp) (* (-> this amp) (-> this damp-amp))) (set! (-> this period) (* (-> this period) (-> this damp-period))) - (set! (-> this ticks) f30-0) + (set! (-> this ticks) elapsed-time) (if (< (-> this damp-period) 0.0) (set-zero! this) ) ) - (if (>= f30-0 (-> this duration)) + (if (>= elapsed-time (-> this duration)) (set-zero! this) ) (* (sin (/ (* 65536.0 f28-0) (-> this period))) - (* (-> this amp) (/ (- (-> this duration) f30-0) (-> this duration))) + (* (-> this amp) (/ (- (-> this duration) elapsed-time) (-> this duration))) ) ) ) @@ -90,12 +91,12 @@ (defmethod get-no-update ((this smush-control)) (cond ((!= (-> this amp) 0.0) - (let* ((f30-0 (the float (- (current-time) (-> this start-time)))) - (f0-2 (-> this period)) - (f0-4 (- f30-0 (* (the float (the int (/ f30-0 f0-2))) f0-2))) + (let* ((elapsed-time (the float (- (current-time) (-> this start-time)))) + (period (-> this period)) + (f0-4 (- elapsed-time (* (the float (the int (/ elapsed-time period))) period))) ) (* (sin (/ (* 65536.0 f0-4) (-> this period))) - (* (-> this amp) (/ (- (-> this duration) f30-0) (-> this duration))) + (* (-> this amp) (/ (- (-> this duration) elapsed-time) (-> this duration))) ) ) ) @@ -114,15 +115,22 @@ ) ;; definition for method 12 of type smush-control -(defmethod activate! ((this smush-control) (arg0 float) (arg1 int) (arg2 int) (arg3 float) (arg4 float) (arg5 clock)) +(defmethod activate! ((this smush-control) + (amplitude float) + (period int) + (duration int) + (damp-amplitude float) + (damp-period float) + (clock clock) + ) (when (>= (fabs (* 0.2 (-> this amp))) (fabs (get-no-update this))) - (set! (-> this amp) arg0) - (set! (-> this period) (the float arg1)) - (set! (-> this duration) (the float arg2)) - (set! (-> this damp-amp) arg3) - (set! (-> this damp-period) arg4) + (set! (-> this amp) amplitude) + (set! (-> this period) (the float period)) + (set! (-> this duration) (the float duration)) + (set! (-> this damp-amp) damp-amplitude) + (set! (-> this damp-period) damp-period) (set! (-> this ticks) 0.0) - (set! (-> this start-time) (-> arg5 frame-counter)) + (set! (-> this start-time) (-> clock frame-counter)) ) this ) diff --git a/test/decompiler/reference/jak2/engine/util/sync-info-h_REF.gc b/test/decompiler/reference/jak2/engine/util/sync-info-h_REF.gc index cfa5db033a..ffc06c5c3c 100644 --- a/test/decompiler/reference/jak2/engine/util/sync-info-h_REF.gc +++ b/test/decompiler/reference/jak2/engine/util/sync-info-h_REF.gc @@ -3,6 +3,7 @@ ;; definition of type sync-info-params (deftype sync-info-params (structure) + "Parameters used to set up a [[sync-info]]." ((sync-type symbol) (sync-flags sync-flags) (entity basic) diff --git a/test/decompiler/reference/jak2/kernel/gcommon_REF.gc b/test/decompiler/reference/jak2/kernel/gcommon_REF.gc index 584e8966d0..29a4dbfc32 100644 --- a/test/decompiler/reference/jak2/kernel/gcommon_REF.gc +++ b/test/decompiler/reference/jak2/kernel/gcommon_REF.gc @@ -2,97 +2,115 @@ (in-package goal) ;; definition for function identity -(defun identity ((arg0 object)) - arg0 +(defun identity ((obj object)) + "The identity function." + obj ) ;; definition for function 1/ -(defun 1/ ((arg0 float)) - (/ 1.0 arg0) +(defun 1/ ((x float)) + "Floating point reciprocal." + (/ 1.0 x) ) ;; definition for function + -(defun + ((arg0 int) (arg1 int)) - (+ arg0 arg1) +(defun + ((a int) (b int)) + "64-bit integer addition." + (+ a b) ) ;; definition for function - -(defun - ((arg0 int) (arg1 int)) - (- arg0 arg1) +(defun - ((a int) (b int)) + "64-bit integer subraction." + (- a b) ) ;; definition for function * -(defun * ((arg0 int) (arg1 int)) - (* arg0 arg1) +(defun * ((a int) (b int)) + (* a b) ) ;; definition for function / -(defun / ((arg0 int) (arg1 int)) - (/ arg0 arg1) +(defun / ((a int) (b int)) + "32-bit signed integer division." + (/ a b) ) ;; definition for function ash -(defun ash ((arg0 int) (arg1 int)) - (ash arg0 arg1) +(defun ash ((x int) (shift-amount int)) + "64-bit arithmetic shift. (sign-extends)" + (ash x shift-amount) ) ;; definition for function mod -(defun mod ((arg0 int) (arg1 int)) - (mod arg0 arg1) +(defun mod ((a int) (b int)) + "32-bit mod." + (mod a b) ) ;; definition for function rem -(defun rem ((arg0 int) (arg1 int)) - (mod arg0 arg1) +(defun rem ((a int) (b int)) + "32-bit mod (same as mod)." + (mod a b) ) ;; definition for function abs -(defun abs ((arg0 int)) - (abs arg0) +(defun abs ((x int)) + "64-bit integer absolute value." + (abs x) ) ;; definition for function min -(defun min ((arg0 int) (arg1 int)) - (min arg0 arg1) +(defun min ((a int) (b int)) + "64-bit integer minimum." + (min a b) ) ;; definition for function max -(defun max ((arg0 int) (arg1 int)) - (max arg0 arg1) +(defun max ((a int) (b int)) + "64-bit integer maximum." + (max a b) ) ;; definition for function logior -(defun logior ((arg0 int) (arg1 int)) - (logior arg0 arg1) +(defun logior ((a int) (b int)) + "64-bit bitwise or." + (logior a b) ) ;; definition for function logand -(defun logand ((arg0 int) (arg1 int)) - (logand arg0 arg1) +(defun logand ((a int) (b int)) + "64-bit bitwise and." + (logand a b) ) ;; definition for function lognor -(defun lognor ((arg0 int) (arg1 int)) - (lognor arg0 arg1) +(defun lognor ((a int) (b int)) + "64-bit bitwise not-or." + (lognor a b) ) ;; definition for function logxor -(defun logxor ((arg0 int) (arg1 int)) - (logxor arg0 arg1) +(defun logxor ((a int) (b int)) + "64-bit bitwise exclusive or." + (logxor a b) ) ;; definition for function lognot -(defun lognot ((arg0 int)) - (lognot arg0) +(defun lognot ((x int)) + "64-bit bitwise not." + (lognot x) ) ;; definition for function false-func (defun false-func () + "Returns false." #f ) ;; definition for function true-func (defun true-func () + "Returns true." #t ) @@ -101,6 +119,9 @@ ;; definition of type vec4s (deftype vec4s (uint128) + "Vector of four floats, packed into a 128-bit integer as bitfields. +This behaves like a value type. +This is not the main vector type." ((x float :offset 0 :size 32) (y float :offset 32 :size 32) (z float :offset 64 :size 32) @@ -131,6 +152,9 @@ ;; definition of type vector (deftype vector (structure) + "Vector of four floats, stored in a structure. +This behaves like a reference type. +This is the main vector type." ((data float 4) (x float :overlay-at (-> data 0)) (y float :overlay-at (-> data 1)) @@ -160,6 +184,7 @@ ;; definition of type bfloat (deftype bfloat (basic) + "Boxed (or basic?) float. Just a basic that wraps a single float." ((data float) ) ) @@ -189,12 +214,13 @@ ) ;; definition for function basic-type? -(defun basic-type? ((arg0 basic) (arg1 type)) - (let ((v1-0 (-> arg0 type)) +(defun basic-type? ((obj basic) (typ type)) + "Return if the given basic is a given type. A child of the given type is also acceptable." + (let ((v1-0 (-> obj type)) (a0-1 object) ) (until (= v1-0 a0-1) - (if (= v1-0 arg1) + (if (= v1-0 typ) (return #t) ) (set! v1-0 (-> v1-0 parent)) @@ -204,16 +230,17 @@ ) ;; definition for function type-type? -(defun type-type? ((arg0 type) (arg1 type)) +(defun type-type? ((check-type type) (parent-type type)) + "Return if the first type is the second type, or a child of it." (let ((v1-0 object)) - (if (= arg1 v1-0) + (if (= parent-type v1-0) (return #t) ) - (until (or (= arg0 v1-0) (zero? arg0)) - (if (= arg0 arg1) + (until (or (= check-type v1-0) (zero? check-type)) + (if (= check-type parent-type) (return #t) ) - (set! arg0 (-> arg0 parent)) + (set! check-type (-> check-type parent)) ) ) #f @@ -221,15 +248,17 @@ ;; definition for function type? ;; WARN: Using new Jak 2 rtype-of -(defun type? ((arg0 object) (arg1 type)) +(defun type? ((obj object) (desired-type type)) + "Return if the given object is an instance of the given type. +Works on basics, bintegers, or symbols." (let ((v1-0 object) - (a0-1 (rtype-of arg0)) + (a0-1 (rtype-of obj)) ) - (if (= arg1 v1-0) + (if (= desired-type v1-0) (return #t) ) (until (or (= a0-1 v1-0) (zero? a0-1)) - (if (= a0-1 arg1) + (if (= a0-1 desired-type) (return #t) ) (set! a0-1 (-> a0-1 parent)) @@ -239,15 +268,18 @@ ) ;; definition for function find-parent-method -(defun find-parent-method ((arg0 type) (arg1 int)) +(defun find-parent-method ((typ type) (method-id int)) + "Find the closest parent type that has a different implementation of the given method and return that method. +If it does not exist, return `nothing` function. +This is used to implement call-parent-method." (local-vars (v0-0 function)) - (let ((v1-2 (-> arg0 method-table arg1))) + (let ((v1-2 (-> typ method-table method-id))) (until (!= v0-0 v1-2) - (if (= arg0 object) + (if (= typ object) (return nothing) ) - (set! arg0 (-> arg0 parent)) - (set! v0-0 (-> arg0 method-table arg1)) + (set! typ (-> typ parent)) + (set! v0-0 (-> typ method-table method-id)) (if (zero? v0-0) (return nothing) ) @@ -257,13 +289,14 @@ ) ;; definition for function ref -(defun ref ((arg0 object) (arg1 int)) - (dotimes (v1-0 arg1) +(defun ref ((list object) (idx int)) + "Return the n-th item in a proper list. No bounds checking." + (dotimes (v1-0 idx) (nop!) (nop!) - (set! arg0 (cdr arg0)) + (set! list (cdr list)) ) - (car arg0) + (car list) ) ;; definition for method 4 of type pair @@ -293,8 +326,9 @@ ) ;; definition for function last -(defun last ((arg0 object)) - (let ((v0-0 arg0)) +(defun last ((list object)) + "Return the last object in a proper list." + (let ((v0-0 list)) (while (not (null? (cdr v0-0))) (nop!) (nop!) @@ -305,9 +339,15 @@ ) ;; definition for function member -(defun member ((arg0 object) (arg1 object)) - (let ((v1-0 arg1)) - (while (not (or (null? v1-0) (= (car v1-0) arg0))) +(defun member ((obj-to-find object) (list object)) + "See if the first argument is in the proper list of the second argument. +Checked with simple equality. +If so, return the list starting at the at point (a truthy value). +Otherwise, return #f. +(member 'b '(a b c)) -> (b c d). +(member 'w '(a b c)) -> #f" + (let ((v1-0 list)) + (while (not (or (null? v1-0) (= (car v1-0) obj-to-find))) (set! v1-0 (cdr v1-0)) ) (if (not (null? v1-0)) @@ -317,19 +357,23 @@ ) ;; definition for function nmember -(defun nmember ((arg0 basic) (arg1 object)) - (while (not (or (null? arg1) (name= (car arg1) arg0))) - (set! arg1 (cdr arg1)) +(defun nmember ((obj-to-find basic) (list object)) + "Like member, but membership is checked with the name= function to handle symbols or strings." + (while (not (or (null? list) (name= (car list) obj-to-find))) + (set! list (cdr list)) ) - (if (not (null? arg1)) - arg1 + (if (not (null? list)) + list ) ) ;; definition for function assoc -(defun assoc ((arg0 object) (arg1 object)) - (let ((v1-0 arg1)) - (while (not (or (null? v1-0) (= (car (car v1-0)) arg0))) +(defun assoc ((key object) (assoc-list object)) + "Search an association list for given object. Return #f if not found, otherwise the element with matching car. +(assoc 'a '((a . 1) (b . 2) (c . 3))) -> (a . 1) +(assoc 'x '((a . 1) (b . 2) (c . 3))) -> #f" + (let ((v1-0 assoc-list)) + (while (not (or (null? v1-0) (= (car (car v1-0)) key))) (set! v1-0 (cdr v1-0)) ) (if (not (null? v1-0)) @@ -339,9 +383,10 @@ ) ;; definition for function assoce -(defun assoce ((arg0 object) (arg1 object)) - (let ((v1-0 arg1)) - (while (not (or (null? v1-0) (= (car (car v1-0)) arg0) (= (car (car v1-0)) 'else))) +(defun assoce ((key object) (assoc-list object)) + "Like assoc, but supports a special `else` key which is always considered a match." + (let ((v1-0 assoc-list)) + (while (not (or (null? v1-0) (= (car (car v1-0)) key) (= (car (car v1-0)) 'else))) (set! v1-0 (cdr v1-0)) ) (if (not (null? v1-0)) @@ -351,73 +396,77 @@ ) ;; definition for function nassoc -(defun nassoc ((arg0 string) (arg1 object)) - (while (not (or (null? arg1) (let ((a1-1 (car (car arg1)))) - (if (pair? a1-1) - (nmember arg0 a1-1) - (name= a1-1 arg0) - ) - ) +(defun nassoc ((key string) (assoc-list object)) + "Like assoc, but uses name= instead of = to check equality." + (while (not (or (null? assoc-list) (let ((a1-1 (car (car assoc-list)))) + (if (pair? a1-1) + (nmember key a1-1) + (name= a1-1 key) + ) + ) ) ) - (set! arg1 (cdr arg1)) + (set! assoc-list (cdr assoc-list)) ) - (if (not (null? arg1)) - (car arg1) + (if (not (null? assoc-list)) + (car assoc-list) ) ) ;; definition for function nassoce -(defun nassoce ((arg0 string) (arg1 object)) - (while (not (or (null? arg1) (let ((s4-0 (car (car arg1)))) - (if (pair? s4-0) - (nmember arg0 s4-0) - (or (name= s4-0 arg0) (= s4-0 'else)) - ) - ) +(defun nassoce ((key string) (assoc-list object)) + "Like assoce, but uses name= instead of = to check equality." + (while (not (or (null? assoc-list) (let ((s4-0 (car (car assoc-list)))) + (if (pair? s4-0) + (nmember key s4-0) + (or (name= s4-0 key) (= s4-0 'else)) + ) + ) ) ) - (set! arg1 (cdr arg1)) + (set! assoc-list (cdr assoc-list)) ) - (if (not (null? arg1)) - (car arg1) + (if (not (null? assoc-list)) + (car assoc-list) ) ) ;; definition for function append! -(defun append! ((arg0 object) (arg1 object)) +(defun append! ((list object) (new-obj object)) + "Append the second argument to the end of the list (or empty pair) in the first argument." (cond - ((null? arg0) - arg1 + ((null? list) + new-obj ) (else - (let ((v1-1 arg0)) + (let ((v1-1 list)) (while (not (null? (cdr v1-1))) (nop!) (nop!) (set! v1-1 (cdr v1-1)) ) (if (not (null? v1-1)) - (set! (cdr v1-1) arg1) + (set! (cdr v1-1) new-obj) ) ) - arg0 + list ) ) ) ;; definition for function delete! ;; WARN: Return type mismatch object vs pair. -(defun delete! ((arg0 object) (arg1 object)) +(defun delete! ((obj object) (list object)) + "Remove an element from the given list, return the list." (the-as pair (cond - ((= arg0 (car arg1)) - (cdr arg1) + ((= obj (car list)) + (cdr list) ) (else - (let ((v1-1 arg1) - (a2-0 (cdr arg1)) + (let ((v1-1 list) + (a2-0 (cdr list)) ) - (while (not (or (null? a2-0) (= (car a2-0) arg0))) + (while (not (or (null? a2-0) (= (car a2-0) obj))) (set! v1-1 a2-0) (set! a2-0 (cdr a2-0)) ) @@ -425,23 +474,24 @@ (set! (cdr v1-1) (cdr a2-0)) ) ) - arg1 + list ) ) ) ) ;; definition for function delete-car! -(defun delete-car! ((arg0 object) (arg1 object)) +(defun delete-car! ((car-to-match object) (list object)) + "Remove an element from the given list with a matching car. Return the list." (cond - ((= arg0 (car (car arg1))) - (cdr arg1) + ((= car-to-match (car (car list))) + (cdr list) ) (else - (let ((v1-2 arg1) - (a2-0 (cdr arg1)) + (let ((v1-2 list) + (a2-0 (cdr list)) ) - (while (not (or (null? a2-0) (= (car (car a2-0)) arg0))) + (while (not (or (null? a2-0) (= (car (car a2-0)) car-to-match))) (set! v1-2 a2-0) (set! a2-0 (cdr a2-0)) ) @@ -449,28 +499,35 @@ (set! (cdr v1-2) (cdr a2-0)) ) ) - arg1 + list ) ) ) ;; definition for function insert-cons! -(defun insert-cons! ((arg0 object) (arg1 object)) - (let ((a3-0 (delete-car! (car arg0) arg1))) - (cons arg0 a3-0) +(defun insert-cons! ((new-obj object) (list object)) + "Update an association list to have the given (key . value) pair. +If a previous value exists, it is deleted first. +This function always allocates a pair through `cons` on the global heap, which can never be freed, +so it should almost never be used at runtime." + (let ((a3-0 (delete-car! (car new-obj) list))) + (cons new-obj a3-0) ) ) ;; definition for function sort -(defun sort ((arg0 pair) (arg1 (function object object object))) +(defun sort ((list pair) (compare-func (function object object object))) + "Sort a list using the given comparision function. +The function can return a #t/#f value, or a positive/negative value. +For example, you could use either `-` or `<` as functions to sort integers." (let ((s4-0 -1)) (while (nonzero? s4-0) (set! s4-0 0) - (let ((s3-0 arg0)) + (let ((s3-0 list)) (while (not (or (null? (cdr s3-0)) (not (pair? (cdr s3-0))))) (let* ((s2-0 (car s3-0)) (s1-0 (car (cdr s3-0))) - (v1-1 (arg1 s2-0 s1-0)) + (v1-1 (compare-func s2-0 s1-0)) ) (when (and (or (not v1-1) (> (the-as int v1-1) 0)) (!= v1-1 #t)) (+! s4-0 1) @@ -483,11 +540,13 @@ ) ) ) - arg0 + list ) ;; definition of type inline-array-class (deftype inline-array-class (basic) + "Base class for basic inline arrays. +The stride is stored in the heap-base of the inline-array-class child class." ((length int32) (allocated-length int32) (_data uint8 :dynamic :offset 16) @@ -498,30 +557,30 @@ ) ;; definition for method 3 of type inline-array-class -(defmethod inspect ((this inline-array-class)) - (when (not this) - (set! this this) +(defmethod inspect ((idx-to-remove inline-array-class)) + (when (not idx-to-remove) + (set! idx-to-remove idx-to-remove) (goto cfg-4) ) - (format #t "[~8x] ~A~%" this (-> this type)) - (format #t "~1Tlength: ~D~%" (-> this length)) - (format #t "~1Tallocated-length: ~D~%" (-> this allocated-length)) + (format #t "[~8x] ~A~%" idx-to-remove (-> idx-to-remove type)) + (format #t "~1Tlength: ~D~%" (-> idx-to-remove length)) + (format #t "~1Tallocated-length: ~D~%" (-> idx-to-remove allocated-length)) (label cfg-4) - this + idx-to-remove ) ;; definition for method 0 of type inline-array-class -(defmethod new inline-array-class ((allocation symbol) (type-to-make type) (arg0 int)) +(defmethod new inline-array-class ((allocation symbol) (type-to-make type) (count int)) (let ((v0-0 (object-new allocation type-to-make - (the-as int (+ (-> type-to-make size) (* (the-as uint arg0) (-> type-to-make heap-base)))) + (the-as int (+ (-> type-to-make size) (* (the-as uint count) (-> type-to-make heap-base)))) ) ) ) (when (nonzero? v0-0) - (set! (-> v0-0 length) arg0) - (set! (-> v0-0 allocated-length) arg0) + (set! (-> v0-0 length) count) + (set! (-> v0-0 allocated-length) count) ) v0-0 ) @@ -807,12 +866,13 @@ ) ;; definition for function mem-copy! -(defun mem-copy! ((arg0 pointer) (arg1 pointer) (arg2 int)) - (let ((v0-0 arg0)) - (dotimes (v1-0 arg2) - (set! (-> (the-as (pointer uint8) arg0)) (-> (the-as (pointer uint8) arg1))) - (&+! arg0 1) - (&+! arg1 1) +(defun mem-copy! ((dst pointer) (src pointer) (bytes int)) + "Basic memory copy. This is not an optimized implementation." + (let ((v0-0 dst)) + (dotimes (v1-0 bytes) + (set! (-> (the-as (pointer uint8) dst)) (-> (the-as (pointer uint8) src))) + (&+! dst 1) + (&+! src 1) ) v0-0 ) @@ -820,12 +880,13 @@ ;; definition for function qmem-copy<-! ;; INFO: Used lq/sq -(defun qmem-copy<-! ((arg0 pointer) (arg1 pointer) (arg2 int)) - (let ((v0-0 arg0)) - (countdown (v1-1 (/ (+ arg2 15) 16)) - (set! (-> (the-as (pointer uint128) arg0)) (-> (the-as (pointer uint128) arg1))) - (&+! arg0 16) - (&+! arg1 16) +(defun qmem-copy<-! ((dst pointer) (src pointer) (qwc int)) + "Copy memory by quadword (16-bytes). Must by 16-byte aligned, size in 16-byte units. Increasing address copy. Not an optimized version." + (let ((v0-0 dst)) + (countdown (v1-1 (/ (+ qwc 15) 16)) + (set! (-> (the-as (pointer uint128) dst)) (-> (the-as (pointer uint128) src))) + (&+! dst 16) + (&+! src 16) ) v0-0 ) @@ -833,11 +894,12 @@ ;; definition for function qmem-copy->! ;; INFO: Used lq/sq -(defun qmem-copy->! ((arg0 pointer) (arg1 pointer) (arg2 int)) - (let ((v0-0 arg0)) - (let* ((v1-1 (/ (+ arg2 15) 16)) - (a0-1 (&+ arg0 (* v1-1 16))) - (a1-1 (&+ arg1 (* v1-1 16))) +(defun qmem-copy->! ((dst pointer) (src pointer) (qwc int)) + "Copy memory by quadword (16-bytes). Must by 16-byte aligned, size in 16-byte units. Decreasing address copy. Not an optimized version." + (let ((v0-0 dst)) + (let* ((v1-1 (/ (+ qwc 15) 16)) + (a0-1 (&+ dst (* v1-1 16))) + (a1-1 (&+ src (* v1-1 16))) ) (while (nonzero? v1-1) (+! v1-1 -1) @@ -851,11 +913,13 @@ ) ;; definition for function mem-set32! -(defun mem-set32! ((arg0 pointer) (arg1 int) (arg2 int)) - (let ((v0-0 arg0)) - (dotimes (v1-0 arg1) - (set! (-> (the-as (pointer int32) arg0)) arg2) - (&+! arg0 4) +(defun mem-set32! ((dst pointer) (word-count int) (value int)) + "Set memory to the given 32-bit value, repeated n times. (like C memset, but setting int32_t instead of char). +Not an optimized implementation. Must be 4-byte aligned." + (let ((v0-0 dst)) + (dotimes (v1-0 word-count) + (set! (-> (the-as (pointer int32) dst)) value) + (&+! dst 4) (nop!) ) v0-0 @@ -863,12 +927,13 @@ ) ;; definition for function mem-or! -(defun mem-or! ((arg0 pointer) (arg1 pointer) (arg2 int)) - (let ((v0-0 arg0)) - (dotimes (v1-0 arg2) - (logior! (-> (the-as (pointer uint8) arg0)) (-> (the-as (pointer uint8) arg1))) - (&+! arg0 1) - (&+! arg1 1) +(defun mem-or! ((dst pointer) (src pointer) (bytes int)) + "Set the destiation to `dest = dest | src`. Size in bytes. Not an optimized version." + (let ((v0-0 dst)) + (dotimes (v1-0 bytes) + (logior! (-> (the-as (pointer uint8) dst)) (-> (the-as (pointer uint8) src))) + (&+! dst 1) + (&+! src 1) ) v0-0 ) @@ -878,10 +943,11 @@ ;; ERROR: function was not converted to expressions. Cannot decompile. ;; definition for function fact -(defun fact ((arg0 int)) - (if (= arg0 1) +(defun fact ((x int)) + "Factorial." + (if (= x 1) 1 - (* arg0 (fact (+ arg0 -1))) + (* x (fact (+ x -1))) ) ) @@ -890,37 +956,41 @@ ;; definition for function print ;; WARN: Using new Jak 2 rtype-of -(defun print ((arg0 object)) - ((method-of-type (rtype-of arg0) print) arg0) +(defun print ((obj object)) + "Print any boxed object (symbol, pair, basic, binteger) to #t (the REPL). No newline." + ((method-of-type (rtype-of obj) print) obj) ) ;; definition for function printl ;; WARN: Using new Jak 2 rtype-of -(defun printl ((arg0 object)) - (let ((a0-1 arg0)) +(defun printl ((obj object)) + "Print any boxed object (symbol, pair, basic, binteger) to #t (the REPL), followed by a newline." + (let ((a0-1 obj)) ((method-of-type (rtype-of a0-1) print) a0-1) ) (format #t "~%") - arg0 + obj ) ;; definition for function inspect ;; WARN: Using new Jak 2 rtype-of -(defun inspect ((arg0 object)) - ((method-of-type (rtype-of arg0) inspect) arg0) +(defun inspect ((obj object)) + "Inspect any boxed object (symbol, pair, basic, binteger) to #t (the REPL)." + ((method-of-type (rtype-of obj) inspect) obj) ) ;; definition (debug) for function mem-print -(defun-debug mem-print ((arg0 (pointer uint32)) (arg1 int)) - (dotimes (s4-0 (/ arg1 4)) +(defun-debug mem-print ((ptr (pointer uint32)) (word-count int)) + "Print out data in memory in hex." + (dotimes (s4-0 (/ word-count 4)) (format 0 "~X: ~X ~X ~X ~X~%" - (&-> arg0 (* s4-0 4)) - (-> arg0 (* s4-0 4)) - (-> arg0 (+ (* s4-0 4) 1)) - (-> arg0 (+ (* s4-0 4) 2)) - (-> arg0 (+ (* s4-0 4) 3)) + (&-> ptr (* s4-0 4)) + (-> ptr (* s4-0 4)) + (-> ptr (+ (* s4-0 4) 1)) + (-> ptr (+ (* s4-0 4) 2)) + (-> ptr (+ (* s4-0 4) 3)) ) ) #f @@ -930,13 +1000,14 @@ (define *trace-list* '()) ;; definition for function print-tree-bitmask -(defun print-tree-bitmask ((arg0 int) (arg1 int)) - (dotimes (s4-0 arg1) - (if (not (logtest? arg0 1)) +(defun print-tree-bitmask ((mask int) (count int)) + "Print out ASCII-art tree structure, from a bitmask of nesting levels." + (dotimes (s4-0 count) + (if (not (logtest? mask 1)) (format #t " ") (format #t "| ") ) - (set! arg0 (shr arg0 1)) + (set! mask (shr mask 1)) ) #f ) @@ -945,6 +1016,7 @@ ;; ERROR: Unsupported inline assembly instruction kind - [mtdab a1] ;; ERROR: Unsupported inline assembly instruction kind - [mtdabm a2] (defun breakpoint-range-set! ((arg0 uint) (arg1 uint) (arg2 uint)) + "Unsupported function to set a CPU breakpoint." (.mtc0 Debug arg0) (.mtdab arg1) (.mtdabm arg2) @@ -961,24 +1033,24 @@ ;; ERROR: Unsupported inline assembly instruction kind - [daddu v1, v1, s7] ;; ERROR: Unsupported inline assembly instruction kind - [daddu v1, v1, s7] ;; ERROR: Unsupported inline assembly instruction kind - [daddu v1, v1, s7] -(defun valid? ((arg0 object) (arg1 type) (arg2 string) (arg3 symbol) (arg4 object)) +(defun valid? ((obj object) (expected-type type) (err-msg-str string) (allow-false symbol) (err-msg-dest object)) (local-vars (v1-11 int) (v1-26 int) (v1-56 int) (v1-60 int) (s7-0 none)) (let ((v1-1 - (and (>= (the-as uint arg0) (the-as uint __START-OF-TABLE__)) (< (the-as uint arg0) (the-as uint #x8000000))) + (and (>= (the-as uint obj) (the-as uint __START-OF-TABLE__)) (< (the-as uint obj) (the-as uint #x8000000))) ) ) (cond - ((not arg1) + ((not expected-type) (cond - ((logtest? (the-as int arg0) 3) - (if arg2 - (format arg4 "ERROR: object #x~X ~S is not a valid object (misaligned)~%" arg0 arg2) + ((logtest? (the-as int obj) 3) + (if err-msg-str + (format err-msg-dest "ERROR: object #x~X ~S is not a valid object (misaligned)~%" obj err-msg-str) ) #f ) ((not v1-1) - (if arg2 - (format arg4 "ERROR: object #x~X ~S is not a valid object (bad address)~%" arg0 arg2) + (if err-msg-str + (format err-msg-dest "ERROR: object #x~X ~S is not a valid object (bad address)~%" obj err-msg-str) ) #f ) @@ -987,14 +1059,20 @@ ) ) ) - ((and arg3 (not arg0)) + ((and allow-false (not obj)) #t ) - ((= arg1 structure) + ((= expected-type structure) (cond - ((logtest? (the-as int arg0) 15) - (if arg2 - (format arg4 "ERROR: object #x~X ~S is not a valid object of type '~A' (misaligned)~%" arg0 arg2 arg1) + ((logtest? (the-as int obj) 15) + (if err-msg-str + (format + err-msg-dest + "ERROR: object #x~X ~S is not a valid object of type '~A' (misaligned)~%" + obj + err-msg-str + expected-type + ) ) #f ) @@ -1002,11 +1080,17 @@ (let ((v1-10 #x8000)) (.daddu v1-11 v1-10 s7-0) ) - (< (the-as uint arg0) (the-as uint v1-11)) + (< (the-as uint obj) (the-as uint v1-11)) ) ) - (if arg2 - (format arg4 "ERROR: object #x~X ~S is not a valid object of type '~A' (bad address)~%" arg0 arg2 arg1) + (if err-msg-str + (format + err-msg-dest + "ERROR: object #x~X ~S is not a valid object of type '~A' (bad address)~%" + obj + err-msg-str + expected-type + ) ) #f ) @@ -1015,17 +1099,29 @@ ) ) ) - ((= arg1 pair) + ((= expected-type pair) (cond - ((not (pair? arg0)) - (if arg2 - (format arg4 "ERROR: object #x~X ~S is not a valid object of type '~A' (misaligned)~%" arg0 arg2 arg1) + ((not (pair? obj)) + (if err-msg-str + (format + err-msg-dest + "ERROR: object #x~X ~S is not a valid object of type '~A' (misaligned)~%" + obj + err-msg-str + expected-type + ) ) #f ) ((not v1-1) - (if arg2 - (format arg4 "ERROR: object #x~X ~S is not a valid object of type '~A' (bad address)~%" arg0 arg2 arg1) + (if err-msg-str + (format + err-msg-dest + "ERROR: object #x~X ~S is not a valid object of type '~A' (bad address)~%" + obj + err-msg-str + expected-type + ) ) #f ) @@ -1034,36 +1130,54 @@ ) ) ) - ((= arg1 binteger) + ((= expected-type binteger) (cond - ((not (logtest? (the-as int arg0) 7)) + ((not (logtest? (the-as int obj) 7)) #t ) (else - (if arg2 - (format arg4 "ERROR: object #x~X ~S is not a valid object of type '~A' (misaligned)~%" arg0 arg2 arg1) + (if err-msg-str + (format + err-msg-dest + "ERROR: object #x~X ~S is not a valid object of type '~A' (misaligned)~%" + obj + err-msg-str + expected-type + ) ) #f ) ) ) - ((or (= arg1 symbol) (= arg1 boolean)) + ((or (= expected-type symbol) (= expected-type boolean)) (cond - ((not (logtest? (the-as int arg0) 1)) - (if arg2 - (format arg4 "ERROR: object #x~X ~S is not a valid object of type '~A' (misaligned)~%" arg0 arg2 arg1) + ((not (logtest? (the-as int obj) 1)) + (if err-msg-str + (format + err-msg-dest + "ERROR: object #x~X ~S is not a valid object of type '~A' (misaligned)~%" + obj + err-msg-str + expected-type + ) ) #f ) - ((or (not v1-1) (< (the-as int arg0) (the-as int __START-OF-TABLE__)) (begin - (let ((v1-25 #x8000)) - (.daddu v1-26 v1-25 s7-0) - ) - (>= (the-as int arg0) v1-26) - ) + ((or (not v1-1) (< (the-as int obj) (the-as int __START-OF-TABLE__)) (begin + (let ((v1-25 #x8000)) + (.daddu v1-26 v1-25 s7-0) + ) + (>= (the-as int obj) v1-26) + ) ) - (if arg2 - (format arg4 "ERROR: object #x~X ~S is not a valid object of type '~A' (bad address)~%" arg0 arg2 arg1) + (if err-msg-str + (format + err-msg-dest + "ERROR: object #x~X ~S is not a valid object of type '~A' (bad address)~%" + obj + err-msg-str + expected-type + ) ) #f ) @@ -1072,70 +1186,82 @@ ) ) ) - ((!= (logand (the-as int arg0) 7) 4) - (if arg2 - (format arg4 "ERROR: object #x~X ~S is not a valid object of type '~A' (misaligned)~%" arg0 arg2 arg1) + ((!= (logand (the-as int obj) 7) 4) + (if err-msg-str + (format + err-msg-dest + "ERROR: object #x~X ~S is not a valid object of type '~A' (misaligned)~%" + obj + err-msg-str + expected-type + ) ) #f ) ((not v1-1) - (if arg2 - (format arg4 "ERROR: object #x~X ~S is not a valid object of type '~A' (bad address)~%" arg0 arg2 arg1) - ) - #f - ) - ((and (= arg1 type) (!= (rtype-of arg0) type)) - (if arg2 + (if err-msg-str (format - arg4 - "ERROR: object #x~X ~S is not a valid object of type '~A' (invalid type #x~X)~%" - arg0 - arg2 - arg1 - (rtype-of arg0) + err-msg-dest + "ERROR: object #x~X ~S is not a valid object of type '~A' (bad address)~%" + obj + err-msg-str + expected-type ) ) #f ) - ((and (!= arg1 type) (not (valid? (rtype-of arg0) type (the-as string #f) #t 0))) - (if arg2 + ((and (= expected-type type) (!= (rtype-of obj) type)) + (if err-msg-str (format - arg4 + err-msg-dest "ERROR: object #x~X ~S is not a valid object of type '~A' (invalid type #x~X)~%" - arg0 - arg2 - arg1 - (rtype-of arg0) + obj + err-msg-str + expected-type + (rtype-of obj) ) ) #f ) - ((not (type? arg0 arg1)) - (if arg2 + ((and (!= expected-type type) (not (valid? (rtype-of obj) type (the-as string #f) #t 0))) + (if err-msg-str (format - arg4 + err-msg-dest + "ERROR: object #x~X ~S is not a valid object of type '~A' (invalid type #x~X)~%" + obj + err-msg-str + expected-type + (rtype-of obj) + ) + ) + #f + ) + ((not (type? obj expected-type)) + (if err-msg-str + (format + err-msg-dest "ERROR: object #x~X ~S is not a valid object of type '~A' (is type '~A' instead)~%" - arg0 - arg2 - arg1 - (rtype-of arg0) + obj + err-msg-str + expected-type + (rtype-of obj) ) ) #f ) - ((= arg1 symbol) + ((= expected-type symbol) (let ((v1-55 #x8000)) (.daddu v1-56 v1-55 s7-0) ) (cond - ((>= (the-as uint arg0) (the-as uint v1-56)) - (if arg2 + ((>= (the-as uint obj) (the-as uint v1-56)) + (if err-msg-str (format - arg4 + err-msg-dest "ERROR: object #x~X ~S is not a valid object of type '~A' (not in symbol table)~%" - arg0 - arg2 - arg1 + obj + err-msg-str + expected-type ) ) #f @@ -1149,15 +1275,15 @@ (let ((v1-59 #x8000)) (.daddu v1-60 v1-59 s7-0) ) - (< (the-as uint arg0) (the-as uint v1-60)) + (< (the-as uint obj) (the-as uint v1-60)) ) - (if arg2 + (if err-msg-str (format - arg4 + err-msg-dest "ERROR: object #x~X ~S is not a valid object of type '~A' (inside symbol table)~%" - arg0 - arg2 - arg1 + obj + err-msg-str + expected-type ) ) #f diff --git a/test/decompiler/reference/jak2/kernel/gkernel_REF.gc b/test/decompiler/reference/jak2/kernel/gkernel_REF.gc index fb8c749cc8..a5a4d8fc66 100644 --- a/test/decompiler/reference/jak2/kernel/gkernel_REF.gc +++ b/test/decompiler/reference/jak2/kernel/gkernel_REF.gc @@ -34,19 +34,26 @@ (define *kernel-packages* '()) ;; definition for function load-package -(defun load-package ((arg0 string) (arg1 kheap)) - (when (not (nmember arg0 *kernel-packages*)) - (kmemopen global arg0) - (dgo-load arg0 arg1 (link-flag output-load-msg output-load-true-msg execute-login print-login) #x200000) - (set! *kernel-packages* (cons arg0 *kernel-packages*)) +(defun load-package ((package-name string) (heap kheap)) + "If not already loaded, do a blocking dgo-load to load the given CGO." + (when (not (nmember package-name *kernel-packages*)) + (kmemopen global package-name) + (dgo-load + package-name + heap + (link-flag output-load-msg output-load-true-msg execute-login print-login) + #x200000 + ) + (set! *kernel-packages* (cons package-name *kernel-packages*)) (kmemclose) *kernel-packages* ) ) ;; definition for function unload-package -(defun unload-package ((arg0 string)) - (let ((v1-0 (nmember arg0 *kernel-packages*))) +(defun unload-package ((package-name string)) + "Mark a package as unloaded. Does not actually unload." + (let ((v1-0 (nmember package-name *kernel-packages*))) (if v1-0 (set! *kernel-packages* (delete! (car v1-0) *kernel-packages*)) ) @@ -101,17 +108,18 @@ ;; definition for method 9 of type thread ;; WARN: Return type mismatch int vs none. -(defmethod stack-size-set! ((this thread) (arg0 int)) +(defmethod stack-size-set! ((this thread) (size-bytes int)) + "Adjust the size of the stack that can be stored during a suspend. Must be called before any process allocations." (let ((a2-0 (-> this process))) (cond ((!= this (-> a2-0 main-thread)) (format 0 "ERROR: illegal attempt change stack size of ~A when the main-thread is not the top-thread.~%" a2-0) ) - ((= (-> this stack-size) arg0) + ((= (-> this stack-size) size-bytes) ) ((= (-> a2-0 heap-cur) (+ (+ (-> this stack-size) -4 (-> this type size)) (the-as int this))) - (set! (-> a2-0 heap-cur) (the-as pointer (+ (+ arg0 -4 (-> this type size)) (the-as int this)))) - (set! (-> this stack-size) arg0) + (set! (-> a2-0 heap-cur) (the-as pointer (+ (+ size-bytes -4 (-> this type size)) (the-as int this)))) + (set! (-> this stack-size) size-bytes) ) (else (format 0 "ERROR: illegal attempt change stack size of ~A after more heap allocation has occured.~%" a2-0) @@ -125,6 +133,7 @@ ;; definition for method 0 of type cpu-thread ;; WARN: Return type mismatch pointer vs cpu-thread. (defmethod new cpu-thread ((allocation symbol) (type-to-make type) (arg0 process) (arg1 symbol) (arg2 int) (arg3 pointer)) + "Allocate a thread. If there is already a top-thread for this process, assume this is a temporary thread, and allocate on the bottom of the stack." (let ((v0-0 (cond ((-> arg0 top-thread) (&+ arg3 -7164) @@ -161,6 +170,8 @@ ;; definition for function remove-exit ;; WARN: Return type mismatch int vs none. (defbehavior remove-exit process () + "Remove the top stack frame. If you have no other stack frames, you can use this before a `go` +to skip the `exit` of the state you are currently in." (if (-> self stack-frame-top) (set! (-> self stack-frame-top) (-> self stack-frame-top next)) ) @@ -285,6 +296,7 @@ ;; definition for method 0 of type process-tree (defmethod new process-tree ((allocation symbol) (type-to-make type) (arg0 string)) + "Allocate a process-tree with the kernel clock." (let ((v0-0 (object-new allocation type-to-make (the-as int (-> type-to-make size))))) (set! (-> v0-0 name) arg0) (set! (-> v0-0 mask) (process-mask process-tree)) @@ -315,6 +327,7 @@ ;; definition for method 0 of type process ;; WARN: Return type mismatch object vs process. (defmethod new process ((allocation symbol) (type-to-make type) (arg0 string) (arg1 int)) + "Allocate a process, set up process heap, self/ppointer, clock." (let ((v0-0 (if (logtest? (the-as int allocation) 1) (object-new allocation type-to-make (the-as int (+ (-> process size) arg1))) (+ (the-as int allocation) 4) @@ -355,9 +368,10 @@ ) ;; definition for function inspect-process-heap -(defun inspect-process-heap ((arg0 process)) - (let ((s5-0 (the-as object (&+ (-> arg0 heap-base) 4)))) - (while (< (the-as int s5-0) (the-as int (-> arg0 heap-cur))) +(defun inspect-process-heap ((proc process)) + "Call the inspect method on every object in the process heap." + (let ((s5-0 (the-as object (&+ (-> proc heap-base) 4)))) + (while (< (the-as int s5-0) (the-as int (-> proc heap-cur))) (inspect (the-as basic s5-0)) (set! s5-0 (&+ (the-as pointer s5-0) (logand -16 (+ (asize-of (the-as basic s5-0)) 15)))) ) @@ -460,18 +474,19 @@ ;; ERROR: function was not converted to expressions. Cannot decompile. ;; definition for method 0 of type dead-pool -(defmethod new dead-pool ((allocation symbol) (type-to-make type) (arg0 int) (arg1 int) (arg2 string)) +(defmethod new dead-pool ((allocation symbol) (type-to-make type) (num-proc int) (process-size int) (name string)) + "Allocate a dead pool and set up dead processes" (let ((s3-0 (object-new allocation type-to-make (the-as int (-> type-to-make size))))) - (set! (-> s3-0 name) arg2) + (set! (-> s3-0 name) name) (set! (-> s3-0 mask) (process-mask process-tree)) (set! (-> s3-0 parent) (the-as (pointer process-tree) #f)) (set! (-> s3-0 brother) (the-as (pointer process-tree) #f)) (set! (-> s3-0 child) (the-as (pointer process-tree) #f)) (set! (-> s3-0 self) s3-0) (set! (-> s3-0 ppointer) (the-as (pointer process) (&-> s3-0 self))) - (dotimes (s2-1 arg0) + (dotimes (s2-1 num-proc) (let ((s1-0 (-> s3-0 child)) - (v1-5 ((method-of-type process new) allocation process "dead" arg1)) + (v1-5 ((method-of-type process new) allocation process "dead" process-size)) ) (set! (-> s3-0 child) (process->ppointer v1-5)) (set! (-> v1-5 parent) (process->ppointer (the-as process s3-0))) @@ -485,6 +500,7 @@ ;; definition for method 14 of type dead-pool (defmethod get-process ((this dead-pool) (arg0 type) (arg1 int)) + "Allocate a process from the pool, or #f if it fails." (let ((s4-0 (the-as object (-> this child)))) (when (and (not (the-as (pointer process-tree) s4-0)) *debug-segment* (!= this *debug-dead-pool*)) (set! s4-0 (get-process *debug-dead-pool* arg0 arg1)) @@ -519,31 +535,34 @@ ;; definition for method 15 of type dead-pool ;; WARN: Return type mismatch int vs none. -(defmethod return-process ((this dead-pool) (arg0 process)) - (change-parent arg0 this) +(defmethod return-process ((this dead-pool) (proc process)) + "Return a process to the pool." + (change-parent proc this) 0 (none) ) ;; definition for method 0 of type dead-pool-heap -(defmethod new dead-pool-heap ((allocation symbol) (type-to-make type) (arg0 string) (arg1 int) (arg2 int)) - (let ((s2-0 (object-new allocation type-to-make (the-as int (+ (-> type-to-make size) (* 12 arg1)))))) - (set! (-> s2-0 name) arg0) +(defmethod new dead-pool-heap ((allocation symbol) (type-to-make type) (name string) (max-num-proc int) (heap-size int)) + "Allocate and initialize a dead-pool-heap." + (let ((s2-0 (object-new allocation type-to-make (the-as int (+ (-> type-to-make size) (* 12 max-num-proc)))))) + (set! (-> s2-0 name) name) (set! (-> s2-0 mask) (process-mask process-tree)) - (set! (-> s2-0 allocated-length) arg1) + (set! (-> s2-0 allocated-length) max-num-proc) (set! (-> s2-0 parent) (the-as (pointer process-tree) #f)) (set! (-> s2-0 brother) (the-as (pointer process-tree) #f)) (set! (-> s2-0 child) (the-as (pointer process-tree) #f)) (set! (-> s2-0 self) s2-0) (set! (-> s2-0 ppointer) (the-as (pointer process) (&-> s2-0 self))) - (init s2-0 allocation arg2) + (init s2-0 allocation heap-size) s2-0 ) ) ;; definition for method 16 of type dead-pool-heap ;; WARN: Return type mismatch dead-pool-heap vs none. -(defmethod init ((this dead-pool-heap) (arg0 symbol) (arg1 int)) +(defmethod init ((this dead-pool-heap) (allocation symbol) (heap-size int)) + "Allocate memory for processes and init records." (countdown (v1-0 (-> this allocated-length)) (let ((a0-4 (-> this process-list v1-0))) (set! (-> a0-4 process) *null-process*) @@ -559,7 +578,7 @@ (set! (-> this first-gap) (-> this alive-list)) (set! (-> this first-shrink) #f) (cond - ((zero? arg1) + ((zero? heap-size) (set! (-> this heap base) (the-as pointer 0)) (set! (-> this heap current) (the-as pointer 0)) (set! (-> this heap top) (the-as pointer 0)) @@ -567,9 +586,9 @@ 0 ) (else - (set! (-> this heap base) (malloc arg0 arg1)) + (set! (-> this heap base) (malloc allocation heap-size)) (set! (-> this heap current) (-> this heap base)) - (set! (-> this heap top) (&+ (-> this heap base) arg1)) + (set! (-> this heap top) (&+ (-> this heap base) heap-size)) (set! (-> this heap top-base) (-> this heap top)) ) ) @@ -578,29 +597,34 @@ ;; definition for method 25 of type dead-pool-heap ;; WARN: Return type mismatch object vs pointer. -(defmethod gap-location ((this dead-pool-heap) (arg0 dead-pool-heap-rec)) +(defmethod gap-location ((this dead-pool-heap) (rec dead-pool-heap-rec)) + "Get pointer to gap (possibly zero size) after the given process" (the-as pointer - (if (-> arg0 process) - (+ (+ (-> arg0 process allocated-length) -4 (-> process size)) (the-as int (-> arg0 process))) + (if (-> rec process) + (+ (+ (-> rec process allocated-length) -4 (-> process size)) (the-as int (-> rec process))) (-> this heap base) ) ) ) ;; definition for method 24 of type dead-pool-heap -(defmethod gap-size ((this dead-pool-heap) (arg0 dead-pool-heap-rec)) +(defmethod gap-size ((this dead-pool-heap) (first-rec dead-pool-heap-rec)) + "Get the size of the gap (possibly zero) after the given process. Use #f for the gap at the start of the pool memory." (cond - ((-> arg0 process) - (let ((v1-3 (&+ (&+ (the-as pointer (-> arg0 process)) (-> process size)) (-> arg0 process allocated-length)))) - (if (-> arg0 next) - (&- (the-as pointer (-> arg0 next process)) (the-as uint v1-3)) + ((-> first-rec process) + (let ((v1-3 + (&+ (&+ (the-as pointer (-> first-rec process)) (-> process size)) (-> first-rec process allocated-length)) + ) + ) + (if (-> first-rec next) + (&- (the-as pointer (-> first-rec next process)) (the-as uint v1-3)) (&- (-> this heap top) (the-as uint (&+ v1-3 4))) ) ) ) - ((-> arg0 next) - (&- (the-as pointer (-> arg0 next process)) (the-as uint (&+ (-> this heap base) 4))) + ((-> first-rec next) + (&- (the-as pointer (-> first-rec next process)) (the-as uint (&+ (-> this heap base) 4))) ) (else (&- (-> this heap top) (the-as uint (-> this heap base))) @@ -609,11 +633,12 @@ ) ;; definition for method 26 of type dead-pool-heap -(defmethod find-gap ((this dead-pool-heap) (arg0 dead-pool-heap-rec)) - (while (and (-> arg0 next) (zero? (gap-size this arg0))) - (set! arg0 (-> arg0 next)) +(defmethod find-gap ((this dead-pool-heap) (first-rec dead-pool-heap-rec)) + "Find the first process with a nonzero gap after it, after the given process." + (while (and (-> first-rec next) (zero? (gap-size this first-rec))) + (set! first-rec (-> first-rec next)) ) - arg0 + first-rec ) ;; definition for method 3 of type dead-pool-heap @@ -672,6 +697,7 @@ ;; definition for method 20 of type dead-pool-heap (defmethod memory-used ((this dead-pool-heap)) + "Get the total memory used. Memory in between processes that is not used by a process is considered used." (if (-> this alive-list prev) (- (memory-total this) (gap-size this (-> this alive-list prev))) 0 @@ -680,11 +706,13 @@ ;; definition for method 21 of type dead-pool-heap (defmethod memory-total ((this dead-pool-heap)) + "Get the total size of the heap for processes." (&- (-> this heap top) (the-as uint (-> this heap base))) ) ;; definition for method 22 of type dead-pool-heap (defmethod memory-free ((this dead-pool-heap)) + "Get the size of the unused part of the heap." (let ((v1-0 (-> this heap top))) (if (-> this alive-list prev) (gap-size this (-> this alive-list prev)) @@ -695,13 +723,15 @@ ;; definition for method 23 of type dead-pool-heap (defmethod compact-time ((this dead-pool-heap)) + "Get the compaction time (never set)." (-> this compact-time) ) ;; definition for method 27 of type dead-pool-heap -(defmethod find-gap-by-size ((this dead-pool-heap) (arg0 int)) +(defmethod find-gap-by-size ((this dead-pool-heap) (size int)) + "Find the first gap with a size at least this big" (let ((gp-0 (-> this first-gap))) - (while (and gp-0 (< (gap-size this gp-0) arg0)) + (while (and gp-0 (< (gap-size this gp-0) size)) (set! gp-0 (-> gp-0 next)) ) gp-0 @@ -710,6 +740,7 @@ ;; definition for method 14 of type dead-pool-heap (defmethod get-process ((this dead-pool-heap) (arg0 type) (arg1 int)) + "Allocate a process from the pool, or #f if it fails." (let ((s4-0 (-> this dead-list next)) (s3-0 (the-as process #f)) ) @@ -769,13 +800,14 @@ ;; definition for method 15 of type dead-pool-heap ;; WARN: Return type mismatch int vs none. -(defmethod return-process ((this dead-pool-heap) (arg0 process)) - (if (!= this (-> arg0 pool)) - (format 0 "ERROR: process ~A does not belong to dead-pool-heap ~A.~%" arg0 this) +(defmethod return-process ((this dead-pool-heap) (proc process)) + "Return a process to the pool." + (if (!= this (-> proc pool)) + (format 0 "ERROR: process ~A does not belong to dead-pool-heap ~A.~%" proc this) ) - (change-parent arg0 this) + (change-parent proc this) (set! (-> this child) (the-as (pointer process-tree) #f)) - (let ((s5-1 (-> arg0 ppointer))) + (let ((s5-1 (-> proc ppointer))) (if (or (= (-> this first-gap) s5-1) (< (the-as int (gap-location this (the-as dead-pool-heap-rec s5-1))) (the-as int (gap-location this (-> this first-gap))) ) @@ -802,19 +834,20 @@ ) ;; definition for method 18 of type dead-pool-heap -(defmethod shrink-heap ((this dead-pool-heap) (arg0 process)) - (when arg0 - (let ((s5-0 (-> arg0 ppointer))) - (when (not (or (logtest? (-> arg0 mask) (process-mask heap-shrunk)) - (and (not (-> arg0 next-state)) (not (-> arg0 state))) +(defmethod shrink-heap ((this dead-pool-heap) (proc process)) + "Shrink the heap of a process, allowing the dead pool heap to later reclaim the memory during a compact." + (when proc + (let ((s5-0 (-> proc ppointer))) + (when (not (or (logtest? (-> proc mask) (process-mask heap-shrunk)) + (and (not (-> proc next-state)) (not (-> proc state))) ) ) - (set! (-> arg0 allocated-length) (&- (-> arg0 heap-cur) (the-as uint (-> arg0 stack)))) - (set! (-> arg0 heap-top) (&-> arg0 stack (-> arg0 allocated-length))) - (if (< (the-as int arg0) (the-as int (gap-location this (-> this first-gap)))) + (set! (-> proc allocated-length) (&- (-> proc heap-cur) (the-as uint (-> proc stack)))) + (set! (-> proc heap-top) (&-> proc stack (-> proc allocated-length))) + (if (< (the-as int proc) (the-as int (gap-location this (-> this first-gap)))) (set! (-> this first-gap) (find-gap this (the-as dead-pool-heap-rec s5-0))) ) - (logior! (-> arg0 mask) (process-mask heap-shrunk)) + (logior! (-> proc mask) (process-mask heap-shrunk)) ) (if (= (-> this first-shrink) s5-0) (set! (-> this first-shrink) (the-as dead-pool-heap-rec (-> s5-0 2))) @@ -828,6 +861,7 @@ ;; WARN: Return type mismatch int vs none. ;; WARN: Function (method 17 dead-pool-heap) has a return type of none, but the expression builder found a return statement. (defmethod compact ((this dead-pool-heap) (arg0 int)) + "Relocate process in memory to remove gaps, increasing free memory for this dead-pool-heap." (if (zero? (-> this heap base)) (return 0) ) @@ -888,9 +922,10 @@ ;; definition for method 19 of type dead-pool-heap ;; WARN: Return type mismatch int vs none. -(defmethod churn ((this dead-pool-heap) (arg0 int)) - (while (nonzero? arg0) - (+! arg0 -1) +(defmethod churn ((this dead-pool-heap) (count int)) + "Relocate process in memory, to trigger memory bugs related to process relocation." + (while (nonzero? count) + (+! count -1) (let ((s4-0 (-> this alive-list next))) (when s4-0 (if (or (= (-> this first-gap) s4-0) @@ -953,28 +988,31 @@ (define *global-search-count* 0) ;; definition for function process-by-name -(defun process-by-name ((arg0 string) (arg1 process-tree)) - (set! *global-search-name* arg0) +(defun process-by-name ((process-name string) (tree process-tree)) + "Find the first process with the given name in the process-tree." + (set! *global-search-name* process-name) (search-process-tree - arg1 + tree (lambda ((arg0 process)) (string= (-> arg0 name) (the-as string *global-search-name*))) ) ) ;; definition for function process-not-name -(defun process-not-name ((arg0 string) (arg1 process-tree)) - (set! *global-search-name* arg0) +(defun process-not-name ((name string) (tree process-tree)) + "Find the first process without the given name in the process-tree." + (set! *global-search-name* name) (search-process-tree - arg1 + tree (lambda ((arg0 process)) (not (string= (-> arg0 name) (the-as string *global-search-name*)))) ) ) ;; definition for function process-count -(defun process-count ((arg0 process-tree)) +(defun process-count ((tree process-tree)) + "Count the number of processes in the given process-tree." (set! *global-search-count* 0) (iterate-process-tree - arg0 + tree (lambda ((arg0 process)) (set! *global-search-count* (+ *global-search-count* 1)) #t) *null-kernel-context* ) @@ -982,20 +1020,22 @@ ) ;; definition for function kill-by-name -(defun kill-by-name ((arg0 string) (arg1 process-tree)) +(defun kill-by-name ((name string) (tree process-tree)) + "Kill all processes with the given name." (local-vars (a0-1 process)) - (while (begin (set! a0-1 (process-by-name arg0 arg1)) a0-1) + (while (begin (set! a0-1 (process-by-name name tree)) a0-1) (deactivate a0-1) ) #f ) ;; definition for function kill-by-type -(defun kill-by-type ((arg0 type) (arg1 process-tree)) +(defun kill-by-type ((typ type) (tree process-tree)) + "Kill all processes with the given type." (local-vars (a0-1 process)) - (set! *global-search-name* arg0) + (set! *global-search-name* typ) (while (begin - (set! a0-1 (search-process-tree arg1 (lambda ((arg0 process)) (= (-> arg0 type) *global-search-name*)))) + (set! a0-1 (search-process-tree tree (lambda ((arg0 process)) (= (-> arg0 type) *global-search-name*)))) a0-1 ) (deactivate a0-1) @@ -1004,20 +1044,22 @@ ) ;; definition for function kill-not-name -(defun kill-not-name ((arg0 string) (arg1 process-tree)) +(defun kill-not-name ((name string) (tree process-tree)) + "Kill all processes, except ones with the given name." (local-vars (a0-1 process)) - (while (begin (set! a0-1 (process-not-name arg0 arg1)) a0-1) + (while (begin (set! a0-1 (process-not-name name tree)) a0-1) (deactivate a0-1) ) #f ) ;; definition for function kill-not-type -(defun kill-not-type ((arg0 type) (arg1 process-tree)) +(defun kill-not-type ((typ type) (tree process-tree)) + "Kill all processes, except ones with the exact type." (local-vars (a0-1 process)) - (set! *global-search-name* arg0) + (set! *global-search-name* typ) (while (begin - (set! a0-1 (search-process-tree arg1 (lambda ((arg0 process)) (!= (-> arg0 type) *global-search-name*)))) + (set! a0-1 (search-process-tree tree (lambda ((arg0 process)) (!= (-> arg0 type) *global-search-name*)))) a0-1 ) (deactivate a0-1) @@ -1027,20 +1069,22 @@ ;; definition for method 12 of type process (defmethod run-logic? ((this process)) + "Should this process be run? Checked by execute-process-tree." #t ) ;; definition for function iterate-process-tree -(defun iterate-process-tree ((arg0 process-tree) (arg1 (function object object)) (arg2 kernel-context)) - (let ((s4-0 (or (logtest? (-> arg0 mask) (process-mask process-tree)) (arg1 arg0)))) +(defun iterate-process-tree ((tree process-tree) (callback (function object object)) (context kernel-context)) + "Call a function on each not-dead process in the tree." + (let ((s4-0 (or (logtest? (-> tree mask) (process-mask process-tree)) (callback tree)))) (cond ((= s4-0 'dead) ) (else - (let ((v1-4 (-> arg0 child))) + (let ((v1-4 (-> tree child))) (while v1-4 (let ((s3-1 (-> v1-4 0 brother))) - (iterate-process-tree (-> v1-4 0) arg1 arg2) + (iterate-process-tree (-> v1-4 0) callback context) (set! v1-4 s3-1) ) ) @@ -1052,11 +1096,12 @@ ) ;; definition for function execute-process-tree -(defun execute-process-tree ((arg0 process-tree) (arg1 (function object object)) (arg2 kernel-context)) - (logclear! (-> arg0 mask) (process-mask kernel-run)) - (let ((s3-0 (or (logtest? (-> arg0 mask) (process-mask process-tree)) - (not (and (not (logtest? (-> arg2 prevent-from-run) (-> arg0 mask))) (run-logic? arg0))) - (begin (logior! (-> arg0 mask) (process-mask kernel-run)) (arg1 arg0)) +(defun execute-process-tree ((tree process-tree) (callback (function object object)) (context kernel-context)) + "Iterate over all process, calling the run callback on each, if they should run." + (logclear! (-> tree mask) (process-mask kernel-run)) + (let ((s3-0 (or (logtest? (-> tree mask) (process-mask process-tree)) + (not (and (not (logtest? (-> context prevent-from-run) (-> tree mask))) (run-logic? tree))) + (begin (logior! (-> tree mask) (process-mask kernel-run)) (callback tree)) ) ) ) @@ -1064,10 +1109,10 @@ ((= s3-0 'dead) ) (else - (let ((v1-12 (-> arg0 child))) + (let ((v1-12 (-> tree child))) (while v1-12 (let ((s4-1 (-> v1-12 0 brother))) - (execute-process-tree (-> v1-12 0) arg1 arg2) + (execute-process-tree (-> v1-12 0) callback context) (set! v1-12 s4-1) ) ) @@ -1080,16 +1125,17 @@ ;; definition for function search-process-tree ;; WARN: Return type mismatch process-tree vs process. -(defun search-process-tree ((arg0 process-tree) (arg1 (function process-tree object))) - (when (not (logtest? (-> arg0 mask) (process-mask process-tree))) - (if (arg1 arg0) - (return (the-as process arg0)) +(defun search-process-tree ((tree process-tree) (callback (function process-tree object))) + "Return the first function in the process-tree which the callback returns #t on." + (when (not (logtest? (-> tree mask) (process-mask process-tree))) + (if (callback tree) + (return (the-as process tree)) ) ) - (let ((v1-5 (-> arg0 child))) + (let ((v1-5 (-> tree child))) (while v1-5 (let ((s5-1 (-> v1-5 0 brother))) - (let ((v1-6 (search-process-tree (-> v1-5 0) arg1))) + (let ((v1-6 (search-process-tree (-> v1-5 0) callback))) (if v1-6 (return v1-6) ) @@ -1103,6 +1149,7 @@ ;; definition for function kernel-dispatcher (defun kernel-dispatcher () + "Run the GOAL kernel! Runs the function from the listener (if there is one), then all processes" (when *listener-function* (set! *enable-method-set* (+ *enable-method-set* 1)) (let ((t1-0 (reset-and-call (-> *listener-process* main-thread) *listener-function*))) @@ -1178,6 +1225,7 @@ ;; definition for function sync-dispatcher ;; WARN: Return type mismatch symbol vs object. (defun sync-dispatcher () + "Run the REPL function." (let ((t9-0 *listener-function*)) (when t9-0 (set! *listener-function* #f) @@ -1188,23 +1236,24 @@ ) ;; definition for function inspect-process-tree -(defun inspect-process-tree ((arg0 process-tree) (arg1 int) (arg2 int) (arg3 symbol)) - (print-tree-bitmask arg2 arg1) +(defun inspect-process-tree ((tree process-tree) (depth int) (mask int) (detail symbol)) + "Display a tree-view of a process-tree." + (print-tree-bitmask mask depth) (cond - (arg3 + (detail (format #t "__________________~%") (format #t "~S~A~%" - (if (zero? arg1) + (if (zero? depth) "" "+---" ) - arg0 + tree ) (let ((s2-0 *print-column*)) - (set! *print-column* (the-as binteger (* (* arg1 4) 8))) - (inspect arg0) + (set! *print-column* (the-as binteger (* (* depth 4) 8))) + (inspect tree) (set! *print-column* s2-0) ) ) @@ -1212,29 +1261,29 @@ (format #t "~S~A~%" - (if (zero? arg1) + (if (zero? depth) "" "+---" ) - arg0 + tree ) ) ) - (let ((s2-1 (-> arg0 child))) + (let ((s2-1 (-> tree child))) (while s2-1 (inspect-process-tree (-> s2-1 0) - (+ arg1 1) + (+ depth 1) (if (not (-> s2-1 0 brother)) - arg2 - (logior arg2 (ash 1 (+ arg1 1))) + mask + (logior mask (ash 1 (+ depth 1))) ) - arg3 + detail ) (set! s2-1 (-> s2-1 0 brother)) ) ) - arg0 + tree ) ;; definition for method 0 of type catch-frame @@ -1248,12 +1297,13 @@ ;; definition for method 0 of type protect-frame ;; WARN: Return type mismatch int vs protect-frame. -(defmethod new protect-frame ((allocation symbol) (type-to-make type) (arg0 (function object))) +(defmethod new protect-frame ((stack-addr symbol) (type-to-make type) (exit-func (function object))) + "Allocate and set up a protect-frame. This _must_ be used on the stack." (with-pp - (let ((v0-0 (the-as object (+ (the-as int allocation) 4)))) + (let ((v0-0 (the-as object (+ (the-as int stack-addr) 4)))) (set! (-> (the-as protect-frame v0-0) type) type-to-make) (set! (-> (the-as protect-frame v0-0) name) 'protect-frame) - (set! (-> (the-as protect-frame v0-0) exit) arg0) + (set! (-> (the-as protect-frame v0-0) exit) exit-func) (set! (-> (the-as protect-frame v0-0) next) (-> pp stack-frame-top)) (set! (-> pp stack-frame-top) (the-as protect-frame v0-0)) (the-as protect-frame v0-0) @@ -1263,15 +1313,16 @@ ;; definition for function previous-brother ;; WARN: Return type mismatch (pointer process-tree) vs object. -(defun previous-brother ((arg0 process-tree)) - (let ((v1-0 (-> arg0 parent))) +(defun previous-brother ((tree process-tree)) + "Get the process before this one, at this level." + (let ((v1-0 (-> tree parent))) (when v1-0 (let ((v1-2 (-> v1-0 0 child))) - (if (= v1-2 arg0) + (if (= v1-2 tree) (return (the-as object #f)) ) (while v1-2 - (if (= (-> v1-2 0 brother) arg0) + (if (= (-> v1-2 0 brother) tree) (return (the-as object v1-2)) ) (set! v1-2 (-> v1-2 0 brother)) @@ -1283,35 +1334,37 @@ ) ;; definition for function change-parent -(defun change-parent ((arg0 process-tree) (arg1 process-tree)) - (let ((a2-0 (-> arg0 parent))) +(defun change-parent ((proc-to-change process-tree) (new-parent process-tree)) + "Reparent a process." + (let ((a2-0 (-> proc-to-change parent))) (when a2-0 (let ((v1-2 (-> a2-0 0 child))) (cond - ((= (ppointer->process v1-2) arg0) - (set! (-> a2-0 0 child) (-> arg0 brother)) + ((= (ppointer->process v1-2) proc-to-change) + (set! (-> a2-0 0 child) (-> proc-to-change brother)) ) (else - (while (!= (ppointer->process (-> v1-2 0 brother)) arg0) + (while (!= (ppointer->process (-> v1-2 0 brother)) proc-to-change) (nop!) (nop!) (nop!) (set! v1-2 (-> v1-2 0 brother)) ) - (set! (-> v1-2 0 brother) (-> arg0 brother)) + (set! (-> v1-2 0 brother) (-> proc-to-change brother)) ) ) ) ) ) - (set! (-> arg0 parent) (-> arg1 ppointer)) - (set! (-> arg0 brother) (-> arg1 child)) - (set! (-> arg1 child) (-> arg0 ppointer)) - arg0 + (set! (-> proc-to-change parent) (-> new-parent ppointer)) + (set! (-> proc-to-change brother) (-> new-parent child)) + (set! (-> new-parent child) (-> proc-to-change ppointer)) + proc-to-change ) ;; definition for function change-brother (defun change-brother ((arg0 process-tree) (arg1 process-tree)) + "Unused, and wrong." (when (and arg0 (!= (-> arg0 brother) arg1) (!= arg0 arg1)) (let ((a2-1 (-> arg0 parent))) (when a2-1 @@ -1363,24 +1416,25 @@ ) ;; definition for function change-to-last-brother -(defun change-to-last-brother ((arg0 process-tree)) - (when (and (-> arg0 brother) (-> arg0 parent)) - (let* ((a1-0 (-> arg0 parent)) +(defun change-to-last-brother ((proc process-tree)) + "Move this process to the end of its brother list." + (when (and (-> proc brother) (-> proc parent)) + (let* ((a1-0 (-> proc parent)) (v1-4 (-> a1-0 0 child)) ) (cond - ((= (-> v1-4 0) arg0) - (set! (-> a1-0 0 child) (-> arg0 brother)) + ((= (-> v1-4 0) proc) + (set! (-> a1-0 0 child) (-> proc brother)) ) (else - (while (!= (-> v1-4 0 brother 0) arg0) + (while (!= (-> v1-4 0 brother 0) proc) (nop!) (nop!) (nop!) (nop!) (set! v1-4 (-> v1-4 0 brother)) ) - (set! (-> v1-4 0 brother) (-> arg0 brother)) + (set! (-> v1-4 0 brother) (-> proc brother)) ) ) (while (-> v1-4 0 brother) @@ -1390,15 +1444,16 @@ (nop!) (set! v1-4 (-> v1-4 0 brother)) ) - (set! (-> v1-4 0 brother) (-> arg0 ppointer)) + (set! (-> v1-4 0 brother) (-> proc ppointer)) ) - (set! (-> arg0 brother) (the-as (pointer process-tree) #f)) + (set! (-> proc brother) (the-as (pointer process-tree) #f)) ) - arg0 + proc ) ;; definition for method 9 of type process (defmethod activate ((this process) (arg0 process-tree) (arg1 basic) (arg2 pointer)) + "Move a process from dead to active, moving it to the given tree." (set! (-> this mask) (logclear (-> arg0 mask) (process-mask sleep sleep-code process-tree heap-shrunk))) (set! (-> this clock) (-> arg0 clock)) (set! (-> this status) 'ready) @@ -1472,6 +1527,7 @@ ;; definition for method 10 of type process-tree ;; WARN: Return type mismatch int vs none. (defmethod deactivate ((this process-tree)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." 0 (none) ) @@ -1489,6 +1545,7 @@ ;; ERROR: Unsupported inline assembly instruction kind - [lw ra, return-from-thread(s7)] ;; ERROR: Unsupported inline assembly instruction kind - [jr ra] (defmethod deactivate ((this process)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (local-vars (s7-0 none) (ra-0 int)) (with-pp (when (!= (-> this status) 'dead) diff --git a/test/decompiler/reference/jak2/kernel/gstring_REF.gc b/test/decompiler/reference/jak2/kernel/gstring_REF.gc index fb26ab2c61..3ca4641bfc 100644 --- a/test/decompiler/reference/jak2/kernel/gstring_REF.gc +++ b/test/decompiler/reference/jak2/kernel/gstring_REF.gc @@ -20,9 +20,10 @@ ) ;; definition for function copy-string<-string -(defun copy-string<-string ((arg0 string) (arg1 string)) - (let ((v1-0 (-> arg0 data))) - (let ((a1-1 (-> arg1 data))) +(defun copy-string<-string ((dst string) (src string)) + "Copy a string. No bounds check. Writes null terminator." + (let ((v1-0 (-> dst data))) + (let ((a1-1 (-> src data))) (while (nonzero? (-> a1-1 0)) (set! (-> v1-0 0) (-> a1-1 0)) (set! v1-0 (&-> v1-0 1)) @@ -31,7 +32,7 @@ ) (set! (-> v1-0 0) (the-as uint 0)) ) - arg0 + dst ) ;; definition for method 0 of type string @@ -55,11 +56,12 @@ ) ;; definition for function string= -(defun string= ((arg0 string) (arg1 string)) - (let ((a2-0 (-> arg0 data)) - (v1-0 (-> arg1 data)) +(defun string= ((a string) (b string)) + "Check for string equality." + (let ((a2-0 (-> a data)) + (v1-0 (-> b data)) ) - (if (or (zero? arg0) (zero? arg1)) + (if (or (zero? a) (zero? b)) (return #f) ) (while (and (nonzero? (-> a2-0 0)) (nonzero? (-> v1-0 0))) @@ -74,10 +76,11 @@ ) ;; definition for function string-prefix= -(defun string-prefix= ((arg0 string) (arg1 string)) - (let ((v1-0 (-> arg0 data))) - (let ((a2-0 (-> arg1 data))) - (if (or (zero? arg0) (zero? arg1)) +(defun string-prefix= ((prefix string) (str string)) + "Check if a string starts with a given string." + (let ((v1-0 (-> prefix data))) + (let ((a2-0 (-> str data))) + (if (or (zero? prefix) (zero? str)) (return #f) ) (while (and (nonzero? (-> v1-0 0)) (nonzero? (-> a2-0 0))) @@ -93,27 +96,29 @@ ) ;; definition for function charp-prefix= -(defun charp-prefix= ((arg0 (pointer uint8)) (arg1 (pointer uint8))) - (while (and (nonzero? (-> arg0 0)) (nonzero? (-> arg1 0))) - (if (!= (-> arg0 0) (-> arg1 0)) +(defun charp-prefix= ((prefix (pointer uint8)) (str (pointer uint8))) + "Check if a c-string starts with a given c-string." + (while (and (nonzero? (-> prefix 0)) (nonzero? (-> str 0))) + (if (!= (-> prefix 0) (-> str 0)) (return #f) ) - (set! arg0 (&-> arg0 1)) - (set! arg1 (&-> arg1 1)) + (set! prefix (&-> prefix 1)) + (set! str (&-> str 1)) ) - (zero? (-> arg0 0)) + (zero? (-> prefix 0)) ) ;; definition for function string-suffix= -(defun string-suffix= ((arg0 string) (arg1 string)) - (let ((s5-0 (-> arg0 data)) - (gp-0 (-> arg1 data)) +(defun string-suffix= ((suffix string) (str string)) + "Check if a string ends with a given string." + (let ((s5-0 (-> suffix data)) + (gp-0 (-> str data)) ) - (if (or (zero? arg0) (zero? arg1)) + (if (or (zero? suffix) (zero? str)) (return #f) ) - (let ((s4-0 (length arg0)) - (v1-5 (length arg1)) + (let ((s4-0 (length suffix)) + (v1-5 (length str)) ) (if (< s4-0 v1-5) (return #f) @@ -133,12 +138,13 @@ ) ;; definition for function string-position -(defun string-position ((arg0 string) (arg1 string)) +(defun string-position ((substr string) (base-str string)) + "Find the point where a string occurs in another. If it doesn't, return -1." (let ((s5-0 0) - (s4-0 (-> arg1 data)) + (s4-0 (-> base-str data)) ) (while (nonzero? (-> s4-0 0)) - (if (charp-prefix= (-> arg0 data) s4-0) + (if (charp-prefix= (-> substr data) s4-0) (return s5-0) ) (+! s5-0 1) @@ -149,16 +155,17 @@ ) ;; definition for function string-charp= -(defun string-charp= ((arg0 string) (arg1 (pointer uint8))) - (let ((v1-0 (-> arg0 data))) - (while (and (nonzero? (-> v1-0 0)) (nonzero? (-> arg1 0))) - (if (!= (-> v1-0 0) (-> arg1 0)) +(defun string-charp= ((a string) (b (pointer uint8))) + "Check if a string is equal to a c-string." + (let ((v1-0 (-> a data))) + (while (and (nonzero? (-> v1-0 0)) (nonzero? (-> b 0))) + (if (!= (-> v1-0 0) (-> b 0)) (return #f) ) (set! v1-0 (&-> v1-0 1)) - (set! arg1 (&-> arg1 1)) + (set! b (&-> b 1)) ) - (and (zero? (-> v1-0 0)) (zero? (-> arg1 0))) + (and (zero? (-> v1-0 0)) (zero? (-> b 0))) ) ) @@ -166,79 +173,86 @@ ;; ERROR: function was not converted to expressions. Cannot decompile. ;; definition for function copyn-string<-charp -(defun copyn-string<-charp ((arg0 string) (arg1 (pointer uint8)) (arg2 int)) - (let ((v1-0 (-> arg0 data))) - (dotimes (a3-0 arg2) - (set! (-> v1-0 0) (-> arg1 0)) +(defun copyn-string<-charp ((dst string) (src (pointer uint8)) (num-chars int)) + "Copy part of a c-string to a string. Writes null terminator after num-chars." + (let ((v1-0 (-> dst data))) + (dotimes (a3-0 num-chars) + (set! (-> v1-0 0) (-> src 0)) (set! v1-0 (&-> v1-0 1)) - (set! arg1 (&-> arg1 1)) + (set! src (&-> src 1)) ) (set! (-> v1-0 0) (the-as uint 0)) ) - arg0 + dst ) ;; definition for function string<-charp -(defun string<-charp ((arg0 string) (arg1 (pointer uint8))) - (let ((v1-0 (-> arg0 data))) - (while (nonzero? (-> arg1 0)) - (set! (-> v1-0 0) (-> arg1 0)) +(defun string<-charp ((dst string) (src (pointer uint8))) + "Copy a c-string to a string. Writes the null terminator." + (let ((v1-0 (-> dst data))) + (while (nonzero? (-> src 0)) + (set! (-> v1-0 0) (-> src 0)) (set! v1-0 (&-> v1-0 1)) - (set! arg1 (&-> arg1 1)) + (set! src (&-> src 1)) ) (set! (-> v1-0 0) (the-as uint 0)) ) - arg0 + dst ) ;; definition for function charp<-string -(defun charp<-string ((arg0 (pointer uint8)) (arg1 string)) - (let ((v1-0 (-> arg1 data))) +(defun charp<-string ((dst (pointer uint8)) (src string)) + "Copy a string to a c-string. Writes the null terminator." + (let ((v1-0 (-> src data))) (while (nonzero? (-> v1-0 0)) - (set! (-> arg0 0) (-> v1-0 0)) - (set! arg0 (&-> arg0 1)) + (set! (-> dst 0) (-> v1-0 0)) + (set! dst (&-> dst 1)) (set! v1-0 (&-> v1-0 1)) ) ) - (set! (-> arg0 0) (the-as uint 0)) + (set! (-> dst 0) (the-as uint 0)) 0 ) ;; definition for function copyn-charp<-string ;; WARN: Return type mismatch int vs none. -(defun copyn-charp<-string ((arg0 (pointer uint8)) (arg1 string) (arg2 int)) - (let ((v1-0 (-> arg1 data))) - (while (and (nonzero? (-> v1-0 0)) (< 1 arg2)) - (set! (-> arg0 0) (-> v1-0 0)) - (set! arg0 (&-> arg0 1)) +(defun copyn-charp<-string ((dst (pointer uint8)) (src string) (len int)) + "Copy part of a string to a c-string. Writes null terminator, repeatedly, to reach the given length. +If the source is longer than the length, the null terminator is still included." + (let ((v1-0 (-> src data))) + (while (and (nonzero? (-> v1-0 0)) (< 1 len)) + (set! (-> dst 0) (-> v1-0 0)) + (set! dst (&-> dst 1)) (set! v1-0 (&-> v1-0 1)) - (set! arg2 (+ arg2 -1)) + (set! len (+ len -1)) ) ) - (while (> arg2 0) - (set! (-> arg0 0) (the-as uint 0)) - (set! arg0 (&-> arg0 1)) - (set! arg2 (+ arg2 -1)) + (while (> len 0) + (set! (-> dst 0) (the-as uint 0)) + (set! dst (&-> dst 1)) + (set! len (+ len -1)) ) 0 (none) ) ;; definition for function copy-charp<-charp -(defun copy-charp<-charp ((arg0 (pointer uint8)) (arg1 (pointer uint8))) - (while (nonzero? (-> arg1 0)) - (set! (-> arg0 0) (-> arg1 0)) - (set! arg0 (&-> arg0 1)) - (set! arg1 (&-> arg1 1)) +(defun copy-charp<-charp ((dst (pointer uint8)) (src (pointer uint8))) + "C-string copy, writes null terminator." + (while (nonzero? (-> src 0)) + (set! (-> dst 0) (-> src 0)) + (set! dst (&-> dst 1)) + (set! src (&-> src 1)) ) - (set! (-> arg0 0) (the-as uint 0)) - arg0 + (set! (-> dst 0) (the-as uint 0)) + dst ) ;; definition for function cat-string<-string -(defun cat-string<-string ((arg0 string) (arg1 string)) - (let ((v1-0 (-> arg0 data))) - (let ((a1-1 (-> arg1 data))) +(defun cat-string<-string ((dst string) (src string)) + "Append a string to another." + (let ((v1-0 (-> dst data))) + (let ((a1-1 (-> src data))) (while (nonzero? (-> v1-0 0)) (nop!) (nop!) @@ -253,32 +267,34 @@ ) (set! (-> v1-0 0) (the-as uint 0)) ) - arg0 + dst ) ;; definition for function catn-string<-charp -(defun catn-string<-charp ((arg0 string) (arg1 (pointer uint8)) (arg2 int)) - (let ((v1-0 (-> arg0 data))) +(defun catn-string<-charp ((dst string) (src (pointer uint8)) (num-chars int)) + "Append part of a string to another. Writes null terminator." + (let ((v1-0 (-> dst data))) (while (nonzero? (-> v1-0 0)) (nop!) (nop!) (nop!) (set! v1-0 (&-> v1-0 1)) ) - (dotimes (a3-2 arg2) - (set! (-> v1-0 0) (-> arg1 0)) + (dotimes (a3-2 num-chars) + (set! (-> v1-0 0) (-> src 0)) (set! v1-0 (&-> v1-0 1)) - (set! arg1 (&-> arg1 1)) + (set! src (&-> src 1)) ) (set! (-> v1-0 0) (the-as uint 0)) ) - arg0 + dst ) ;; definition for function cat-string<-string_to_charp -(defun cat-string<-string_to_charp ((arg0 string) (arg1 string) (arg2 (pointer uint8))) - (let ((v1-0 (-> arg1 data)) - (v0-0 (-> arg0 data)) +(defun cat-string<-string_to_charp ((dst string) (src string) (stop-ptr (pointer uint8))) + "Append part of a string to another, up to the given pointer." + (let ((v1-0 (-> src data)) + (v0-0 (-> dst data)) ) (while (nonzero? (-> v0-0 0)) (nop!) @@ -286,7 +302,7 @@ (nop!) (set! v0-0 (&-> v0-0 1)) ) - (while (and (>= (the-as int arg2) (the-as int v1-0)) (nonzero? (-> v1-0 0))) + (while (and (>= (the-as int stop-ptr) (the-as int v1-0)) (nonzero? (-> v1-0 0))) (set! (-> v0-0 0) (-> v1-0 0)) (set! v0-0 (&-> v0-0 1)) (set! v1-0 (&-> v1-0 1)) @@ -297,15 +313,16 @@ ) ;; definition for function append-character-to-string -(defun append-character-to-string ((arg0 string) (arg1 uint8)) - (let ((v1-0 (-> arg0 data))) +(defun append-character-to-string ((str string) (char uint8)) + "Append a single character to a string. Writes null terminator after." + (let ((v1-0 (-> str data))) (while (nonzero? (-> v1-0 0)) (nop!) (nop!) (nop!) (set! v1-0 (&-> v1-0 1)) ) - (set! (-> v1-0 0) (the-as uint arg1)) + (set! (-> v1-0 0) (the-as uint char)) (set! (-> v1-0 1) (the-as uint 0)) ) 0 @@ -313,36 +330,39 @@ ) ;; definition for function charp-basename -(defun charp-basename ((arg0 (pointer uint8))) - (let ((v1-0 arg0)) +(defun charp-basename ((str (pointer uint8))) + "Strip the directory and suffix from a c-string." + (let ((v1-0 str)) (while (nonzero? (-> v1-0 0)) (set! v1-0 (&-> v1-0 1)) ) - (while (< (the-as int arg0) (the-as int v1-0)) + (while (< (the-as int str) (the-as int v1-0)) (set! v1-0 (&-> v1-0 -1)) (if (or (= (-> v1-0 0) 47) (= (-> v1-0 0) 92)) (return (&-> v1-0 1)) ) ) ) - arg0 + str ) ;; definition for function clear -(defun clear ((arg0 string)) - (set! (-> arg0 data 0) (the-as uint 0)) - arg0 +(defun clear ((str string)) + "Set string to the empty string." + (set! (-> str data 0) (the-as uint 0)) + str ) ;; definition for function string arg0 data v1-4) (-> arg1 data v1-4)) + ((< (-> a data v1-4) (-> b data v1-4)) (return #t) ) - ((< (-> arg1 data v1-4) (-> arg0 data v1-4)) + ((< (-> b data v1-4) (-> a data v1-4)) (return #f) ) ) @@ -352,14 +372,15 @@ ) ;; definition for function string>? -(defun string>? ((arg0 string) (arg1 string)) - (let ((s4-1 (min (length arg0) (length arg1)))) +(defun string>? ((a string) (b string)) + "Slightly incorrect ordering of strings." + (let ((s4-1 (min (length a) (length b)))) (dotimes (v1-4 s4-1) (cond - ((< (-> arg0 data v1-4) (-> arg1 data v1-4)) + ((< (-> a data v1-4) (-> b data v1-4)) (return #f) ) - ((< (-> arg1 data v1-4) (-> arg0 data v1-4)) + ((< (-> b data v1-4) (-> a data v1-4)) (return #t) ) ) @@ -369,14 +390,15 @@ ) ;; definition for function string<=? -(defun string<=? ((arg0 string) (arg1 string)) - (let ((s4-1 (min (length arg0) (length arg1)))) +(defun string<=? ((a string) (b string)) + "Slightly incorrect ordering of strings." + (let ((s4-1 (min (length a) (length b)))) (dotimes (v1-4 s4-1) (cond - ((< (-> arg0 data v1-4) (-> arg1 data v1-4)) + ((< (-> a data v1-4) (-> b data v1-4)) (return #t) ) - ((< (-> arg1 data v1-4) (-> arg0 data v1-4)) + ((< (-> b data v1-4) (-> a data v1-4)) (return #f) ) ) @@ -386,14 +408,15 @@ ) ;; definition for function string>=? -(defun string>=? ((arg0 string) (arg1 string)) - (let ((s4-1 (min (length arg0) (length arg1)))) +(defun string>=? ((a string) (b string)) + "Slightly incorrect ordering of strings." + (let ((s4-1 (min (length a) (length b)))) (dotimes (v1-4 s4-1) (cond - ((< (-> arg0 data v1-4) (-> arg1 data v1-4)) + ((< (-> a data v1-4) (-> b data v1-4)) (return #f) ) - ((< (-> arg1 data v1-4) (-> arg0 data v1-4)) + ((< (-> b data v1-4) (-> a data v1-4)) (return #t) ) ) @@ -407,6 +430,7 @@ ;; definition for function string-skip-to-char (defun string-skip-to-char ((arg0 (pointer uint8)) (arg1 uint)) + "Advance to the given character." (while (and (nonzero? (-> arg0 0)) (!= (-> arg0 0) arg1)) (set! arg0 (&-> arg0 1)) ) @@ -415,6 +439,7 @@ ;; definition for function string-cat-to-last-char (defun string-cat-to-last-char ((arg0 string) (arg1 string) (arg2 uint)) + "Append append-str to end of base-str, up to the last occurance of char" (let ((s4-0 (&-> (the-as (pointer uint8) arg1) 3))) (let ((v1-0 (string-skip-to-char (-> arg1 data) arg2))) (when (= (-> v1-0 0) arg2) @@ -430,6 +455,7 @@ ;; definition for function string-skip-whitespace (defun string-skip-whitespace ((arg0 (pointer uint8))) + "Jump over whitespace chars." (while (and (nonzero? (-> arg0 0)) (or (= (-> arg0 0) 32) (= (-> arg0 0) 9) (= (-> arg0 0) 13) (= (-> arg0 0) 10))) (set! arg0 (&-> arg0 1)) ) @@ -438,6 +464,7 @@ ;; definition for function string-suck-up! (defun string-suck-up! ((arg0 string) (arg1 (pointer uint8))) + "Move the string forward so the pointer is now at the beginning." (when (!= arg1 (-> arg0 data)) (let ((v1-2 (-> arg0 data))) (while (nonzero? (-> arg1 0)) @@ -454,6 +481,7 @@ ;; definition for function string-strip-leading-whitespace! (defun string-strip-leading-whitespace! ((arg0 string)) + "Strip leading whitespace." (let ((a1-0 (string-skip-whitespace (-> arg0 data)))) (string-suck-up! arg0 a1-0) ) @@ -462,6 +490,7 @@ ;; definition for function string-strip-trailing-whitespace! (defun string-strip-trailing-whitespace! ((arg0 string)) + "String trailing whitespace." (when (nonzero? (length arg0)) (let ((v1-6 (&+ (-> arg0 data) (+ (length arg0) -1)))) (while (and (>= (the-as int v1-6) (the-as int (-> arg0 data))) @@ -478,6 +507,7 @@ ;; definition for function string-strip-whitespace! (defun string-strip-whitespace! ((arg0 string)) + "Strip whitespace from the beginning and end of a string" (string-strip-trailing-whitespace! arg0) (string-strip-leading-whitespace! arg0) #f @@ -546,6 +576,7 @@ ;; definition for function string->int (defun string->int ((arg0 string)) + "Convert string to int." (let ((a0-1 (-> arg0 data)) (v0-0 0) (v1-0 #f) @@ -615,6 +646,7 @@ ;; definition for function string->float (defun string->float ((arg0 string)) + "Convert string to float. Finally implemented!" (let ((a0-1 (-> arg0 data)) (f0-0 0.0) (v1-0 #f) diff --git a/test/decompiler/reference/jak2/levels/atoll/atoll-obs_REF.gc b/test/decompiler/reference/jak2/levels/atoll/atoll-obs_REF.gc index 9fa57e9396..14aeebd640 100644 --- a/test/decompiler/reference/jak2/levels/atoll/atoll-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/atoll/atoll-obs_REF.gc @@ -133,6 +133,7 @@ ;; definition for method 10 of type piston (defmethod deactivate ((this piston)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this looping-id)) ((method-of-type process-focusable deactivate) this) (none) @@ -892,11 +893,13 @@ This commonly includes things such as: ;; definition for method 12 of type slider (defmethod run-logic? ((this slider)) + "Should this process be run? Checked by execute-process-tree." #t ) ;; definition for method 10 of type slider (defmethod deactivate ((this slider)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (the-as sound-id (-> this sound-id))) (call-parent-method this) (none) diff --git a/test/decompiler/reference/jak2/levels/atoll/atoll-tank_REF.gc b/test/decompiler/reference/jak2/levels/atoll/atoll-tank_REF.gc index 3eeb086672..e96e77f368 100644 --- a/test/decompiler/reference/jak2/levels/atoll/atoll-tank_REF.gc +++ b/test/decompiler/reference/jak2/levels/atoll/atoll-tank_REF.gc @@ -1676,6 +1676,7 @@ ;; definition for method 10 of type atoll-tank (defmethod deactivate ((this atoll-tank)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this aftermath-part)) (kill-and-free-particles (-> this aftermath-part)) ) @@ -1694,6 +1695,7 @@ ;; definition for method 12 of type atoll-tank (defmethod run-logic? ((this atoll-tank)) + "Should this process be run? Checked by execute-process-tree." #t ) diff --git a/test/decompiler/reference/jak2/levels/atoll/sniper_REF.gc b/test/decompiler/reference/jak2/levels/atoll/sniper_REF.gc index 8c5455219c..6bb681ab43 100644 --- a/test/decompiler/reference/jak2/levels/atoll/sniper_REF.gc +++ b/test/decompiler/reference/jak2/levels/atoll/sniper_REF.gc @@ -200,6 +200,7 @@ ;; definition for method 12 of type sniper (defmethod run-logic? ((this sniper)) + "Should this process be run? Checked by execute-process-tree." (let ((f0-0 573440.0)) (>= (* f0-0 f0-0) (vector-vector-distance-squared (-> this root trans) (camera-pos))) ) diff --git a/test/decompiler/reference/jak2/levels/castle/boss/castle-baron_REF.gc b/test/decompiler/reference/jak2/levels/castle/boss/castle-baron_REF.gc index 5b2f375712..b39842c6f9 100644 --- a/test/decompiler/reference/jak2/levels/castle/boss/castle-baron_REF.gc +++ b/test/decompiler/reference/jak2/levels/castle/boss/castle-baron_REF.gc @@ -129,6 +129,7 @@ This commonly includes things such as: ;; definition for method 10 of type cboss-elevator (defmethod deactivate ((this cboss-elevator)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this sound-id)) (call-parent-method this) (none) diff --git a/test/decompiler/reference/jak2/levels/castle/castle-obs_REF.gc b/test/decompiler/reference/jak2/levels/castle/castle-obs_REF.gc index cfd02a6418..a58235fc21 100644 --- a/test/decompiler/reference/jak2/levels/castle/castle-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/castle/castle-obs_REF.gc @@ -96,6 +96,7 @@ This commonly includes things such as: ;; definition for method 10 of type cas-conveyor (defmethod deactivate ((this cas-conveyor)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this sound-id)) (call-parent-method this) (none) @@ -1035,6 +1036,7 @@ This commonly includes things such as: ;; definition for method 10 of type cas-elevator (defmethod deactivate ((this cas-elevator)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this sound-id)) (call-parent-method this) (none) @@ -2184,6 +2186,7 @@ This commonly includes things such as: ;; definition for method 10 of type cas-rot-blade (defmethod deactivate ((this cas-rot-blade)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this sound-id)) (call-parent-method this) (none) diff --git a/test/decompiler/reference/jak2/levels/castle/pad/caspad-obs_REF.gc b/test/decompiler/reference/jak2/levels/castle/pad/caspad-obs_REF.gc index e783add2ac..922cf3765c 100644 --- a/test/decompiler/reference/jak2/levels/castle/pad/caspad-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/castle/pad/caspad-obs_REF.gc @@ -165,6 +165,7 @@ ;; definition for method 10 of type cpad-elevator (defmethod deactivate ((this cpad-elevator)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this sound-id)) (call-parent-method this) (none) diff --git a/test/decompiler/reference/jak2/levels/castle/roboguard-level_REF.gc b/test/decompiler/reference/jak2/levels/castle/roboguard-level_REF.gc index 15aeb34634..022fed5bc2 100644 --- a/test/decompiler/reference/jak2/levels/castle/roboguard-level_REF.gc +++ b/test/decompiler/reference/jak2/levels/castle/roboguard-level_REF.gc @@ -1218,6 +1218,7 @@ ;; definition for method 10 of type roboguard-level (defmethod deactivate ((this roboguard-level)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this roll-sound)) (call-parent-method this) (none) diff --git a/test/decompiler/reference/jak2/levels/city/bombbot/bombbot_REF.gc b/test/decompiler/reference/jak2/levels/city/bombbot/bombbot_REF.gc index ec8becb1bb..4283562d74 100644 --- a/test/decompiler/reference/jak2/levels/city/bombbot/bombbot_REF.gc +++ b/test/decompiler/reference/jak2/levels/city/bombbot/bombbot_REF.gc @@ -1357,6 +1357,7 @@ ;; definition for method 12 of type bombbot (defmethod run-logic? ((this bombbot)) + "Should this process be run? Checked by execute-process-tree." #t ) diff --git a/test/decompiler/reference/jak2/levels/city/ctywide-obs_REF.gc b/test/decompiler/reference/jak2/levels/city/ctywide-obs_REF.gc index 5811b36732..50b4637bc0 100644 --- a/test/decompiler/reference/jak2/levels/city/ctywide-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/city/ctywide-obs_REF.gc @@ -2992,6 +2992,7 @@ This commonly includes things such as: ;; definition for method 12 of type baron-statue (defmethod run-logic? ((this baron-statue)) + "Should this process be run? Checked by execute-process-tree." #t ) @@ -3936,6 +3937,7 @@ This commonly includes things such as: ;; definition for method 12 of type burning-bush (defmethod run-logic? ((this burning-bush)) + "Should this process be run? Checked by execute-process-tree." (or (not (logtest? (-> this mask) (process-mask actor-pause))) (or (and (nonzero? (-> this draw)) (logtest? (-> this draw status) (draw-control-status on-screen)) diff --git a/test/decompiler/reference/jak2/levels/city/generic/neon-praxis-part_REF.gc b/test/decompiler/reference/jak2/levels/city/generic/neon-praxis-part_REF.gc index d0bf3ba086..54bd8f3040 100644 --- a/test/decompiler/reference/jak2/levels/city/generic/neon-praxis-part_REF.gc +++ b/test/decompiler/reference/jak2/levels/city/generic/neon-praxis-part_REF.gc @@ -1098,6 +1098,7 @@ ;; definition for method 10 of type city-neon-praxis (defmethod deactivate ((this city-neon-praxis)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (dotimes (s5-0 2) (let ((a0-1 (-> this parts s5-0))) (if (nonzero? a0-1) diff --git a/test/decompiler/reference/jak2/levels/city/kiddogescort/crocesc_REF.gc b/test/decompiler/reference/jak2/levels/city/kiddogescort/crocesc_REF.gc index 770c755260..bfc0ee9ed5 100644 --- a/test/decompiler/reference/jak2/levels/city/kiddogescort/crocesc_REF.gc +++ b/test/decompiler/reference/jak2/levels/city/kiddogescort/crocesc_REF.gc @@ -277,6 +277,7 @@ ;; definition for method 12 of type crocadog-escort (defmethod run-logic? ((this crocadog-escort)) + "Should this process be run? Checked by execute-process-tree." (or (not (logtest? (process-mask enemy) (-> *setting-control* user-current process-mask))) (logtest? (-> this bot-flags) (bot-flags bf09)) ) diff --git a/test/decompiler/reference/jak2/levels/city/kiddogescort/kidesc_REF.gc b/test/decompiler/reference/jak2/levels/city/kiddogescort/kidesc_REF.gc index 2bb548553f..6991c7a912 100644 --- a/test/decompiler/reference/jak2/levels/city/kiddogescort/kidesc_REF.gc +++ b/test/decompiler/reference/jak2/levels/city/kiddogescort/kidesc_REF.gc @@ -233,6 +233,7 @@ ;; definition for method 12 of type kid-escort (defmethod run-logic? ((this kid-escort)) + "Should this process be run? Checked by execute-process-tree." (or (not (logtest? (process-mask enemy) (-> *setting-control* user-current process-mask))) (logtest? (-> this bot-flags) (bot-flags bf09)) ) diff --git a/test/decompiler/reference/jak2/levels/city/market/ashelin/ctyasha-obs_REF.gc b/test/decompiler/reference/jak2/levels/city/market/ashelin/ctyasha-obs_REF.gc index f1add1f0e5..4925a1bc72 100644 --- a/test/decompiler/reference/jak2/levels/city/market/ashelin/ctyasha-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/city/market/ashelin/ctyasha-obs_REF.gc @@ -1569,6 +1569,7 @@ This commonly includes things such as: ;; definition for method 12 of type tanker-deadly (defmethod run-logic? ((this tanker-deadly)) + "Should this process be run? Checked by execute-process-tree." #t ) diff --git a/test/decompiler/reference/jak2/levels/city/palace/ctypal-obs_REF.gc b/test/decompiler/reference/jak2/levels/city/palace/ctypal-obs_REF.gc index 38dddc95ba..851f6e8eb7 100644 --- a/test/decompiler/reference/jak2/levels/city/palace/ctypal-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/city/palace/ctypal-obs_REF.gc @@ -280,6 +280,7 @@ This commonly includes things such as: ;; definition for method 12 of type ctypal-baron-statue-broken (defmethod run-logic? ((this ctypal-baron-statue-broken)) + "Should this process be run? Checked by execute-process-tree." #t ) diff --git a/test/decompiler/reference/jak2/levels/city/port/ctyport-part_REF.gc b/test/decompiler/reference/jak2/levels/city/port/ctyport-part_REF.gc index f2c19bd6b2..72ef5627cb 100644 --- a/test/decompiler/reference/jak2/levels/city/port/ctyport-part_REF.gc +++ b/test/decompiler/reference/jak2/levels/city/port/ctyport-part_REF.gc @@ -3570,6 +3570,7 @@ ;; definition for method 10 of type hiphog-exterior-marquee (defmethod deactivate ((this hiphog-exterior-marquee)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (dotimes (s5-0 1) (let ((a0-1 (-> this parts s5-0))) (if (nonzero? a0-1) diff --git a/test/decompiler/reference/jak2/levels/city/slums/neon-baron-part_REF.gc b/test/decompiler/reference/jak2/levels/city/slums/neon-baron-part_REF.gc index 0cc5550c68..fef837d2da 100644 --- a/test/decompiler/reference/jak2/levels/city/slums/neon-baron-part_REF.gc +++ b/test/decompiler/reference/jak2/levels/city/slums/neon-baron-part_REF.gc @@ -3295,6 +3295,7 @@ ;; definition for method 10 of type neon-baron (defmethod deactivate ((this neon-baron)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (dotimes (s5-0 1) (let ((a0-1 (-> this parts s5-0))) (if (nonzero? a0-1) diff --git a/test/decompiler/reference/jak2/levels/city/traffic/traffic-manager_REF.gc b/test/decompiler/reference/jak2/levels/city/traffic/traffic-manager_REF.gc index c56458b5b2..d51e1a661f 100644 --- a/test/decompiler/reference/jak2/levels/city/traffic/traffic-manager_REF.gc +++ b/test/decompiler/reference/jak2/levels/city/traffic/traffic-manager_REF.gc @@ -407,6 +407,7 @@ ;; definition for method 10 of type traffic-manager (defmethod deactivate ((this traffic-manager)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (stop-alarm-sound (-> this traffic-engine)) (set! *traffic-manager* #f) (remove-setting *setting-control* this 'task-mask) diff --git a/test/decompiler/reference/jak2/levels/city/traffic/vehicle/transport_REF.gc b/test/decompiler/reference/jak2/levels/city/traffic/vehicle/transport_REF.gc index c251a004e7..bbc8d309db 100644 --- a/test/decompiler/reference/jak2/levels/city/traffic/vehicle/transport_REF.gc +++ b/test/decompiler/reference/jak2/levels/city/traffic/vehicle/transport_REF.gc @@ -307,6 +307,7 @@ ;; definition for method 12 of type transport (defmethod run-logic? ((this transport)) + "Should this process be run? Checked by execute-process-tree." #t ) @@ -327,6 +328,7 @@ ;; definition for method 10 of type transport (defmethod deactivate ((this transport)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this ambient-sound-id)) (call-parent-method this) (none) diff --git a/test/decompiler/reference/jak2/levels/city/traffic/vehicle/vehicle-util_REF.gc b/test/decompiler/reference/jak2/levels/city/traffic/vehicle/vehicle-util_REF.gc index 29931fa2f6..3a395cdfc3 100644 --- a/test/decompiler/reference/jak2/levels/city/traffic/vehicle/vehicle-util_REF.gc +++ b/test/decompiler/reference/jak2/levels/city/traffic/vehicle/vehicle-util_REF.gc @@ -188,6 +188,7 @@ ;; definition for method 10 of type vehicle (defmethod deactivate ((this vehicle)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (vehicle-method-110 this) (call-parent-method this) (none) diff --git a/test/decompiler/reference/jak2/levels/common/ai/bot_REF.gc b/test/decompiler/reference/jak2/levels/common/ai/bot_REF.gc index ce52962310..745c88da44 100644 --- a/test/decompiler/reference/jak2/levels/common/ai/bot_REF.gc +++ b/test/decompiler/reference/jak2/levels/common/ai/bot_REF.gc @@ -3,6 +3,7 @@ ;; definition for method 12 of type bot (defmethod run-logic? ((this bot)) + "Should this process be run? Checked by execute-process-tree." #t ) @@ -1429,6 +1430,7 @@ If the player is too far, play a warning speech." ;; definition for method 10 of type bot (defmethod deactivate ((this bot)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (send-event (handle->process (-> this health-handle)) 'hide-and-die) (if (nonzero? (-> this ai-ctrl)) (ai-task-control-method-9 (-> this ai-ctrl)) diff --git a/test/decompiler/reference/jak2/levels/common/ai/sig/sig_REF.gc b/test/decompiler/reference/jak2/levels/common/ai/sig/sig_REF.gc index b5b21015b7..1e621c9d99 100644 --- a/test/decompiler/reference/jak2/levels/common/ai/sig/sig_REF.gc +++ b/test/decompiler/reference/jak2/levels/common/ai/sig/sig_REF.gc @@ -467,6 +467,7 @@ ;; definition for method 10 of type sig (defmethod deactivate ((this sig)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (let ((v1-0 (the-as sound-rpc-set-param (get-sound-buffer-entry)))) (set! (-> v1-0 command) (sound-command set-param)) (set! (-> v1-0 id) (-> this plasma powerup-sound-id)) diff --git a/test/decompiler/reference/jak2/levels/common/airlock_REF.gc b/test/decompiler/reference/jak2/levels/common/airlock_REF.gc index b18f7d6a6b..19ef96c91c 100644 --- a/test/decompiler/reference/jak2/levels/common/airlock_REF.gc +++ b/test/decompiler/reference/jak2/levels/common/airlock_REF.gc @@ -108,6 +108,7 @@ ;; definition for method 10 of type com-airlock (defmethod deactivate ((this com-airlock)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (process-entity-status! this (entity-perm-status subtask-complete) #f) (if (nonzero? (-> this sound-id)) (sound-stop (-> this sound-id)) diff --git a/test/decompiler/reference/jak2/levels/common/elec-gate_REF.gc b/test/decompiler/reference/jak2/levels/common/elec-gate_REF.gc index 2e80e6f661..34d9212bc9 100644 --- a/test/decompiler/reference/jak2/levels/common/elec-gate_REF.gc +++ b/test/decompiler/reference/jak2/levels/common/elec-gate_REF.gc @@ -824,6 +824,7 @@ ;; definition for method 10 of type elec-gate (defmethod deactivate ((this elec-gate)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (set-elec-scale-if-close! this 0.0) (call-parent-method this) (none) diff --git a/test/decompiler/reference/jak2/levels/common/enemy/hover/crimson-guard-hover_REF.gc b/test/decompiler/reference/jak2/levels/common/enemy/hover/crimson-guard-hover_REF.gc index 5c00e4cd04..f0c6aa5293 100644 --- a/test/decompiler/reference/jak2/levels/common/enemy/hover/crimson-guard-hover_REF.gc +++ b/test/decompiler/reference/jak2/levels/common/enemy/hover/crimson-guard-hover_REF.gc @@ -1822,6 +1822,7 @@ ;; definition for method 10 of type crimson-guard-hover (defmethod deactivate ((this crimson-guard-hover)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this smoke-part)) (kill-and-free-particles (-> this smoke-part)) ) diff --git a/test/decompiler/reference/jak2/levels/common/enemy/hover/hover-enemy_REF.gc b/test/decompiler/reference/jak2/levels/common/enemy/hover/hover-enemy_REF.gc index ccbbb2a7f2..8ef4291de8 100644 --- a/test/decompiler/reference/jak2/levels/common/enemy/hover/hover-enemy_REF.gc +++ b/test/decompiler/reference/jak2/levels/common/enemy/hover/hover-enemy_REF.gc @@ -929,6 +929,7 @@ ;; definition for method 10 of type hover-enemy (defmethod deactivate ((this hover-enemy)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (hover-nav-control-method-9 (-> this hover)) ((method-of-type enemy deactivate) this) (none) diff --git a/test/decompiler/reference/jak2/levels/common/enemy/hover/wasp_REF.gc b/test/decompiler/reference/jak2/levels/common/enemy/hover/wasp_REF.gc index 8a0caf94ab..36e74d94d0 100644 --- a/test/decompiler/reference/jak2/levels/common/enemy/hover/wasp_REF.gc +++ b/test/decompiler/reference/jak2/levels/common/enemy/hover/wasp_REF.gc @@ -1472,6 +1472,7 @@ ;; definition for method 10 of type wasp (defmethod deactivate ((this wasp)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this smoke-part)) (kill-and-free-particles (-> this smoke-part)) ) diff --git a/test/decompiler/reference/jak2/levels/common/entities/com-elevator_REF.gc b/test/decompiler/reference/jak2/levels/common/entities/com-elevator_REF.gc index 2a5b6a5f8c..76ba5e9971 100644 --- a/test/decompiler/reference/jak2/levels/common/entities/com-elevator_REF.gc +++ b/test/decompiler/reference/jak2/levels/common/entities/com-elevator_REF.gc @@ -194,6 +194,7 @@ ;; definition for method 10 of type com-elevator (defmethod deactivate ((this com-elevator)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this sound-id)) (call-parent-method this) (none) @@ -341,6 +342,7 @@ For example for an elevator pre-compute the distance between the first and last ;; definition for method 10 of type tomb-trans-elevator (defmethod deactivate ((this tomb-trans-elevator)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this sound-id)) (call-parent-method this) (none) diff --git a/test/decompiler/reference/jak2/levels/common/entities/spydroid_REF.gc b/test/decompiler/reference/jak2/levels/common/entities/spydroid_REF.gc index 80ecd0bfe3..9708e0d330 100644 --- a/test/decompiler/reference/jak2/levels/common/entities/spydroid_REF.gc +++ b/test/decompiler/reference/jak2/levels/common/entities/spydroid_REF.gc @@ -1359,6 +1359,7 @@ ;; definition for method 10 of type spydroid (defmethod deactivate ((this spydroid)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this explode-part)) (kill-and-free-particles (-> this explode-part)) ) diff --git a/test/decompiler/reference/jak2/levels/common/race/race-manager_REF.gc b/test/decompiler/reference/jak2/levels/common/race/race-manager_REF.gc index 57d14b665c..ae4fdd447c 100644 --- a/test/decompiler/reference/jak2/levels/common/race/race-manager_REF.gc +++ b/test/decompiler/reference/jak2/levels/common/race/race-manager_REF.gc @@ -1603,6 +1603,7 @@ ;; definition for method 10 of type race-manager (defmethod deactivate ((this race-manager)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (persist-with-delay *setting-control* 'music-volume (seconds 3) 'music-volume 'abs 0.0 0) (send-event *traffic-manager* 'restore-default-settings) (call-parent-method this) diff --git a/test/decompiler/reference/jak2/levels/common/warp-gate_REF.gc b/test/decompiler/reference/jak2/levels/common/warp-gate_REF.gc index 193cdaf26a..e03f75163f 100644 --- a/test/decompiler/reference/jak2/levels/common/warp-gate_REF.gc +++ b/test/decompiler/reference/jak2/levels/common/warp-gate_REF.gc @@ -1177,6 +1177,7 @@ This commonly includes things such as: ;; definition for method 10 of type air-train (defmethod deactivate ((this air-train)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this hover-sound)) (if (nonzero? (-> this part-exhaust-left)) (kill-and-free-particles (-> this part-exhaust-left)) diff --git a/test/decompiler/reference/jak2/levels/demo/demo-obs_REF.gc b/test/decompiler/reference/jak2/levels/demo/demo-obs_REF.gc index 5c9fe0e5ce..2bff1bcc3f 100644 --- a/test/decompiler/reference/jak2/levels/demo/demo-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/demo/demo-obs_REF.gc @@ -60,6 +60,7 @@ ;; definition for method 10 of type demo-control (defmethod deactivate ((this demo-control)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (dotimes (s5-0 2) (set-pending-file (-> this buffer s5-0) (the-as string #f) -1 (the-as handle #f) 100000000.0) ) diff --git a/test/decompiler/reference/jak2/levels/dig/dig-digger_REF.gc b/test/decompiler/reference/jak2/levels/dig/dig-digger_REF.gc index a02363621a..dfb11dd63d 100644 --- a/test/decompiler/reference/jak2/levels/dig/dig-digger_REF.gc +++ b/test/decompiler/reference/jak2/levels/dig/dig-digger_REF.gc @@ -1513,6 +1513,7 @@ This commonly includes things such as: ;; definition for method 10 of type dig-digger (defmethod deactivate ((this dig-digger)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this smoke-part)) (kill-and-free-particles (-> this smoke-part)) ) diff --git a/test/decompiler/reference/jak2/levels/dig/dig-obs_REF.gc b/test/decompiler/reference/jak2/levels/dig/dig-obs_REF.gc index 58b4359c3f..79509f9a2d 100644 --- a/test/decompiler/reference/jak2/levels/dig/dig-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/dig/dig-obs_REF.gc @@ -576,6 +576,7 @@ ;; definition for method 12 of type dig-log (defmethod run-logic? ((this dig-log)) + "Should this process be run? Checked by execute-process-tree." #t ) @@ -833,6 +834,7 @@ This commonly includes things such as: ;; definition for method 12 of type dig-button (defmethod run-logic? ((this dig-button)) + "Should this process be run? Checked by execute-process-tree." #t ) diff --git a/test/decompiler/reference/jak2/levels/dig/dig3-obs_REF.gc b/test/decompiler/reference/jak2/levels/dig/dig3-obs_REF.gc index c8327f5032..9ad6058cf7 100644 --- a/test/decompiler/reference/jak2/levels/dig/dig3-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/dig/dig3-obs_REF.gc @@ -1172,6 +1172,7 @@ This commonly includes things such as: ;; definition for method 10 of type dig-balloon-lurker (defmethod deactivate ((this dig-balloon-lurker)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this pedal-sound-id)) ((method-of-type process-drawable deactivate) this) (none) @@ -1343,6 +1344,7 @@ This commonly includes things such as: ;; definition for method 10 of type dig-wheel-step (defmethod deactivate ((this dig-wheel-step)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this wheel-sound-id)) ((method-of-type process-drawable deactivate) this) (none) @@ -2178,6 +2180,7 @@ This commonly includes things such as: ;; definition for method 12 of type dig-totem (defmethod run-logic? ((this dig-totem)) + "Should this process be run? Checked by execute-process-tree." #t ) diff --git a/test/decompiler/reference/jak2/levels/drill/drill-mech-master_REF.gc b/test/decompiler/reference/jak2/levels/drill/drill-mech-master_REF.gc index 669951d670..e278194e6d 100644 --- a/test/decompiler/reference/jak2/levels/drill/drill-mech-master_REF.gc +++ b/test/decompiler/reference/jak2/levels/drill/drill-mech-master_REF.gc @@ -103,6 +103,7 @@ ;; definition for method 10 of type drill-mech-master (defmethod deactivate ((this drill-mech-master)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (set! *drill-mech-master* (the-as (pointer drill-mech-master) #f)) (if (nonzero? (-> this alarm-sound-id)) (sound-stop (-> this alarm-sound-id)) diff --git a/test/decompiler/reference/jak2/levels/drill/drill-obs_REF.gc b/test/decompiler/reference/jak2/levels/drill/drill-obs_REF.gc index 987159b28f..e20b3a6b0c 100644 --- a/test/decompiler/reference/jak2/levels/drill/drill-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/drill/drill-obs_REF.gc @@ -520,6 +520,7 @@ This commonly includes things such as: ;; definition for method 10 of type drill-elevator (defmethod deactivate ((this drill-elevator)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this sound-id)) (call-parent-method this) (none) @@ -689,6 +690,7 @@ do so. ;; definition for method 10 of type drill-mech-elevator (defmethod deactivate ((this drill-mech-elevator)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this running-sound-id)) (sound-stop (-> this running-sound-id)) ) @@ -937,6 +939,7 @@ For example for an elevator pre-compute the distance between the first and last ;; definition for method 10 of type fire-floor (defmethod deactivate ((this fire-floor)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this sound-id)) (if (nonzero? (-> this part-off)) (kill-and-free-particles (-> this part-off)) @@ -1173,6 +1176,7 @@ This commonly includes things such as: ;; definition for method 10 of type drill-switch (defmethod deactivate ((this drill-switch)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this green-part)) (kill-and-free-particles (-> this green-part)) ) @@ -1558,6 +1562,7 @@ This commonly includes things such as: ;; definition for method 10 of type drill-laser (defmethod deactivate ((this drill-laser)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this hit-sound-id)) ((method-of-type process-drawable deactivate) this) (none) diff --git a/test/decompiler/reference/jak2/levels/drill/drill-panel_REF.gc b/test/decompiler/reference/jak2/levels/drill/drill-panel_REF.gc index 4eebc062df..9df2716f16 100644 --- a/test/decompiler/reference/jak2/levels/drill/drill-panel_REF.gc +++ b/test/decompiler/reference/jak2/levels/drill/drill-panel_REF.gc @@ -63,6 +63,7 @@ ;; definition for method 10 of type drill-control-panel (defmethod deactivate ((this drill-control-panel)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this idle-sound-id)) (if (nonzero? (-> this debris-part)) (kill-and-free-particles (-> this debris-part)) diff --git a/test/decompiler/reference/jak2/levels/drill/ginsu_REF.gc b/test/decompiler/reference/jak2/levels/drill/ginsu_REF.gc index e051138518..cc85c267e8 100644 --- a/test/decompiler/reference/jak2/levels/drill/ginsu_REF.gc +++ b/test/decompiler/reference/jak2/levels/drill/ginsu_REF.gc @@ -984,6 +984,7 @@ ;; definition for method 10 of type ginsu (defmethod deactivate ((this ginsu)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this blade-part)) (kill-and-free-particles (-> this blade-part)) ) diff --git a/test/decompiler/reference/jak2/levels/forest/forest-obs_REF.gc b/test/decompiler/reference/jak2/levels/forest/forest-obs_REF.gc index 9d88346ca8..db7bf63c9d 100644 --- a/test/decompiler/reference/jak2/levels/forest/forest-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/forest/forest-obs_REF.gc @@ -429,6 +429,7 @@ This commonly includes things such as: ;; definition for method 10 of type forest-youngsamos (defmethod deactivate ((this forest-youngsamos)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (valid? (-> this hud) (the-as type #f) "" #t 0) (send-event (handle->process (-> this hud)) 'hide-and-die) ) diff --git a/test/decompiler/reference/jak2/levels/forest/predator_REF.gc b/test/decompiler/reference/jak2/levels/forest/predator_REF.gc index 42587746d5..8edaa6ac64 100644 --- a/test/decompiler/reference/jak2/levels/forest/predator_REF.gc +++ b/test/decompiler/reference/jak2/levels/forest/predator_REF.gc @@ -1521,6 +1521,7 @@ ;; definition for method 12 of type predator (defmethod run-logic? ((this predator)) + "Should this process be run? Checked by execute-process-tree." #t ) diff --git a/test/decompiler/reference/jak2/levels/fortress/dump/fordumpc-obs_REF.gc b/test/decompiler/reference/jak2/levels/fortress/dump/fordumpc-obs_REF.gc index 7d09ceba06..1426da55bc 100644 --- a/test/decompiler/reference/jak2/levels/fortress/dump/fordumpc-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/fortress/dump/fordumpc-obs_REF.gc @@ -409,6 +409,7 @@ This commonly includes things such as: ;; definition for method 10 of type fort-missile-target (defmethod deactivate ((this fort-missile-target)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (the-as sound-id (-> this sound-id))) (call-parent-method this) (none) @@ -968,6 +969,7 @@ This commonly includes things such as: ;; definition for method 10 of type fort-missile (defmethod deactivate ((this fort-missile)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (set-fordumpc-light-flag! #f) (send-event (handle->process (-> this hud)) 'hide-and-die) (if (nonzero? (-> this part-doom)) diff --git a/test/decompiler/reference/jak2/levels/fortress/dump/fort-robotank-turret_REF.gc b/test/decompiler/reference/jak2/levels/fortress/dump/fort-robotank-turret_REF.gc index df66fccde7..0ca2f15017 100644 --- a/test/decompiler/reference/jak2/levels/fortress/dump/fort-robotank-turret_REF.gc +++ b/test/decompiler/reference/jak2/levels/fortress/dump/fort-robotank-turret_REF.gc @@ -370,6 +370,7 @@ ;; definition for method 10 of type fort-roboscreen (defmethod deactivate ((this fort-roboscreen)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (disable *screen-filter*) (set-roboscreen-alpha! 0.0) (call-parent-method this) @@ -1536,6 +1537,7 @@ ;; definition for method 10 of type fort-robotank-turret (defmethod deactivate ((this fort-robotank-turret)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (logclear! (-> this flags) (robotank-turret-flags rotflags-6)) (sound-stop (-> this turn-sound-id)) (let ((a0-4 (handle->process (-> this screen)))) diff --git a/test/decompiler/reference/jak2/levels/fortress/dump/fort-robotank_REF.gc b/test/decompiler/reference/jak2/levels/fortress/dump/fort-robotank_REF.gc index 0a3469aef5..e93ab962e6 100644 --- a/test/decompiler/reference/jak2/levels/fortress/dump/fort-robotank_REF.gc +++ b/test/decompiler/reference/jak2/levels/fortress/dump/fort-robotank_REF.gc @@ -1037,6 +1037,7 @@ ;; definition for method 10 of type fort-robotank (defmethod deactivate ((this fort-robotank)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (stop! (-> this idle-sound)) (stop! (-> this barrel-sound)) ((method-of-type process-drawable deactivate) this) diff --git a/test/decompiler/reference/jak2/levels/fortress/exit/forexita-obs_REF.gc b/test/decompiler/reference/jak2/levels/fortress/exit/forexita-obs_REF.gc index 09e22b6a1f..97fe2c4e86 100644 --- a/test/decompiler/reference/jak2/levels/fortress/exit/forexita-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/fortress/exit/forexita-obs_REF.gc @@ -222,6 +222,7 @@ For example for an elevator pre-compute the distance between the first and last ;; definition for method 10 of type fort-lift-plat (defmethod deactivate ((this fort-lift-plat)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this sound-id)) ((method-of-type plat deactivate) this) (none) diff --git a/test/decompiler/reference/jak2/levels/fortress/rescue/forrescb-obs_REF.gc b/test/decompiler/reference/jak2/levels/fortress/rescue/forrescb-obs_REF.gc index fe7ad8a3d8..645a194163 100644 --- a/test/decompiler/reference/jak2/levels/fortress/rescue/forrescb-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/fortress/rescue/forrescb-obs_REF.gc @@ -420,6 +420,7 @@ This commonly includes things such as: ;; definition for method 10 of type fort-elec-belt-inst (defmethod deactivate ((this fort-elec-belt-inst)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this sound-id)) (call-parent-method this) (none) diff --git a/test/decompiler/reference/jak2/levels/gungame/gungame-obs_REF.gc b/test/decompiler/reference/jak2/levels/gungame/gungame-obs_REF.gc index 647d94cc69..7c4893395c 100644 --- a/test/decompiler/reference/jak2/levels/gungame/gungame-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/gungame/gungame-obs_REF.gc @@ -198,6 +198,7 @@ ;; definition for method 10 of type training-manager (defmethod deactivate ((this training-manager)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (handle->process (-> this voicebox)) (send-event (handle->process (-> this voicebox)) 'die) ) diff --git a/test/decompiler/reference/jak2/levels/hiphog/whack_REF.gc b/test/decompiler/reference/jak2/levels/hiphog/whack_REF.gc index 7cbcdeb516..023054f150 100644 --- a/test/decompiler/reference/jak2/levels/hiphog/whack_REF.gc +++ b/test/decompiler/reference/jak2/levels/hiphog/whack_REF.gc @@ -1782,6 +1782,7 @@ ;; definition for method 10 of type whack-a-metal (defmethod deactivate ((this whack-a-metal)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (dotimes (s5-0 2) (if (nonzero? (-> this score-part s5-0)) (kill-and-free-particles (-> this score-part s5-0)) diff --git a/test/decompiler/reference/jak2/levels/nest/boss/metalkor-extras_REF.gc b/test/decompiler/reference/jak2/levels/nest/boss/metalkor-extras_REF.gc index d8295cb2f3..5b136a5bd4 100644 --- a/test/decompiler/reference/jak2/levels/nest/boss/metalkor-extras_REF.gc +++ b/test/decompiler/reference/jak2/levels/nest/boss/metalkor-extras_REF.gc @@ -1707,6 +1707,7 @@ ;; definition for method 10 of type rift-ring-ingame (defmethod deactivate ((this rift-ring-ingame)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (-> this spin-sound-playing) (sound-stop (-> this spin-sound)) ) diff --git a/test/decompiler/reference/jak2/levels/nest/boss/metalkor-states_REF.gc b/test/decompiler/reference/jak2/levels/nest/boss/metalkor-states_REF.gc index 4f565c6ed4..c97b348302 100644 --- a/test/decompiler/reference/jak2/levels/nest/boss/metalkor-states_REF.gc +++ b/test/decompiler/reference/jak2/levels/nest/boss/metalkor-states_REF.gc @@ -307,6 +307,7 @@ ;; definition for method 10 of type metalkor (defmethod deactivate ((this metalkor)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (-> this wing-sound-playing) (sound-stop (-> this wing-sound)) ) diff --git a/test/decompiler/reference/jak2/levels/palace/boss/squid-extras_REF.gc b/test/decompiler/reference/jak2/levels/palace/boss/squid-extras_REF.gc index a963e7247f..47cb64e651 100644 --- a/test/decompiler/reference/jak2/levels/palace/boss/squid-extras_REF.gc +++ b/test/decompiler/reference/jak2/levels/palace/boss/squid-extras_REF.gc @@ -429,6 +429,7 @@ ;; definition for method 10 of type squid-whirlwind (defmethod deactivate ((this squid-whirlwind)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (-> this whirl-sound-playing) (sound-stop (-> this whirl-sound)) ) diff --git a/test/decompiler/reference/jak2/levels/palace/boss/squid-setup_REF.gc b/test/decompiler/reference/jak2/levels/palace/boss/squid-setup_REF.gc index 4b4983781a..63f872edf8 100644 --- a/test/decompiler/reference/jak2/levels/palace/boss/squid-setup_REF.gc +++ b/test/decompiler/reference/jak2/levels/palace/boss/squid-setup_REF.gc @@ -1748,6 +1748,7 @@ ;; definition for method 10 of type squid (defmethod deactivate ((this squid)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this thruster-part)) (kill-and-free-particles (-> this thruster-part)) ) diff --git a/test/decompiler/reference/jak2/levels/palace/cable/palcab-obs_REF.gc b/test/decompiler/reference/jak2/levels/palace/cable/palcab-obs_REF.gc index 15dac58b07..66a524c469 100644 --- a/test/decompiler/reference/jak2/levels/palace/cable/palcab-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/palace/cable/palcab-obs_REF.gc @@ -1015,6 +1015,7 @@ This commonly includes things such as: ;; definition for method 10 of type pal-rot-gun (defmethod deactivate ((this pal-rot-gun)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this sound-id)) (sound-stop (-> this shot-sound-id)) (call-parent-method this) diff --git a/test/decompiler/reference/jak2/levels/sewer/sew-gunturret_REF.gc b/test/decompiler/reference/jak2/levels/sewer/sew-gunturret_REF.gc index 46d54937d7..220a1bbfa2 100644 --- a/test/decompiler/reference/jak2/levels/sewer/sew-gunturret_REF.gc +++ b/test/decompiler/reference/jak2/levels/sewer/sew-gunturret_REF.gc @@ -1049,6 +1049,7 @@ ;; definition for method 10 of type sew-gunturret (defmethod deactivate ((this sew-gunturret)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this smoke-part)) (kill-and-free-particles (-> this smoke-part)) ) diff --git a/test/decompiler/reference/jak2/levels/sewer/sewer-obs2_REF.gc b/test/decompiler/reference/jak2/levels/sewer/sewer-obs2_REF.gc index 76f7ab19c0..154cba33f0 100644 --- a/test/decompiler/reference/jak2/levels/sewer/sewer-obs2_REF.gc +++ b/test/decompiler/reference/jak2/levels/sewer/sewer-obs2_REF.gc @@ -148,6 +148,7 @@ ;; definition for method 10 of type sew-elevator (defmethod deactivate ((this sew-elevator)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this sound-id)) (call-parent-method this) (none) @@ -627,6 +628,7 @@ This commonly includes things such as: ;; definition for method 12 of type sew-mar-statue (defmethod run-logic? ((this sew-mar-statue)) + "Should this process be run? Checked by execute-process-tree." #t ) diff --git a/test/decompiler/reference/jak2/levels/stadium/skate/skatea-obs_REF.gc b/test/decompiler/reference/jak2/levels/stadium/skate/skatea-obs_REF.gc index 0f3e463717..ad4c796586 100644 --- a/test/decompiler/reference/jak2/levels/stadium/skate/skatea-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/stadium/skate/skatea-obs_REF.gc @@ -1359,6 +1359,7 @@ ;; definition for method 10 of type hoverboard-training-manager (defmethod deactivate ((this hoverboard-training-manager)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (send-event *traffic-manager* 'restore-default-settings) (call-parent-method this) (none) diff --git a/test/decompiler/reference/jak2/levels/stadium/stadium-obs_REF.gc b/test/decompiler/reference/jak2/levels/stadium/stadium-obs_REF.gc index 3a517bf8f3..d48c5edf39 100644 --- a/test/decompiler/reference/jak2/levels/stadium/stadium-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/stadium/stadium-obs_REF.gc @@ -1096,6 +1096,7 @@ This commonly includes things such as: ;; definition for method 10 of type rift-rider (defmethod deactivate ((this rift-rider)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this sound-id)) (call-parent-method this) (none) @@ -2128,6 +2129,7 @@ This commonly includes things such as: ;; definition for method 10 of type stad-samos (defmethod deactivate ((this stad-samos)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (valid? (-> this hud) (the-as type #f) "" #t 0) (send-event (handle->process (-> this hud)) 'hide-and-die) ) @@ -2786,6 +2788,7 @@ This commonly includes things such as: ;; definition for method 12 of type stad-force-field (defmethod run-logic? ((this stad-force-field)) + "Should this process be run? Checked by execute-process-tree." #t ) diff --git a/test/decompiler/reference/jak2/levels/strip/chaincrate_REF.gc b/test/decompiler/reference/jak2/levels/strip/chaincrate_REF.gc index 54408f571b..f2378165e4 100644 --- a/test/decompiler/reference/jak2/levels/strip/chaincrate_REF.gc +++ b/test/decompiler/reference/jak2/levels/strip/chaincrate_REF.gc @@ -267,6 +267,7 @@ ;; definition for method 10 of type strip-chain-crate-slave (defmethod deactivate ((this strip-chain-crate-slave)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this part2)) (kill-and-free-particles (-> this part2)) ) diff --git a/test/decompiler/reference/jak2/levels/strip/strip-drop_REF.gc b/test/decompiler/reference/jak2/levels/strip/strip-drop_REF.gc index a626c87cb5..d11d054cde 100644 --- a/test/decompiler/reference/jak2/levels/strip/strip-drop_REF.gc +++ b/test/decompiler/reference/jak2/levels/strip/strip-drop_REF.gc @@ -368,6 +368,7 @@ ;; definition for method 10 of type crane (defmethod deactivate ((this crane)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (-> this crate) (deactivate (-> this crate 0)) ) diff --git a/test/decompiler/reference/jak2/levels/strip/strip-obs_REF.gc b/test/decompiler/reference/jak2/levels/strip/strip-obs_REF.gc index 7585467eaf..41d78cc098 100644 --- a/test/decompiler/reference/jak2/levels/strip/strip-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/strip/strip-obs_REF.gc @@ -649,6 +649,7 @@ This commonly includes things such as: ;; definition for method 10 of type grenade-point (defmethod deactivate ((this grenade-point)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this part2)) (kill-and-free-particles (-> this part2)) ) @@ -1718,6 +1719,7 @@ This commonly includes things such as: ;; definition for method 10 of type drill-plat (defmethod deactivate ((this drill-plat)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this plat-sound)) (stop! (-> this plat-sound)) ) diff --git a/test/decompiler/reference/jak2/levels/title/title-obs_REF.gc b/test/decompiler/reference/jak2/levels/title/title-obs_REF.gc index 7dfb563094..e574eead32 100644 --- a/test/decompiler/reference/jak2/levels/title/title-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/title/title-obs_REF.gc @@ -67,6 +67,7 @@ ;; definition for method 10 of type title-control (defmethod deactivate ((this title-control)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (dotimes (s5-0 2) (set-pending-file (-> this buffer s5-0) (the-as string #f) -1 (the-as handle #f) 100000000.0) ) diff --git a/test/decompiler/reference/jak2/levels/tomb/tomb-obs_REF.gc b/test/decompiler/reference/jak2/levels/tomb/tomb-obs_REF.gc index 2bf6681574..20728ac687 100644 --- a/test/decompiler/reference/jak2/levels/tomb/tomb-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/tomb/tomb-obs_REF.gc @@ -1745,6 +1745,7 @@ This commonly includes things such as: ;; definition for method 10 of type tomb-plat-return (defmethod deactivate ((this tomb-plat-return)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this sound-id)) (call-parent-method this) (none) @@ -2108,6 +2109,7 @@ This commonly includes things such as: ;; definition for method 10 of type tomb-sphinx (defmethod deactivate ((this tomb-sphinx)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this sound-id)) (call-parent-method this) (none) diff --git a/test/decompiler/reference/jak2/levels/tomb/widow-extras_REF.gc b/test/decompiler/reference/jak2/levels/tomb/widow-extras_REF.gc index b4f0559046..be99bf7d1e 100644 --- a/test/decompiler/reference/jak2/levels/tomb/widow-extras_REF.gc +++ b/test/decompiler/reference/jak2/levels/tomb/widow-extras_REF.gc @@ -1251,6 +1251,7 @@ This commonly includes things such as: ;; definition for method 10 of type widow-bomb (defmethod deactivate ((this widow-bomb)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this explode-part)) (kill-and-free-particles (-> this explode-part)) ) @@ -1671,6 +1672,7 @@ This commonly includes things such as: ;; definition for method 10 of type tomb-boss-pillar (defmethod deactivate ((this tomb-boss-pillar)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this explode-part)) (kill-and-free-particles (-> this explode-part)) ) diff --git a/test/decompiler/reference/jak2/levels/tomb/widow2_REF.gc b/test/decompiler/reference/jak2/levels/tomb/widow2_REF.gc index 8ff55dd3d9..f4504e4f04 100644 --- a/test/decompiler/reference/jak2/levels/tomb/widow2_REF.gc +++ b/test/decompiler/reference/jak2/levels/tomb/widow2_REF.gc @@ -94,6 +94,7 @@ ;; definition for method 10 of type widow (defmethod deactivate ((this widow)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this drill-spark-part)) (kill-and-free-particles (-> this drill-spark-part)) ) diff --git a/test/decompiler/reference/jak2/levels/under/centipede_REF.gc b/test/decompiler/reference/jak2/levels/under/centipede_REF.gc index d5cd7cc118..51fb664864 100644 --- a/test/decompiler/reference/jak2/levels/under/centipede_REF.gc +++ b/test/decompiler/reference/jak2/levels/under/centipede_REF.gc @@ -242,6 +242,7 @@ ;; definition for method 10 of type centipede (defmethod deactivate ((this centipede)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (when (-> this set-camera-mode?) (set! (-> this set-camera-mode?) #f) (remove-setting-by-arg0 *setting-control* 'mode-name) diff --git a/test/decompiler/reference/jak2/levels/under/jellyfish_REF.gc b/test/decompiler/reference/jak2/levels/under/jellyfish_REF.gc index d001d170ca..af7c65e0db 100644 --- a/test/decompiler/reference/jak2/levels/under/jellyfish_REF.gc +++ b/test/decompiler/reference/jak2/levels/under/jellyfish_REF.gc @@ -1286,6 +1286,7 @@ ;; definition for method 10 of type jellyfish (defmethod deactivate ((this jellyfish)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this sound-id)) (call-parent-method this) (none) diff --git a/test/decompiler/reference/jak2/levels/under/under-obs_REF.gc b/test/decompiler/reference/jak2/levels/under/under-obs_REF.gc index 4444d20597..e3a7c5fa84 100644 --- a/test/decompiler/reference/jak2/levels/under/under-obs_REF.gc +++ b/test/decompiler/reference/jak2/levels/under/under-obs_REF.gc @@ -384,6 +384,7 @@ ;; definition for method 10 of type bubbler (defmethod deactivate ((this bubbler)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this ambient-id)) ((method-of-type process-drawable deactivate) this) (none) @@ -1743,6 +1744,7 @@ This commonly includes things such as: ;; definition for method 10 of type under-lift (defmethod deactivate ((this under-lift)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this sound-id)) (call-parent-method this) (none) diff --git a/test/decompiler/reference/jak2/levels/under/under-shoot-block_REF.gc b/test/decompiler/reference/jak2/levels/under/under-shoot-block_REF.gc index fcddc5ad81..f11fa193f6 100644 --- a/test/decompiler/reference/jak2/levels/under/under-shoot-block_REF.gc +++ b/test/decompiler/reference/jak2/levels/under/under-shoot-block_REF.gc @@ -2335,6 +2335,7 @@ ;; definition for method 10 of type under-shoot-block (defmethod deactivate ((this under-shoot-block)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (let ((s5-0 (-> this puzzle spawners))) (countdown (s4-0 (-> s5-0 length)) (let ((s3-0 (-> s5-0 s4-0))) diff --git a/test/decompiler/reference/jak2/levels/under/underb-master_REF.gc b/test/decompiler/reference/jak2/levels/under/underb-master_REF.gc index 956d4a36a1..76be9b64fe 100644 --- a/test/decompiler/reference/jak2/levels/under/underb-master_REF.gc +++ b/test/decompiler/reference/jak2/levels/under/underb-master_REF.gc @@ -205,6 +205,7 @@ ;; definition for method 10 of type underb-master (defmethod deactivate ((this underb-master)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (sound-stop (-> this ambient-sound-id)) (send-event (handle->process (-> this warp-handle)) 'die-fast) (set! *underb-master* (the-as (pointer underb-master) #f)) @@ -706,6 +707,7 @@ ;; definition for method 10 of type under-locking (defmethod deactivate ((this under-locking)) + "Make a process dead, clean it up, remove it from the active pool, and return to dead pool." (if (nonzero? (-> this draining-part)) (kill-and-free-particles (-> this draining-part)) ) diff --git a/test/decompiler/reference/jak3/engine/anim/aligner-h_REF.gc b/test/decompiler/reference/jak3/engine/anim/aligner-h_REF.gc index 975becda60..29aa31e110 100644 --- a/test/decompiler/reference/jak3/engine/anim/aligner-h_REF.gc +++ b/test/decompiler/reference/jak3/engine/anim/aligner-h_REF.gc @@ -46,16 +46,12 @@ ;; definition for method 0 of type align-control ;; WARN: Return type mismatch object vs align-control. (defmethod new align-control ((allocation symbol) (type-to-make type) (arg0 process)) - (let ((v0-0 (the-as object (object-new allocation type-to-make (the-as int (-> type-to-make size)))))) - (when (zero? (the-as align-control v0-0)) + (let ((this (object-new allocation type-to-make (the-as int (-> type-to-make size))))) + (when (zero? this) (go process-drawable-art-error "memory") (return (the-as align-control 0)) ) - (set! (-> (the-as align-control v0-0) process) (the-as process-drawable arg0)) - (the-as align-control v0-0) + (set! (-> this process) (the-as process-drawable arg0)) + (the-as align-control this) ) ) - - - - diff --git a/test/decompiler/reference/jak3/engine/gfx/texture/texture_REF.gc b/test/decompiler/reference/jak3/engine/gfx/texture/texture_REF.gc index 9a39195778..4d9fcf480c 100644 --- a/test/decompiler/reference/jak3/engine/gfx/texture/texture_REF.gc +++ b/test/decompiler/reference/jak3/engine/gfx/texture/texture_REF.gc @@ -366,13 +366,13 @@ ) ;; definition for method 10 of type texture-page -(defmethod get-leftover-block-count ((this texture-page) (arg0 int) (arg1 int)) +(defmethod get-leftover-block-count ((this texture-page) (num-segments int) (upload-offset int)) "Unused - statistics for how much unused memory we have" - (let ((v1-0 arg1)) - (dotimes (a2-1 arg0) - (+! v1-0 (-> this segment a2-1 size)) + (let ((offset upload-offset)) + (dotimes (i num-segments) + (+! offset (-> this segment i size)) ) - (logand (/ v1-0 64) 63) + (logand (/ offset 64) 63) ) ) diff --git a/test/decompiler/reference/jak3/engine/math/vector_REF.gc b/test/decompiler/reference/jak3/engine/math/vector_REF.gc index a9bc430bed..adcc9b6c4b 100644 --- a/test/decompiler/reference/jak3/engine/math/vector_REF.gc +++ b/test/decompiler/reference/jak3/engine/math/vector_REF.gc @@ -890,19 +890,19 @@ ) ;; definition for function vector-xz-normalize! -(defun vector-xz-normalize! ((arg0 vector) (arg1 float)) +(defun vector-xz-normalize! ((vec vector) (arg1 float)) "Normalize, xz components only." - (let* ((v1-0 arg0) + (let* ((v1-0 vec) (f0-4 (sqrtf (+ (* (-> v1-0 x) (-> v1-0 x)) (* (-> v1-0 z) (-> v1-0 z))))) ) (when (!= f0-4 0.0) (let ((v1-3 (/ arg1 f0-4))) - (set! (-> arg0 x) (* (-> arg0 x) v1-3)) - (set! (-> arg0 z) (* (-> arg0 z) v1-3)) + (set! (-> vec x) (* (-> vec x) v1-3)) + (set! (-> vec z) (* (-> vec z) v1-3)) ) ) ) - arg0 + vec ) ;; definition for function vector-xz-normalize-copy! @@ -1753,7 +1753,3 @@ ) arg0 ) - - - -