fcdev 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (260) hide show
  1. package/README.md +21 -2
  2. package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +164 -0
  3. package/docs/02-/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +157 -0
  4. package/docs/03-/347/233/256/346/240/207/350/247/204/350/214/203.md +123 -0
  5. package/docs/04-cc65/345/267/245/345/205/267/351/223/276.md +51 -0
  6. package/docs/05-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +100 -0
  7. package/docs/06-/345/217/215/346/261/207/347/274/226.md +103 -0
  8. package/docs/07-/345/210/233/345/273/272/345/214/205/344/270/216/346/250/241/346/235/277.md +74 -0
  9. package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +72 -0
  10. package/docs/09-/345/217/221/345/270/203.md +67 -0
  11. package/docs/10-VS Code/346/211/251/345/261/225.md" +131 -0
  12. package/docs/nes/01-NES/347/233/256/346/240/207.md +52 -0
  13. package/docs/sb2000/01-/345/274/200/345/217/221/346/214/207/345/215/227.md +252 -0
  14. package/docs/sb2000/02-/347/263/273/347/273/237/350/260/203/347/224/250/346/211/213/345/206/214.md +797 -0
  15. package/docs/sb2000/03-/347/241/254/344/273/266/350/257/264/346/230/216.md +27 -0
  16. package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +46 -0
  17. package/docs//347/274/272/351/231/267/350/256/260/345/275/225.md +10 -0
  18. package/package.json +4 -3
  19. package/src/api/header-parser.mjs +78 -0
  20. package/src/api/index.mjs +128 -0
  21. package/src/build/bank-link-config.mjs +74 -0
  22. package/src/build/index.mjs +1 -0
  23. package/src/build/program-builder.mjs +5 -2
  24. package/src/cli/commands/api-command.mjs +62 -0
  25. package/src/cli/commands/docs-command.mjs +58 -0
  26. package/src/cli/index.mjs +6 -0
  27. package/src/docs/doc-index.mjs +101 -0
  28. package/src/docs/doc-topics.mjs +38 -0
  29. package/src/docs/index.mjs +10 -0
  30. package/src/targets/target-registry.mjs +38 -0
  31. package/targets/nes/lib/fcnes.lib +0 -0
  32. package/targets/nes/lib/nes-font.o +0 -0
  33. package/targets/sb2000/api-reference.md +3295 -0
  34. package/targets/sb2000/api-unwrapped.json +36 -0
  35. package/targets/sb2000/asminc/sb2000.inc +203 -1
  36. package/targets/sb2000/include/sb2000-bank.h +74 -0
  37. package/targets/sb2000/include/sb2000-clock.h +68 -0
  38. package/targets/sb2000/include/sb2000-disk.h +141 -0
  39. package/targets/sb2000/include/sb2000-display.h +352 -0
  40. package/targets/sb2000/include/sb2000-file.h +273 -0
  41. package/targets/sb2000/include/sb2000-ime.h +158 -0
  42. package/targets/sb2000/include/sb2000-input.h +192 -0
  43. package/targets/sb2000/include/sb2000-math.h +228 -0
  44. package/targets/sb2000/include/sb2000-memory.h +115 -0
  45. package/targets/sb2000/include/sb2000-printer.h +116 -0
  46. package/targets/sb2000/include/sb2000-sound.h +134 -0
  47. package/targets/sb2000/include/sb2000-symbols.h +397 -1
  48. package/targets/sb2000/include/sb2000-system.h +219 -0
  49. package/targets/sb2000/include/sb2000-text.h +99 -0
  50. package/targets/sb2000/include/sb2000.h +13 -20
  51. package/targets/sb2000/lib/crt0.o +0 -0
  52. package/targets/sb2000/lib/sb2000.lib +0 -0
  53. package/targets/sb2000/lib-build.json +1 -1
  54. package/targets/sb2000/link-banked.cfg +42 -0
  55. package/targets/sb2000/src/crt0.s +89 -4
  56. package/targets/sb2000/src/lib/bank/sb-bank-current.c +18 -0
  57. package/targets/sb2000/src/lib/bank/sb-bank-select.c +21 -0
  58. package/targets/sb2000/src/lib/bank/sbi-bank-trampoline.s +46 -0
  59. package/targets/sb2000/src/lib/clock/sb-clock-get-date.c +17 -0
  60. package/targets/sb2000/src/lib/clock/sb-clock-get-time.c +17 -0
  61. package/targets/sb2000/src/lib/clock/sb-clock-set-date.c +21 -0
  62. package/targets/sb2000/src/lib/clock/sb-clock-set-time.c +17 -0
  63. package/targets/sb2000/src/lib/clock/sbi-date-from-fat.c +20 -0
  64. package/targets/sb2000/src/lib/clock/sbi-date-to-fat.c +24 -0
  65. package/targets/sb2000/src/lib/clock/sbi-time-from-fat.c +20 -0
  66. package/targets/sb2000/src/lib/clock/sbi-time-to-fat.c +19 -0
  67. package/targets/sb2000/src/lib/disk/sb-disk-format-track.c +18 -0
  68. package/targets/sb2000/src/lib/disk/sb-disk-free-bytes.c +38 -0
  69. package/targets/sb2000/src/lib/disk/sb-disk-init.c +16 -0
  70. package/targets/sb2000/src/lib/disk/sb-disk-read-sector.c +24 -0
  71. package/targets/sb2000/src/lib/disk/sb-disk-read-sectors.c +17 -0
  72. package/targets/sb2000/src/lib/disk/sb-disk-scan-track.c +27 -0
  73. package/targets/sb2000/src/lib/disk/sb-disk-start.c +16 -0
  74. package/targets/sb2000/src/lib/disk/sb-disk-stop.c +16 -0
  75. package/targets/sb2000/src/lib/disk/sb-disk-write-sector.c +19 -0
  76. package/targets/sb2000/src/lib/disk/sb-disk-write-sectors.c +17 -0
  77. package/targets/sb2000/src/lib/disk/sbi-disk-batch.c +23 -0
  78. package/targets/sb2000/src/lib/disk/sbi-disk-call.c +17 -0
  79. package/targets/sb2000/src/lib/disk/sbi-disk-set-position.c +18 -0
  80. package/targets/sb2000/src/lib/display/sb-cell-address.c +20 -0
  81. package/targets/sb2000/src/lib/display/sb-cells-copy.c +27 -0
  82. package/targets/sb2000/src/lib/display/sb-cells-fill.c +25 -0
  83. package/targets/sb2000/src/lib/display/sb-cells-rect.c +20 -0
  84. package/targets/sb2000/src/lib/display/sb-display-mode.c +16 -0
  85. package/targets/sb2000/src/lib/display/sb-glyph-address.c +28 -0
  86. package/targets/sb2000/src/lib/display/sb-image-fill-rect.c +26 -0
  87. package/targets/sb2000/src/lib/display/sb-image-load-raw.c +22 -0
  88. package/targets/sb2000/src/lib/display/sb-image-show-full.c +20 -0
  89. package/targets/sb2000/src/lib/display/sb-image-show.c +25 -0
  90. package/targets/sb2000/src/lib/display/sb-image-unpack-map.c +28 -0
  91. package/targets/sb2000/src/lib/display/sb-image-unpack-tiles.c +20 -0
  92. package/targets/sb2000/src/lib/display/sb-image-unpack-to-memory.c +22 -0
  93. package/targets/sb2000/src/lib/display/sb-palette-write.c +20 -0
  94. package/targets/sb2000/src/lib/display/sb-screen-clear.c +19 -0
  95. package/targets/sb2000/src/lib/display/sb-screen-flush.c +16 -0
  96. package/targets/sb2000/src/lib/display/sb-text-draw.c +22 -0
  97. package/targets/sb2000/src/lib/display/sb-text-field-ascii.c +25 -0
  98. package/targets/sb2000/src/lib/display/sb-text-field.c +25 -0
  99. package/targets/sb2000/src/lib/display/sb-text-to-memory.c +27 -0
  100. package/targets/sb2000/src/lib/display/sb-vram-bank.c +17 -0
  101. package/targets/sb2000/src/lib/display/sb-vram-fill.c +21 -0
  102. package/targets/sb2000/src/lib/display/sb-vram-load.c +21 -0
  103. package/targets/sb2000/src/lib/display/sb-window-compact.c +16 -0
  104. package/targets/sb2000/src/lib/display/sb-window-init.c +16 -0
  105. package/targets/sb2000/src/lib/display/sb-window-restore.c +17 -0
  106. package/targets/sb2000/src/lib/display/sb-window-save.c +21 -0
  107. package/targets/sb2000/src/lib/file/sb-dir-change.c +21 -0
  108. package/targets/sb2000/src/lib/file/sb-dir-current.c +27 -0
  109. package/targets/sb2000/src/lib/file/sb-dir-make.c +21 -0
  110. package/targets/sb2000/src/lib/file/sb-dir-open.c +61 -0
  111. package/targets/sb2000/src/lib/file/sb-dir-read.c +87 -0
  112. package/targets/sb2000/src/lib/file/sb-dir-remove.c +21 -0
  113. package/targets/sb2000/src/lib/file/sb-file-close.c +21 -0
  114. package/targets/sb2000/src/lib/file/sb-file-delete.c +21 -0
  115. package/targets/sb2000/src/lib/file/sb-file-get-attr.c +25 -0
  116. package/targets/sb2000/src/lib/file/sb-file-get-date.c +25 -0
  117. package/targets/sb2000/src/lib/file/sb-file-get-time.c +25 -0
  118. package/targets/sb2000/src/lib/file/sb-file-load.c +50 -0
  119. package/targets/sb2000/src/lib/file/sb-file-open.c +26 -0
  120. package/targets/sb2000/src/lib/file/sb-file-read.c +52 -0
  121. package/targets/sb2000/src/lib/file/sb-file-rename.c +30 -0
  122. package/targets/sb2000/src/lib/file/sb-file-save.c +31 -0
  123. package/targets/sb2000/src/lib/file/sb-file-set-attr.c +22 -0
  124. package/targets/sb2000/src/lib/file/sb-file-set-date.c +25 -0
  125. package/targets/sb2000/src/lib/file/sb-file-set-time.c +22 -0
  126. package/targets/sb2000/src/lib/file/sb-file-size.c +27 -0
  127. package/targets/sb2000/src/lib/file/sb-file-write-all.c +32 -0
  128. package/targets/sb2000/src/lib/file/sb-file-write.c +60 -0
  129. package/targets/sb2000/src/lib/file/sbi-dir-state.c +15 -0
  130. package/targets/sb2000/src/lib/file/sbi-dos-call.c +17 -0
  131. package/targets/sb2000/src/lib/file/sbi-load-sector.c +18 -0
  132. package/targets/sb2000/src/lib/file/sbi-select-handle.c +20 -0
  133. package/targets/sb2000/src/lib/file/sbi-set-path.c +26 -0
  134. package/targets/sb2000/src/lib/ime/sb-ime-get-method.c +17 -0
  135. package/targets/sb2000/src/lib/ime/sb-ime-get-state.c +18 -0
  136. package/targets/sb2000/src/lib/ime/sb-ime-hex.c +20 -0
  137. package/targets/sb2000/src/lib/ime/sb-ime-init.c +26 -0
  138. package/targets/sb2000/src/lib/ime/sb-ime-key-wait.c +19 -0
  139. package/targets/sb2000/src/lib/ime/sb-ime-key.c +19 -0
  140. package/targets/sb2000/src/lib/ime/sb-ime-parse.c +23 -0
  141. package/targets/sb2000/src/lib/ime/sb-ime-resume.c +16 -0
  142. package/targets/sb2000/src/lib/ime/sb-ime-select.c +19 -0
  143. package/targets/sb2000/src/lib/ime/sb-ime-set-state.c +18 -0
  144. package/targets/sb2000/src/lib/ime/sb-ime-set-width.c +16 -0
  145. package/targets/sb2000/src/lib/ime/sb-ime-suspend.c +16 -0
  146. package/targets/sb2000/src/lib/input/sb-break-disable.c +16 -0
  147. package/targets/sb2000/src/lib/input/sb-break-enable.c +16 -0
  148. package/targets/sb2000/src/lib/input/sb-key-count.c +17 -0
  149. package/targets/sb2000/src/lib/input/sb-key-flush.c +16 -0
  150. package/targets/sb2000/src/lib/input/sb-key-init.c +16 -0
  151. package/targets/sb2000/src/lib/input/sb-key-modifiers.c +16 -0
  152. package/targets/sb2000/src/lib/input/sb-key-poll.c +17 -0
  153. package/targets/sb2000/src/lib/input/sb-key-wait.c +17 -0
  154. package/targets/sb2000/src/lib/input/sb-keyboard-reset.c +17 -0
  155. package/targets/sb2000/src/lib/input/sb-mouse-buttons.c +21 -0
  156. package/targets/sb2000/src/lib/input/sb-mouse-position.c +18 -0
  157. package/targets/sb2000/src/lib/input/sb-mouse-reset.c +17 -0
  158. package/targets/sb2000/src/lib/input/sb-mouse-set-double-click.c +17 -0
  159. package/targets/sb2000/src/lib/input/sb-mouse-set-limits.c +26 -0
  160. package/targets/sb2000/src/lib/input/sb-mouse-set-position.c +18 -0
  161. package/targets/sb2000/src/lib/input/sb-pad-init.c +17 -0
  162. package/targets/sb2000/src/lib/input/sb-pad-poll.c +17 -0
  163. package/targets/sb2000/src/lib/input/sb-pad-state.c +16 -0
  164. package/targets/sb2000/src/lib/input/sb-pad-wait.c +17 -0
  165. package/targets/sb2000/src/lib/math/sb-float-add.c +19 -0
  166. package/targets/sb2000/src/lib/math/sb-float-div.c +19 -0
  167. package/targets/sb2000/src/lib/math/sb-float-from-text.c +18 -0
  168. package/targets/sb2000/src/lib/math/sb-float-mul.c +19 -0
  169. package/targets/sb2000/src/lib/math/sb-float-sub.c +19 -0
  170. package/targets/sb2000/src/lib/math/sb-float-to-text.c +19 -0
  171. package/targets/sb2000/src/lib/math/sb-int24-add.c +21 -0
  172. package/targets/sb2000/src/lib/math/sb-int24-div.c +26 -0
  173. package/targets/sb2000/src/lib/math/sb-int24-mul.c +20 -0
  174. package/targets/sb2000/src/lib/math/sb-int24-sub.c +21 -0
  175. package/targets/sb2000/src/lib/math/sb-int40-from-text.c +19 -0
  176. package/targets/sb2000/src/lib/math/sb-int40-to-text.c +27 -0
  177. package/targets/sb2000/src/lib/math/sb-line-step.c +21 -0
  178. package/targets/sb2000/src/lib/math/sb-math-div16.c +27 -0
  179. package/targets/sb2000/src/lib/math/sb-math-time-text.c +21 -0
  180. package/targets/sb2000/src/lib/math/sb-random-next.c +20 -0
  181. package/targets/sb2000/src/lib/math/sb-random-seed.c +19 -0
  182. package/targets/sb2000/src/lib/math/sb-random-warm-up.c +16 -0
  183. package/targets/sb2000/src/lib/math/sbi-peek.c +20 -0
  184. package/targets/sb2000/src/lib/math/sbi-poke.c +20 -0
  185. package/targets/sb2000/src/lib/memory/sb-address-to-far.c +20 -0
  186. package/targets/sb2000/src/lib/memory/sb-far-read-byte.c +17 -0
  187. package/targets/sb2000/src/lib/memory/sb-far-read.c +36 -0
  188. package/targets/sb2000/src/lib/memory/sb-far-write-byte.c +17 -0
  189. package/targets/sb2000/src/lib/memory/sb-far-write.c +36 -0
  190. package/targets/sb2000/src/lib/memory/sb-page-alloc.c +19 -0
  191. package/targets/sb2000/src/lib/memory/sb-page-free.c +19 -0
  192. package/targets/sb2000/src/lib/memory/sb-page-largest-free.c +17 -0
  193. package/targets/sb2000/src/lib/memory/sb-window-map-group.c +17 -0
  194. package/targets/sb2000/src/lib/memory/sb-window-map.c +18 -0
  195. package/targets/sb2000/src/lib/memory/sbi-far-copy-in.s +17 -0
  196. package/targets/sb2000/src/lib/memory/sbi-far-copy-out.s +17 -0
  197. package/targets/sb2000/src/lib/memory/sbi-far-read-byte.s +19 -0
  198. package/targets/sb2000/src/lib/memory/sbi-far-write-byte.s +17 -0
  199. package/targets/sb2000/src/lib/printer/sb-printer-carriage-return.c +16 -0
  200. package/targets/sb2000/src/lib/printer/sb-printer-feed.c +17 -0
  201. package/targets/sb2000/src/lib/printer/sb-printer-graphics-mode.c +16 -0
  202. package/targets/sb2000/src/lib/printer/sb-printer-home.c +16 -0
  203. package/targets/sb2000/src/lib/printer/sb-printer-init-port.c +16 -0
  204. package/targets/sb2000/src/lib/printer/sb-printer-page-left.c +16 -0
  205. package/targets/sb2000/src/lib/printer/sb-printer-page-length.c +17 -0
  206. package/targets/sb2000/src/lib/printer/sb-printer-position.c +18 -0
  207. package/targets/sb2000/src/lib/printer/sb-printer-reset.c +16 -0
  208. package/targets/sb2000/src/lib/printer/sb-printer-send-byte.c +18 -0
  209. package/targets/sb2000/src/lib/printer/sb-printer-text.c +29 -0
  210. package/targets/sb2000/src/lib/sb-internal.h +111 -0
  211. package/targets/sb2000/src/lib/sound/sb-sound-effect-from.c +19 -0
  212. package/targets/sb2000/src/lib/sound/sb-sound-play-from.c +18 -0
  213. package/targets/sb2000/src/lib/sound/sb-sound-play-wav-from.c +18 -0
  214. package/targets/sb2000/src/lib/sound/sb-sound-play-wav.c +16 -0
  215. package/targets/sb2000/src/lib/sound/sb-sound-repeat-wav-from.c +19 -0
  216. package/targets/sb2000/src/lib/sound/sb-sound-status.c +17 -0
  217. package/targets/sb2000/src/lib/sound/sb-sound-stop.c +16 -0
  218. package/targets/sb2000/src/lib/sound/sb-sound-tempo.c +17 -0
  219. package/targets/sb2000/src/lib/sound/sb-sound-transpose.c +17 -0
  220. package/targets/sb2000/src/lib/sound/sb-speech-off.c +16 -0
  221. package/targets/sb2000/src/lib/sound/sb-speech-send-entry-from.c +21 -0
  222. package/targets/sb2000/src/lib/sound/sb-speech-send-from.c +19 -0
  223. package/targets/sb2000/src/lib/sound/sb-speech-send.c +16 -0
  224. package/targets/sb2000/src/lib/system/sb-call-banked.c +19 -0
  225. package/targets/sb2000/src/lib/system/sb-context-restore.c +16 -0
  226. package/targets/sb2000/src/lib/system/sb-context-save.c +19 -0
  227. package/targets/sb2000/src/lib/system/sb-display-off.c +16 -0
  228. package/targets/sb2000/src/lib/system/sb-display-on.c +16 -0
  229. package/targets/sb2000/src/lib/system/sb-display-option.c +18 -0
  230. package/targets/sb2000/src/lib/system/sb-exec.c +22 -0
  231. package/targets/sb2000/src/lib/system/sb-irq-enable.c +19 -0
  232. package/targets/sb2000/src/lib/system/sb-irq-hook-reset.c +20 -0
  233. package/targets/sb2000/src/lib/system/sb-irq-hook-set.c +39 -0
  234. package/targets/sb2000/src/lib/system/sb-irq-mask.c +19 -0
  235. package/targets/sb2000/src/lib/system/sb-jump-banked.s +25 -0
  236. package/targets/sb2000/src/lib/system/sb-nmi-disable.c +16 -0
  237. package/targets/sb2000/src/lib/system/sb-nmi-enable.c +16 -0
  238. package/targets/sb2000/src/lib/system/sb-nmi-hook-reset.c +20 -0
  239. package/targets/sb2000/src/lib/system/sb-nmi-hook-set.c +33 -0
  240. package/targets/sb2000/src/lib/system/sb-nmi-service.c +19 -0
  241. package/targets/sb2000/src/lib/system/sb-stack-pointer.s +18 -0
  242. package/targets/sb2000/src/lib/system/sb-system-init.c +16 -0
  243. package/targets/sb2000/src/lib/system/sb-system-state.c +20 -0
  244. package/targets/sb2000/src/lib/system/sb-wait-frames.s +19 -0
  245. package/targets/sb2000/src/lib/system/sbi-exec-run.s +43 -0
  246. package/targets/sb2000/src/lib/system/sbi-interrupts-off.s +19 -0
  247. package/targets/sb2000/src/lib/system/sbi-interrupts-restore.s +17 -0
  248. package/targets/sb2000/src/lib/text/sb-beep.c +16 -0
  249. package/targets/sb2000/src/lib/text/sb-cursor-column.c +16 -0
  250. package/targets/sb2000/src/lib/text/sb-cursor-left.c +16 -0
  251. package/targets/sb2000/src/lib/text/sb-cursor-right.c +16 -0
  252. package/targets/sb2000/src/lib/text/sb-cursor-row.c +16 -0
  253. package/targets/sb2000/src/lib/text/sb-cursor-set-column.c +18 -0
  254. package/targets/sb2000/src/lib/text/sb-cursor-up.c +16 -0
  255. package/targets/sb2000/src/lib/text/sb-print-hex.c +22 -0
  256. package/targets/sb2000/src/lib/text/sb-print-uint.c +25 -0
  257. package/targets/sb2000/src/lib/text/sb-print.c +35 -0
  258. package/targets/sb2000/src/lib/text/sb-putc.c +26 -0
  259. package/targets/sb2000/src/sb2000.s +0 -3
  260. package/targets/sb2000/target.json +14 -0
@@ -0,0 +1,3295 @@
1
+ # SB2000 C 接口参考
2
+
3
+ 本文由头文件 `include/sb2000-*.h` 的文档注释生成,请不要手改;改注释后运行 `node tools/gen-sb2000-api-doc.mjs`。
4
+ 共 184 个函数,14 个模块。随时查询用 `fcdev api`:`fcdev api <函数名>` 看完整文档,`fcdev api <模块名>` 看模块的函数列表,`fcdev api '$7B'` 看用到某个系统调用的函数,`fcdev api <词>` 按名称与说明搜索。
5
+
6
+ 约定:
7
+
8
+ - 所有函数用 `#include <sb2000.h>` 引入;返回 DOS 出错码或软驱状态码的函数,0 表示成功,结果经指针参数带回。
9
+ - 字符串、缓冲区、结构体指针必须在程序窗口 `$8000-$BFFF` 里(系统服务换页后程序窗口不可见的,函数内部已经处理好,调用者不用管)。
10
+ - 程序最大 16K(窗口 `$8000-$BFFF`,C 软件栈占顶端 1K)。
11
+
12
+ ## 目录
13
+
14
+ - [bank(sb2000-bank.h)](#bank)
15
+ - [日期与时间(sb2000-clock.h)](#clock)
16
+ - [软驱扇区(sb2000-disk.h)](#disk)
17
+ - [显示、窗口与图片(sb2000-display.h)](#display)
18
+ - [文件与目录(sb2000-file.h)](#file)
19
+ - [中文输入法(sb2000-ime.h)](#ime)
20
+ - [键盘、手柄与鼠标(sb2000-input.h)](#input)
21
+ - [数学(sb2000-math.h)](#math)
22
+ - [内存页与远指针(sb2000-memory.h)](#memory)
23
+ - [打印机(sb2000-printer.h)](#printer)
24
+ - [声音与语音(sb2000-sound.h)](#sound)
25
+ - [系统与中断(sb2000-system.h)](#system)
26
+ - [文字输出(sb2000-text.h)](#text)
27
+ - [总头文件与通用调用(sb2000.h)](#sb2000)
28
+ - [系统调用覆盖表](#系统调用覆盖表)
29
+
30
+ <a id="bank"></a>
31
+ ## bank(sb2000-bank.h)
32
+
33
+ | 函数 | 说明 | 系统调用 |
34
+ | --- | --- | --- |
35
+ | [`sb_bank_select`](#sb_bank_select) | 把一个库页换进窗口 2,窗口 2 里原来的库页看不到了。调用蹦床时会自动换页,只有需要直接读库页里的数据时才自己调用。 | $29 |
36
+ | [`sb_bank_current`](#sb_bank_current) | 取窗口 2 当前的库页号。 | |
37
+
38
+ <a id="sb_bank_select"></a>
39
+ ### sb_bank_select
40
+
41
+ ```c
42
+ void sb_bank_select(unsigned char bank);
43
+ ```
44
+
45
+ 把一个库页换进窗口 2,窗口 2 里原来的库页看不到了。调用蹦床时会自动换页,只有需要直接读库页里的数据时才自己调用。
46
+
47
+ 系统调用:$29
48
+
49
+ 参数:
50
+
51
+ - `bank`:库页号,1 到 fcdev.json 里 banks 的值。
52
+
53
+ <a id="sb_bank_current"></a>
54
+ ### sb_bank_current
55
+
56
+ ```c
57
+ unsigned char sb_bank_current(void);
58
+ ```
59
+
60
+ 取窗口 2 当前的库页号。
61
+
62
+ 返回:库页号;程序刚启动时是 1。
63
+
64
+ <a id="clock"></a>
65
+ ## 日期与时间(sb2000-clock.h)
66
+
67
+ | 函数 | 说明 | 系统调用 |
68
+ | --- | --- | --- |
69
+ | [`sb_clock_set_date`](#sb_clock_set_date) | 设置系统日期。系统按年份能否被 4 整除判断闰年(不处理世纪年)。 | $7F/$01 |
70
+ | [`sb_clock_get_date`](#sb_clock_get_date) | 取系统日期。过了午夜后第一次取时,系统先把日期加一天。 | $7F/$02 |
71
+ | [`sb_clock_set_time`](#sb_clock_set_time) | 设置系统时间。 | $7F/$03 |
72
+ | [`sb_clock_get_time`](#sb_clock_get_time) | 取系统时间。 | $7F/$04 |
73
+
74
+ <a id="sb_clock_set_date"></a>
75
+ ### sb_clock_set_date
76
+
77
+ ```c
78
+ unsigned char sb_clock_set_date(const sb_date_t *date);
79
+ ```
80
+
81
+ 设置系统日期。系统按年份能否被 4 整除判断闰年(不处理世纪年)。
82
+
83
+ 系统调用:$7F/$01
84
+
85
+ 参数:
86
+
87
+ - `date`:新日期。
88
+
89
+ 返回:0 成功;SB_ERR_BAD_PARAMETER 日期不合法,系统日期不变。
90
+
91
+ <a id="sb_clock_get_date"></a>
92
+ ### sb_clock_get_date
93
+
94
+ ```c
95
+ void sb_clock_get_date(sb_date_t *date);
96
+ ```
97
+
98
+ 取系统日期。过了午夜后第一次取时,系统先把日期加一天。
99
+
100
+ 系统调用:$7F/$02
101
+
102
+ 参数:
103
+
104
+ - `date`:返回当前日期。
105
+
106
+ <a id="sb_clock_set_time"></a>
107
+ ### sb_clock_set_time
108
+
109
+ ```c
110
+ unsigned char sb_clock_set_time(const sb_time_t *time);
111
+ ```
112
+
113
+ 设置系统时间。
114
+
115
+ 系统调用:$7F/$03
116
+
117
+ 参数:
118
+
119
+ - `time`:新时间。
120
+
121
+ 返回:0 成功;SB_ERR_BAD_PARAMETER 时间不合法,系统时间不变。
122
+
123
+ <a id="sb_clock_get_time"></a>
124
+ ### sb_clock_get_time
125
+
126
+ ```c
127
+ void sb_clock_get_time(sb_time_t *time);
128
+ ```
129
+
130
+ 取系统时间。
131
+
132
+ 系统调用:$7F/$04
133
+
134
+ 参数:
135
+
136
+ - `time`:返回当前时间。
137
+
138
+ <a id="disk"></a>
139
+ ## 软驱扇区(sb2000-disk.h)
140
+
141
+ | 函数 | 说明 | 系统调用 |
142
+ | --- | --- | --- |
143
+ | [`sb_disk_init`](#sb_disk_init) | 启动软驱并复位到 0 磁道,读出状态后停转。可用来检查驱动器是否就绪。 | $80/$00 |
144
+ | [`sb_disk_start`](#sb_disk_start) | 启动软驱。文件服务会自己启动与停转软驱,只有直接读写扇区时才需要。 | $80/$06 |
145
+ | [`sb_disk_stop`](#sb_disk_stop) | 让软驱停转。直接读写扇区之后调用,文件服务每次操作之后都会自己调用。 | $80/$07 |
146
+ | [`sb_disk_read_sector`](#sb_disk_read_sector) | 读一个扇区,先检测盘片。 | $80/$02 |
147
+ | [`sb_disk_write_sector`](#sb_disk_write_sector) | 写一个扇区,先检测盘片。 | $80/$03 |
148
+ | [`sb_disk_read_sectors`](#sb_disk_read_sectors) | 从起始扇区连续读若干扇区到扩展 RAM 页里,扇区号递增,满 18 换面,两面满换磁道。先检测盘片。 | $80/$04 |
149
+ | [`sb_disk_write_sectors`](#sb_disk_write_sectors) | 把扩展 RAM 页里的数据连续写到若干扇区,扇区号递增的规则同 sb_disk_read_sectors。先检测盘片,写保护时立即停止。 | $80/$05 |
150
+ | [`sb_disk_scan_track`](#sb_disk_scan_track) | 逐个读一个磁道的 18 个扇区,读不出的在位图里置位。不检测盘片,直接读每个扇区。 | $80/$08 |
151
+ | [`sb_disk_format_track`](#sb_disk_format_track) | 格式化一个磁道:磁道 0 的 18 个扇区填 $00,其他磁道填 $F6。先检测盘片。会清掉这个磁道上的全部数据。 | $80/$01 |
152
+ | [`sb_disk_free_bytes`](#sb_disk_free_bytes) | 取磁盘上的空闲字节数(空闲簇数乘每簇字节数)。 | $7B/$01、$7B/$06 |
153
+
154
+ <a id="sb_disk_init"></a>
155
+ ### sb_disk_init
156
+
157
+ ```c
158
+ unsigned char sb_disk_init(void);
159
+ ```
160
+
161
+ 启动软驱并复位到 0 磁道,读出状态后停转。可用来检查驱动器是否就绪。
162
+
163
+ 系统调用:$80/$00
164
+
165
+ 返回:0 成功;SB_ERR_NOT_READY 驱动器没有响应。
166
+
167
+ <a id="sb_disk_start"></a>
168
+ ### sb_disk_start
169
+
170
+ ```c
171
+ unsigned char sb_disk_start(void);
172
+ ```
173
+
174
+ 启动软驱。文件服务会自己启动与停转软驱,只有直接读写扇区时才需要。
175
+
176
+ 系统调用:$80/$06
177
+
178
+ 返回:0 成功;SB_ERR_NOT_READY 驱动器未准备好。
179
+
180
+ <a id="sb_disk_stop"></a>
181
+ ### sb_disk_stop
182
+
183
+ ```c
184
+ void sb_disk_stop(void);
185
+ ```
186
+
187
+ 让软驱停转。直接读写扇区之后调用,文件服务每次操作之后都会自己调用。
188
+
189
+ 系统调用:$80/$07
190
+
191
+ <a id="sb_disk_read_sector"></a>
192
+ ### sb_disk_read_sector
193
+
194
+ ```c
195
+ unsigned char sb_disk_read_sector(unsigned char head, unsigned char track, unsigned char sector, void *dest);
196
+ ```
197
+
198
+ 读一个扇区,先检测盘片。
199
+
200
+ 系统调用:$80/$02
201
+
202
+ 参数:
203
+
204
+ - `head`:面,0 或 1。
205
+ - `track`:磁道,0 到 79。
206
+ - `sector`:扇区号,1 到 18。
207
+ - `dest`:接收 512 字节的缓冲区,在程序窗口里。
208
+
209
+ 返回:0 成功;SB_ERR_NO_DISK 驱动器中没有磁盘;SB_ERR_UNKNOWN_DISK 未知磁盘类型;SB_ERR_CRC 扇区校验错。
210
+
211
+ <a id="sb_disk_write_sector"></a>
212
+ ### sb_disk_write_sector
213
+
214
+ ```c
215
+ unsigned char sb_disk_write_sector(unsigned char head, unsigned char track, unsigned char sector, const void *src);
216
+ ```
217
+
218
+ 写一个扇区,先检测盘片。
219
+
220
+ 系统调用:$80/$03
221
+
222
+ 参数:
223
+
224
+ - `head`:面,0 或 1。
225
+ - `track`:磁道,0 到 79。
226
+ - `sector`:扇区号,1 到 18。
227
+ - `src`:要写入的 512 字节,在程序窗口里。
228
+
229
+ 返回:0 成功;SB_ERR_WRITE_PROTECT 磁盘写保护;SB_ERR_NO_DISK 驱动器中没有磁盘;SB_ERR_UNKNOWN_DISK 未知磁盘类型。
230
+
231
+ <a id="sb_disk_read_sectors"></a>
232
+ ### sb_disk_read_sectors
233
+
234
+ ```c
235
+ unsigned char sb_disk_read_sectors(unsigned char head, unsigned char track, unsigned char sector, unsigned char page, unsigned char page_sector, unsigned int count, unsigned char mode);
236
+ ```
237
+
238
+ 从起始扇区连续读若干扇区到扩展 RAM 页里,扇区号递增,满 18 换面,两面满换磁道。先检测盘片。
239
+
240
+ 系统调用:$80/$04
241
+
242
+ 参数:
243
+
244
+ - `head`:起始面,0 或 1。
245
+ - `track`:起始磁道,0 到 79。
246
+ - `sector`:起始扇区号,1 到 18。
247
+ - `page`:接收数据的扩展 RAM 页号。
248
+ - `page_sector`:数据从页内第几个 512 字节开始放,0 到 7;每页放 8 个扇区,页要有足够的连续页。
249
+ - `count`:扇区数。
250
+ - `mode`:SB_DISK_STOP_ON_ERROR 或 SB_DISK_SKIP_ERRORS,见这两个常量的说明。
251
+
252
+ 返回:0 成功;SB_ERR_NO_DISK 驱动器中没有磁盘;SB_ERR_CRC 等扇区出错码(mode 为 SB_DISK_STOP_ON_ERROR 时)。
253
+
254
+ <a id="sb_disk_write_sectors"></a>
255
+ ### sb_disk_write_sectors
256
+
257
+ ```c
258
+ unsigned char sb_disk_write_sectors(unsigned char head, unsigned char track, unsigned char sector, unsigned char page, unsigned char page_sector, unsigned int count, unsigned char mode);
259
+ ```
260
+
261
+ 把扩展 RAM 页里的数据连续写到若干扇区,扇区号递增的规则同 sb_disk_read_sectors。先检测盘片,写保护时立即停止。
262
+
263
+ 系统调用:$80/$05
264
+
265
+ 参数:
266
+
267
+ - `head`:起始面,0 或 1。
268
+ - `track`:起始磁道,0 到 79。
269
+ - `sector`:起始扇区号,1 到 18。
270
+ - `page`:数据所在的扩展 RAM 页号。
271
+ - `page_sector`:数据从页内第几个 512 字节开始,0 到 7。
272
+ - `count`:扇区数。
273
+ - `mode`:SB_DISK_STOP_ON_ERROR 或 SB_DISK_SKIP_ERRORS。
274
+
275
+ 返回:0 成功;SB_ERR_WRITE_PROTECT 磁盘写保护;SB_ERR_NO_DISK 驱动器中没有磁盘。
276
+
277
+ <a id="sb_disk_scan_track"></a>
278
+ ### sb_disk_scan_track
279
+
280
+ ```c
281
+ unsigned char sb_disk_scan_track(unsigned char head, unsigned char track, unsigned char *bad_map);
282
+ ```
283
+
284
+ 逐个读一个磁道的 18 个扇区,读不出的在位图里置位。不检测盘片,直接读每个扇区。
285
+
286
+ 系统调用:$80/$08
287
+
288
+ 参数:
289
+
290
+ - `head`:面,0 或 1。
291
+ - `track`:磁道,0 到 79。
292
+ - `bad_map`:返回 3 字节位图:第 0 字节的位 7 到位 0 依次对应扇区 1 到 8,第 1 字节对应扇区 9 到 16,第 2 字节的位 7、位 6 对应扇区 17、18;置位表示读不出。
293
+
294
+ 返回:0 成功;SB_ERR_BAD_DISK_PARAM 面或磁道超出范围。
295
+
296
+ <a id="sb_disk_format_track"></a>
297
+ ### sb_disk_format_track
298
+
299
+ ```c
300
+ unsigned char sb_disk_format_track(unsigned char head, unsigned char track);
301
+ ```
302
+
303
+ 格式化一个磁道:磁道 0 的 18 个扇区填 $00,其他磁道填 $F6。先检测盘片。会清掉这个磁道上的全部数据。
304
+
305
+ 系统调用:$80/$01
306
+
307
+ 参数:
308
+
309
+ - `head`:面,0 或 1。
310
+ - `track`:磁道,0 到 79。
311
+
312
+ 返回:0 成功;SB_ERR_BAD_DISK_PARAM 面或磁道超出范围;SB_ERR_WRITE_PROTECT 磁盘写保护;SB_ERR_NO_DISK 驱动器中没有磁盘。
313
+
314
+ <a id="sb_disk_free_bytes"></a>
315
+ ### sb_disk_free_bytes
316
+
317
+ ```c
318
+ unsigned char sb_disk_free_bytes(unsigned long *bytes);
319
+ ```
320
+
321
+ 取磁盘上的空闲字节数(空闲簇数乘每簇字节数)。
322
+
323
+ 系统调用:$7B/$01、$7B/$06
324
+
325
+ 参数:
326
+
327
+ - `bytes`:返回空闲字节数。
328
+
329
+ 返回:0 成功;其他是读 FAT 时的磁盘出错码。
330
+
331
+ <a id="display"></a>
332
+ ## 显示、窗口与图片(sb2000-display.h)
333
+
334
+ | 函数 | 说明 | 系统调用 |
335
+ | --- | --- | --- |
336
+ | [`sb_cells_fill`](#sb_cells_fill) | 从指定位置起线性地(先列后行,到行尾接下一行)把 count 个单元写成同一个值,写完刷新一次名称表到显存。 | $40 |
337
+ | [`sb_cells_rect`](#sb_cells_rect) | 把一个矩形区域的单元写成同一个值,每行刷新一次。 | $40 |
338
+ | [`sb_cells_copy`](#sb_cells_copy) | 把程序窗口里的一块单元数据逐行复制到屏幕,写完刷新一次名称表。 | $40 |
339
+ | [`sb_screen_clear`](#sb_screen_clear) | 清屏:把屏幕缓冲里指定名称表的全部单元填成同一个值(只写缓冲,不刷新显存)。 | $30/$0A |
340
+ | [`sb_screen_flush`](#sb_screen_flush) | 把一张名称表缓冲经 DMA 写到显存,并等一帧。 | $30/$00-$03 |
341
+ | [`sb_cell_address`](#sb_cell_address) | 求屏幕缓冲里一个单元的远地址,可以交给 sb_far_read、sb_far_write 读写。 | $30/$04-$07 |
342
+ | [`sb_text_field`](#sb_text_field) | 在屏幕上显示一行文字(可混排汉字与西文):把字符串画成点阵写进显存的图块,再把上下两行单元写进名称表缓冲并刷新。 | $45 |
343
+ | [`sb_text_field_ascii`](#sb_text_field_ascii) | 同 sb_text_field,但只处理单字节字符,不补空白图块,只写一行单元:第 i 列的单元值是 cell + 步长 × i;步长在大字体(8×16 字模,DOS 的默认)下是 2,小字体下是 1。 | $46 |
344
+ | [`sb_text_draw`](#sb_text_draw) | 把字符串画成点阵图块,经 DMA 写进显存的图块区(目的地址 = 图块号 × 16),不写名称表。 | $3C、$3D、$3E、$3F |
345
+ | [`sb_text_to_memory`](#sb_text_to_memory) | 把字符串画成点阵图块,写进调用者指定的扩展 RAM 地址(不经显存)。每个图块二平面 16 字节、四平面 32 字节,按平面顺序各 8 字节; | $47、$48 |
346
+ | [`sb_display_mode`](#sb_display_mode) | 设置显示模式(显示模式影子 $0638 的高 2 位,决定文字字库区域的取法),低 6 位不变。 | $11/$00-$03 |
347
+ | [`sb_glyph_address`](#sb_glyph_address) | 查字符码对应的字模所在的页与页内地址,不绘制。字符码高字节为 0 时 $20 到 $7F 取西文字模(8×8 或 8×16,由显示模式决定), | $3B |
348
+ | [`sb_window_init`](#sb_window_init) | 初始化窗口管理:30 个窗口号全部空闲,保存区末尾回到 $8060。程序开始用窗口之前调用一次。 | $59/$06 |
349
+ | [`sb_window_save`](#sb_window_save) | 把名称表缓冲里的一个矩形保存起来,以后用 sb_window_restore 原样写回。只保存缓冲,不碰显存。 | $59/$00-$03 |
350
+ | [`sb_window_restore`](#sb_window_restore) | 把保存的窗口内容写回名称表缓冲并释放窗口号。只写缓冲,不刷新显存,要用 sb_screen_flush 刷新。 | $59/$04 |
351
+ | [`sb_window_compact`](#sb_window_compact) | 整理窗口保存区:没有窗口时末尾回到 $8060,否则把后面的数据前移填掉空洞。 | $59/$05 |
352
+ | [`sb_palette_write`](#sb_palette_write) | 把一组颜色写进调色板,从调色板第 offset 项起。显示开着且 NMI 开着时由 NMI 处理程序写入。 | $5D |
353
+ | [`sb_vram_fill`](#sb_vram_fill) | 用一个字节填充显存的一段。长度为 0 什么都不做。 | $32 |
354
+ | [`sb_vram_load`](#sb_vram_load) | 把扩展 RAM 里的一段数据经 DMA 写进显存。长度为 0 什么都不做。 | $33 |
355
+ | [`sb_vram_bank`](#sb_vram_bank) | 设置显存 bank 寄存器($4300)。 | $2A |
356
+ | [`sb_image_load_raw`](#sb_image_load_raw) | 不解压,直接把一段图案数据经 DMA 写进显存的图块区(目的地址 = 图块号 × 16),再等垂直消隐。长度为 0 直接返回。 | $5A |
357
+ | [`sb_image_unpack_tiles`](#sb_image_unpack_tiles) | 解压图案流并经 DMA 写进显存的图块区。流的格式:16 字节字典加指令流,指令字节 $00 结束; | $5B |
358
+ | [`sb_image_unpack_map`](#sb_image_unpack_map) | 解压映射流并按效果写进屏幕:流里的单元值加上 map->base 与调色板位,再按效果把矩形写进名称表缓冲并刷新到显存。 | $5C |
359
+ | [`sb_image_fill_rect`](#sb_image_fill_rect) | 用与 sb_image_unpack_map 相同的效果把一个单元值(map->base)铺满矩形,不加调色板位。 | $60 |
360
+ | [`sb_image_show`](#sb_image_show) | 显示压缩图片:10 字节头 [宽、高、图案数(16 位)、调色板组数、每组色数、映射流偏移(16 位)、调色板偏移(16 位)](偏移相对头的起点), | $5F |
361
+ | [`sb_image_show_full`](#sb_image_show_full) | 显示整屏图片:头格式同 sb_image_show;图案流解压到起始图块 tile,映射流直接按顺序解到名称表缓冲的开头(单元基础值是 tile,不加调色板位), | $5E |
362
+ | [`sb_image_unpack_to_memory`](#sb_image_unpack_to_memory) | 把图案流解压到内存,格式同 sb_image_unpack_tiles。目的地址 address 是窗口地址($8000 到 $FFFF,高 4 位选页,低 12 位是页内偏移), | $61 |
363
+
364
+ <a id="sb_cells_fill"></a>
365
+ ### sb_cells_fill
366
+
367
+ ```c
368
+ void sb_cells_fill(unsigned char table, unsigned char col, unsigned char row, unsigned int count, unsigned int cell, unsigned char palette);
369
+ ```
370
+
371
+ 从指定位置起线性地(先列后行,到行尾接下一行)把 count 个单元写成同一个值,写完刷新一次名称表到显存。
372
+
373
+ 系统调用:$40
374
+
375
+ 参数:
376
+
377
+ - `table`:名称表号,0 到 3。
378
+ - `col`:起点列,0 到 31。
379
+ - `row`:起点行,0 到 29。
380
+ - `count`:单元个数,不要超过名称表里剩下的单元数;0 会被当作 65536,不要用。
381
+ - `cell`:单元值,低 12 位是图块号,高 4 位被调色板号替换。
382
+ - `palette`:调色板号,0 到 15。
383
+
384
+ <a id="sb_cells_rect"></a>
385
+ ### sb_cells_rect
386
+
387
+ ```c
388
+ void sb_cells_rect(unsigned char table, unsigned char col, unsigned char row, unsigned char width, unsigned char height, unsigned int cell, unsigned char palette);
389
+ ```
390
+
391
+ 把一个矩形区域的单元写成同一个值,每行刷新一次。
392
+
393
+ 系统调用:$40
394
+
395
+ 参数:
396
+
397
+ - `table`:名称表号,0 到 3。
398
+ - `col`:左上角列。
399
+ - `row`:左上角行。
400
+ - `width`:宽,列数,列加宽不超过 32。
401
+ - `height`:高,行数,行加高不超过 30。
402
+ - `cell`:单元值,低 12 位是图块号。
403
+ - `palette`:调色板号,0 到 15。
404
+
405
+ <a id="sb_cells_copy"></a>
406
+ ### sb_cells_copy
407
+
408
+ ```c
409
+ void sb_cells_copy(unsigned char table, unsigned char col, unsigned char row, unsigned char width, unsigned char height, const unsigned int *cells);
410
+ ```
411
+
412
+ 把程序窗口里的一块单元数据逐行复制到屏幕,写完刷新一次名称表。
413
+
414
+ 系统调用:$40
415
+
416
+ 参数:
417
+
418
+ - `table`:名称表号,0 到 3。
419
+ - `col`:左上角列。
420
+ - `row`:左上角行。
421
+ - `width`:宽,列数。
422
+ - `height`:高,行数。
423
+ - `cells`:单元数据,width × height 个,按行排列,在程序窗口里;单元值原样写入,不替换调色板位。
424
+
425
+ <a id="sb_screen_clear"></a>
426
+ ### sb_screen_clear
427
+
428
+ ```c
429
+ void sb_screen_clear(unsigned char tables, unsigned int cell);
430
+ ```
431
+
432
+ 清屏:把屏幕缓冲里指定名称表的全部单元填成同一个值(只写缓冲,不刷新显存)。
433
+
434
+ 系统调用:$30/$0A
435
+
436
+ 参数:
437
+
438
+ - `tables`:位掩码,位 0 到 3 依次对应名称表 0 到 3(缓冲里的名称表 4 到 7)。
439
+ - `cell`:单元值。
440
+
441
+ <a id="sb_screen_flush"></a>
442
+ ### sb_screen_flush
443
+
444
+ ```c
445
+ void sb_screen_flush(unsigned char table);
446
+ ```
447
+
448
+ 把一张名称表缓冲经 DMA 写到显存,并等一帧。
449
+
450
+ 系统调用:$30/$00-$03
451
+
452
+ 参数:
453
+
454
+ - `table`:名称表号,0 到 3。
455
+
456
+ <a id="sb_cell_address"></a>
457
+ ### sb_cell_address
458
+
459
+ ```c
460
+ void sb_cell_address(unsigned char table, unsigned char col, unsigned char row, unsigned char *page, unsigned int *offset);
461
+ ```
462
+
463
+ 求屏幕缓冲里一个单元的远地址,可以交给 sb_far_read、sb_far_write 读写。
464
+
465
+ 系统调用:$30/$04-$07
466
+
467
+ 参数:
468
+
469
+ - `table`:名称表号,0 到 3。
470
+ - `col`:列。
471
+ - `row`:行。
472
+ - `page`:返回页号。
473
+ - `offset`:返回页内偏移。
474
+
475
+ <a id="sb_text_field"></a>
476
+ ### sb_text_field
477
+
478
+ ```c
479
+ void sb_text_field(unsigned char table, unsigned char col, unsigned char row, const char *text, unsigned int cell, unsigned char palette, unsigned char color);
480
+ ```
481
+
482
+ 在屏幕上显示一行文字(可混排汉字与西文):把字符串画成点阵写进显存的图块,再把上下两行单元写进名称表缓冲并刷新。
483
+ 汉字占 2 列;宽度限制在 32 列以内,汉字起点离右边界不足 2 列时不画。
484
+ 二平面模式下,上行第 k 列的单元值是 cell + 2k,下行再加 1。
485
+
486
+ 系统调用:$45
487
+
488
+ 参数:
489
+
490
+ - `table`:名称表号,0 到 3。
491
+ - `col`:起点列。
492
+ - `row`:起点行,文字占上下两行。
493
+ - `text`:以 0 结尾的字符串,在程序窗口里。
494
+ - `cell`:起始图块号(单元值的低 12 位),文字的字模写进显存从它起的图块。
495
+ - `palette`:调色板号,0 到 15。
496
+ - `color`:前景色 0 到 15:每一位决定一个平面里字模是否出现。
497
+
498
+ <a id="sb_text_field_ascii"></a>
499
+ ### sb_text_field_ascii
500
+
501
+ ```c
502
+ void sb_text_field_ascii(unsigned char table, unsigned char col, unsigned char row, const char *text, unsigned int cell, unsigned char palette, unsigned char color);
503
+ ```
504
+
505
+ 同 sb_text_field,但只处理单字节字符,不补空白图块,只写一行单元:第 i 列的单元值是 cell + 步长 × i;步长在大字体(8×16 字模,DOS 的默认)下是 2,小字体下是 1。
506
+
507
+ 系统调用:$46
508
+
509
+ 参数:
510
+
511
+ - `table`:名称表号,0 到 3。
512
+ - `col`:起点列。
513
+ - `row`:行。
514
+ - `text`:以 0 结尾的字符串,在程序窗口里。
515
+ - `cell`:起始图块号。
516
+ - `palette`:调色板号,0 到 15。
517
+ - `color`:前景色 0 到 15。
518
+
519
+ <a id="sb_text_draw"></a>
520
+ ### sb_text_draw
521
+
522
+ ```c
523
+ void sb_text_draw(unsigned int tile, const char *text, unsigned char terminator, unsigned char color, unsigned char four_planes, unsigned char ascii_only);
524
+ ```
525
+
526
+ 把字符串画成点阵图块,经 DMA 写进显存的图块区(目的地址 = 图块号 × 16),不写名称表。
527
+ 返回后 $064C/$064D 被换算成字节地址(图块号 × 16)。
528
+
529
+ 系统调用:$3C、$3D、$3E、$3F
530
+
531
+ 参数:
532
+
533
+ - `tile`:起始图块号。
534
+ - `text`:字符串,在程序窗口里。
535
+ - `terminator`:结束符,读到该字节为止。
536
+ - `color`:前景色 0 到 15:每一位决定一个平面里字模是否出现。
537
+ - `four_planes`:0 画二平面图块(每个 16 字节),非 0 画四平面图块(每个 32 字节)。
538
+ - `ascii_only`:0 处理汉字与西文,非 0 只处理单字节字符。
539
+
540
+ <a id="sb_text_to_memory"></a>
541
+ ### sb_text_to_memory
542
+
543
+ ```c
544
+ unsigned int sb_text_to_memory(const char *text, unsigned char terminator, unsigned char group, unsigned int address, unsigned int capacity, unsigned char four_planes, unsigned char color, unsigned char ascii_only);
545
+ ```
546
+
547
+ 把字符串画成点阵图块,写进调用者指定的扩展 RAM 地址(不经显存)。每个图块二平面 16 字节、四平面 32 字节,按平面顺序各 8 字节;
548
+ 汉字占两个图块宽。目的区装不下下一个字符时在该字符之前停止。目的区跨 4KB 页时窗口 2、3 的映射随之后移,输出线性连续。
549
+
550
+ 系统调用:$47、$48
551
+
552
+ 参数:
553
+
554
+ - `text`:字符串,在程序窗口里。
555
+ - `terminator`:结束符,读到该字节为止(汉字比较第一个字节)。
556
+ - `group`:目的页组的首页号。
557
+ - `address`:目的窗口地址($8000 到 $FFFF,高 4 位选页,低 12 位是页内偏移),页号 = (高 4 位) - 8 + group。
558
+ - `capacity`:目的区还能容纳的字节数。
559
+ - `four_planes`:0 画二平面图块,非 0 画四平面图块。
560
+ - `color`:前景色 0 到 15。
561
+ - `ascii_only`:0 处理汉字与西文,非 0 只处理单字节字符。
562
+
563
+ 返回:实际写入的字节数。
564
+
565
+ <a id="sb_display_mode"></a>
566
+ ### sb_display_mode
567
+
568
+ ```c
569
+ void sb_display_mode(unsigned char mode);
570
+ ```
571
+
572
+ 设置显示模式(显示模式影子 $0638 的高 2 位,决定文字字库区域的取法),低 6 位不变。
573
+
574
+ 系统调用:$11/$00-$03
575
+
576
+ 参数:
577
+
578
+ - `mode`:显示模式 0 到 3,对应高 2 位 $00、$40、$80、$C0。
579
+
580
+ <a id="sb_glyph_address"></a>
581
+ ### sb_glyph_address
582
+
583
+ ```c
584
+ unsigned char sb_glyph_address(unsigned int code, unsigned char *page, unsigned int *offset, unsigned char *shape);
585
+ ```
586
+
587
+ 查字符码对应的字模所在的页与页内地址,不绘制。字符码高字节为 0 时 $20 到 $7F 取西文字模(8×8 或 8×16,由显示模式决定),
588
+ 高字节不小于 $A1 时按 GB2312 区位处理:$A1 到 $A9 区是符号,$B0 到 $F7 区是汉字(32 字节,前 16 字节是每行左半边,后 16 字节是右半边)。
589
+
590
+ 系统调用:$3B
591
+
592
+ 参数:
593
+
594
+ - `code`:字符码,西文放低字节,汉字是 GB2312 内码。
595
+ - `page`:返回字模所在的页。
596
+ - `offset`:返回字模在页内的偏移。
597
+ - `shape`:返回字模形式(低 3 位)。
598
+
599
+ 返回:0 成功;$FF 字符码不合法。
600
+
601
+ <a id="sb_window_init"></a>
602
+ ### sb_window_init
603
+
604
+ ```c
605
+ void sb_window_init(void);
606
+ ```
607
+
608
+ 初始化窗口管理:30 个窗口号全部空闲,保存区末尾回到 $8060。程序开始用窗口之前调用一次。
609
+
610
+ 系统调用:$59/$06
611
+
612
+ <a id="sb_window_save"></a>
613
+ ### sb_window_save
614
+
615
+ ```c
616
+ unsigned char sb_window_save(unsigned char table, unsigned char left, unsigned char top, unsigned char right, unsigned char bottom);
617
+ ```
618
+
619
+ 把名称表缓冲里的一个矩形保存起来,以后用 sb_window_restore 原样写回。只保存缓冲,不碰显存。
620
+
621
+ 系统调用:$59/$00-$03
622
+
623
+ 参数:
624
+
625
+ - `table`:名称表号,0 到 3。
626
+ - `left`:左上角列。
627
+ - `top`:左上角行。
628
+ - `right`:右下角列(含),小于 32。
629
+ - `bottom`:右下角行(含),小于 30。
630
+
631
+ 返回:窗口号 1 到 30;SB_WINDOW_BAD_RECT 坐标不合法;SB_WINDOW_TOO_MANY 窗口用完;SB_WINDOW_NO_ROOM 保存区装不下,出错时窗口表与保存区不变。
632
+
633
+ <a id="sb_window_restore"></a>
634
+ ### sb_window_restore
635
+
636
+ ```c
637
+ void sb_window_restore(unsigned char id);
638
+ ```
639
+
640
+ 把保存的窗口内容写回名称表缓冲并释放窗口号。只写缓冲,不刷新显存,要用 sb_screen_flush 刷新。
641
+ 窗口号不小于 $1F 或表里没有时什么都不做。只有释放的是表里最后一项时才回收保存区,否则留下空洞,要用 sb_window_compact 整理。
642
+
643
+ 系统调用:$59/$04
644
+
645
+ 参数:
646
+
647
+ - `id`:窗口号。
648
+
649
+ <a id="sb_window_compact"></a>
650
+ ### sb_window_compact
651
+
652
+ ```c
653
+ void sb_window_compact(void);
654
+ ```
655
+
656
+ 整理窗口保存区:没有窗口时末尾回到 $8060,否则把后面的数据前移填掉空洞。
657
+ 注意:第一个窗口之后的空洞,系统修正表项的方式只在空洞大小恰等于前一个窗口长度时才正确,其他情况会让表项指向乱数据,不要在窗口之间有空洞时使用。
658
+
659
+ 系统调用:$59/$05
660
+
661
+ <a id="sb_palette_write"></a>
662
+ ### sb_palette_write
663
+
664
+ ```c
665
+ void sb_palette_write(unsigned char offset, const unsigned char *colors, unsigned char count);
666
+ ```
667
+
668
+ 把一组颜色写进调色板,从调色板第 offset 项起。显示开着且 NMI 开着时由 NMI 处理程序写入。
669
+
670
+ 系统调用:$5D
671
+
672
+ 参数:
673
+
674
+ - `offset`:起始项,调色板共 64 项。
675
+ - `colors`:颜色字节,在程序窗口里。
676
+ - `count`:个数,0 什么都不做。
677
+
678
+ <a id="sb_vram_fill"></a>
679
+ ### sb_vram_fill
680
+
681
+ ```c
682
+ void sb_vram_fill(unsigned int address, unsigned int length, unsigned char value);
683
+ ```
684
+
685
+ 用一个字节填充显存的一段。长度为 0 什么都不做。
686
+
687
+ 系统调用:$32
688
+
689
+ 参数:
690
+
691
+ - `address`:显存起始地址。
692
+ - `length`:长度,字节。
693
+ - `value`:填充值。
694
+
695
+ <a id="sb_vram_load"></a>
696
+ ### sb_vram_load
697
+
698
+ ```c
699
+ void sb_vram_load(unsigned char page, unsigned int offset, unsigned int address, unsigned int length);
700
+ ```
701
+
702
+ 把扩展 RAM 里的一段数据经 DMA 写进显存。长度为 0 什么都不做。
703
+
704
+ 系统调用:$33
705
+
706
+ 参数:
707
+
708
+ - `page`:源数据所在的扩展 RAM 页。
709
+ - `offset`:源数据在页内的偏移。
710
+ - `address`:显存目的地址。
711
+ - `length`:长度,字节。
712
+
713
+ <a id="sb_vram_bank"></a>
714
+ ### sb_vram_bank
715
+
716
+ ```c
717
+ void sb_vram_bank(unsigned char bank);
718
+ ```
719
+
720
+ 设置显存 bank 寄存器($4300)。
721
+
722
+ 系统调用:$2A
723
+
724
+ 参数:
725
+
726
+ - `bank`:要写入的值。
727
+
728
+ <a id="sb_image_load_raw"></a>
729
+ ### sb_image_load_raw
730
+
731
+ ```c
732
+ void sb_image_load_raw(const void *data, unsigned int length, unsigned int tile);
733
+ ```
734
+
735
+ 不解压,直接把一段图案数据经 DMA 写进显存的图块区(目的地址 = 图块号 × 16),再等垂直消隐。长度为 0 直接返回。
736
+
737
+ 系统调用:$5A
738
+
739
+ 参数:
740
+
741
+ - `data`:图案数据,在程序窗口里。
742
+ - `length`:长度,字节。
743
+ - `tile`:起始图块号。
744
+
745
+ <a id="sb_image_unpack_tiles"></a>
746
+ ### sb_image_unpack_tiles
747
+
748
+ ```c
749
+ void sb_image_unpack_tiles(const void *stream, unsigned int tile);
750
+ ```
751
+
752
+ 解压图案流并经 DMA 写进显存的图块区。流的格式:16 字节字典加指令流,指令字节 $00 结束;
753
+ 指令字节高 4 位 H、低 4 位 L:H 为 1 到 12 把字典第 L 项重复 H 次,H=$D 后跟 L 个原样字节,H=$E 后跟 1 个字节重复 L 次,H=$F 后跟起始字节输出 L 个递增字节。
754
+
755
+ 系统调用:$5B
756
+
757
+ 参数:
758
+
759
+ - `stream`:图案流,在程序窗口里。
760
+ - `tile`:起始图块号。
761
+
762
+ <a id="sb_image_unpack_map"></a>
763
+ ### sb_image_unpack_map
764
+
765
+ ```c
766
+ void sb_image_unpack_map(const void *stream, const sb_map_t *map);
767
+ ```
768
+
769
+ 解压映射流并按效果写进屏幕:流里的单元值加上 map->base 与调色板位,再按效果把矩形写进名称表缓冲并刷新到显存。
770
+ 指令字节高 3 位 T、低 5 位 N:$00 结束;T=0 取一个 16 位值填 N 个;T=1 取一个值,N 个单元依次加 1;T=2 取 N 个 16 位值;T=3 先取一个高字节再取 N 个低字节;T 不小于 4 取一个值,N 个单元依次加 2。
771
+ 矩形限制在 32×32 内,起点列或行不小于 32 或宽高为 0 时什么都不写。
772
+
773
+ 系统调用:$5C
774
+
775
+ 参数:
776
+
777
+ - `stream`:映射流,在程序窗口里。
778
+ - `map`:写到屏幕的位置、效果与速度。
779
+
780
+ <a id="sb_image_fill_rect"></a>
781
+ ### sb_image_fill_rect
782
+
783
+ ```c
784
+ void sb_image_fill_rect(const sb_map_t *map);
785
+ ```
786
+
787
+ 用与 sb_image_unpack_map 相同的效果把一个单元值(map->base)铺满矩形,不加调色板位。
788
+
789
+ 系统调用:$60
790
+
791
+ 参数:
792
+
793
+ - `map`:矩形、效果与速度;base 是单元值。
794
+
795
+ <a id="sb_image_show"></a>
796
+ ### sb_image_show
797
+
798
+ ```c
799
+ void sb_image_show(const void *image, const sb_map_t *map, unsigned char palette_group);
800
+ ```
801
+
802
+ 显示压缩图片:10 字节头 [宽、高、图案数(16 位)、调色板组数、每组色数、映射流偏移(16 位)、调色板偏移(16 位)](偏移相对头的起点),
803
+ 先解压图案流(头后,图块号取 map->base),再写调色板(偏移 = 调色板组号 × 每组色数,长度 = 头里的组数 × 每组色数),最后按映射流、位置、效果与速度显示。
804
+
805
+ 系统调用:$5F
806
+
807
+ 参数:
808
+
809
+ - `image`:图片数据(头加图案流、映射流、调色板),在程序窗口里。
810
+ - `map`:位置、效果、速度;base 是图案的起始图块号。
811
+ - `palette_group`:调色板组号。
812
+
813
+ <a id="sb_image_show_full"></a>
814
+ ### sb_image_show_full
815
+
816
+ ```c
817
+ void sb_image_show_full(const void *image, unsigned int tile, unsigned char table);
818
+ ```
819
+
820
+ 显示整屏图片:头格式同 sb_image_show;图案流解压到起始图块 tile,映射流直接按顺序解到名称表缓冲的开头(单元基础值是 tile,不加调色板位),
821
+ 解完整张名称表 DMA 一次,调色板从第 0 项起写 $40 字节。
822
+
823
+ 系统调用:$5E
824
+
825
+ 参数:
826
+
827
+ - `image`:图片数据,在程序窗口里。
828
+ - `tile`:起始图块号。
829
+ - `table`:名称表号,0 到 3。
830
+
831
+ <a id="sb_image_unpack_to_memory"></a>
832
+ ### sb_image_unpack_to_memory
833
+
834
+ ```c
835
+ unsigned int sb_image_unpack_to_memory(const void *stream, unsigned char group, unsigned int address);
836
+ ```
837
+
838
+ 把图案流解压到内存,格式同 sb_image_unpack_tiles。目的地址 address 是窗口地址($8000 到 $FFFF,高 4 位选页,低 12 位是页内偏移),
839
+ 页号 = (address 高 4 位) - 8 + group;目的页与下一页映射到窗口 2、3,所以目的地址线性连续。
840
+
841
+ 系统调用:$61
842
+
843
+ 参数:
844
+
845
+ - `stream`:图案流,在程序窗口里。
846
+ - `group`:目的页组的首页号。
847
+ - `address`:目的窗口地址。
848
+
849
+ 返回:解出的字节数。
850
+
851
+ <a id="file"></a>
852
+ ## 文件与目录(sb2000-file.h)
853
+
854
+ | 函数 | 说明 | 系统调用 |
855
+ | --- | --- | --- |
856
+ | [`sb_file_open`](#sb_file_open) | 打开文件或目录项。打开方式用 SB_MODE_ 开头的常量: | $7B/$09 |
857
+ | [`sb_file_close`](#sb_file_close) | 关闭文件,写回目录项,并让软驱停转。关闭空闲的句柄什么都不做,也不出错。 | $7C/$02 |
858
+ | [`sb_file_size`](#sb_file_size) | 取文件大小。 | $7C/$0D |
859
+ | [`sb_file_read`](#sb_file_read) | 从文件的指定位置读数据到内存,长度不限(内部分块读)。 | $7C/$05 |
860
+ | [`sb_file_write`](#sb_file_write) | 改写文件里已有的一段数据,文件大小不变(内部分块写)。不能用它扩大文件或新建文件,那些用 sb_file_write_all 或 sb_file_save。 | $7C/$06 |
861
+ | [`sb_file_write_all`](#sb_file_write_all) | 把内存里的数据写成一个文件(已存在则覆盖),文件大小就是数据长度。数据先放进临时分配的扩展 RAM 页,再整个写出。 | $7C/$10 |
862
+ | [`sb_file_load`](#sb_file_load) | 把整个文件读入新分配的扩展 RAM 页,适合比内存大的文件:数据在页里,用 sb_far_read 按需取出。 | $7C/$0F |
863
+ | [`sb_file_save`](#sb_file_save) | 把扩展 RAM 页里的数据整个写成一个文件(已存在则覆盖)。数据长度为 0 时只创建空文件。 | $7C/$10 |
864
+ | [`sb_file_delete`](#sb_file_delete) | 删除文件:目录项标为已删除并释放空间,之后软驱停转。 | $7C/$03 |
865
+ | [`sb_file_rename`](#sb_file_rename) | 给文件改名。新名称是 NAME.EXT 格式,不含目录。 | $7C/$04 |
866
+ | [`sb_file_get_date`](#sb_file_get_date) | 取已打开文件的修改日期。 | $7C/$08 |
867
+ | [`sb_file_set_date`](#sb_file_set_date) | 设置已打开文件的修改日期,关闭时写回目录项(方式 SB_MODE_CREATE、SB_MODE_UPDATE)。 | $7C/$07 |
868
+ | [`sb_file_get_time`](#sb_file_get_time) | 取已打开文件的修改时间。 | $7C/$0A |
869
+ | [`sb_file_set_time`](#sb_file_set_time) | 设置已打开文件的修改时间,关闭时写回目录项(方式 SB_MODE_CREATE、SB_MODE_UPDATE)。 | $7C/$09 |
870
+ | [`sb_file_get_attr`](#sb_file_get_attr) | 取已打开文件的属性。 | $7C/$0C |
871
+ | [`sb_file_set_attr`](#sb_file_set_attr) | 设置已打开文件的属性,关闭时写回目录项(方式 SB_MODE_CREATE、SB_MODE_UPDATE)。 | $7C/$0B |
872
+ | [`sb_dir_make`](#sb_dir_make) | 创建子目录。只支持一级子目录,在子目录里再建目录出错。 | $7D/$02 |
873
+ | [`sb_dir_remove`](#sb_dir_remove) | 删除空的子目录。 | $7D/$03 |
874
+ | [`sb_dir_change`](#sb_dir_change) | 设置当前目录,相对路径都以它为起点。 | $7B/$0B |
875
+ | [`sb_dir_current`](#sb_dir_current) | 取当前目录自己的名称,格式 \NAME.EXT,根目录是 \。 | $7D/$01 |
876
+ | [`sb_dir_open`](#sb_dir_open) | 开始遍历一个目录。遍历期间不要做其他磁盘操作,它们会占用同一个扇区缓冲。 | $7B/$01、$7B/$03、$7B/$09 |
877
+ | [`sb_dir_read`](#sb_dir_read) | 取下一个目录项,跳过已删除的项;卷标和子目录也会返回,用属性区分。 | $7B/$00、$7B/$01 |
878
+
879
+ <a id="sb_file_open"></a>
880
+ ### sb_file_open
881
+
882
+ ```c
883
+ unsigned char sb_file_open(const char *path, unsigned char mode, unsigned char *handle);
884
+ ```
885
+
886
+ 打开文件或目录项。打开方式用 SB_MODE_ 开头的常量:
887
+ SB_MODE_OPEN 打开已有文件(只读);SB_MODE_CREATE 创建文件,已存在则覆盖;
888
+ SB_MODE_UPDATE 打开已有文件,可按偏移写,关闭时写回目录项;SB_MODE_ENTRY 取得根目录或子目录的目录项。
889
+ 相对路径在当前目录里找。
890
+
891
+ 系统调用:$7B/$09
892
+
893
+ 参数:
894
+
895
+ - `path`:路径,零结尾,最长 28 个字符。
896
+ - `mode`:打开方式。
897
+ - `handle`:返回句柄号,0 到 3。
898
+
899
+ 返回:0 成功;SB_ERR_FILE_NOT_FOUND 文件不存在;SB_ERR_PATH_NOT_FOUND 目录不存在;SB_ERR_TOO_MANY_FILES 4 个句柄都在用; SB_ERR_BAD_NAME 名称含非法字符或路径过长;SB_ERR_BAD_OPEN_MODE 打开方式不合法;SB_ERR_ACCESS_DENIED 名称与卷标同名。
900
+
901
+ <a id="sb_file_close"></a>
902
+ ### sb_file_close
903
+
904
+ ```c
905
+ unsigned char sb_file_close(unsigned char handle);
906
+ ```
907
+
908
+ 关闭文件,写回目录项,并让软驱停转。关闭空闲的句柄什么都不做,也不出错。
909
+
910
+ 系统调用:$7C/$02
911
+
912
+ 参数:
913
+
914
+ - `handle`:句柄号。
915
+
916
+ 返回:0 成功;SB_ERR_BAD_PARAMETER 句柄号超出 0-3。
917
+
918
+ <a id="sb_file_size"></a>
919
+ ### sb_file_size
920
+
921
+ ```c
922
+ unsigned char sb_file_size(unsigned char handle, unsigned long *size);
923
+ ```
924
+
925
+ 取文件大小。
926
+
927
+ 系统调用:$7C/$0D
928
+
929
+ 参数:
930
+
931
+ - `handle`:句柄号。
932
+ - `size`:返回文件大小,字节。
933
+
934
+ 返回:0 成功。
935
+
936
+ <a id="sb_file_read"></a>
937
+ ### sb_file_read
938
+
939
+ ```c
940
+ unsigned char sb_file_read(unsigned char handle, unsigned long offset, void *dest, unsigned int length);
941
+ ```
942
+
943
+ 从文件的指定位置读数据到内存,长度不限(内部分块读)。
944
+
945
+ 系统调用:$7C/$05
946
+
947
+ 参数:
948
+
949
+ - `handle`:句柄号,打开方式要是 SB_MODE_OPEN、SB_MODE_CREATE 或 SB_MODE_UPDATE。
950
+ - `offset`:文件内偏移。
951
+ - `dest`:目的地,必须在程序窗口 $8000-$BFFF 内,且不在窗口 3($B000-$BFFF)。
952
+ - `length`:字节数;偏移不小于文件大小或偏移加长度超过文件大小时出错,数据不会被截短读入。
953
+
954
+ 返回:0 成功;$14 读写位置超出文件;SB_ERR_BAD_OPEN_MODE 打开方式不允许读;SB_ERR_NO_MEMORY 没有空闲页做中转。
955
+
956
+ <a id="sb_file_write"></a>
957
+ ### sb_file_write
958
+
959
+ ```c
960
+ unsigned char sb_file_write(unsigned char handle, unsigned long offset, const void *src, unsigned int length);
961
+ ```
962
+
963
+ 改写文件里已有的一段数据,文件大小不变(内部分块写)。不能用它扩大文件或新建文件,那些用 sb_file_write_all 或 sb_file_save。
964
+
965
+ 系统调用:$7C/$06
966
+
967
+ 参数:
968
+
969
+ - `handle`:句柄号,打开方式要是 SB_MODE_CREATE 或 SB_MODE_UPDATE。
970
+ - `offset`:文件内偏移。
971
+ - `src`:数据来源,位置的要求同 sb_file_read 的 dest。
972
+ - `length`:字节数。
973
+
974
+ 返回:0 成功;$14 写入范围超出文件当前大小;SB_ERR_BAD_OPEN_MODE 打开方式不允许写;SB_ERR_NO_MEMORY 没有空闲页做中转。
975
+
976
+ <a id="sb_file_write_all"></a>
977
+ ### sb_file_write_all
978
+
979
+ ```c
980
+ unsigned char sb_file_write_all(const char *path, const void *data, unsigned int length);
981
+ ```
982
+
983
+ 把内存里的数据写成一个文件(已存在则覆盖),文件大小就是数据长度。数据先放进临时分配的扩展 RAM 页,再整个写出。
984
+
985
+ 系统调用:$7C/$10
986
+
987
+ 参数:
988
+
989
+ - `path`:路径。
990
+ - `data`:数据,位置的要求同 sb_file_read 的 dest。
991
+ - `length`:字节数,0 只创建空文件。
992
+
993
+ 返回:0 成功;SB_ERR_NO_MEMORY 没有足够的页;SB_ERR_NO_SPACE 磁盘空间不够;其他是创建与写入的出错码。
994
+
995
+ <a id="sb_file_load"></a>
996
+ ### sb_file_load
997
+
998
+ ```c
999
+ unsigned char sb_file_load(const char *path, unsigned char *first_page, unsigned long *size);
1000
+ ```
1001
+
1002
+ 把整个文件读入新分配的扩展 RAM 页,适合比内存大的文件:数据在页里,用 sb_far_read 按需取出。
1003
+ 用完要用 sb_page_free 释放页。空文件不分配页,页号返回 0。
1004
+
1005
+ 系统调用:$7C/$0F
1006
+
1007
+ 参数:
1008
+
1009
+ - `path`:路径。
1010
+ - `first_page`:返回第一个页号。
1011
+ - `size`:返回文件大小,字节。
1012
+
1013
+ 返回:0 成功;SB_ERR_NO_MEMORY 没有足够的连续空闲页;其他是打开与读取的出错码。
1014
+
1015
+ <a id="sb_file_save"></a>
1016
+ ### sb_file_save
1017
+
1018
+ ```c
1019
+ unsigned char sb_file_save(const char *path, unsigned char first_page, unsigned long size);
1020
+ ```
1021
+
1022
+ 把扩展 RAM 页里的数据整个写成一个文件(已存在则覆盖)。数据长度为 0 时只创建空文件。
1023
+
1024
+ 系统调用:$7C/$10
1025
+
1026
+ 参数:
1027
+
1028
+ - `path`:路径。
1029
+ - `first_page`:数据的第一个页号。
1030
+ - `size`:数据长度,字节,不超过 16777215。
1031
+
1032
+ 返回:0 成功;SB_ERR_NO_SPACE 磁盘空间不够,已写入的其他文件完好;其他是创建与写入的出错码。
1033
+
1034
+ <a id="sb_file_delete"></a>
1035
+ ### sb_file_delete
1036
+
1037
+ ```c
1038
+ unsigned char sb_file_delete(const char *path);
1039
+ ```
1040
+
1041
+ 删除文件:目录项标为已删除并释放空间,之后软驱停转。
1042
+
1043
+ 系统调用:$7C/$03
1044
+
1045
+ 参数:
1046
+
1047
+ - `path`:路径。
1048
+
1049
+ 返回:0 成功;SB_ERR_ACCESS_DENIED 文件是只读的;SB_ERR_FILE_NOT_FOUND 文件不存在。
1050
+
1051
+ <a id="sb_file_rename"></a>
1052
+ ### sb_file_rename
1053
+
1054
+ ```c
1055
+ unsigned char sb_file_rename(const char *path, const char *new_name);
1056
+ ```
1057
+
1058
+ 给文件改名。新名称是 NAME.EXT 格式,不含目录。
1059
+
1060
+ 系统调用:$7C/$04
1061
+
1062
+ 参数:
1063
+
1064
+ - `path`:原路径。
1065
+ - `new_name`:新名称。
1066
+
1067
+ 返回:0 成功;SB_ERR_FILE_EXISTS 新名称已存在;SB_ERR_BAD_NAME 新名称含非法字符。
1068
+
1069
+ <a id="sb_file_get_date"></a>
1070
+ ### sb_file_get_date
1071
+
1072
+ ```c
1073
+ unsigned char sb_file_get_date(unsigned char handle, sb_date_t *date);
1074
+ ```
1075
+
1076
+ 取已打开文件的修改日期。
1077
+
1078
+ 系统调用:$7C/$08
1079
+
1080
+ 参数:
1081
+
1082
+ - `handle`:句柄号。
1083
+ - `date`:返回日期。
1084
+
1085
+ 返回:0 成功。
1086
+
1087
+ <a id="sb_file_set_date"></a>
1088
+ ### sb_file_set_date
1089
+
1090
+ ```c
1091
+ unsigned char sb_file_set_date(unsigned char handle, const sb_date_t *date);
1092
+ ```
1093
+
1094
+ 设置已打开文件的修改日期,关闭时写回目录项(方式 SB_MODE_CREATE、SB_MODE_UPDATE)。
1095
+
1096
+ 系统调用:$7C/$07
1097
+
1098
+ 参数:
1099
+
1100
+ - `handle`:句柄号。
1101
+ - `date`:新日期。
1102
+
1103
+ 返回:0 成功;SB_ERR_BAD_PARAMETER 日期不合法。
1104
+
1105
+ <a id="sb_file_get_time"></a>
1106
+ ### sb_file_get_time
1107
+
1108
+ ```c
1109
+ unsigned char sb_file_get_time(unsigned char handle, sb_time_t *time);
1110
+ ```
1111
+
1112
+ 取已打开文件的修改时间。
1113
+
1114
+ 系统调用:$7C/$0A
1115
+
1116
+ 参数:
1117
+
1118
+ - `handle`:句柄号。
1119
+ - `time`:返回时间。
1120
+
1121
+ 返回:0 成功。
1122
+
1123
+ <a id="sb_file_set_time"></a>
1124
+ ### sb_file_set_time
1125
+
1126
+ ```c
1127
+ unsigned char sb_file_set_time(unsigned char handle, const sb_time_t *time);
1128
+ ```
1129
+
1130
+ 设置已打开文件的修改时间,关闭时写回目录项(方式 SB_MODE_CREATE、SB_MODE_UPDATE)。
1131
+
1132
+ 系统调用:$7C/$09
1133
+
1134
+ 参数:
1135
+
1136
+ - `handle`:句柄号。
1137
+ - `time`:新时间。
1138
+
1139
+ 返回:0 成功;SB_ERR_BAD_PARAMETER 时间不合法。
1140
+
1141
+ <a id="sb_file_get_attr"></a>
1142
+ ### sb_file_get_attr
1143
+
1144
+ ```c
1145
+ unsigned char sb_file_get_attr(unsigned char handle, unsigned char *attr);
1146
+ ```
1147
+
1148
+ 取已打开文件的属性。
1149
+
1150
+ 系统调用:$7C/$0C
1151
+
1152
+ 参数:
1153
+
1154
+ - `handle`:句柄号。
1155
+ - `attr`:返回属性,SB_ATTR_ 开头的常量按位组合。
1156
+
1157
+ 返回:0 成功。
1158
+
1159
+ <a id="sb_file_set_attr"></a>
1160
+ ### sb_file_set_attr
1161
+
1162
+ ```c
1163
+ unsigned char sb_file_set_attr(unsigned char handle, unsigned char attr);
1164
+ ```
1165
+
1166
+ 设置已打开文件的属性,关闭时写回目录项(方式 SB_MODE_CREATE、SB_MODE_UPDATE)。
1167
+ 属性大于 $3F 或带卷标位时出错。只读文件不能删除,方式 SB_MODE_CREATE 打开则直接覆盖并恢复成存档属性。
1168
+
1169
+ 系统调用:$7C/$0B
1170
+
1171
+ 参数:
1172
+
1173
+ - `handle`:句柄号。
1174
+ - `attr`:新属性。
1175
+
1176
+ 返回:0 成功;SB_ERR_BAD_PARAMETER 属性不合法。
1177
+
1178
+ <a id="sb_dir_make"></a>
1179
+ ### sb_dir_make
1180
+
1181
+ ```c
1182
+ unsigned char sb_dir_make(const char *path);
1183
+ ```
1184
+
1185
+ 创建子目录。只支持一级子目录,在子目录里再建目录出错。
1186
+
1187
+ 系统调用:$7D/$02
1188
+
1189
+ 参数:
1190
+
1191
+ - `path`:路径。
1192
+
1193
+ 返回:0 成功;SB_ERR_DIR_EXISTS 目录已存在;SB_ERR_DUPLICATE_NAME 同名文件已存在;SB_ERR_PATH_NOT_FOUND 父目录不存在;SB_ERR_DIR_TOO_DEEP 目录嵌套层数过多。
1194
+
1195
+ <a id="sb_dir_remove"></a>
1196
+ ### sb_dir_remove
1197
+
1198
+ ```c
1199
+ unsigned char sb_dir_remove(const char *path);
1200
+ ```
1201
+
1202
+ 删除空的子目录。
1203
+
1204
+ 系统调用:$7D/$03
1205
+
1206
+ 参数:
1207
+
1208
+ - `path`:路径。
1209
+
1210
+ 返回:0 成功;SB_ERR_DIR_NOT_EMPTY 目录非空;SB_ERR_ACCESS_DENIED 目录是只读的;SB_ERR_DUPLICATE_NAME 路径是文件;SB_ERR_PATH_NOT_FOUND 路径不存在。
1211
+
1212
+ <a id="sb_dir_change"></a>
1213
+ ### sb_dir_change
1214
+
1215
+ ```c
1216
+ unsigned char sb_dir_change(const char *path);
1217
+ ```
1218
+
1219
+ 设置当前目录,相对路径都以它为起点。
1220
+
1221
+ 系统调用:$7B/$0B
1222
+
1223
+ 参数:
1224
+
1225
+ - `path`:路径,根目录写 "\"。
1226
+
1227
+ 返回:0 成功;SB_ERR_PATH_NOT_FOUND 路径不存在或是文件,当前目录不变。
1228
+
1229
+ <a id="sb_dir_current"></a>
1230
+ ### sb_dir_current
1231
+
1232
+ ```c
1233
+ unsigned char sb_dir_current(char *name);
1234
+ ```
1235
+
1236
+ 取当前目录自己的名称,格式 \NAME.EXT,根目录是 \。
1237
+
1238
+ 系统调用:$7D/$01
1239
+
1240
+ 参数:
1241
+
1242
+ - `name`:返回名称,缓冲区至少 16 个字节。
1243
+
1244
+ 返回:0 成功。
1245
+
1246
+ <a id="sb_dir_open"></a>
1247
+ ### sb_dir_open
1248
+
1249
+ ```c
1250
+ unsigned char sb_dir_open(const char *path);
1251
+ ```
1252
+
1253
+ 开始遍历一个目录。遍历期间不要做其他磁盘操作,它们会占用同一个扇区缓冲。
1254
+
1255
+ 系统调用:$7B/$01、$7B/$03、$7B/$09
1256
+
1257
+ 参数:
1258
+
1259
+ - `path`:目录路径;写 NULL 或空字符串表示当前目录,"\" 表示根目录。
1260
+
1261
+ 返回:0 成功;SB_ERR_PATH_NOT_FOUND 目录不存在;其他是磁盘出错码。
1262
+
1263
+ <a id="sb_dir_read"></a>
1264
+ ### sb_dir_read
1265
+
1266
+ ```c
1267
+ unsigned char sb_dir_read(sb_dir_entry_t *entry);
1268
+ ```
1269
+
1270
+ 取下一个目录项,跳过已删除的项;卷标和子目录也会返回,用属性区分。
1271
+
1272
+ 系统调用:$7B/$00、$7B/$01
1273
+
1274
+ 参数:
1275
+
1276
+ - `entry`:返回目录项。
1277
+
1278
+ 返回:0 取到一项;SB_DIR_END 已经没有更多的项;其他是磁盘出错码。
1279
+
1280
+ <a id="ime"></a>
1281
+ ## 中文输入法(sb2000-ime.h)
1282
+
1283
+ | 函数 | 说明 | 系统调用 |
1284
+ | --- | --- | --- |
1285
+ | [`sb_ime_init`](#sb_ime_init) | 初始化输入法:记下状态行的位置与颜色,选择初始输入法,登记说明文字。 | $6D/$00 |
1286
+ | [`sb_ime_select`](#sb_ime_select) | 选择输入法。成功时清按键队列与输入缓冲,状态行换成该输入法的名称。 | $6D/$01 |
1287
+ | [`sb_ime_set_state`](#sb_ime_set_state) | 设置输入法状态:允许位与标志位(只取低 7 位,位 7 保留)。 | $6D/$02 |
1288
+ | [`sb_ime_get_state`](#sb_ime_get_state) | 取输入法状态。 | $6D/$08 |
1289
+ | [`sb_ime_get_method`](#sb_ime_get_method) | 取当前输入法序号。 | $6D/$07 |
1290
+ | [`sb_ime_resume`](#sb_ime_resume) | 恢复被暂停的输入法:暂停标志置位时清除它并刷新状态行,否则什么都不做。 | $6D/$03 |
1291
+ | [`sb_ime_suspend`](#sb_ime_suspend) | 暂停输入法:清候选字,状态行清为空,暂停标志置位。已经暂停时什么都不做。暂停期间按键原样传回。 | $6D/$04 |
1292
+ | [`sb_ime_set_width`](#sb_ime_set_width) | 设置半角或全角:状态行文字换成“半角”或“全角”,标志位里的全角位相应清除或置位。全角时输出的半角符号会换成全角内码。 | $6D/$05、$6D/$06 |
1293
+ | [`sb_ime_key`](#sb_ime_key) | 处理一个按键(不等待):从键盘队列取一个键交给输入法,没有键时直接返回。 | $6D/$0B |
1294
+ | [`sb_ime_key_wait`](#sb_ime_key_wait) | 等待并处理按键,直到输入法有结果(结果标志不为 0)才返回,没有键时一直等下去。 | $6D/$0A |
1295
+ | [`sb_ime_hex`](#sb_ime_hex) | 把一个 16 位内码转成 4 个小写十六进制字符。 | $6D/$0E |
1296
+ | [`sb_ime_parse`](#sb_ime_parse) | 把 4 个输入字符转成汉字内码:全是数字当区位码(4 位十进制),第一个字符是 a 到 f 当 4 位十六进制内码。 | $6D/$0D |
1297
+
1298
+ <a id="sb_ime_init"></a>
1299
+ ### sb_ime_init
1300
+
1301
+ ```c
1302
+ unsigned char sb_ime_init(const sb_ime_config_t *config);
1303
+ ```
1304
+
1305
+ 初始化输入法:记下状态行的位置与颜色,选择初始输入法,登记说明文字。
1306
+
1307
+ 系统调用:$6D/$00
1308
+
1309
+ 参数:
1310
+
1311
+ - `config`:初始化参数。
1312
+
1313
+ 返回:0 成功;1 输入法序号不小于 10、没有权限或不可选,其余参数已写入。
1314
+
1315
+ <a id="sb_ime_select"></a>
1316
+ ### sb_ime_select
1317
+
1318
+ ```c
1319
+ unsigned char sb_ime_select(unsigned char method, unsigned char flags);
1320
+ ```
1321
+
1322
+ 选择输入法。成功时清按键队列与输入缓冲,状态行换成该输入法的名称。
1323
+
1324
+ 系统调用:$6D/$01
1325
+
1326
+ 参数:
1327
+
1328
+ - `method`:输入法序号 0 到 9;序号 3 到 6 要 ERAM $0392 里对应的位允许,7 不可选。
1329
+ - `flags`:0,或 SB_IME_CHECK_ALLOWED 表示同时核对允许位。
1330
+
1331
+ 返回:0 成功;1 失败,状态不变。
1332
+
1333
+ <a id="sb_ime_set_state"></a>
1334
+ ### sb_ime_set_state
1335
+
1336
+ ```c
1337
+ void sb_ime_set_state(unsigned char allow, unsigned char flags);
1338
+ ```
1339
+
1340
+ 设置输入法状态:允许位与标志位(只取低 7 位,位 7 保留)。
1341
+
1342
+ 系统调用:$6D/$02
1343
+
1344
+ 参数:
1345
+
1346
+ - `allow`:允许位。
1347
+ - `flags`:标志位。
1348
+
1349
+ <a id="sb_ime_get_state"></a>
1350
+ ### sb_ime_get_state
1351
+
1352
+ ```c
1353
+ void sb_ime_get_state(unsigned char *allow, unsigned char *flags);
1354
+ ```
1355
+
1356
+ 取输入法状态。
1357
+
1358
+ 系统调用:$6D/$08
1359
+
1360
+ 参数:
1361
+
1362
+ - `allow`:返回允许位。
1363
+ - `flags`:返回标志位的低 7 位。
1364
+
1365
+ <a id="sb_ime_get_method"></a>
1366
+ ### sb_ime_get_method
1367
+
1368
+ ```c
1369
+ unsigned char sb_ime_get_method(void);
1370
+ ```
1371
+
1372
+ 取当前输入法序号。
1373
+
1374
+ 系统调用:$6D/$07
1375
+
1376
+ 返回:序号 0 到 9。
1377
+
1378
+ <a id="sb_ime_resume"></a>
1379
+ ### sb_ime_resume
1380
+
1381
+ ```c
1382
+ void sb_ime_resume(void);
1383
+ ```
1384
+
1385
+ 恢复被暂停的输入法:暂停标志置位时清除它并刷新状态行,否则什么都不做。
1386
+
1387
+ 系统调用:$6D/$03
1388
+
1389
+ <a id="sb_ime_suspend"></a>
1390
+ ### sb_ime_suspend
1391
+
1392
+ ```c
1393
+ void sb_ime_suspend(void);
1394
+ ```
1395
+
1396
+ 暂停输入法:清候选字,状态行清为空,暂停标志置位。已经暂停时什么都不做。暂停期间按键原样传回。
1397
+
1398
+ 系统调用:$6D/$04
1399
+
1400
+ <a id="sb_ime_set_width"></a>
1401
+ ### sb_ime_set_width
1402
+
1403
+ ```c
1404
+ void sb_ime_set_width(unsigned char full);
1405
+ ```
1406
+
1407
+ 设置半角或全角:状态行文字换成“半角”或“全角”,标志位里的全角位相应清除或置位。全角时输出的半角符号会换成全角内码。
1408
+
1409
+ 系统调用:$6D/$05、$6D/$06
1410
+
1411
+ 参数:
1412
+
1413
+ - `full`:0 半角,非 0 全角。
1414
+
1415
+ <a id="sb_ime_key"></a>
1416
+ ### sb_ime_key
1417
+
1418
+ ```c
1419
+ unsigned char sb_ime_key(sb_ime_result_t *result);
1420
+ ```
1421
+
1422
+ 处理一个按键(不等待):从键盘队列取一个键交给输入法,没有键时直接返回。
1423
+ 输入法的热键:Alt+F1 到 Alt+F10 选输入法 0 到 9,Ctrl+F1 暂停与恢复,Ctrl+F8、Ctrl+F9 切换全角半角,数字键 1 到 5 与空格选候选字。
1424
+
1425
+ 系统调用:$6D/$0B
1426
+
1427
+ 参数:
1428
+
1429
+ - `result`:返回处理结果。
1430
+
1431
+ 返回:结果标志,同 result->flag:0 无输出,2 输出汉字内码,$82 按键原样传回。
1432
+
1433
+ <a id="sb_ime_key_wait"></a>
1434
+ ### sb_ime_key_wait
1435
+
1436
+ ```c
1437
+ unsigned char sb_ime_key_wait(sb_ime_result_t *result);
1438
+ ```
1439
+
1440
+ 等待并处理按键,直到输入法有结果(结果标志不为 0)才返回,没有键时一直等下去。
1441
+
1442
+ 系统调用:$6D/$0A
1443
+
1444
+ 参数:
1445
+
1446
+ - `result`:返回处理结果。
1447
+
1448
+ 返回:结果标志,同 result->flag。
1449
+
1450
+ <a id="sb_ime_hex"></a>
1451
+ ### sb_ime_hex
1452
+
1453
+ ```c
1454
+ void sb_ime_hex(unsigned int code, char *text);
1455
+ ```
1456
+
1457
+ 把一个 16 位内码转成 4 个小写十六进制字符。
1458
+
1459
+ 系统调用:$6D/$0E
1460
+
1461
+ 参数:
1462
+
1463
+ - `code`:内码。
1464
+ - `text`:返回 4 个字符与结尾的 0,要有 5 字节空间。
1465
+
1466
+ <a id="sb_ime_parse"></a>
1467
+ ### sb_ime_parse
1468
+
1469
+ ```c
1470
+ unsigned char sb_ime_parse(const char *chars, unsigned int *code);
1471
+ ```
1472
+
1473
+ 把 4 个输入字符转成汉字内码:全是数字当区位码(4 位十进制),第一个字符是 a 到 f 当 4 位十六进制内码。
1474
+
1475
+ 系统调用:$6D/$0D
1476
+
1477
+ 参数:
1478
+
1479
+ - `chars`:4 个输入字符。
1480
+ - `code`:返回内码。
1481
+
1482
+ 返回:0 成功;1 不合法。
1483
+
1484
+ <a id="input"></a>
1485
+ ## 键盘、手柄与鼠标(sb2000-input.h)
1486
+
1487
+ | 函数 | 说明 | 系统调用 |
1488
+ | --- | --- | --- |
1489
+ | [`sb_getkey`](#sb_getkey) | 等待按键并返回它的 ASCII 码。 | |
1490
+ | [`sb_key_wait`](#sb_key_wait) | 等到有按键,取出它的 ASCII 码与扫描码。 | $6B/$04 |
1491
+ | [`sb_key_poll`](#sb_key_poll) | 不等待,取出队列里的一个按键。 | $6B/$03 |
1492
+ | [`sb_key_count`](#sb_key_count) | 按键队列里的按键数。 | $6B/$06 |
1493
+ | [`sb_key_flush`](#sb_key_flush) | 清空按键队列。 | $6B/$05 |
1494
+ | [`sb_key_init`](#sb_key_init) | 复位键盘与鼠标,清空按键队列。约需几十帧。 | $6B/$00 |
1495
+ | [`sb_break_enable`](#sb_break_enable) | 打开按 ESC 中断程序:之后按 ESC,系统取出上下文栈顶的恢复点(sb_context_save 保存的)并跳转过去。 | $6B/$01 |
1496
+ | [`sb_break_disable`](#sb_break_disable) | 关闭按 ESC 中断程序。 | $6B/$02 |
1497
+ | [`sb_key_modifiers`](#sb_key_modifiers) | 修饰键状态:位 0 右 Shift,位 1 左 Shift,位 2 Ctrl,位 3 Alt,位 4 ScrollLock,位 5 NumLock,位 6 CapsLock,位 7 Insert。 | |
1498
+ | [`sb_keyboard_reset`](#sb_keyboard_reset) | 复位并识别键盘。复位后键盘不再上报按键,需要再调用 sb_key_init 才恢复,一般用 sb_key_init 即可。 | $17 |
1499
+ | [`sb_pad_init`](#sb_pad_init) | 初始化手柄状态,并打开 NMI 里读手柄的服务。 | $12/$85、$6A/$00 |
1500
+ | [`sb_pad_poll`](#sb_pad_poll) | 不等待,取一个按下的手柄键。 | $6A/$01 |
1501
+ | [`sb_pad_wait`](#sb_pad_wait) | 等到有手柄键按下。 | $6A/$02 |
1502
+ | [`sb_pad_state`](#sb_pad_state) | 取一个手柄的原始按键状态,由 sb_pad_poll、sb_pad_wait 更新:位 7 是 A,位 6 是 B,位 5 选择,位 4 开始, | |
1503
+ | [`sb_mouse_reset`](#sb_mouse_reset) | 复位鼠标,返回鼠标是否接入。复位要尝试多次,约需几十帧;之后要用 sb_irq_enable(SB_IRQ_SOURCE_MOUSE) 允许鼠标中断, | $14 |
1504
+ | [`sb_mouse_set_limits`](#sb_mouse_set_limits) | 设置鼠标光标坐标的范围,原有的双击间隔不变。 | $6C/$00 |
1505
+ | [`sb_mouse_set_position`](#sb_mouse_set_position) | 设置鼠标光标的坐标。 | $6C/$04 |
1506
+ | [`sb_mouse_position`](#sb_mouse_position) | 取鼠标光标的坐标。每收到一个数据包,坐标就加上位移,并限制在设置的范围内。 | $6C/$02 |
1507
+ | [`sb_mouse_buttons`](#sb_mouse_buttons) | 取两个鼠标键的状态。单击、双击读走即清。 | $6C/$03 |
1508
+ | [`sb_mouse_set_double_click`](#sb_mouse_set_double_click) | 设置鼠标双击的间隔:按下后在这个间隔内再次按下算双击,间隔由定时器中断计时,默认 10。 | $6C/$01 |
1509
+
1510
+ <a id="sb_getkey"></a>
1511
+ ### sb_getkey
1512
+
1513
+ ```c
1514
+ unsigned char sb_getkey(void);
1515
+ ```
1516
+
1517
+ 等待按键并返回它的 ASCII 码。
1518
+
1519
+ 返回:按键的 ASCII 码;没有字符的键(如功能键)为 0。
1520
+
1521
+ <a id="sb_key_wait"></a>
1522
+ ### sb_key_wait
1523
+
1524
+ ```c
1525
+ unsigned int sb_key_wait(void);
1526
+ ```
1527
+
1528
+ 等到有按键,取出它的 ASCII 码与扫描码。
1529
+
1530
+ 系统调用:$6B/$04
1531
+
1532
+ 返回:低字节是 ASCII 码,高字节是扫描码。
1533
+
1534
+ <a id="sb_key_poll"></a>
1535
+ ### sb_key_poll
1536
+
1537
+ ```c
1538
+ unsigned int sb_key_poll(void);
1539
+ ```
1540
+
1541
+ 不等待,取出队列里的一个按键。
1542
+
1543
+ 系统调用:$6B/$03
1544
+
1545
+ 返回:低字节是 ASCII 码,高字节是扫描码;队列为空时为 0。
1546
+
1547
+ <a id="sb_key_count"></a>
1548
+ ### sb_key_count
1549
+
1550
+ ```c
1551
+ unsigned char sb_key_count(void);
1552
+ ```
1553
+
1554
+ 按键队列里的按键数。
1555
+
1556
+ 系统调用:$6B/$06
1557
+
1558
+ 返回:按键数,0 到 5。
1559
+
1560
+ <a id="sb_key_flush"></a>
1561
+ ### sb_key_flush
1562
+
1563
+ ```c
1564
+ void sb_key_flush(void);
1565
+ ```
1566
+
1567
+ 清空按键队列。
1568
+
1569
+ 系统调用:$6B/$05
1570
+
1571
+ <a id="sb_key_init"></a>
1572
+ ### sb_key_init
1573
+
1574
+ ```c
1575
+ void sb_key_init(void);
1576
+ ```
1577
+
1578
+ 复位键盘与鼠标,清空按键队列。约需几十帧。
1579
+
1580
+ 系统调用:$6B/$00
1581
+
1582
+ <a id="sb_break_enable"></a>
1583
+ ### sb_break_enable
1584
+
1585
+ ```c
1586
+ void sb_break_enable(void);
1587
+ ```
1588
+
1589
+ 打开按 ESC 中断程序:之后按 ESC,系统取出上下文栈顶的恢复点(sb_context_save 保存的)并跳转过去。
1590
+
1591
+ 系统调用:$6B/$01
1592
+
1593
+ <a id="sb_break_disable"></a>
1594
+ ### sb_break_disable
1595
+
1596
+ ```c
1597
+ void sb_break_disable(void);
1598
+ ```
1599
+
1600
+ 关闭按 ESC 中断程序。
1601
+
1602
+ 系统调用:$6B/$02
1603
+
1604
+ <a id="sb_key_modifiers"></a>
1605
+ ### sb_key_modifiers
1606
+
1607
+ ```c
1608
+ unsigned char sb_key_modifiers(void);
1609
+ ```
1610
+
1611
+ 修饰键状态:位 0 右 Shift,位 1 左 Shift,位 2 Ctrl,位 3 Alt,位 4 ScrollLock,位 5 NumLock,位 6 CapsLock,位 7 Insert。
1612
+
1613
+ 返回:修饰键状态。
1614
+
1615
+ <a id="sb_keyboard_reset"></a>
1616
+ ### sb_keyboard_reset
1617
+
1618
+ ```c
1619
+ unsigned char sb_keyboard_reset(void);
1620
+ ```
1621
+
1622
+ 复位并识别键盘。复位后键盘不再上报按键,需要再调用 sb_key_init 才恢复,一般用 sb_key_init 即可。
1623
+
1624
+ 系统调用:$17
1625
+
1626
+ 返回:1 通过,0 失败。
1627
+
1628
+ <a id="sb_pad_init"></a>
1629
+ ### sb_pad_init
1630
+
1631
+ ```c
1632
+ void sb_pad_init(void);
1633
+ ```
1634
+
1635
+ 初始化手柄状态,并打开 NMI 里读手柄的服务。
1636
+
1637
+ 系统调用:$12/$85、$6A/$00
1638
+
1639
+ <a id="sb_pad_poll"></a>
1640
+ ### sb_pad_poll
1641
+
1642
+ ```c
1643
+ unsigned char sb_pad_poll(void);
1644
+ ```
1645
+
1646
+ 不等待,取一个按下的手柄键。
1647
+
1648
+ 系统调用:$6A/$01
1649
+
1650
+ 返回:键码,$FF 表示没有键。
1651
+
1652
+ <a id="sb_pad_wait"></a>
1653
+ ### sb_pad_wait
1654
+
1655
+ ```c
1656
+ unsigned char sb_pad_wait(void);
1657
+ ```
1658
+
1659
+ 等到有手柄键按下。
1660
+
1661
+ 系统调用:$6A/$02
1662
+
1663
+ 返回:键码。
1664
+
1665
+ <a id="sb_pad_state"></a>
1666
+ ### sb_pad_state
1667
+
1668
+ ```c
1669
+ unsigned char sb_pad_state(unsigned char pad);
1670
+ ```
1671
+
1672
+ 取一个手柄的原始按键状态,由 sb_pad_poll、sb_pad_wait 更新:位 7 是 A,位 6 是 B,位 5 选择,位 4 开始,
1673
+ 位 3 上,位 2 下,位 1 左,位 0 右。
1674
+
1675
+ 参数:
1676
+
1677
+ - `pad`:手柄号,0 是 1 号手柄,其他是 2 号手柄。
1678
+
1679
+ 返回:原始状态。
1680
+
1681
+ <a id="sb_mouse_reset"></a>
1682
+ ### sb_mouse_reset
1683
+
1684
+ ```c
1685
+ unsigned char sb_mouse_reset(void);
1686
+ ```
1687
+
1688
+ 复位鼠标,返回鼠标是否接入。复位要尝试多次,约需几十帧;之后要用 sb_irq_enable(SB_IRQ_SOURCE_MOUSE) 允许鼠标中断,
1689
+ 再设置坐标范围与初始坐标。
1690
+
1691
+ 系统调用:$14
1692
+
1693
+ 返回:非 0 表示鼠标已接入,0 表示没有鼠标。
1694
+
1695
+ <a id="sb_mouse_set_limits"></a>
1696
+ ### sb_mouse_set_limits
1697
+
1698
+ ```c
1699
+ void sb_mouse_set_limits(unsigned char x_min, unsigned char y_min, unsigned char x_max, unsigned char y_max);
1700
+ ```
1701
+
1702
+ 设置鼠标光标坐标的范围,原有的双击间隔不变。
1703
+
1704
+ 系统调用:$6C/$00
1705
+
1706
+ 参数:
1707
+
1708
+ - `x_min`:X 下限。
1709
+ - `y_min`:Y 下限。
1710
+ - `x_max`:X 上限。
1711
+ - `y_max`:Y 上限。
1712
+
1713
+ <a id="sb_mouse_set_position"></a>
1714
+ ### sb_mouse_set_position
1715
+
1716
+ ```c
1717
+ void sb_mouse_set_position(unsigned char x, unsigned char y);
1718
+ ```
1719
+
1720
+ 设置鼠标光标的坐标。
1721
+
1722
+ 系统调用:$6C/$04
1723
+
1724
+ 参数:
1725
+
1726
+ - `x`:X 坐标。
1727
+ - `y`:Y 坐标。
1728
+
1729
+ <a id="sb_mouse_position"></a>
1730
+ ### sb_mouse_position
1731
+
1732
+ ```c
1733
+ void sb_mouse_position(unsigned char *x, unsigned char *y);
1734
+ ```
1735
+
1736
+ 取鼠标光标的坐标。每收到一个数据包,坐标就加上位移,并限制在设置的范围内。
1737
+
1738
+ 系统调用:$6C/$02
1739
+
1740
+ 参数:
1741
+
1742
+ - `x`:返回 X 坐标。
1743
+ - `y`:返回 Y 坐标。
1744
+
1745
+ <a id="sb_mouse_buttons"></a>
1746
+ ### sb_mouse_buttons
1747
+
1748
+ ```c
1749
+ void sb_mouse_buttons(sb_mouse_buttons_t *buttons);
1750
+ ```
1751
+
1752
+ 取两个鼠标键的状态。单击、双击读走即清。
1753
+
1754
+ 系统调用:$6C/$03
1755
+
1756
+ 参数:
1757
+
1758
+ - `buttons`:返回按键状态。
1759
+
1760
+ <a id="sb_mouse_set_double_click"></a>
1761
+ ### sb_mouse_set_double_click
1762
+
1763
+ ```c
1764
+ void sb_mouse_set_double_click(unsigned char interval);
1765
+ ```
1766
+
1767
+ 设置鼠标双击的间隔:按下后在这个间隔内再次按下算双击,间隔由定时器中断计时,默认 10。
1768
+ 间隔为 0 时不产生双击。
1769
+
1770
+ 系统调用:$6C/$01
1771
+
1772
+ 参数:
1773
+
1774
+ - `interval`:间隔,单位是定时器中断的次数。
1775
+
1776
+ <a id="math"></a>
1777
+ ## 数学(sb2000-math.h)
1778
+
1779
+ | 函数 | 说明 | 系统调用 |
1780
+ | --- | --- | --- |
1781
+ | [`sb_random_seed`](#sb_random_seed) | 设置伪随机数寄存器。寄存器的两个高字节全为 0 时,下一次步进前系统先把次高字节置成 $FF,所以种子 0 也能用。 | 直接写 $0696-$0699 |
1782
+ | [`sb_random_next`](#sb_random_next) | 把伪随机数寄存器步进一次,返回新的寄存器值。 | $4A/$01 |
1783
+ | [`sb_random_warm_up`](#sb_random_warm_up) | 把伪随机数寄存器连续步进 100 次,用来打散刚设置的种子。 | $4A/$00 |
1784
+ | [`sb_math_div16`](#sb_math_div16) | 16 位数除以 8 位数。 | $4B |
1785
+ | [`sb_math_time_text`](#sb_math_time_text) | 把时、分、秒转成 HH:MM:SS 文字。 | $4C |
1786
+ | [`sb_float_from_text`](#sb_float_from_text) | 十进制文字转浮点数。 | $4D/$00 |
1787
+ | [`sb_float_to_text`](#sb_float_to_text) | 浮点数转十进制文字。 | $4E/$00 |
1788
+ | [`sb_float_add`](#sb_float_add) | 浮点加法:a + b。 | $51 |
1789
+ | [`sb_float_sub`](#sb_float_sub) | 浮点减法:a - b。 | $52 |
1790
+ | [`sb_float_mul`](#sb_float_mul) | 浮点乘法:a * b。 | $4F |
1791
+ | [`sb_float_div`](#sb_float_div) | 浮点除法:a / b。除数的尾数为 0 时结果的第 1 个字节(阶码)为 $80。 | $50 |
1792
+ | [`sb_int40_from_text`](#sb_int40_from_text) | 十进制数字文字转 40 位整数。前导空格当 0,超过 40 位时高位丢弃。 | $4D/$01 |
1793
+ | [`sb_int40_to_text`](#sb_int40_to_text) | 40 位整数转十进制数字文字,数字左对齐、右边补字符 0。 | $4E/$01 |
1794
+ | [`sb_line_step`](#sb_line_step) | 直线步进(布雷森汉姆算法):从当前点向终点前进指定的步数,落点写回 x、y。步数不小于主轴长度时直接落在终点。 | $53 |
1795
+ | [`sb_int24_add`](#sb_int24_add) | 3 字节整数加法:a + b,带符号。 | $54/$00 |
1796
+ | [`sb_int24_sub`](#sb_int24_sub) | 3 字节整数减法:a - b,带符号。 | $54/$01 |
1797
+ | [`sb_int24_mul`](#sb_int24_mul) | 3 字节整数乘法:a * b,乘积最多 48 位。 | $54/$02 |
1798
+ | [`sb_int24_div`](#sb_int24_div) | 3 字节整数除法:a / b,得商与余数。 | $54/$03 |
1799
+
1800
+ <a id="sb_random_seed"></a>
1801
+ ### sb_random_seed
1802
+
1803
+ ```c
1804
+ void sb_random_seed(unsigned long seed);
1805
+ ```
1806
+
1807
+ 设置伪随机数寄存器。寄存器的两个高字节全为 0 时,下一次步进前系统先把次高字节置成 $FF,所以种子 0 也能用。
1808
+
1809
+ 系统调用:直接写 $0696-$0699
1810
+
1811
+ 参数:
1812
+
1813
+ - `seed`:32 位种子。
1814
+
1815
+ <a id="sb_random_next"></a>
1816
+ ### sb_random_next
1817
+
1818
+ ```c
1819
+ unsigned long sb_random_next(void);
1820
+ ```
1821
+
1822
+ 把伪随机数寄存器步进一次,返回新的寄存器值。
1823
+
1824
+ 系统调用:$4A/$01
1825
+
1826
+ 返回:步进后的 32 位寄存器值。
1827
+
1828
+ <a id="sb_random_warm_up"></a>
1829
+ ### sb_random_warm_up
1830
+
1831
+ ```c
1832
+ void sb_random_warm_up(void);
1833
+ ```
1834
+
1835
+ 把伪随机数寄存器连续步进 100 次,用来打散刚设置的种子。
1836
+
1837
+ 系统调用:$4A/$00
1838
+
1839
+ <a id="sb_math_div16"></a>
1840
+ ### sb_math_div16
1841
+
1842
+ ```c
1843
+ unsigned char sb_math_div16(unsigned int dividend, unsigned char divisor, unsigned int *quotient, unsigned char *remainder);
1844
+ ```
1845
+
1846
+ 16 位数除以 8 位数。
1847
+
1848
+ 系统调用:$4B
1849
+
1850
+ 参数:
1851
+
1852
+ - `dividend`:被除数。
1853
+ - `divisor`:除数。
1854
+ - `quotient`:返回商。
1855
+ - `remainder`:返回余数。
1856
+
1857
+ 返回:0 成功;$FF 除数为 0,商与余数没有意义。
1858
+
1859
+ <a id="sb_math_time_text"></a>
1860
+ ### sb_math_time_text
1861
+
1862
+ ```c
1863
+ void sb_math_time_text(unsigned char hour, unsigned char minute, unsigned char second, char *text);
1864
+ ```
1865
+
1866
+ 把时、分、秒转成 HH:MM:SS 文字。
1867
+
1868
+ 系统调用:$4C
1869
+
1870
+ 参数:
1871
+
1872
+ - `hour`:时。
1873
+ - `minute`:分。
1874
+ - `second`:秒。
1875
+ - `text`:返回 8 个字符加结尾的 0,要有 9 字节空间。
1876
+
1877
+ <a id="sb_float_from_text"></a>
1878
+ ### sb_float_from_text
1879
+
1880
+ ```c
1881
+ void sb_float_from_text(const char *text, sb_float_t *result);
1882
+ ```
1883
+
1884
+ 十进制文字转浮点数。
1885
+
1886
+ 系统调用:$4D/$00
1887
+
1888
+ 参数:
1889
+
1890
+ - `text`:13 个字符:第 1 个是符号(空格或 -),后面 12 个是带小数点的数字。
1891
+ - `result`:返回浮点数。
1892
+
1893
+ <a id="sb_float_to_text"></a>
1894
+ ### sb_float_to_text
1895
+
1896
+ ```c
1897
+ void sb_float_to_text(const sb_float_t *value, char *text);
1898
+ ```
1899
+
1900
+ 浮点数转十进制文字。
1901
+
1902
+ 系统调用:$4E/$00
1903
+
1904
+ 参数:
1905
+
1906
+ - `value`:浮点数。
1907
+ - `text`:返回 13 个字符(符号加 12 位带小数点的数字)与结尾的 0,要有 14 字节空间。
1908
+
1909
+ <a id="sb_float_add"></a>
1910
+ ### sb_float_add
1911
+
1912
+ ```c
1913
+ void sb_float_add(const sb_float_t *a, const sb_float_t *b, sb_float_t *result);
1914
+ ```
1915
+
1916
+ 浮点加法:a + b。
1917
+
1918
+ 系统调用:$51
1919
+
1920
+ 参数:
1921
+
1922
+ - `a`:第一个操作数。
1923
+ - `b`:第二个操作数。
1924
+ - `result`:返回结果,可以与 a 或 b 是同一个变量。
1925
+
1926
+ <a id="sb_float_sub"></a>
1927
+ ### sb_float_sub
1928
+
1929
+ ```c
1930
+ void sb_float_sub(const sb_float_t *a, const sb_float_t *b, sb_float_t *result);
1931
+ ```
1932
+
1933
+ 浮点减法:a - b。
1934
+
1935
+ 系统调用:$52
1936
+
1937
+ 参数:
1938
+
1939
+ - `a`:第一个操作数。
1940
+ - `b`:第二个操作数。
1941
+ - `result`:返回结果,可以与 a 或 b 是同一个变量。
1942
+
1943
+ <a id="sb_float_mul"></a>
1944
+ ### sb_float_mul
1945
+
1946
+ ```c
1947
+ void sb_float_mul(const sb_float_t *a, const sb_float_t *b, sb_float_t *result);
1948
+ ```
1949
+
1950
+ 浮点乘法:a * b。
1951
+
1952
+ 系统调用:$4F
1953
+
1954
+ 参数:
1955
+
1956
+ - `a`:第一个操作数。
1957
+ - `b`:第二个操作数。
1958
+ - `result`:返回结果,可以与 a 或 b 是同一个变量。
1959
+
1960
+ <a id="sb_float_div"></a>
1961
+ ### sb_float_div
1962
+
1963
+ ```c
1964
+ void sb_float_div(const sb_float_t *a, const sb_float_t *b, sb_float_t *result);
1965
+ ```
1966
+
1967
+ 浮点除法:a / b。除数的尾数为 0 时结果的第 1 个字节(阶码)为 $80。
1968
+
1969
+ 系统调用:$50
1970
+
1971
+ 参数:
1972
+
1973
+ - `a`:第一个操作数。
1974
+ - `b`:第二个操作数。
1975
+ - `result`:返回结果,可以与 a 或 b 是同一个变量。
1976
+
1977
+ <a id="sb_int40_from_text"></a>
1978
+ ### sb_int40_from_text
1979
+
1980
+ ```c
1981
+ void sb_int40_from_text(const char *digits, unsigned char count, unsigned char *value);
1982
+ ```
1983
+
1984
+ 十进制数字文字转 40 位整数。前导空格当 0,超过 40 位时高位丢弃。
1985
+
1986
+ 系统调用:$4D/$01
1987
+
1988
+ 参数:
1989
+
1990
+ - `digits`:数字字符,不带符号与小数点。
1991
+ - `count`:数字个数,0 到 12。
1992
+ - `value`:返回 5 个字节的整数,高字节在前。
1993
+
1994
+ <a id="sb_int40_to_text"></a>
1995
+ ### sb_int40_to_text
1996
+
1997
+ ```c
1998
+ unsigned char sb_int40_to_text(const unsigned char *value, char *digits, unsigned char *length);
1999
+ ```
2000
+
2001
+ 40 位整数转十进制数字文字,数字左对齐、右边补字符 0。
2002
+
2003
+ 系统调用:$4E/$01
2004
+
2005
+ 参数:
2006
+
2007
+ - `value`:5 个字节的整数,高字节在前。
2008
+ - `digits`:返回 13 个数字字符与结尾的 0,要有 14 字节空间。
2009
+ - `length`:返回去掉前导 0 后的有效位数,至少为 1。
2010
+
2011
+ 返回:0 成功;$FF 数值不小于 10^12,放不下。
2012
+
2013
+ <a id="sb_line_step"></a>
2014
+ ### sb_line_step
2015
+
2016
+ ```c
2017
+ void sb_line_step(sb_line_t *line, unsigned char steps);
2018
+ ```
2019
+
2020
+ 直线步进(布雷森汉姆算法):从当前点向终点前进指定的步数,落点写回 x、y。步数不小于主轴长度时直接落在终点。
2021
+
2022
+ 系统调用:$53
2023
+
2024
+ 参数:
2025
+
2026
+ - `line`:参数块,调用前填好 x、y、end_x、end_y;系统服务换页后程序窗口不可见,所以函数把它复制到 ERAM 里再调用,返回后复制回来。
2027
+ - `steps`:前进的步数,0 表示 256 步。
2028
+
2029
+ <a id="sb_int24_add"></a>
2030
+ ### sb_int24_add
2031
+
2032
+ ```c
2033
+ unsigned char sb_int24_add(const sb_int24_t *a, const sb_int24_t *b, sb_int24_t *result);
2034
+ ```
2035
+
2036
+ 3 字节整数加法:a + b,带符号。
2037
+
2038
+ 系统调用:$54/$00
2039
+
2040
+ 参数:
2041
+
2042
+ - `a`:第一个操作数。
2043
+ - `b`:第二个操作数。
2044
+ - `result`:返回结果。
2045
+
2046
+ 返回:0 没有溢出;1 结果超过 24 位,result 里是低 24 位。
2047
+
2048
+ <a id="sb_int24_sub"></a>
2049
+ ### sb_int24_sub
2050
+
2051
+ ```c
2052
+ unsigned char sb_int24_sub(const sb_int24_t *a, const sb_int24_t *b, sb_int24_t *result);
2053
+ ```
2054
+
2055
+ 3 字节整数减法:a - b,带符号。
2056
+
2057
+ 系统调用:$54/$01
2058
+
2059
+ 参数:
2060
+
2061
+ - `a`:第一个操作数。
2062
+ - `b`:第二个操作数。
2063
+ - `result`:返回结果。
2064
+
2065
+ 返回:0 没有溢出;1 结果超过 24 位,result 里是低 24 位。
2066
+
2067
+ <a id="sb_int24_mul"></a>
2068
+ ### sb_int24_mul
2069
+
2070
+ ```c
2071
+ void sb_int24_mul(const sb_int24_t *a, const sb_int24_t *b, unsigned char *sign, unsigned char *product);
2072
+ ```
2073
+
2074
+ 3 字节整数乘法:a * b,乘积最多 48 位。
2075
+
2076
+ 系统调用:$54/$02
2077
+
2078
+ 参数:
2079
+
2080
+ - `a`:第一个操作数。
2081
+ - `b`:第二个操作数。
2082
+ - `sign`:返回乘积的符号,$00 正、$FF 负。
2083
+ - `product`:返回 6 个字节的乘积,高字节在前。
2084
+
2085
+ <a id="sb_int24_div"></a>
2086
+ ### sb_int24_div
2087
+
2088
+ ```c
2089
+ unsigned char sb_int24_div(const sb_int24_t *a, const sb_int24_t *b, sb_int24_t *quotient, sb_int24_t *remainder);
2090
+ ```
2091
+
2092
+ 3 字节整数除法:a / b,得商与余数。
2093
+
2094
+ 系统调用:$54/$03
2095
+
2096
+ 参数:
2097
+
2098
+ - `a`:被除数。
2099
+ - `b`:除数。
2100
+ - `quotient`:返回商,符号是商的符号。
2101
+ - `remainder`:返回余数的数值,符号字节与商相同。
2102
+
2103
+ 返回:0 成功;1 除数为 0,商与余数没有意义。
2104
+
2105
+ <a id="memory"></a>
2106
+ ## 内存页与远指针(sb2000-memory.h)
2107
+
2108
+ | 函数 | 说明 | 系统调用 |
2109
+ | --- | --- | --- |
2110
+ | [`sb_page_alloc`](#sb_page_alloc) | 分配连续的扩展 RAM 页。页数为 0 时不分配,只返回第一个空闲页的页号。 | $7E/$00 |
2111
+ | [`sb_page_free`](#sb_page_free) | 释放连续的扩展 RAM 页。 | $7E/$01 |
2112
+ | [`sb_page_largest_free`](#sb_page_largest_free) | 求最长的连续空闲页数。 | $7E/$02 |
2113
+ | [`sb_far_read_byte`](#sb_far_read_byte) | 读扩展 RAM 页里的一个字节。 | |
2114
+ | [`sb_far_write_byte`](#sb_far_write_byte) | 写扩展 RAM 页里的一个字节。 | |
2115
+ | [`sb_far_read`](#sb_far_read) | 把扩展 RAM 里的一段数据读到内存,可以跨页。数据经 $0700 缓冲中转,调用期间会改写 $0700-$07FF。 | |
2116
+ | [`sb_far_write`](#sb_far_write) | 把内存里的一段数据写到扩展 RAM,可以跨页。数据经 $0700 缓冲中转,调用期间会改写 $0700-$07FF。 | |
2117
+ | [`sb_address_to_far`](#sb_address_to_far) | 把窗口地址换算成远指针:页号 = 地址高 4 位 - 8 + 页组首页号(按 8 位回绕),页内偏移是地址的低 12 位。 | $2C |
2118
+ | [`sb_window_map`](#sb_window_map) | 把一个扩展 RAM 页映射到一个窗口。调用返回后映射保持,直到再次映射。 | $29 |
2119
+ | [`sb_window_map_group`](#sb_window_map_group) | 把页组的 4 个连续页映射到 4 个窗口($8000-$BFFF),调用返回后映射保持。 | $27 |
2120
+
2121
+ <a id="sb_page_alloc"></a>
2122
+ ### sb_page_alloc
2123
+
2124
+ ```c
2125
+ unsigned char sb_page_alloc(unsigned char count, unsigned char *first_page);
2126
+ ```
2127
+
2128
+ 分配连续的扩展 RAM 页。页数为 0 时不分配,只返回第一个空闲页的页号。
2129
+
2130
+ 系统调用:$7E/$00
2131
+
2132
+ 参数:
2133
+
2134
+ - `count`:页数,每页 4K。
2135
+ - `first_page`:返回分配到的第一个页号;失败时为 0。
2136
+
2137
+ 返回:0 成功;SB_ERR_NO_MEMORY 没有这么多连续的空闲页。
2138
+
2139
+ <a id="sb_page_free"></a>
2140
+ ### sb_page_free
2141
+
2142
+ ```c
2143
+ unsigned char sb_page_free(unsigned char first_page, unsigned char count);
2144
+ ```
2145
+
2146
+ 释放连续的扩展 RAM 页。
2147
+
2148
+ 系统调用:$7E/$01
2149
+
2150
+ 参数:
2151
+
2152
+ - `first_page`:第一个页号,必须不小于 $80 且小于 $F0。
2153
+ - `count`:页数;这个服务不检查页号加页数是否越过 $F0。
2154
+
2155
+ 返回:0 成功;SB_ERR_BAD_ADDRESS 起始页号不合法,没有释放任何页。
2156
+
2157
+ <a id="sb_page_largest_free"></a>
2158
+ ### sb_page_largest_free
2159
+
2160
+ ```c
2161
+ unsigned char sb_page_largest_free(void);
2162
+ ```
2163
+
2164
+ 求最长的连续空闲页数。
2165
+
2166
+ 系统调用:$7E/$02
2167
+
2168
+ 返回:页数;计数是 8 位,256 页全部空闲时回绕成 0。
2169
+
2170
+ <a id="sb_far_read_byte"></a>
2171
+ ### sb_far_read_byte
2172
+
2173
+ ```c
2174
+ unsigned char sb_far_read_byte(unsigned char page, unsigned int offset);
2175
+ ```
2176
+
2177
+ 读扩展 RAM 页里的一个字节。
2178
+
2179
+ 参数:
2180
+
2181
+ - `page`:页号。
2182
+ - `offset`:页内偏移,超过 $0FFF 时折算到后面的页。
2183
+
2184
+ 返回:读到的字节。
2185
+
2186
+ <a id="sb_far_write_byte"></a>
2187
+ ### sb_far_write_byte
2188
+
2189
+ ```c
2190
+ void sb_far_write_byte(unsigned char page, unsigned int offset, unsigned char value);
2191
+ ```
2192
+
2193
+ 写扩展 RAM 页里的一个字节。
2194
+
2195
+ 参数:
2196
+
2197
+ - `page`:页号。
2198
+ - `offset`:页内偏移,超过 $0FFF 时折算到后面的页。
2199
+ - `value`:要写的字节。
2200
+
2201
+ <a id="sb_far_read"></a>
2202
+ ### sb_far_read
2203
+
2204
+ ```c
2205
+ void sb_far_read(unsigned char page, unsigned int offset, void *dest, unsigned int length);
2206
+ ```
2207
+
2208
+ 把扩展 RAM 里的一段数据读到内存,可以跨页。数据经 $0700 缓冲中转,调用期间会改写 $0700-$07FF。
2209
+
2210
+ 参数:
2211
+
2212
+ - `page`:起始页号。
2213
+ - `offset`:页内偏移,超过 $0FFF 时折算到后面的页。
2214
+ - `dest`:目的地,必须在程序窗口的前 3 个窗口($8000-$AFFF)、$6000-$7FFF 或内核 RAM 里,不能在窗口 3。
2215
+ - `length`:字节数。
2216
+
2217
+ <a id="sb_far_write"></a>
2218
+ ### sb_far_write
2219
+
2220
+ ```c
2221
+ void sb_far_write(unsigned char page, unsigned int offset, const void *src, unsigned int length);
2222
+ ```
2223
+
2224
+ 把内存里的一段数据写到扩展 RAM,可以跨页。数据经 $0700 缓冲中转,调用期间会改写 $0700-$07FF。
2225
+
2226
+ 参数:
2227
+
2228
+ - `page`:起始页号。
2229
+ - `offset`:页内偏移,超过 $0FFF 时折算到后面的页。
2230
+ - `src`:数据来源,位置的要求同 sb_far_read 的 dest。
2231
+ - `length`:字节数。
2232
+
2233
+ <a id="sb_address_to_far"></a>
2234
+ ### sb_address_to_far
2235
+
2236
+ ```c
2237
+ void sb_address_to_far(unsigned char group, unsigned int address, unsigned char *page, unsigned int *offset);
2238
+ ```
2239
+
2240
+ 把窗口地址换算成远指针:页号 = 地址高 4 位 - 8 + 页组首页号(按 8 位回绕),页内偏移是地址的低 12 位。
2241
+
2242
+ 系统调用:$2C
2243
+
2244
+ 参数:
2245
+
2246
+ - `group`:页组的首页号。
2247
+ - `address`:窗口地址,$8000-$FFFF。
2248
+ - `page`:返回页号。
2249
+ - `offset`:返回页内偏移。
2250
+
2251
+ <a id="sb_window_map"></a>
2252
+ ### sb_window_map
2253
+
2254
+ ```c
2255
+ void sb_window_map(unsigned char window, unsigned char page);
2256
+ ```
2257
+
2258
+ 把一个扩展 RAM 页映射到一个窗口。调用返回后映射保持,直到再次映射。
2259
+ 窗口 0-2 可以用来临时访问别的页;程序自己占用的窗口被换走后,里面的代码与数据在恢复前看不到。
2260
+ 窗口 3 里有程序的软件栈,不要映射。
2261
+
2262
+ 系统调用:$29
2263
+
2264
+ 参数:
2265
+
2266
+ - `window`:窗口号 0-3,0 是 $8000,1 是 $9000,2 是 $A000,3 是 $B000。
2267
+ - `page`:页号。
2268
+
2269
+ <a id="sb_window_map_group"></a>
2270
+ ### sb_window_map_group
2271
+
2272
+ ```c
2273
+ void sb_window_map_group(unsigned char group);
2274
+ ```
2275
+
2276
+ 把页组的 4 个连续页映射到 4 个窗口($8000-$BFFF),调用返回后映射保持。
2277
+ 调用者本身的代码所在的窗口也会换掉,所以新页组里同一地址要有同样的代码。
2278
+
2279
+ 系统调用:$27
2280
+
2281
+ 参数:
2282
+
2283
+ - `group`:页组的首页号。
2284
+
2285
+ <a id="printer"></a>
2286
+ ## 打印机(sb2000-printer.h)
2287
+
2288
+ | 函数 | 说明 | 系统调用 |
2289
+ | --- | --- | --- |
2290
+ | [`sb_printer_text`](#sb_printer_text) | 打印一段文字,到 0 结束。每行先发 ESC @ 与图形命令,再逐字符取字模发送,行满换行,行末进纸并让打印头回到左端。 | $76/$00 |
2291
+ | [`sb_printer_reset`](#sb_printer_reset) | 发送复位命令 ESC @。 | $76/$01 |
2292
+ | [`sb_printer_home`](#sb_printer_home) | 发送 ESC <,让打印头回到左端。 | $76/$02 |
2293
+ | [`sb_printer_carriage_return`](#sb_printer_carriage_return) | 复位打印机并发送回车。 | $76/$03 |
2294
+ | [`sb_printer_feed`](#sb_printer_feed) | 进纸,发送 ESC J n。 | $76/$04 |
2295
+ | [`sb_printer_position`](#sb_printer_position) | 横向定位:绝对定位发送 ESC $ 加两个字节,相对定位发送 ESC \ 加两个字节。 | $76/$05、$76/$06 |
2296
+ | [`sb_printer_send_byte`](#sb_printer_send_byte) | 把一个字节原样发给打印机,不做变换。 | $76/$07 |
2297
+ | [`sb_printer_graphics_mode`](#sb_printer_graphics_mode) | 发送 ESC * 39 1144,进入 24 针三倍密度位图模式,每行 1144 列。 | $76/$08 |
2298
+ | [`sb_printer_init_port`](#sb_printer_init_port) | 初始化并口并等待。只初始化一次,之后的调用什么都不做;其他打印机函数每次都会先调用它,所以一般不必单独调用。 | $76/$0E |
2299
+ | [`sb_printer_page_length`](#sb_printer_page_length) | 按纸张类型设置页长计数(单位 1/216 英寸,进纸时从中扣除):0 是 1900,1 是 2523(11.68 英寸,A4),2 是 2106,3 是 1488,4 是 2077,5 是 1821; | $76/$0F |
2300
+ | [`sb_printer_page_left`](#sb_printer_page_left) | 取本页剩余走纸量(单位 1/216 英寸)。剩余不足 $58 时打印文字会自动收尾进纸并按纸张类型重新装入页长。 | |
2301
+
2302
+ <a id="sb_printer_text"></a>
2303
+ ### sb_printer_text
2304
+
2305
+ ```c
2306
+ void sb_printer_text(const char *text, const sb_printer_style_t *style);
2307
+ ```
2308
+
2309
+ 打印一段文字,到 0 结束。每行先发 ESC @ 与图形命令,再逐字符取字模发送,行满换行,行末进纸并让打印头回到左端。
2310
+ 文字里的控制码:$0D $0A 换行;$92 n 设置字宽与点数模式;$95 n 设置变换模式;$99 n 设置附加空白列;$9B n 设置换行后的进纸量,具体见系统调用手册(docs/sb2000/02-系统调用手册.md)5.11 节。
2311
+
2312
+ 系统调用:$76/$00
2313
+
2314
+ 参数:
2315
+
2316
+ - `text`:文字,零结尾,在程序窗口 $8000-$BFFF 里。
2317
+ - `style`:打印格式;传 0 时用字宽 0、点数模式 0、无附加空白列、进纸量 $18。
2318
+
2319
+ <a id="sb_printer_reset"></a>
2320
+ ### sb_printer_reset
2321
+
2322
+ ```c
2323
+ void sb_printer_reset(void);
2324
+ ```
2325
+
2326
+ 发送复位命令 ESC @。
2327
+
2328
+ 系统调用:$76/$01
2329
+
2330
+ <a id="sb_printer_home"></a>
2331
+ ### sb_printer_home
2332
+
2333
+ ```c
2334
+ void sb_printer_home(void);
2335
+ ```
2336
+
2337
+ 发送 ESC <,让打印头回到左端。
2338
+
2339
+ 系统调用:$76/$02
2340
+
2341
+ <a id="sb_printer_carriage_return"></a>
2342
+ ### sb_printer_carriage_return
2343
+
2344
+ ```c
2345
+ void sb_printer_carriage_return(void);
2346
+ ```
2347
+
2348
+ 复位打印机并发送回车。
2349
+
2350
+ 系统调用:$76/$03
2351
+
2352
+ <a id="sb_printer_feed"></a>
2353
+ ### sb_printer_feed
2354
+
2355
+ ```c
2356
+ void sb_printer_feed(unsigned char units);
2357
+ ```
2358
+
2359
+ 进纸,发送 ESC J n。
2360
+
2361
+ 系统调用:$76/$04
2362
+
2363
+ 参数:
2364
+
2365
+ - `units`:进纸量,单位 1/216 英寸。
2366
+
2367
+ <a id="sb_printer_position"></a>
2368
+ ### sb_printer_position
2369
+
2370
+ ```c
2371
+ void sb_printer_position(unsigned char relative, unsigned int position);
2372
+ ```
2373
+
2374
+ 横向定位:绝对定位发送 ESC $ 加两个字节,相对定位发送 ESC \ 加两个字节。
2375
+
2376
+ 系统调用:$76/$05、$76/$06
2377
+
2378
+ 参数:
2379
+
2380
+ - `relative`:0 绝对定位,非 0 相对定位。
2381
+ - `position`:位置,单位 1/60 英寸(绝对)或 1/120 英寸(相对),16 位。
2382
+
2383
+ <a id="sb_printer_send_byte"></a>
2384
+ ### sb_printer_send_byte
2385
+
2386
+ ```c
2387
+ void sb_printer_send_byte(unsigned char value);
2388
+ ```
2389
+
2390
+ 把一个字节原样发给打印机,不做变换。
2391
+
2392
+ 系统调用:$76/$07
2393
+
2394
+ 参数:
2395
+
2396
+ - `value`:要发送的字节。
2397
+
2398
+ <a id="sb_printer_graphics_mode"></a>
2399
+ ### sb_printer_graphics_mode
2400
+
2401
+ ```c
2402
+ void sb_printer_graphics_mode(void);
2403
+ ```
2404
+
2405
+ 发送 ESC * 39 1144,进入 24 针三倍密度位图模式,每行 1144 列。
2406
+
2407
+ 系统调用:$76/$08
2408
+
2409
+ <a id="sb_printer_init_port"></a>
2410
+ ### sb_printer_init_port
2411
+
2412
+ ```c
2413
+ void sb_printer_init_port(void);
2414
+ ```
2415
+
2416
+ 初始化并口并等待。只初始化一次,之后的调用什么都不做;其他打印机函数每次都会先调用它,所以一般不必单独调用。
2417
+
2418
+ 系统调用:$76/$0E
2419
+
2420
+ <a id="sb_printer_page_length"></a>
2421
+ ### sb_printer_page_length
2422
+
2423
+ ```c
2424
+ void sb_printer_page_length(unsigned char paper);
2425
+ ```
2426
+
2427
+ 按纸张类型设置页长计数(单位 1/216 英寸,进纸时从中扣除):0 是 1900,1 是 2523(11.68 英寸,A4),2 是 2106,3 是 1488,4 是 2077,5 是 1821;
2428
+ 6 以上只把参数存进计数的高字节。
2429
+
2430
+ 系统调用:$76/$0F
2431
+
2432
+ 参数:
2433
+
2434
+ - `paper`:纸张类型,0 到 5。
2435
+
2436
+ <a id="sb_printer_page_left"></a>
2437
+ ### sb_printer_page_left
2438
+
2439
+ ```c
2440
+ unsigned int sb_printer_page_left(void);
2441
+ ```
2442
+
2443
+ 取本页剩余走纸量(单位 1/216 英寸)。剩余不足 $58 时打印文字会自动收尾进纸并按纸张类型重新装入页长。
2444
+
2445
+ 返回:剩余走纸量。
2446
+
2447
+ <a id="sound"></a>
2448
+ ## 声音与语音(sb2000-sound.h)
2449
+
2450
+ | 函数 | 说明 | 系统调用 |
2451
+ | --- | --- | --- |
2452
+ | [`sb_sound_play_from`](#sb_sound_play_from) | 载入并播放一首曲子(音乐格式或音效格式)。先关闭声音更新,复位发声状态,起播后再打开声音更新。 | $65/$00 |
2453
+ | [`sb_sound_stop`](#sb_sound_stop) | 停止播放:复位发声状态,关闭声音更新,播放状态变成 $FF。 | $65/$02 |
2454
+ | [`sb_sound_status`](#sb_sound_status) | 取播放状态。 | $65/$03 |
2455
+ | [`sb_sound_transpose`](#sb_sound_transpose) | 调整 4 个音乐声道的移调值:每个声道的移调值都加上 delta(8 位回绕)。 | $65/$04 |
2456
+ | [`sb_sound_tempo`](#sb_sound_tempo) | 调整拍速:拍速值加上 delta(8 位回绕),同步写进备份单元。 | $65/$05 |
2457
+ | [`sb_sound_effect_from`](#sb_sound_effect_from) | 复位后播放一首音效格式的曲子(音效声道 4-7)。音乐格式的曲子用它起不了播,要用 sb_sound_play_from。 | $65/$0B |
2458
+ | [`sb_sound_play_wav_from`](#sb_sound_play_wav_from) | 播放内存里的 WAV(8 位采样)。屏蔽中断播放,播完才返回。 | $65/$0C |
2459
+ | [`sb_sound_play_wav`](#sb_sound_play_wav) | 播放程序自己窗口里的 WAV,规则同 sb_sound_play_wav_from。 | $65/$0C |
2460
+ | [`sb_sound_repeat_wav_from`](#sb_sound_repeat_wav_from) | 重复播放内存里的 WAV。次数不为 0 时先等 5 帧再开始;播完(含次数为 0)后声音寄存器恢复。 | $65/$0D |
2461
+ | [`sb_speech_off`](#sb_speech_off) | 关闭语音:清语音芯片的使能位与语音控制标志的“已使用”位。 | $74/$00 |
2462
+ | [`sb_speech_send_from`](#sb_speech_send_from) | 同步发送一段语音数据(LPC 码流):先复位语音芯片,写命令字节 $0A,再把数据逐字节写给语音端口,读到结束帧后返回。 | $75/$00 |
2463
+ | [`sb_speech_send`](#sb_speech_send) | 同步发送程序自己窗口里的语音数据,规则同 sb_speech_send_from。 | $75/$00 |
2464
+ | [`sb_speech_send_entry_from`](#sb_speech_send_entry_from) | 按序号发送词条表里的一个词条。词条表头 2 字节是词条个数(低字节在前),之后每项 3 字节:页号增量、相对表起点的偏移低字节、偏移高字节。 | $75/$01 |
2465
+
2466
+ <a id="sb_sound_play_from"></a>
2467
+ ### sb_sound_play_from
2468
+
2469
+ ```c
2470
+ void sb_sound_play_from(unsigned char group, unsigned int address);
2471
+ ```
2472
+
2473
+ 载入并播放一首曲子(音乐格式或音效格式)。先关闭声音更新,复位发声状态,起播后再打开声音更新。
2474
+
2475
+ 系统调用:$65/$00
2476
+
2477
+ 参数:
2478
+
2479
+ - `group`:曲子所在页组的首页号。
2480
+ - `address`:曲子在页组窗口里的地址。
2481
+
2482
+ <a id="sb_sound_stop"></a>
2483
+ ### sb_sound_stop
2484
+
2485
+ ```c
2486
+ void sb_sound_stop(void);
2487
+ ```
2488
+
2489
+ 停止播放:复位发声状态,关闭声音更新,播放状态变成 $FF。
2490
+
2491
+ 系统调用:$65/$02
2492
+
2493
+ <a id="sb_sound_status"></a>
2494
+ ### sb_sound_status
2495
+
2496
+ ```c
2497
+ unsigned char sb_sound_status(void);
2498
+ ```
2499
+
2500
+ 取播放状态。
2501
+
2502
+ 系统调用:$65/$03
2503
+
2504
+ 返回:播放状态,停止播放后是 $FF。
2505
+
2506
+ <a id="sb_sound_transpose"></a>
2507
+ ### sb_sound_transpose
2508
+
2509
+ ```c
2510
+ void sb_sound_transpose(unsigned char delta);
2511
+ ```
2512
+
2513
+ 调整 4 个音乐声道的移调值:每个声道的移调值都加上 delta(8 位回绕)。
2514
+
2515
+ 系统调用:$65/$04
2516
+
2517
+ 参数:
2518
+
2519
+ - `delta`:要加的值,负数用补码。
2520
+
2521
+ <a id="sb_sound_tempo"></a>
2522
+ ### sb_sound_tempo
2523
+
2524
+ ```c
2525
+ void sb_sound_tempo(unsigned char delta);
2526
+ ```
2527
+
2528
+ 调整拍速:拍速值加上 delta(8 位回绕),同步写进备份单元。
2529
+
2530
+ 系统调用:$65/$05
2531
+
2532
+ 参数:
2533
+
2534
+ - `delta`:要加的值,负数用补码。
2535
+
2536
+ <a id="sb_sound_effect_from"></a>
2537
+ ### sb_sound_effect_from
2538
+
2539
+ ```c
2540
+ void sb_sound_effect_from(unsigned char group, unsigned int address);
2541
+ ```
2542
+
2543
+ 复位后播放一首音效格式的曲子(音效声道 4-7)。音乐格式的曲子用它起不了播,要用 sb_sound_play_from。
2544
+
2545
+ 系统调用:$65/$0B
2546
+
2547
+ 参数:
2548
+
2549
+ - `group`:曲子所在页组的首页号。
2550
+ - `address`:曲子在页组窗口里的地址。
2551
+
2552
+ <a id="sb_sound_play_wav_from"></a>
2553
+ ### sb_sound_play_wav_from
2554
+
2555
+ ```c
2556
+ void sb_sound_play_wav_from(unsigned char group, unsigned int address);
2557
+ ```
2558
+
2559
+ 播放内存里的 WAV(8 位采样)。屏蔽中断播放,播完才返回。
2560
+ 采样率取文件头偏移 $18 的低字节:$44 是 44100 Hz,$22 是 22050 Hz,其他按 11025 Hz;采样长度取偏移 $28 的 4 个字节,跳过 44 字节文件头;
2561
+ 实际会多播一个采样(总数是长度加 1)。
2562
+
2563
+ 系统调用:$65/$0C
2564
+
2565
+ 参数:
2566
+
2567
+ - `group`:WAV 所在页组的首页号。
2568
+ - `address`:WAV 文件头在页组窗口里的地址。
2569
+
2570
+ <a id="sb_sound_play_wav"></a>
2571
+ ### sb_sound_play_wav
2572
+
2573
+ ```c
2574
+ void sb_sound_play_wav(const void *wav);
2575
+ ```
2576
+
2577
+ 播放程序自己窗口里的 WAV,规则同 sb_sound_play_wav_from。
2578
+
2579
+ 系统调用:$65/$0C
2580
+
2581
+ 参数:
2582
+
2583
+ - `wav`:WAV 文件头的地址,在程序窗口 $8000-$BFFF 里。
2584
+
2585
+ <a id="sb_sound_repeat_wav_from"></a>
2586
+ ### sb_sound_repeat_wav_from
2587
+
2588
+ ```c
2589
+ void sb_sound_repeat_wav_from(unsigned char group, unsigned int address, unsigned char times);
2590
+ ```
2591
+
2592
+ 重复播放内存里的 WAV。次数不为 0 时先等 5 帧再开始;播完(含次数为 0)后声音寄存器恢复。
2593
+
2594
+ 系统调用:$65/$0D
2595
+
2596
+ 参数:
2597
+
2598
+ - `group`:WAV 所在页组的首页号。
2599
+ - `address`:WAV 文件头在页组窗口里的地址。
2600
+ - `times`:重复的遍数。
2601
+
2602
+ <a id="sb_speech_off"></a>
2603
+ ### sb_speech_off
2604
+
2605
+ ```c
2606
+ void sb_speech_off(void);
2607
+ ```
2608
+
2609
+ 关闭语音:清语音芯片的使能位与语音控制标志的“已使用”位。
2610
+
2611
+ 系统调用:$74/$00
2612
+
2613
+ <a id="sb_speech_send_from"></a>
2614
+ ### sb_speech_send_from
2615
+
2616
+ ```c
2617
+ void sb_speech_send_from(unsigned char group, unsigned int address);
2618
+ ```
2619
+
2620
+ 同步发送一段语音数据(LPC 码流):先复位语音芯片,写命令字节 $0A,再把数据逐字节写给语音端口,读到结束帧后返回。
2621
+ 数据要以结束帧(SB_SPEECH_END_FRAME,低 4 位全 1)收尾,否则不会返回。
2622
+
2623
+ 系统调用:$75/$00
2624
+
2625
+ 参数:
2626
+
2627
+ - `group`:数据所在页组的首页号。
2628
+ - `address`:数据在页组窗口里的地址。
2629
+
2630
+ <a id="sb_speech_send"></a>
2631
+ ### sb_speech_send
2632
+
2633
+ ```c
2634
+ void sb_speech_send(const void *data);
2635
+ ```
2636
+
2637
+ 同步发送程序自己窗口里的语音数据,规则同 sb_speech_send_from。
2638
+
2639
+ 系统调用:$75/$00
2640
+
2641
+ 参数:
2642
+
2643
+ - `data`:语音数据的地址,在程序窗口 $8000-$BFFF 里。
2644
+
2645
+ <a id="sb_speech_send_entry_from"></a>
2646
+ ### sb_speech_send_entry_from
2647
+
2648
+ ```c
2649
+ void sb_speech_send_entry_from(unsigned char group, unsigned int table, unsigned int index);
2650
+ ```
2651
+
2652
+ 按序号发送词条表里的一个词条。词条表头 2 字节是词条个数(低字节在前),之后每项 3 字节:页号增量、相对表起点的偏移低字节、偏移高字节。
2653
+ 序号不小于词条个数时什么都不发送。
2654
+
2655
+ 系统调用:$75/$01
2656
+
2657
+ 参数:
2658
+
2659
+ - `group`:词条表所在页组的首页号。
2660
+ - `table`:词条表在页组窗口里的地址。
2661
+ - `index`:词条序号,从 0 起。
2662
+
2663
+ <a id="system"></a>
2664
+ ## 系统与中断(sb2000-system.h)
2665
+
2666
+ | 函数 | 说明 | 系统调用 |
2667
+ | --- | --- | --- |
2668
+ | [`sb_wait_frames`](#sb_wait_frames) | 等待指定数量的垂直消隐周期(帧)。 | $1B |
2669
+ | [`sb_nmi_enable`](#sb_nmi_enable) | 打开 NMI(垂直消隐中断)。NMI 里的各项服务(声音更新、读手柄等)要它开着才工作。 | $12/$80 |
2670
+ | [`sb_nmi_disable`](#sb_nmi_disable) | 关闭 NMI。磁盘读写这类要独占硬件的操作前后常成对使用。 | $12/$00 |
2671
+ | [`sb_nmi_service`](#sb_nmi_service) | 打开或关闭 NMI 里的一项服务。服务号用 SB_NMI_SERVICE_ 开头的常量: | $12/$81-$86、$12/$01-$06 |
2672
+ | [`sb_nmi_hook_set`](#sb_nmi_hook_set) | 登记一个 NMI 钩子:对应的 NMI 服务(SB_NMI_SERVICE_HOOK4、SB_NMI_SERVICE_HOOK5)打开后, | |
2673
+ | [`sb_nmi_hook_reset`](#sb_nmi_hook_reset) | 把一个 NMI 钩子恢复成空钩子。钩子号不是 4 或 5 时什么都不做。 | $12/$88 |
2674
+ | [`sb_irq_mask`](#sb_irq_mask) | 屏蔽一个中断源(不再响应它)。中断源用 SB_IRQ_SOURCE_ 开头的常量: | $13/$00-$06 |
2675
+ | [`sb_irq_enable`](#sb_irq_enable) | 允许一个中断源。中断源编号同 sb_irq_mask。 | $13/$80-$86 |
2676
+ | [`sb_irq_hook_set`](#sb_irq_hook_set) | 登记一个中断钩子:对应的中断发生后,系统映射页组并调用入口例程。钩子是汇编例程,在中断里运行,以 RTS 返回,不能调用 C 函数。 | |
2677
+ | [`sb_irq_hook_reset`](#sb_irq_hook_reset) | 把一个中断钩子恢复成空钩子。钩子号:0 定时器,1 中断 3,2 中断 1,3 中断 4,4 鼠标,5 键盘。 | $13/$88 |
2678
+ | [`sb_display_option`](#sb_display_option) | 把值按位并入显示相关的硬件寄存器并写入硬件。选项与它修改的位: | $10 |
2679
+ | [`sb_display_off`](#sb_display_off) | 关闭 NMI,等到垂直消隐后关闭背景与精灵显示,用于大批量改显存前。 | $19 |
2680
+ | [`sb_display_on`](#sb_display_on) | 等到垂直消隐后打开 NMI,并恢复背景与精灵显示。 | $1A |
2681
+ | [`sb_system_state`](#sb_system_state) | 查询显示与系统状态。查询号与结果(位类的结果保持在原来的位上,不移位): | $1E |
2682
+ | [`sb_system_init`](#sb_system_init) | 系统硬件与状态初始化:重设显示、中断屏蔽、定时器、各钩子、键盘手柄鼠标状态、系统时钟(12:00:00)、DOS 内部状态等。 | $18 |
2683
+ | [`sb_call_banked`](#sb_call_banked) | 映射页组到 $8000-$BFFF 后调用其中的例程,例程以 RTS 返回,返回后窗口恢复成调用前的样子。 | $25 |
2684
+ | [`sb_jump_banked`](#sb_jump_banked) | 映射页组到 $8000-$BFFF 后跳转到其中的例程,不再回到本函数。 | $26 |
2685
+ | [`sb_exec`](#sb_exec) | 运行另一个程序,运行完返回。系统按文件大小分配扩展 RAM 页、读入文件、检查文件头魔数 AA 55, | $7F/$00 |
2686
+ | [`sb_stack_pointer`](#sb_stack_pointer) | 取硬件栈指针。返回的是本函数被调用之后的值,即调用者的栈指针减 2。 | |
2687
+ | [`sb_context_save`](#sb_context_save) | 把一个恢复点压入系统的上下文栈(最多 10 项,满了不保存),类似 setjmp。 | $1C |
2688
+ | [`sb_context_restore`](#sb_context_restore) | 弹出上下文栈顶的恢复点并跳过去,类似 longjmp:关闭 NMI 里的各项服务与声音,恢复保存的栈指针后跳转。 | $1D |
2689
+
2690
+ <a id="sb_wait_frames"></a>
2691
+ ### sb_wait_frames
2692
+
2693
+ ```c
2694
+ void __fastcall__ sb_wait_frames(unsigned char frames);
2695
+ ```
2696
+
2697
+ 等待指定数量的垂直消隐周期(帧)。
2698
+
2699
+ 系统调用:$1B
2700
+
2701
+ 参数:
2702
+
2703
+ - `frames`:帧数;0 按 256 计。
2704
+
2705
+ <a id="sb_nmi_enable"></a>
2706
+ ### sb_nmi_enable
2707
+
2708
+ ```c
2709
+ void sb_nmi_enable(void);
2710
+ ```
2711
+
2712
+ 打开 NMI(垂直消隐中断)。NMI 里的各项服务(声音更新、读手柄等)要它开着才工作。
2713
+
2714
+ 系统调用:$12/$80
2715
+
2716
+ <a id="sb_nmi_disable"></a>
2717
+ ### sb_nmi_disable
2718
+
2719
+ ```c
2720
+ void sb_nmi_disable(void);
2721
+ ```
2722
+
2723
+ 关闭 NMI。磁盘读写这类要独占硬件的操作前后常成对使用。
2724
+
2725
+ 系统调用:$12/$00
2726
+
2727
+ <a id="sb_nmi_service"></a>
2728
+ ### sb_nmi_service
2729
+
2730
+ ```c
2731
+ void sb_nmi_service(unsigned char service, unsigned char enable);
2732
+ ```
2733
+
2734
+ 打开或关闭 NMI 里的一项服务。服务号用 SB_NMI_SERVICE_ 开头的常量:
2735
+ SB_NMI_SERVICE_BAR_ANIM 条带动画,SB_NMI_SERVICE_SOUND 声音引擎每帧更新,
2736
+ SB_NMI_SERVICE_HOOK5、SB_NMI_SERVICE_HOOK4 调用登记的钩子,SB_NMI_SERVICE_PAD 读手柄,
2737
+ SB_NMI_SERVICE_PALETTE 上传 $0700 缓冲到调色板。
2738
+ 打开 SB_NMI_SERVICE_PAD 时系统还把 $0634 置 $FF。服务号超出 1-6 时什么都不做。
2739
+
2740
+ 系统调用:$12/$81-$86、$12/$01-$06
2741
+
2742
+ 参数:
2743
+
2744
+ - `service`:服务号,1 到 6。
2745
+ - `enable`:非 0 打开,0 关闭。
2746
+
2747
+ <a id="sb_nmi_hook_set"></a>
2748
+ ### sb_nmi_hook_set
2749
+
2750
+ ```c
2751
+ void sb_nmi_hook_set(unsigned char hook, unsigned char group, unsigned int entry);
2752
+ ```
2753
+
2754
+ 登记一个 NMI 钩子:对应的 NMI 服务(SB_NMI_SERVICE_HOOK4、SB_NMI_SERVICE_HOOK5)打开后,
2755
+ 每次 NMI 都会映射页组并调用入口例程。钩子是汇编例程,在中断里运行,以 RTS 返回,不能调用 C 函数。
2756
+ 钩子号不是 4 或 5 时什么都不做。
2757
+
2758
+ 参数:
2759
+
2760
+ - `hook`:钩子号,4 或 5。
2761
+ - `group`:钩子所在页组的首页号,自己程序里的例程传 SB_BYTE_AT(SB_PROGRAM_START_PAGE)。
2762
+ - `entry`:入口例程的地址。
2763
+
2764
+ <a id="sb_nmi_hook_reset"></a>
2765
+ ### sb_nmi_hook_reset
2766
+
2767
+ ```c
2768
+ void sb_nmi_hook_reset(unsigned char hook);
2769
+ ```
2770
+
2771
+ 把一个 NMI 钩子恢复成空钩子。钩子号不是 4 或 5 时什么都不做。
2772
+
2773
+ 系统调用:$12/$88
2774
+
2775
+ 参数:
2776
+
2777
+ - `hook`:钩子号,4 对应 SB_NMI_SERVICE_HOOK4,5 对应 SB_NMI_SERVICE_HOOK5。
2778
+
2779
+ <a id="sb_irq_mask"></a>
2780
+ ### sb_irq_mask
2781
+
2782
+ ```c
2783
+ void sb_irq_mask(unsigned char source);
2784
+ ```
2785
+
2786
+ 屏蔽一个中断源(不再响应它)。中断源用 SB_IRQ_SOURCE_ 开头的常量:
2787
+ 0 定时器,1 鼠标,2 键盘,3 中断 4,4 软驱,5 中断 2,6 中断 1。
2788
+ 屏蔽键盘时系统还向 $4022 写 $40。中断源超出 0-6 时什么都不做。
2789
+
2790
+ 系统调用:$13/$00-$06
2791
+
2792
+ 参数:
2793
+
2794
+ - `source`:中断源,0 到 6。
2795
+
2796
+ <a id="sb_irq_enable"></a>
2797
+ ### sb_irq_enable
2798
+
2799
+ ```c
2800
+ void sb_irq_enable(unsigned char source);
2801
+ ```
2802
+
2803
+ 允许一个中断源。中断源编号同 sb_irq_mask。
2804
+ 允许定时器时系统设置定时器寄存器;允许鼠标时按鼠标是否接入更新 $0634。
2805
+ 注意:中断源 5、6 的允许,系统用的屏蔽值取自表后相邻字节(原程序的疏漏):
2806
+ 允许中断源 5 实际清掉的是中断源 6 的屏蔽位,允许中断源 6 会把除定时器外的全部屏蔽位清 0。
2807
+ 不建议对这两个中断源使用。
2808
+
2809
+ 系统调用:$13/$80-$86
2810
+
2811
+ 参数:
2812
+
2813
+ - `source`:中断源,0 到 6。
2814
+
2815
+ <a id="sb_irq_hook_set"></a>
2816
+ ### sb_irq_hook_set
2817
+
2818
+ ```c
2819
+ void sb_irq_hook_set(unsigned char hook, unsigned char group, unsigned int entry);
2820
+ ```
2821
+
2822
+ 登记一个中断钩子:对应的中断发生后,系统映射页组并调用入口例程。钩子是汇编例程,在中断里运行,以 RTS 返回,不能调用 C 函数。
2823
+ 钩子号:0 定时器,1 中断 3(系统不会调用它),2 中断 1,3 中断 4,4 鼠标,5 键盘,6 中断 2。
2824
+ 钩子号超出 0-6 时什么都不做。
2825
+
2826
+ 参数:
2827
+
2828
+ - `hook`:钩子号,0 到 6。
2829
+ - `group`:钩子所在页组的首页号,自己程序里的例程传 SB_BYTE_AT(SB_PROGRAM_START_PAGE)。
2830
+ - `entry`:入口例程的地址。
2831
+
2832
+ <a id="sb_irq_hook_reset"></a>
2833
+ ### sb_irq_hook_reset
2834
+
2835
+ ```c
2836
+ void sb_irq_hook_reset(unsigned char hook);
2837
+ ```
2838
+
2839
+ 把一个中断钩子恢复成空钩子。钩子号:0 定时器,1 中断 3,2 中断 1,3 中断 4,4 鼠标,5 键盘。
2840
+ 钩子号超出 0-5 时什么都不做;系统不提供中断 2 钩子的复位。
2841
+
2842
+ 系统调用:$13/$88
2843
+
2844
+ 参数:
2845
+
2846
+ - `hook`:钩子号,0 到 5。
2847
+
2848
+ <a id="sb_display_option"></a>
2849
+ ### sb_display_option
2850
+
2851
+ ```c
2852
+ unsigned char sb_display_option(unsigned char option, unsigned char value);
2853
+ ```
2854
+
2855
+ 把值按位并入显示相关的硬件寄存器并写入硬件。选项与它修改的位:
2856
+ 0 扩展控制 $2008 的位 7;1 $2008 的位 0;2 $2008 的位 2、3;3 $2000 的低 2 位(名称表选择);
2857
+ 4 精灵显示:$2001 的位 4,同时值非 0 时打开 NMI 里的精灵 DMA;5 $2000 的位 5(8x16 精灵);
2858
+ 6 $2001 只保留位 1-4 再并入;7 $2001 的位 3(背景显示)。
2859
+ 值要已经放在寄存器相应的位上,如选项 7 打开背景显示传 0x08。
2860
+
2861
+ 系统调用:$10
2862
+
2863
+ 参数:
2864
+
2865
+ - `option`:选项,0 到 7。
2866
+ - `value`:要并入的位。
2867
+
2868
+ 返回:0 成功;选项超出范围时为 $FF,寄存器不变。
2869
+
2870
+ <a id="sb_display_off"></a>
2871
+ ### sb_display_off
2872
+
2873
+ ```c
2874
+ void sb_display_off(void);
2875
+ ```
2876
+
2877
+ 关闭 NMI,等到垂直消隐后关闭背景与精灵显示,用于大批量改显存前。
2878
+
2879
+ 系统调用:$19
2880
+
2881
+ <a id="sb_display_on"></a>
2882
+ ### sb_display_on
2883
+
2884
+ ```c
2885
+ void sb_display_on(void);
2886
+ ```
2887
+
2888
+ 等到垂直消隐后打开 NMI,并恢复背景与精灵显示。
2889
+
2890
+ 系统调用:$1A
2891
+
2892
+ <a id="sb_system_state"></a>
2893
+ ### sb_system_state
2894
+
2895
+ ```c
2896
+ unsigned char sb_system_state(unsigned char query);
2897
+ ```
2898
+
2899
+ 查询显示与系统状态。查询号与结果(位类的结果保持在原来的位上,不移位):
2900
+ 0 $2008 的位 7;1 $2008 的位 0;2 $2008 的位 2、3;3 $2000 的低 2 位(名称表选择);
2901
+ 4 $2001 的位 4(精灵显示);5 $2000 的位 5(精灵尺寸);
2902
+ 6 显示模式号 0-3,同时把当前字库的位置放进系统的字库参数单元;
2903
+ 7 NMI 服务开关 $0630 的位 1-7,位 0 换成“NMI 是否开着”;8 中断屏蔽影子;
2904
+ 9 鼠标是否在线(1 在线);10 恒为 1;11 键盘自检结果;12 $2001 的位 3、4(背景与精灵是否显示)。
2905
+ 查询号超出 0-12 时不调用,返回 0。
2906
+
2907
+ 系统调用:$1E
2908
+
2909
+ 参数:
2910
+
2911
+ - `query`:查询号,0 到 12。
2912
+
2913
+ 返回:查询结果。
2914
+
2915
+ <a id="sb_system_init"></a>
2916
+ ### sb_system_init
2917
+
2918
+ ```c
2919
+ void sb_system_init(void);
2920
+ ```
2921
+
2922
+ 系统硬件与状态初始化:重设显示、中断屏蔽、定时器、各钩子、键盘手柄鼠标状态、系统时钟(12:00:00)、DOS 内部状态等。
2923
+ 程序一般不需要调用,调用后程序此前的显示与输入设置都会丢失。
2924
+
2925
+ 系统调用:$18
2926
+
2927
+ <a id="sb_call_banked"></a>
2928
+ ### sb_call_banked
2929
+
2930
+ ```c
2931
+ void sb_call_banked(unsigned char group, unsigned int entry);
2932
+ ```
2933
+
2934
+ 映射页组到 $8000-$BFFF 后调用其中的例程,例程以 RTS 返回,返回后窗口恢复成调用前的样子。
2935
+ 调用 ROM 里的运行库时页组为 0。要调用自己程序里的函数,页组传 SB_BYTE_AT(SB_PROGRAM_START_PAGE)。
2936
+
2937
+ 系统调用:$25
2938
+
2939
+ 参数:
2940
+
2941
+ - `group`:页组的首页号,连续 4 页。
2942
+ - `entry`:例程在窗口里的地址。
2943
+
2944
+ <a id="sb_jump_banked"></a>
2945
+ ### sb_jump_banked
2946
+
2947
+ ```c
2948
+ void __fastcall__ sb_jump_banked(unsigned char group, unsigned int entry);
2949
+ ```
2950
+
2951
+ 映射页组到 $8000-$BFFF 后跳转到其中的例程,不再回到本函数。
2952
+ 例程的 RTS 直接返回到调用本函数的位置,相当于尾调用。
2953
+
2954
+ 系统调用:$26
2955
+
2956
+ 参数:
2957
+
2958
+ - `group`:页组的首页号,连续 4 页。
2959
+ - `entry`:例程在窗口里的地址。
2960
+
2961
+ <a id="sb_exec"></a>
2962
+ ### sb_exec
2963
+
2964
+ ```c
2965
+ unsigned char sb_exec(const char *path);
2966
+ ```
2967
+
2968
+ 运行另一个程序,运行完返回。系统按文件大小分配扩展 RAM 页、读入文件、检查文件头魔数 AA 55,
2969
+ 运行完关闭文件并释放页;子程序以 RTS 返回,用的窗口与页都是它自己的,不影响本程序。
2970
+
2971
+ 系统调用:$7F/$00
2972
+
2973
+ 参数:
2974
+
2975
+ - `path`:程序的路径,零结尾,最长 28 个字符。
2976
+
2977
+ 返回:0 成功;SB_ERR_FILE_NOT_FOUND 文件不存在;$3E 文件头魔数不符;SB_ERR_NO_MEMORY 没有足够的连续空闲页。
2978
+
2979
+ <a id="sb_stack_pointer"></a>
2980
+ ### sb_stack_pointer
2981
+
2982
+ ```c
2983
+ unsigned char sb_stack_pointer(void);
2984
+ ```
2985
+
2986
+ 取硬件栈指针。返回的是本函数被调用之后的值,即调用者的栈指针减 2。
2987
+
2988
+ 返回:硬件栈指针的低字节(高字节固定为 $01)。
2989
+
2990
+ <a id="sb_context_save"></a>
2991
+ ### sb_context_save
2992
+
2993
+ ```c
2994
+ void sb_context_save(unsigned char group, unsigned int entry, unsigned char stack_pointer);
2995
+ ```
2996
+
2997
+ 把一个恢复点压入系统的上下文栈(最多 10 项,满了不保存),类似 setjmp。
2998
+ 之后 sb_context_restore 或按 ESC 中断(sb_break_enable)会取出它,把硬件栈指针设成保存的值并跳到入口例程。
2999
+ 入口例程是新的执行起点,不要用 RTS 返回。
3000
+
3001
+ 系统调用:$1C
3002
+
3003
+ 参数:
3004
+
3005
+ - `group`:入口例程所在页组的首页号,自己程序里的例程传 SB_BYTE_AT(SB_PROGRAM_START_PAGE)。
3006
+ - `entry`:入口例程的地址。
3007
+ - `stack_pointer`:恢复时要设的硬件栈指针,通常取 sb_stack_pointer() 的返回值。
3008
+
3009
+ <a id="sb_context_restore"></a>
3010
+ ### sb_context_restore
3011
+
3012
+ ```c
3013
+ void sb_context_restore(void);
3014
+ ```
3015
+
3016
+ 弹出上下文栈顶的恢复点并跳过去,类似 longjmp:关闭 NMI 里的各项服务与声音,恢复保存的栈指针后跳转。
3017
+ 栈里有恢复点时不会返回;栈空时直接返回。
3018
+
3019
+ 系统调用:$1D
3020
+
3021
+ <a id="text"></a>
3022
+ ## 文字输出(sb2000-text.h)
3023
+
3024
+ | 函数 | 说明 | 系统调用 |
3025
+ | --- | --- | --- |
3026
+ | [`sb_puts`](#sb_puts) | 从行首显示零结尾字符串并换行。 | |
3027
+ | [`sb_newline`](#sb_newline) | 回到行首并换行,行满时自动滚动屏幕。 | |
3028
+ | [`sb_print`](#sb_print) | 在光标处显示字符串,光标移到字符串之后,行满时自动换行。 | |
3029
+ | [`sb_putc`](#sb_putc) | 在光标处显示一个字符,光标右移一格。换行符 \n 换行,回车符 \r 回到行首。 | |
3030
+ | [`sb_print_hex`](#sb_print_hex) | 在光标处显示一个字节的两位十六进制数(大写),光标移到它之后。 | |
3031
+ | [`sb_print_uint`](#sb_print_uint) | 在光标处显示一个无符号十进制数,光标移到它之后。 | |
3032
+ | [`sb_cursor_left`](#sb_cursor_left) | 光标左移一列,到行首时移到上一行的末尾。 | |
3033
+ | [`sb_cursor_right`](#sb_cursor_right) | 光标右移一列,到第 32 列时回到第 1 列并换行。 | |
3034
+ | [`sb_cursor_up`](#sb_cursor_up) | 光标移到上一行的末尾;已在第一行时不动。 | |
3035
+ | [`sb_cursor_set_column`](#sb_cursor_set_column) | 设置光标所在的列。列号超出 1-31 时不改。 | |
3036
+ | [`sb_cursor_column`](#sb_cursor_column) | 取光标所在的列。 | |
3037
+ | [`sb_cursor_row`](#sb_cursor_row) | 取光标所在的显示行。 | |
3038
+ | [`sb_beep`](#sb_beep) | 发一声提示音,用方波通道 2。 | |
3039
+
3040
+ <a id="sb_puts"></a>
3041
+ ### sb_puts
3042
+
3043
+ ```c
3044
+ void __fastcall__ sb_puts(const char *s);
3045
+ ```
3046
+
3047
+ 从行首显示零结尾字符串并换行。
3048
+ 字符码不小于 0xA1 的两个字节按 GB2312 显示一个汉字。
3049
+
3050
+ 参数:
3051
+
3052
+ - `s`:零结尾的字符串。
3053
+
3054
+ <a id="sb_newline"></a>
3055
+ ### sb_newline
3056
+
3057
+ ```c
3058
+ void sb_newline(void);
3059
+ ```
3060
+
3061
+ 回到行首并换行,行满时自动滚动屏幕。
3062
+
3063
+ <a id="sb_print"></a>
3064
+ ### sb_print
3065
+
3066
+ ```c
3067
+ void sb_print(const char *s);
3068
+ ```
3069
+
3070
+ 在光标处显示字符串,光标移到字符串之后,行满时自动换行。
3071
+
3072
+ 参数:
3073
+
3074
+ - `s`:零结尾的字符串。
3075
+
3076
+ <a id="sb_putc"></a>
3077
+ ### sb_putc
3078
+
3079
+ ```c
3080
+ void sb_putc(char c);
3081
+ ```
3082
+
3083
+ 在光标处显示一个字符,光标右移一格。换行符 \n 换行,回车符 \r 回到行首。
3084
+
3085
+ 参数:
3086
+
3087
+ - `c`:字符。
3088
+
3089
+ <a id="sb_print_hex"></a>
3090
+ ### sb_print_hex
3091
+
3092
+ ```c
3093
+ void sb_print_hex(unsigned char value);
3094
+ ```
3095
+
3096
+ 在光标处显示一个字节的两位十六进制数(大写),光标移到它之后。
3097
+
3098
+ 参数:
3099
+
3100
+ - `value`:要显示的字节。
3101
+
3102
+ <a id="sb_print_uint"></a>
3103
+ ### sb_print_uint
3104
+
3105
+ ```c
3106
+ void sb_print_uint(unsigned int value);
3107
+ ```
3108
+
3109
+ 在光标处显示一个无符号十进制数,光标移到它之后。
3110
+
3111
+ 参数:
3112
+
3113
+ - `value`:要显示的数,0 到 65535。
3114
+
3115
+ <a id="sb_cursor_left"></a>
3116
+ ### sb_cursor_left
3117
+
3118
+ ```c
3119
+ void sb_cursor_left(void);
3120
+ ```
3121
+
3122
+ 光标左移一列,到行首时移到上一行的末尾。
3123
+
3124
+ <a id="sb_cursor_right"></a>
3125
+ ### sb_cursor_right
3126
+
3127
+ ```c
3128
+ void sb_cursor_right(void);
3129
+ ```
3130
+
3131
+ 光标右移一列,到第 32 列时回到第 1 列并换行。
3132
+
3133
+ <a id="sb_cursor_up"></a>
3134
+ ### sb_cursor_up
3135
+
3136
+ ```c
3137
+ void sb_cursor_up(void);
3138
+ ```
3139
+
3140
+ 光标移到上一行的末尾;已在第一行时不动。
3141
+
3142
+ <a id="sb_cursor_set_column"></a>
3143
+ ### sb_cursor_set_column
3144
+
3145
+ ```c
3146
+ void sb_cursor_set_column(unsigned char column);
3147
+ ```
3148
+
3149
+ 设置光标所在的列。列号超出 1-31 时不改。
3150
+
3151
+ 参数:
3152
+
3153
+ - `column`:列号,1 到 31。
3154
+
3155
+ <a id="sb_cursor_column"></a>
3156
+ ### sb_cursor_column
3157
+
3158
+ ```c
3159
+ unsigned char sb_cursor_column(void);
3160
+ ```
3161
+
3162
+ 取光标所在的列。
3163
+
3164
+ 返回:列号,从 1 起。
3165
+
3166
+ <a id="sb_cursor_row"></a>
3167
+ ### sb_cursor_row
3168
+
3169
+ ```c
3170
+ unsigned char sb_cursor_row(void);
3171
+ ```
3172
+
3173
+ 取光标所在的显示行。
3174
+
3175
+ 返回:行号,从 0 起。
3176
+
3177
+ <a id="sb_beep"></a>
3178
+ ### sb_beep
3179
+
3180
+ ```c
3181
+ void sb_beep(void);
3182
+ ```
3183
+
3184
+ 发一声提示音,用方波通道 2。
3185
+
3186
+ <a id="sb2000"></a>
3187
+ ## 总头文件与通用调用(sb2000.h)
3188
+
3189
+ | 函数 | 说明 | 系统调用 |
3190
+ | --- | --- | --- |
3191
+ | [`sb_syscall`](#sb_syscall) | 调用系统服务,结果由调用者读各服务规定的变量。 | |
3192
+
3193
+ <a id="sb_syscall"></a>
3194
+ ### sb_syscall
3195
+
3196
+ ```c
3197
+ void __fastcall__ sb_syscall(unsigned char function, unsigned char sub);
3198
+ ```
3199
+
3200
+ 调用系统服务,结果由调用者读各服务规定的变量。
3201
+
3202
+ 参数:
3203
+
3204
+ - `function`:功能号,如 SB_FN_INPUT。
3205
+ - `sub`:子功能号,如 SB_SUB_KEY_GET_WAIT;没有子功能的服务可以写 0。
3206
+
3207
+ ## 系统调用覆盖表
3208
+
3209
+ BIOS 里有处理例程的每个功能号:被哪些函数封装,或者为什么不封装。需要没有封装的部分时,用 `sb_syscall` 加 `sb2000-symbols.h` 里的常量直接调用。
3210
+
3211
+ | 功能号 | 封装函数 | 没有封装的部分 |
3212
+ | --- | --- | --- |
3213
+ | $10 | sb_display_option | |
3214
+ | $11 | sb_display_mode | |
3215
+ | $12 | sb_pad_init、sb_nmi_enable、sb_nmi_disable、sb_nmi_service 等 5 个 | |
3216
+ | $13 | sb_irq_mask、sb_irq_enable、sb_irq_hook_reset | |
3217
+ | $14 | sb_mouse_reset | |
3218
+ | $15 | (不封装) | 只把 $0636 置 1,BIOS 里没有读取这个单元的指令,用途没有查清。需要时用 sb_syscall。 |
3219
+ | $17 | sb_keyboard_reset | |
3220
+ | $18 | sb_system_init | |
3221
+ | $19 | sb_display_off | |
3222
+ | $1A | sb_display_on | |
3223
+ | $1B | sb_wait_frames | |
3224
+ | $1C | sb_context_save | |
3225
+ | $1D | sb_context_restore | |
3226
+ | $1E | sb_system_state | |
3227
+ | $1F | (不封装) | 把系统时钟的时、分、秒(原始计数)复制到 $069A 起,与 sb_clock_get_time($7F/$04)取到的是同一个时钟,只是没有换算成 FAT 的 2 秒精度,没有单独封装的必要。 |
3228
+ | $24 | (不封装) | 按远指针读一个字节并后移指针。sb_far_read、sb_far_read_byte 已经覆盖,它们直接调用内核的远读入口($FFF3),比逐字节调用 $24 快。 |
3229
+ | $25 | sb_call_banked | |
3230
+ | $26 | sb_jump_banked | |
3231
+ | $27 | sb_window_map_group | |
3232
+ | $28 | (不封装) | 把页号换算成 DMA 源地址的高字节,是 DMA 服务(sb_vram_load、sb_text_to_memory 等)的内部步骤,程序自己用不到。 |
3233
+ | $29 | sb_bank_select、sb_window_map | |
3234
+ | $2A | sb_vram_bank | |
3235
+ | $2B | (不封装) | 按远指针写一个字节并后移指针。sb_far_write、sb_far_write_byte 已经覆盖,它们直接调用内核的远写入口($FFF6)。 |
3236
+ | $2C | sb_address_to_far | |
3237
+ | $30 | sb_screen_clear、sb_screen_flush、sb_cell_address | 子功能 $08(写单元)、$09(读单元)没有封装:屏幕缓冲在扩展 RAM 页里,用 sb_cell_address 取得地址后直接用 sb_far_read、sb_far_write 读写即可。 |
3238
+ | $31 | (不封装) | 按位掩码一次填多块显存,内含分段 DMA 与调色板缓冲上传,分段细节没有实测。用 sb_vram_fill 分段填充可以得到同样的效果。需要时用 sb_syscall,参数见系统调用手册 5.7.2 节。 |
3239
+ | $32 | sb_vram_fill | |
3240
+ | $33 | sb_vram_load | |
3241
+ | $34 | (不封装) | 同 $33(扩展 RAM 到显存的 DMA,已由 sb_vram_load 封装),区别是控制字不同、目的地址取自两个没有命名的单元,参数没有查清。 |
3242
+ | $3B | sb_glyph_address | |
3243
+ | $3C | sb_text_draw | |
3244
+ | $3D | sb_text_draw | |
3245
+ | $3E | sb_text_draw | |
3246
+ | $3F | sb_text_draw | |
3247
+ | $40 | sb_cells_fill、sb_cells_rect、sb_cells_copy | |
3248
+ | $41 | (不封装) | 屏幕单元写入服务:每格的值依次加步长(用来排布成对的字模图块),一次写上下两格。常量填充用 sb_cells_fill、sb_cells_rect。主要给文字编辑软件整块排版用,语义复杂,需要时用 sb_syscall,参数见系统调用手册 5.12 节。 |
3249
+ | $42 | (不封装) | 屏幕单元写入服务:按列写,每次连写左右两格后下移一行。理由同 $41。 |
3250
+ | $43 | (不封装) | 屏幕单元写入服务:同 $41,每次只写一格。理由同 $41。 |
3251
+ | $44 | (不封装) | 屏幕单元写入服务:按列写单格,下移一行。理由同 $41。 |
3252
+ | $45 | sb_text_field | |
3253
+ | $46 | sb_text_field_ascii | |
3254
+ | $47 | sb_text_to_memory | |
3255
+ | $48 | sb_text_to_memory | |
3256
+ | $4A | sb_random_next、sb_random_warm_up | |
3257
+ | $4B | sb_math_div16 | |
3258
+ | $4C | sb_math_time_text | |
3259
+ | $4D | sb_float_from_text、sb_int40_from_text | 子功能 2(40 位小数与十进制小数位互转)没有封装,转换规则只有部分文字说明。 |
3260
+ | $4E | sb_float_to_text、sb_int40_to_text | 子功能 2(同上)没有封装。 |
3261
+ | $4F | sb_float_mul | 子功能非 0 时把结果换算成 40.40 定点数放 $06AA-$06B3,没有封装,需要时用 sb_syscall。 |
3262
+ | $50 | sb_float_div | 子功能非 0 的定点数结果没有封装,理由同 $4F。 |
3263
+ | $51 | sb_float_add | |
3264
+ | $52 | sb_float_sub | |
3265
+ | $53 | sb_line_step | |
3266
+ | $54 | sb_int24_add、sb_int24_sub、sb_int24_mul、sb_int24_div | |
3267
+ | $59 | sb_window_init、sb_window_save、sb_window_restore、sb_window_compact | |
3268
+ | $5A | sb_image_load_raw | |
3269
+ | $5B | sb_image_unpack_tiles | |
3270
+ | $5C | sb_image_unpack_map | |
3271
+ | $5D | sb_palette_write | |
3272
+ | $5E | sb_image_show_full | |
3273
+ | $5F | sb_image_show | |
3274
+ | $60 | sb_image_fill_rect | |
3275
+ | $61 | sb_image_unpack_to_memory | |
3276
+ | $65 | sb_sound_play_from、sb_sound_stop、sb_sound_status、sb_sound_transpose 等 9 个 | 子功能 1(与 0 只差一个单元的值)、9(起播后不重新打开声音更新,卡拉 OK 用)、$0A(不复位的音效起播)、6 到 8(原程序疑似漏写取下标的指令,不建议使用)没有封装。 |
3277
+ | $66 | (不封装) | 卡拉 OK 歌词滚动:要特定格式的歌词文字流,整个流程(停声、起播、逐行排版、条带动画)只有 KARAOK.EXE 这类程序用,没有通用用途。需要时用 sb_syscall,文字流格式见 docs/sb2000/02-系统调用手册.md 第 10 节。 |
3278
+ | $6A | sb_pad_init、sb_pad_poll、sb_pad_wait | |
3279
+ | $6B | sb_key_wait、sb_key_poll、sb_key_count、sb_key_flush 等 7 个 | |
3280
+ | $6C | sb_mouse_set_limits、sb_mouse_set_position、sb_mouse_position、sb_mouse_buttons 等 5 个 | |
3281
+ | $6D | sb_ime_init、sb_ime_select、sb_ime_set_state、sb_ime_get_state 等 12 个 | 子功能 $09(登记自定义输入法 6)、$0C 与 $0F 到 $12(词库查询、汉字反查读音)、$13 到 $24(转发给外挂输入法模块)没有封装;外挂模块与联想方式没有验证。 |
3282
+ | $74 | sb_speech_off | 子功能 1 到 9(语音控制标志位的开关)、$0A 到 $0D(交给 NMI 逐字节发送语音数据)没有封装,需要时直接读写 $032B 与用 sb_syscall。 |
3283
+ | $75 | sb_speech_send_from、sb_speech_send、sb_speech_send_entry_from | 子功能 2 及以上(按播放列表连续发送)没有封装。 |
3284
+ | $76 | sb_printer_text、sb_printer_reset、sb_printer_home、sb_printer_carriage_return 等 10 个 | 子功能 9 到 $0C(字模转置、展开、逐列发送、发送空列)是 sb_printer_text 的内部步骤,没有封装。 |
3285
+ | $77 | (不封装) | 与 $76 是同一个入口(分发器对 $76 到 $7A 做完全相同的事,只看子功能),统一用 sb_printer_* 系列。 |
3286
+ | $78 | (不封装) | 与 $77 一样,是 $76 的同一个入口。 |
3287
+ | $79 | (不封装) | 与 $77 一样,是 $76 的同一个入口。 |
3288
+ | $7A | (不封装) | 与 $77 一样,是 $76 的同一个入口。 |
3289
+ | $7B | sb_disk_free_bytes、sb_file_open、sb_dir_change、sb_dir_open 等 5 个 | 子功能 $00、$02、$04、$05、$07、$08、$0C 到 $12 是文件系统内部步骤(扇区定位、FAT 读写与缓存、簇链、分配与传输),由 sb_file_*、sb_dir_*、sb_disk_* 覆盖,没有单独封装;$13(复位全部句柄)每条命令开头由系统调用,程序一般不必调用。 |
3290
+ | $7C | sb_file_close、sb_file_size、sb_file_read、sb_file_write 等 15 个 | 子功能 $00、$01 与 $0E(读引导扇区取磁盘参数)没有封装:磁盘参数在启动时已由 DOS 读好,更换磁盘后的重新读取没有验证。 |
3291
+ | $7D | sb_dir_make、sb_dir_remove、sb_dir_current | 子功能 $00 没有封装(作用没有查清)。 |
3292
+ | $7E | sb_page_alloc、sb_page_free、sb_page_largest_free | |
3293
+ | $7F | sb_clock_set_date、sb_clock_get_date、sb_clock_set_time、sb_clock_get_time 等 5 个 | |
3294
+ | $80 | sb_disk_init、sb_disk_start、sb_disk_stop、sb_disk_read_sector 等 9 个 | |
3295
+ | $81 | (不封装) | 只有子功能 0,什么都不做。 |