clean up and document LoadIndexedFile

src/constants.a

@@ -7,7 +7,7 @@
 ;
 ; LC RAM BANK 1
 ; D000..E789 - persistent data structures (gGlobalPrefsStore, gGamesListStore)
-; E95E..FFF1 - main program code
+; E911..FFF1 - main program code
 ; FFF2..FFF9 - API functions and global constants available for main program
 ;              code, prelaunchers, transition effects, &c.
 ;              (Wait/UnwaitForVBL, MockingboardStuff, MachineStatus)

src/glue.prorwts2.a

@@ -1,22 +1,24 @@
 ;license:MIT
-;(c) 2018-2020 by 4am & qkumba
+;(c) 2018-2021 by 4am & qkumba
 ;
 ; ProRWTS2 glue functions
 ;
 ; Public functions
 ; - LoadFile
+; - LoadAuxFile
 ; - LoadDHRFile
+; - LoadIndexedFile
 ;
 ; Public variables
 ; - gRootDirectory
 ;
 ; A general note about paths:
 ;
-; LoadFile, LoadDHRFile, and SaveSmallFile support subdirectories.
+; Load[*]File routines support subdirectories. Directories are delimited by '/'
-; Directories are delimited by '/' like ProDOS. At program startup, we get the
+; like ProDOS. At program startup, we get the current directory and save it;
-; current directory and save it; that is the PROGRAM ROOT DIRECTORY. All
+; that is the PROGRAM ROOT DIRECTORY. All pathnames are relative to the PROGRAM
-; pathnames are relative to the PROGRAM ROOT DIRECTORY. There is no concept of
+; ROOT DIRECTORY. There is no concept of setting or changing the 'current'
-; setting or changing the 'current' directory.
+; directory.
 ;
 ; The PROGRAM ROOT DIRECTORY is not guaranteed to be the root directory of the
 ; underlying ProDOS disk (although it can be). But it doesn't matter, because
@@ -109,5 +111,81 @@ LoadDHRFile
          jsr   LoadDHRFileInternal
          jmp   SwitchToBank1
 
+;------------------------------------------------------------------------------
+; LoadIndexedFile
+; Load a file from inside an indexed file, all at once
+;
+; To save disk space, some collections of small, related files (e.g. per-game
+; help files) are merged into a single data file with an associated index file.
+; The index stores the original filename along with an offset (into the merged
+; data file) and a length.
+;
+; Callers are responsible for loading the index file and finding the relevant
+; record within the index. Most callers use okvs_find() for this.
+;
+; in:    stack contains 6 bytes of parameters:
+;          +1 [word] pointer to filename of merged data file
+;          +3 [word] address of load destination
+;          +5 [word] pointer to index record (see note)
+; out:   all flags clobbered
+;        all registers clobbered
+;------------------------------------------------------------------------------
+LoadIndexedFile
+         +PARAMS_ON_STACK 6
+         +LDPARAM 1
+         +ST16 @filename
+         +LDPARAM 3
+         +ST16 @address
+         +LDPARAM 5
+         +ST16 zpword
+         inc   $BF0E                 ; disable ROM mapping on return
+         ldx   #2
+         ldy   #0
+         lda   (zpword), y
+         tay
+-        iny
+         lda   (zpword), y
+         sta   @offset, x
+         dex
+         bpl   -
+         dex
+-        iny
+         lda   (zpword), y
+         sta   @size - $fe, x
+         inx
+         bmi   -
+         jsr   $bf00                 ; yes, ProDOS abstraction
+         !byte $c8
+         !word @c8_parms
+         jsr   $bf00
+         !byte $ce
+         !word @ce_parms
+         jsr   $bf00
+         !byte $ca
+         !word @ca_parms
+         jsr   $bf00
+         !byte $cc
+         !word @cc_parms
+         dec   $BF0E                 ; re-enable ROM mapping on return
+         jmp   SwitchToBank1
+
+@c8_parms
+         !byte 3
+@filename
+         !word $DFDF                 ; SMC
+         !byte 0
+@ce_parms
+         !byte $d0
+         !byte 1
+@offset  !byte 0, 0, 0               ; SMC
+         !byte $ff
+@ca_parms
+         !byte $ff
+@cc_parms
+         !byte 1
+@address !word $DFDF                 ; SMC
+@size    !word $DFDF                 ; SMC
+         !word $ffff
+
 gRootDirectory
          !word $FDFD

src/ui.attract.dhgr.a

@@ -144,7 +144,7 @@ LoadDHGRTransition
          jsr   pref_get              ; get DHGR transition effect from prefs
          !word kNextDFX
          !word -
-         +ST16 zpword                ; A/Y = filename (don't load file yet)
+         +ST16 @indexRecordPtr       ; A/Y = filename (don't load file yet)
                                      ; $WINDEX = index of the transition in DFX store
          +LDADDR -
          jsr   okvs_next             ; get transition after this one
@@ -154,9 +154,11 @@ LoadDHGRTransition
          !word kNextDFX
 +        !word $FDFD                 ; SMC
 
-         jsr   LoadFulFile
+         jsr   LoadIndexedFile
          !word kDFXFile
          !word $6000
+@indexRecordPtr
+         !word $FDFD                 ; SMC
          rts
 
 ;------------------------------------------------------------------------------

src/ui.attract.hgr.a

@@ -37,7 +37,7 @@ HGRActionSlideshow
          jsr   okvs_iter             ; cycle through all listed HGR files
          !word gSlideshowStore
          !word HGRActionCallback     ; address of callback (called on each file)
-HGRRTS   rts                         ; exit with last picture still visible
+         rts                         ; exit with last picture still visible
 
 ;------------------------------------------------------------------------------
 ; HGRSingle
@@ -75,7 +75,7 @@ LoadHGRTransition
          jsr   pref_get              ; get HGR transition effect from prefs
          !word kNextFX
          !word -
-         +ST16 zpword                ; A/Y = filename (don't load file yet)
+         +ST16 @indexRecordPtr       ; A/Y = filename (don't load file yet)
                                      ; $WINDEX = index of the transition in FX store
          +LDADDR -
          jsr   okvs_next             ; get transition after this one
@@ -85,10 +85,12 @@ LoadHGRTransition
          !word kNextFX
 +        !word $FDFD                 ; SMC
 
-         jsr   LoadFulFile
+         jsr   LoadIndexedFile
          !word kFXFile
          !word $6000
-         rts
+@indexRecordPtr
+         !word $FDFD                 ; SMC
+HGRRTS   rts
 
 ;------------------------------------------------------------------------------
 ; HGRTitleCallback [private]

src/ui.attract.mode.a

@@ -78,13 +78,18 @@ MiniAttractMode
          !word kRootDirectory
          !word kMiniAttractIndexFile
 -        !word $6000
+
          jsr   okvs_find
          !word -
 +        !word $FDFD                 ; SMC
-         +ST16 zpword
+         +ST16 @indexRecordPtr
-         jsr   LoadFulFile
+
+         jsr   LoadIndexedFile
          !word kAttractModeFulFile
 -        !word $6000
+@indexRecordPtr
+         !word $FDFD                 ; SMC
+
          +LDADDR -
          jsr   okvs_len
          lda   WCOUNT
@@ -180,10 +185,11 @@ RunAttractModule
          jsr   okvs_find
          !word -
 @key2    !word $FDFD                 ; SMC
-         +ST16 zpword
+         +ST16 +
-         jsr   LoadFulFile
+         jsr   LoadIndexedFile
          !word kAttractModeSlideshowFulFile
          !word $800
++        !word $FDFD                 ; SMC
          pla                         ; restore module type
 
 -        and   #$0F                  ; convert ASCII digit to int

src/ui.credits.a

@@ -6,7 +6,6 @@
 ; Public functions
 ; - Credits
 ; - Help
-; - LoadFulFile
 ;
 
 ;------------------------------------------------------------------------------
@@ -22,10 +21,12 @@ Credits
          !word kRootDirectory
          !word kCreditsFile
          !word $8000
---       jsr   ForceHGRMode
+.clearAndDisplayHelp
+         jsr   ForceHGRMode
          jsr   ClearOffscreen
          ldx   #0
--        lda   OffscreenPage
+.displayHelp
+         lda   OffscreenPage
          ror                         ; draw on offscreen page
          +LDADDR $8000
          jsr   DrawPage              ; draw credits
@@ -53,90 +54,32 @@ Credits
 Help
          jsr   GetGameToLaunch
          bcs   @global
-         +ST16 ++
+         +ST16 @game
+
          jsr   LoadFile
          !word kRootDirectory
          !word kGameHelpIndexFile
--        !word $6000
+@okvsPtr !word $6000
+
          jsr   okvs_find
-         !word -
+         !word @okvsPtr
-++       !word $DFDF                ; SMC
+@game    !word $FDFD                 ; SMC
-         +ST16 zpword
+         +ST16 @indexRecordPtr
-         jsr   LoadFulFile
+
+         jsr   LoadIndexedFile
          !word kGameHelpFile
          !word $8000
+@indexRecordPtr
+         !word $FDFD                 ; SMC
+
          clc
-         bcc   --                    ; always branches
+         bcc   .clearAndDisplayHelp  ; always branches
+
 @global  jsr   LoadFile              ; load help text into $8000
          !word kRootDirectory
          !word kHelpTextFile
          !word $8000
+
          jsr   LoadHelpOffscreen     ; load fancy backdrop
          ldx   #7
-         bne   --                    ; always branches
+         bne   .displayHelp          ; always branches
-
-;------------------------------------------------------------------------------
-; LoadFulFile
-; Load a *ful file (compiled okvs with offset value) into memory all at once
-;
-; in:    stack contains 4 bytes of parameters:
-;          +1 [word] pointer to filename to open
-;          +3 [word] address of load destination
-;        zpword: pointer to okvs key field
-; out:   all flags clobbered
-;        all registers clobbered
-;------------------------------------------------------------------------------
-LoadFulFile
-         +PARAMS_ON_STACK 4
-         +LDPARAM 1
-         +ST16 @filename
-         +LDPARAM 3
-         +ST16 @address
-         inc   $BF0E                 ; disable ROM mapping on return
-         ldx   #2
-         ldy   #0
-         lda   (zpword), y
-         tay
--        iny
-         lda   (zpword), y
-         sta   @offset, x
-         dex
-         bpl   -
-         dex
--        iny
-         lda   (zpword), y
-         sta   @size - $fe, x
-         inx
-         bmi   -
-         jsr   $bf00                 ; yes, ProDOS abstraction
-         !byte $c8
-         !word @c8_parms
-         jsr   $bf00
-         !byte $ce
-         !word @ce_parms
-         jsr   $bf00
-         !byte $ca
-         !word @ca_parms
-         jsr   $bf00
-         !byte $cc
-         !word @cc_parms
-         dec   $BF0E                 ; re-enable ROM mapping on return
-         jmp   SwitchToBank1
-
-@c8_parms
-         !byte 3
-@filename
-         !word $DFDF                 ; SMC
-         !byte 0
-@ce_parms
-         !byte $d0
-         !byte 1
-@offset  !byte 0, 0, 0               ; SMC
-         !byte $ff
-@ca_parms
-         !byte $ff
-@cc_parms
-         !byte 1
-@address !word $DFDF                 ; SMC
-@size    !word $DFDF                 ; SMC
-         !word $ffff