sfml.js 1.0.0-rc.1 → 1.0.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 (334) hide show
  1. package/README.ja.md +177 -0
  2. package/README.ko.md +177 -0
  3. package/README.md +119 -14
  4. package/README.zh-CN.md +177 -0
  5. package/assets/branding/sfml-js-symbol-pentagon.svg +24 -0
  6. package/assets/branding/sfml-js-wordmark-dark.svg +20 -0
  7. package/assets/branding/sfml-js-wordmark.svg +19 -0
  8. package/assets/breakout.png +0 -0
  9. package/dist/audio/effect-processor.d.ts +53 -8
  10. package/dist/audio/effect-processor.js +35 -5
  11. package/dist/audio/input-sound-file.d.ts +101 -15
  12. package/dist/audio/input-sound-file.js +101 -15
  13. package/dist/audio/listener.d.ts +74 -12
  14. package/dist/audio/listener.js +74 -12
  15. package/dist/audio/music.d.ts +172 -22
  16. package/dist/audio/music.js +185 -24
  17. package/dist/audio/output-sound-file.d.ts +36 -4
  18. package/dist/audio/output-sound-file.js +36 -4
  19. package/dist/audio/playback-device.d.ts +103 -17
  20. package/dist/audio/playback-device.js +97 -16
  21. package/dist/audio/sound-buffer-recorder.d.ts +89 -9
  22. package/dist/audio/sound-buffer-recorder.js +89 -9
  23. package/dist/audio/sound-buffer.d.ts +121 -16
  24. package/dist/audio/sound-buffer.js +98 -13
  25. package/dist/audio/sound-file-factory.d.ts +84 -11
  26. package/dist/audio/sound-file-factory.js +84 -11
  27. package/dist/audio/sound-file-reader.d.ts +155 -24
  28. package/dist/audio/sound-file-reader.js +84 -13
  29. package/dist/audio/sound-file-writer.d.ts +49 -7
  30. package/dist/audio/sound-file-writer.js +13 -2
  31. package/dist/audio/sound-recorder.d.ts +143 -19
  32. package/dist/audio/sound-recorder.js +142 -18
  33. package/dist/audio/sound-source.d.ts +273 -45
  34. package/dist/audio/sound-source.js +273 -45
  35. package/dist/audio/sound-stream.d.ts +57 -9
  36. package/dist/audio/sound-stream.js +43 -7
  37. package/dist/audio/sound.d.ts +32 -5
  38. package/dist/audio/sound.js +32 -5
  39. package/dist/audio/value.d.ts +291 -48
  40. package/dist/audio/value.js +235 -39
  41. package/dist/audio/worker.d.ts +256 -38
  42. package/dist/graphics/blend-mode.d.ts +199 -33
  43. package/dist/graphics/blend-mode.js +163 -27
  44. package/dist/graphics/boolean-vector.d.ts +102 -16
  45. package/dist/graphics/boolean-vector.js +102 -16
  46. package/dist/graphics/circle-shape.d.ts +68 -11
  47. package/dist/graphics/circle-shape.js +37 -6
  48. package/dist/graphics/color.d.ts +227 -42
  49. package/dist/graphics/color.js +177 -32
  50. package/dist/graphics/convex-shape.d.ts +45 -7
  51. package/dist/graphics/convex-shape.js +31 -5
  52. package/dist/graphics/drawable.d.ts +15 -2
  53. package/dist/graphics/drawable.js +6 -1
  54. package/dist/graphics/font.d.ts +153 -24
  55. package/dist/graphics/font.js +116 -18
  56. package/dist/graphics/glsl-matrix.d.ts +44 -7
  57. package/dist/graphics/glsl-matrix.js +44 -7
  58. package/dist/graphics/glsl.d.ts +129 -21
  59. package/dist/graphics/glsl.js +123 -20
  60. package/dist/graphics/glyph.d.ts +106 -17
  61. package/dist/graphics/glyph.js +76 -12
  62. package/dist/graphics/image.d.ts +159 -24
  63. package/dist/graphics/image.js +122 -18
  64. package/dist/graphics/primitive-type.d.ts +42 -7
  65. package/dist/graphics/primitive-type.js +42 -7
  66. package/dist/graphics/rect.d.ts +162 -26
  67. package/dist/graphics/rect.js +101 -16
  68. package/dist/graphics/rectangle-shape.d.ts +44 -7
  69. package/dist/graphics/rectangle-shape.js +31 -5
  70. package/dist/graphics/render-states.d.ts +153 -25
  71. package/dist/graphics/render-states.js +49 -8
  72. package/dist/graphics/render-target.d.ts +145 -22
  73. package/dist/graphics/render-target.js +110 -17
  74. package/dist/graphics/render-texture.d.ts +100 -16
  75. package/dist/graphics/render-texture.js +80 -13
  76. package/dist/graphics/render-window.d.ts +106 -17
  77. package/dist/graphics/render-window.js +57 -9
  78. package/dist/graphics/shader.d.ts +153 -24
  79. package/dist/graphics/shader.js +126 -20
  80. package/dist/graphics/shape.d.ts +133 -21
  81. package/dist/graphics/shape.js +115 -18
  82. package/dist/graphics/sprite.d.ts +71 -11
  83. package/dist/graphics/sprite.js +57 -9
  84. package/dist/graphics/stencil-mode.d.ts +193 -32
  85. package/dist/graphics/stencil-mode.js +121 -20
  86. package/dist/graphics/swap.d.ts +13 -2
  87. package/dist/graphics/text.d.ts +624 -103
  88. package/dist/graphics/text.js +443 -73
  89. package/dist/graphics/texture.d.ts +209 -32
  90. package/dist/graphics/texture.js +137 -21
  91. package/dist/graphics/transform.d.ts +93 -14
  92. package/dist/graphics/transform.js +93 -14
  93. package/dist/graphics/transformable.d.ts +13 -2
  94. package/dist/graphics/transformable.js +13 -2
  95. package/dist/graphics/vertex-array.d.ts +83 -14
  96. package/dist/graphics/vertex-array.js +70 -12
  97. package/dist/graphics/vertex-buffer.d.ts +162 -26
  98. package/dist/graphics/vertex-buffer.js +106 -17
  99. package/dist/graphics/vertex.d.ts +83 -14
  100. package/dist/graphics/vertex.js +43 -7
  101. package/dist/graphics/view.d.ts +140 -22
  102. package/dist/graphics/view.js +103 -16
  103. package/dist/internal/glsl-value.d.ts +30 -5
  104. package/dist/internal/glsl-value.js +30 -5
  105. package/dist/internal/scalar.d.ts +9 -1
  106. package/dist/internal/transformable.d.ts +84 -13
  107. package/dist/internal/value-storage.d.ts +8 -1
  108. package/dist/network/common.d.ts +6 -1
  109. package/dist/network/common.js +6 -1
  110. package/dist/network/dns.d.ts +103 -14
  111. package/dist/network/dns.js +55 -6
  112. package/dist/network/ftp.d.ts +217 -33
  113. package/dist/network/ftp.js +217 -33
  114. package/dist/network/gen/constants.d.ts +750 -124
  115. package/dist/network/gen/constants.js +750 -124
  116. package/dist/network/http.d.ts +365 -57
  117. package/dist/network/http.js +365 -57
  118. package/dist/network/ip-address.d.ts +179 -26
  119. package/dist/network/ip-address.js +164 -24
  120. package/dist/network/packet.d.ts +200 -29
  121. package/dist/network/packet.js +101 -13
  122. package/dist/network/sftp.d.ts +525 -84
  123. package/dist/network/sftp.js +322 -53
  124. package/dist/network/socket-selector.d.ts +109 -15
  125. package/dist/network/socket-selector.js +103 -14
  126. package/dist/network/socket.d.ts +245 -33
  127. package/dist/network/socket.js +205 -28
  128. package/dist/network/tcp-listener.d.ts +91 -13
  129. package/dist/network/tcp-listener.js +85 -12
  130. package/dist/network/tcp-socket.d.ts +232 -33
  131. package/dist/network/tcp-socket.js +153 -22
  132. package/dist/network/tls-material.d.ts +18 -2
  133. package/dist/network/tls-material.js +18 -2
  134. package/dist/network/udp-socket.d.ts +137 -19
  135. package/dist/network/udp-socket.js +101 -13
  136. package/dist/system/angle.d.ts +60 -10
  137. package/dist/system/angle.js +60 -10
  138. package/dist/system/clock.d.ts +51 -8
  139. package/dist/system/clock.js +51 -8
  140. package/dist/system/err.d.ts +14 -2
  141. package/dist/system/err.js +14 -2
  142. package/dist/system/error.d.ts +12 -2
  143. package/dist/system/error.js +12 -2
  144. package/dist/system/file-input-stream.d.ts +54 -7
  145. package/dist/system/file-input-stream.js +54 -7
  146. package/dist/system/input-stream.d.ts +97 -13
  147. package/dist/system/input-stream.js +60 -8
  148. package/dist/system/operators.d.ts +146 -19
  149. package/dist/system/operators.js +118 -15
  150. package/dist/system/sleep.d.ts +6 -1
  151. package/dist/system/sleep.js +6 -1
  152. package/dist/system/suspend-aware-clock.d.ts +18 -3
  153. package/dist/system/suspend-aware-clock.js +18 -3
  154. package/dist/system/time.d.ts +81 -12
  155. package/dist/system/time.js +63 -9
  156. package/dist/system/timeout-with-predicate.d.ts +48 -7
  157. package/dist/system/timeout-with-predicate.js +20 -3
  158. package/dist/system/unicode.d.ts +42 -6
  159. package/dist/system/unicode.js +42 -6
  160. package/dist/system/vector2.d.ts +240 -36
  161. package/dist/system/vector2.js +105 -16
  162. package/dist/system/vector3.d.ts +197 -31
  163. package/dist/system/vector3.js +104 -16
  164. package/dist/system/version.d.ts +43 -7
  165. package/dist/system/version.js +7 -1
  166. package/dist/window/clipboard.d.ts +12 -2
  167. package/dist/window/clipboard.js +12 -2
  168. package/dist/window/context-settings.d.ts +78 -13
  169. package/dist/window/context-settings.js +30 -5
  170. package/dist/window/context.d.ts +70 -10
  171. package/dist/window/context.js +52 -7
  172. package/dist/window/cursor.d.ts +44 -6
  173. package/dist/window/cursor.js +28 -4
  174. package/dist/window/event.d.ts +423 -70
  175. package/dist/window/event.js +36 -6
  176. package/dist/window/gen/constants.d.ts +1890 -314
  177. package/dist/window/gen/constants.js +1890 -314
  178. package/dist/window/joystick.d.ts +67 -11
  179. package/dist/window/joystick.js +43 -7
  180. package/dist/window/keyboard.d.ts +42 -6
  181. package/dist/window/keyboard.js +26 -4
  182. package/dist/window/mouse.d.ts +24 -3
  183. package/dist/window/mouse.js +24 -3
  184. package/dist/window/sensor.d.ts +20 -3
  185. package/dist/window/sensor.js +20 -3
  186. package/dist/window/touch.d.ts +19 -4
  187. package/dist/window/touch.js +19 -4
  188. package/dist/window/video-mode.d.ts +61 -10
  189. package/dist/window/video-mode.js +36 -6
  190. package/dist/window/vulkan.d.ts +26 -3
  191. package/dist/window/vulkan.js +26 -3
  192. package/dist/window/window.d.ts +296 -44
  193. package/dist/window/window.js +241 -34
  194. package/docs/README.ja.md +30 -0
  195. package/docs/README.ko.md +30 -0
  196. package/docs/README.md +30 -0
  197. package/docs/README.zh-CN.md +30 -0
  198. package/docs/api.ja.md +84 -0
  199. package/docs/api.ko.md +84 -0
  200. package/docs/api.md +48 -1080
  201. package/docs/api.zh-CN.md +81 -0
  202. package/docs/audio.ja.md +249 -0
  203. package/docs/audio.ko.md +251 -0
  204. package/docs/audio.md +132 -92
  205. package/docs/audio.zh-CN.md +252 -0
  206. package/docs/concepts.ja.md +130 -0
  207. package/docs/concepts.ko.md +130 -0
  208. package/docs/concepts.md +131 -0
  209. package/docs/concepts.zh-CN.md +131 -0
  210. package/docs/development.ja.md +144 -0
  211. package/docs/development.ko.md +144 -0
  212. package/docs/development.md +112 -43
  213. package/docs/development.zh-CN.md +146 -0
  214. package/docs/getting-started.ja.md +154 -0
  215. package/docs/getting-started.ko.md +154 -0
  216. package/docs/getting-started.md +156 -0
  217. package/docs/getting-started.zh-CN.md +156 -0
  218. package/docs/graphics.ja.md +256 -0
  219. package/docs/graphics.ko.md +254 -0
  220. package/docs/graphics.md +255 -0
  221. package/docs/graphics.zh-CN.md +257 -0
  222. package/docs/network.ja.md +214 -0
  223. package/docs/network.ko.md +216 -0
  224. package/docs/network.md +133 -84
  225. package/docs/network.zh-CN.md +218 -0
  226. package/docs/system.ja.md +169 -0
  227. package/docs/system.ko.md +171 -0
  228. package/docs/system.md +173 -0
  229. package/docs/system.zh-CN.md +173 -0
  230. package/docs/window.ja.md +138 -0
  231. package/docs/window.ko.md +140 -0
  232. package/docs/window.md +141 -0
  233. package/docs/window.zh-CN.md +141 -0
  234. package/native/shared-handle.h +41 -3
  235. package/package.json +17 -6
  236. package/src/audio/effect-processor.ts +53 -8
  237. package/src/audio/input-sound-file.ts +101 -15
  238. package/src/audio/listener.ts +74 -12
  239. package/src/audio/music.ts +191 -25
  240. package/src/audio/output-sound-file.ts +36 -4
  241. package/src/audio/playback-device.ts +103 -17
  242. package/src/audio/sound-buffer-recorder.ts +89 -9
  243. package/src/audio/sound-buffer.ts +121 -16
  244. package/src/audio/sound-file-factory.ts +84 -11
  245. package/src/audio/sound-file-reader.ts +155 -24
  246. package/src/audio/sound-file-writer.ts +49 -7
  247. package/src/audio/sound-recorder.ts +155 -20
  248. package/src/audio/sound-source.ts +273 -45
  249. package/src/audio/sound-stream.ts +57 -9
  250. package/src/audio/sound.ts +32 -5
  251. package/src/audio/value.ts +291 -48
  252. package/src/audio/worker.ts +256 -38
  253. package/src/graphics/blend-mode.ts +199 -33
  254. package/src/graphics/boolean-vector.ts +102 -16
  255. package/src/graphics/circle-shape.ts +68 -11
  256. package/src/graphics/color.ts +227 -42
  257. package/src/graphics/convex-shape.ts +45 -7
  258. package/src/graphics/drawable.ts +15 -2
  259. package/src/graphics/font.ts +153 -24
  260. package/src/graphics/glsl-matrix.ts +44 -7
  261. package/src/graphics/glsl.ts +129 -21
  262. package/src/graphics/glyph.ts +106 -17
  263. package/src/graphics/image.ts +159 -24
  264. package/src/graphics/primitive-type.ts +42 -7
  265. package/src/graphics/rect.ts +162 -26
  266. package/src/graphics/rectangle-shape.ts +44 -7
  267. package/src/graphics/render-states.ts +153 -25
  268. package/src/graphics/render-target.ts +145 -22
  269. package/src/graphics/render-texture.ts +100 -16
  270. package/src/graphics/render-window.ts +113 -18
  271. package/src/graphics/shader.ts +153 -24
  272. package/src/graphics/shape.ts +133 -21
  273. package/src/graphics/sprite.ts +71 -11
  274. package/src/graphics/stencil-mode.ts +193 -32
  275. package/src/graphics/swap.ts +13 -2
  276. package/src/graphics/text.ts +624 -103
  277. package/src/graphics/texture.ts +209 -32
  278. package/src/graphics/transform.ts +93 -14
  279. package/src/graphics/transformable.ts +13 -2
  280. package/src/graphics/vertex-array.ts +83 -14
  281. package/src/graphics/vertex-buffer.ts +162 -26
  282. package/src/graphics/vertex.ts +83 -14
  283. package/src/graphics/view.ts +140 -22
  284. package/src/internal/glsl-value.ts +30 -5
  285. package/src/internal/scalar.ts +9 -1
  286. package/src/internal/transformable.ts +84 -13
  287. package/src/internal/value-storage.ts +8 -1
  288. package/src/network/common.ts +6 -1
  289. package/src/network/dns.ts +103 -14
  290. package/src/network/ftp.ts +217 -33
  291. package/src/network/gen/constants.ts +750 -124
  292. package/src/network/http.ts +365 -57
  293. package/src/network/ip-address.ts +179 -26
  294. package/src/network/packet.ts +200 -29
  295. package/src/network/sftp.ts +525 -84
  296. package/src/network/socket-selector.ts +109 -15
  297. package/src/network/socket.ts +245 -33
  298. package/src/network/tcp-listener.ts +91 -13
  299. package/src/network/tcp-socket.ts +232 -33
  300. package/src/network/tls-material.ts +18 -2
  301. package/src/network/udp-socket.ts +137 -19
  302. package/src/system/angle.ts +60 -10
  303. package/src/system/clock.ts +51 -8
  304. package/src/system/err.ts +14 -2
  305. package/src/system/error.ts +12 -2
  306. package/src/system/file-input-stream.ts +54 -7
  307. package/src/system/input-stream.ts +97 -13
  308. package/src/system/operators.ts +146 -19
  309. package/src/system/sleep.ts +6 -1
  310. package/src/system/suspend-aware-clock.ts +18 -3
  311. package/src/system/time.ts +81 -12
  312. package/src/system/timeout-with-predicate.ts +48 -7
  313. package/src/system/unicode.ts +42 -6
  314. package/src/system/vector2.ts +240 -36
  315. package/src/system/vector3.ts +197 -31
  316. package/src/system/version.ts +43 -7
  317. package/src/window/clipboard.ts +12 -2
  318. package/src/window/context-settings.ts +78 -13
  319. package/src/window/context.ts +70 -10
  320. package/src/window/cursor.ts +44 -6
  321. package/src/window/event.ts +423 -70
  322. package/src/window/gen/constants.ts +1890 -314
  323. package/src/window/joystick.ts +67 -11
  324. package/src/window/keyboard.ts +42 -6
  325. package/src/window/mouse.ts +24 -3
  326. package/src/window/sensor.ts +20 -3
  327. package/src/window/touch.ts +19 -4
  328. package/src/window/video-mode.ts +61 -10
  329. package/src/window/vulkan.ts +26 -3
  330. package/src/window/window.ts +314 -46
  331. package/tools/constant-docs.cjs +109 -0
  332. package/tools/constant-docs.json +1318 -0
  333. package/tools/generate-network-constants.cjs +21 -9
  334. package/tools/generate-window-constants.cjs +26 -12
@@ -12,25 +12,57 @@ import { Image } from './image';
12
12
 
13
13
  // Window's methods operate on the same native window owned by this target.
14
14
  // installWindowMethods supplies these methods before any instance is created.
15
- /** 继承 Window 的窗口操作和同源受保护钩子,保持 Window 类型兼容。 */
15
+ /**
16
+ * Inherits Window operations and protected hooks from the same origin,
17
+ * preserving Window type compatibility.
18
+ * @zh 继承 Window 的窗口操作和同源受保护钩子,保持 Window 类型兼容。
19
+ * @ja Window の操作と同じ宣言元の protected フックを継承し、Window 型との互換性を保ちます。
20
+ * @ko Window의 창 작업과 동일한 선언에서 유래한 protected 훅을 상속하여 Window 형식 호환성을 유지합니다.
21
+ */
16
22
  // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
17
23
  export interface RenderWindow extends Window {}
18
24
 
19
- /** 同时支持 Window 窗口操作和 RenderTarget 二维绘制的窗口。 */
25
+ /**
26
+ * A window supporting both Window operations and RenderTarget 2D drawing.
27
+ * @zh 同时支持 Window 窗口操作和 RenderTarget 二维绘制的窗口。
28
+ * @ja Window のウィンドウ操作と RenderTarget の二次元描画を両方サポートするウィンドウ。
29
+ * @ko Window 창 작업과 RenderTarget 2차원 그리기를 모두 지원하는 창입니다.
30
+ */
20
31
  // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
21
32
  export class RenderWindow extends RenderTarget {
22
33
  readonly [graphicsNative]: NativeGraphicsHandle<'window'>;
23
- /** 渲染窗口 Native 目标句柄,与 Window 句柄不同。 */
34
+ /**
35
+ * Native render window target handle, distinct from the Window handle.
36
+ * @zh 渲染窗口 Native 目标句柄,与 Window 句柄不同。
37
+ * @ja Window ハンドルとは異なる、レンダーウィンドウの Native ターゲットハンドル。
38
+ * @ko Window 핸들과 다른 렌더 창의 Native 대상 핸들입니다.
39
+ */
24
40
  private readonly target: NativeGraphicsHandle<'renderWindow'>;
25
41
 
26
- /** 创建尚未打开的渲染窗口。 */
42
+ /**
43
+ * Creates a render window that is not yet open.
44
+ * @zh 创建尚未打开的渲染窗口。
45
+ * @ja まだ開いていないレンダーウィンドウを作成します。
46
+ * @ko 아직 열리지 않은 렌더 창을 만듭니다.
47
+ */
27
48
  constructor();
28
- /** 以像素尺寸、标题和可选窗口参数创建渲染窗口。 */
49
+ /**
50
+ * Creates a render window with pixel size, title and optional window
51
+ * parameters.
52
+ * @zh 以像素尺寸、标题和可选窗口参数创建渲染窗口。
53
+ * @ja ピクセルサイズ、タイトル、任意のウィンドウパラメーターでレンダーウィンドウを作成します。
54
+ * @ko 픽셀 크기, 제목 및 선택적 창 매개변수로 렌더 창을 만듭니다.
55
+ */
29
56
  constructor(
30
57
  mode: Readonly<VideoMode> | Readonly<Vector2u>, title: string,
31
58
  options?: Readonly<WindowOptions>,
32
59
  );
33
- /** 为现有系统窗口句柄创建渲染上下文。 */
60
+ /**
61
+ * Creates a rendering context for an existing system window handle.
62
+ * @zh 为现有系统窗口句柄创建渲染上下文。
63
+ * @ja 既存のシステムウィンドウハンドル用に描画コンテキストを作成します。
64
+ * @ko 기존 시스템 창 핸들의 렌더링 컨텍스트를 만듭니다.
65
+ */
34
66
  constructor(handle: WindowHandle, settings?: Readonly<ContextSettings>);
35
67
  constructor(
36
68
  mode?: Readonly<VideoMode> | Readonly<Vector2u> | WindowHandle,
@@ -47,7 +79,13 @@ export class RenderWindow extends RenderTarget {
47
79
  } else if (mode !== undefined) {
48
80
  Window.prototype.create.bind(this)(mode, title as string, options);
49
81
  }
50
- /** 先同步默认和当前视图,再允许用户钩子修改当前视图。 */
82
+ /**
83
+ * Synchronizes default and current views before allowing user hooks to
84
+ * modify the current view.
85
+ * @zh 先同步默认和当前视图,再允许用户钩子修改当前视图。
86
+ * @ja 既定ビューと現在のビューを同期してから、ユーザーフックによる現在のビューの変更を許可します。
87
+ * @ko 기본 뷰와 현재 뷰를 동기화한 후 사용자 훅이 현재 뷰를 수정할 수 있게 합니다.
88
+ */
51
89
  const initializeViews = () => {
52
90
  super.initializeViews(Window.prototype.getSize.call(this));
53
91
  };
@@ -58,12 +96,22 @@ export class RenderWindow extends RenderTarget {
58
96
  }, () => this.onResize());
59
97
  }
60
98
 
61
- /** 打开或重建渲染窗口,mode 指定像素尺寸。 */
99
+ /**
100
+ * Opens or recreates the render window; mode specifies its pixel size.
101
+ * @zh 打开或重建渲染窗口,mode 指定像素尺寸。
102
+ * @ja レンダーウィンドウを開くか再作成します。mode はピクセルサイズを指定します。
103
+ * @ko 렌더 창을 열거나 다시 만듭니다. mode는 픽셀 크기를 지정합니다.
104
+ */
62
105
  create(
63
106
  mode: Readonly<VideoMode> | Readonly<Vector2u>, title: string,
64
107
  options?: Readonly<WindowOptions>,
65
108
  ): void;
66
- /** 用现有系统窗口句柄重建渲染上下文。 */
109
+ /**
110
+ * Recreates a rendering context using an existing system window handle.
111
+ * @zh 用现有系统窗口句柄重建渲染上下文。
112
+ * @ja 既存のシステムウィンドウハンドルで描画コンテキストを再作成します。
113
+ * @ko 기존 시스템 창 핸들로 렌더링 컨텍스트를 다시 만듭니다.
114
+ */
67
115
  create(handle: WindowHandle, settings?: Readonly<ContextSettings>): void;
68
116
  create(
69
117
  mode: Readonly<VideoMode> | Readonly<Vector2u> | WindowHandle,
@@ -80,41 +128,77 @@ export class RenderWindow extends RenderTarget {
80
128
  }
81
129
  }
82
130
 
83
- /** 提交排队绘制并关闭窗口;对象之后可再次 create。 */
131
+ /**
132
+ * Submits queued draws and closes the window; create can be called again on
133
+ * this object.
134
+ * @zh 提交排队绘制并关闭窗口;对象之后可再次 create。
135
+ * @ja キュー内の描画を送信してウィンドウを閉じます。このオブジェクトで再び create を呼び出せます。
136
+ * @ko 대기 중인 그리기를 제출하고 창을 닫습니다. 이후 이 객체에서 create를 다시 호출할 수 있습니다.
137
+ */
84
138
  close(): void {
85
139
  this.flush();
86
140
  Window.prototype.close.call(this);
87
141
  }
88
142
 
89
- /** 返回窗口客户区的像素尺寸。 */
143
+ /**
144
+ * Returns the window client area's pixel size.
145
+ * @zh 返回窗口客户区的像素尺寸。
146
+ * @ja ウィンドウのクライアント領域のピクセルサイズを返します。
147
+ * @ko 창 클라이언트 영역의 픽셀 크기를 반환합니다.
148
+ */
90
149
  getSize(): Vector2u {
91
150
  return Window.prototype.getSize.call(this);
92
151
  }
93
152
 
94
- /** 提交排队绘制并设置客户区像素尺寸。 */
153
+ /**
154
+ * Submits queued draws and sets the client area's pixel size.
155
+ * @zh 提交排队绘制并设置客户区像素尺寸。
156
+ * @ja キュー内の描画を送信し、クライアント領域のピクセルサイズを設定します。
157
+ * @ko 대기 중인 그리기를 제출하고 클라이언트 영역의 픽셀 크기를 설정합니다.
158
+ */
95
159
  setSize(size: Readonly<Vector2u>): void {
96
160
  windowSize(size);
97
161
  this.flush();
98
162
  Window.prototype.setSize.call(this, size);
99
163
  }
100
164
 
101
- /** 设置客户区最小像素尺寸;undefined 取消限制。 */
165
+ /**
166
+ * Sets the minimum client area size in pixels; undefined removes the limit.
167
+ * @zh 设置客户区最小像素尺寸;undefined 取消限制。
168
+ * @ja クライアント領域の最小ピクセルサイズを設定します。undefined は制限を解除します。
169
+ * @ko 클라이언트 영역의 최소 픽셀 크기를 설정합니다. undefined는 제한을 해제합니다.
170
+ */
102
171
  setMinimumSize(size: Readonly<Vector2u> | undefined): void {
103
172
  if (size !== undefined) windowSize(size);
104
173
  this.flush();
105
174
  Window.prototype.setMinimumSize.call(this, size);
106
175
  }
107
176
 
108
- /** 设置客户区最大像素尺寸;undefined 取消限制。 */
177
+ /**
178
+ * Sets the maximum client area size in pixels; undefined removes the limit.
179
+ * @zh 设置客户区最大像素尺寸;undefined 取消限制。
180
+ * @ja クライアント領域の最大ピクセルサイズを設定します。undefined は制限を解除します。
181
+ * @ko 클라이언트 영역의 최대 픽셀 크기를 설정합니다. undefined는 제한을 해제합니다.
182
+ */
109
183
  setMaximumSize(size: Readonly<Vector2u> | undefined): void {
110
184
  if (size !== undefined) windowSize(size);
111
185
  this.flush();
112
186
  Window.prototype.setMaximumSize.call(this, size);
113
187
  }
114
188
 
115
- /** 使用图像设置窗口图标。 */
189
+ /**
190
+ * Sets the window icon using an image.
191
+ * @zh 使用图像设置窗口图标。
192
+ * @ja 画像を使ってウィンドウアイコンを設定します。
193
+ * @ko 이미지로 창 아이콘을 설정합니다.
194
+ */
116
195
  setIcon(image: Image): void;
117
- /** 使用指定尺寸的 RGBA8 像素设置窗口图标。 */
196
+ /**
197
+ * Sets the window icon using RGBA8 pixels of the specified size.
198
+ * @zh 使用指定尺寸的 RGBA8 像素设置窗口图标。
199
+ * @ja 指定サイズの RGBA8 ピクセルでウィンドウアイコンを設定します。
200
+ * @ko 지정한 크기의 RGBA8 픽셀로 창 아이콘을 설정합니다.
201
+ */
118
202
  setIcon(size: Readonly<Vector2u>, pixels: Uint8Array): void;
119
203
  setIcon(imageOrSize: Image | Readonly<Vector2u>, pixels?: Uint8Array): void {
120
204
  if (imageOrSize instanceof Image) {
@@ -125,12 +209,23 @@ export class RenderWindow extends RenderTarget {
125
209
  }
126
210
  }
127
211
 
128
- /** 返回窗口帧缓冲是否启用 sRGB 颜色转换。 */
212
+ /**
213
+ * Returns whether the window framebuffer enables sRGB color conversion.
214
+ * @zh 返回窗口帧缓冲是否启用 sRGB 颜色转换。
215
+ * @ja ウィンドウのフレームバッファーで sRGB 色変換が有効かを返します。
216
+ * @ko 창 프레임버퍼의 sRGB 색상 변환 활성화 여부를 반환합니다.
217
+ */
129
218
  isSrgb(): boolean {
130
219
  return native.isRenderWindowSrgb(this.target);
131
220
  }
132
221
 
133
- /** 同步提交绘制并交换窗口缓冲;可受垂直同步或帧率上限影响而等待。 */
222
+ /**
223
+ * Synchronously submits draws and swaps window buffers; may wait for vertical
224
+ * sync or the frame rate limit.
225
+ * @zh 同步提交绘制并交换窗口缓冲;可受垂直同步或帧率上限影响而等待。
226
+ * @ja 描画を同期的に送信し、ウィンドウバッファーを交換します。垂直同期やフレームレート上限により待機する場合があります。
227
+ * @ko 그리기를 동기적으로 제출하고 창 버퍼를 교환합니다. 수직 동기화 또는 프레임 속도 제한으로 대기할 수 있습니다.
228
+ */
134
229
  display(): void {
135
230
  this.submit(true);
136
231
  }
@@ -11,13 +11,33 @@ import { InputStream } from '../system/input-stream';
11
11
  import { Texture, type ReadonlyTexture } from './texture';
12
12
  import * as Glsl from './glsl';
13
13
 
14
- /** GLSL 着色器阶段。 */
14
+ /**
15
+ * GLSL shader stages.
16
+ * @zh GLSL 着色器阶段。
17
+ * @ja GLSL シェーダーステージ。
18
+ * @ko GLSL 셰이더 단계입니다.
19
+ */
15
20
  export enum ShaderType {
16
- /** 顶点处理阶段。 */
21
+ /**
22
+ * Vertex processing stage.
23
+ * @zh 顶点处理阶段。
24
+ * @ja 頂点処理ステージ。
25
+ * @ko 꼭짓점 처리 단계입니다.
26
+ */
17
27
  Vertex,
18
- /** 几何图元处理阶段。 */
28
+ /**
29
+ * Geometry primitive processing stage.
30
+ * @zh 几何图元处理阶段。
31
+ * @ja ジオメトリプリミティブ処理ステージ。
32
+ * @ko 기하 프리미티브 처리 단계입니다.
33
+ */
19
34
  Geometry,
20
- /** 片元颜色处理阶段。 */
35
+ /**
36
+ * Fragment color processing stage.
37
+ * @zh 片元颜色处理阶段。
38
+ * @ja フラグメント色処理ステージ。
39
+ * @ko 프래그먼트 색상 처리 단계입니다.
40
+ */
21
41
  Fragment,
22
42
  }
23
43
 
@@ -29,7 +49,12 @@ type ArrayElement = number | R<Glsl.Vec2> | R<Glsl.Vec3> | R<Glsl.Vec4> |
29
49
  R<Glsl.Mat3> | R<Glsl.Mat4>;
30
50
  type Sources<T> = [ T, ShaderType ] | [ T, T ] | [ T, T, T ];
31
51
 
32
- /** 同一个着色器程序的只读接口。 */
52
+ /**
53
+ * Read-only interface to the same shader program.
54
+ * @zh 同一个着色器程序的只读接口。
55
+ * @ja 同じシェーダープログラムへの読み取り専用インターフェース。
56
+ * @ko 동일한 셰이더 프로그램의 읽기 전용 인터페이스입니다.
57
+ */
33
58
  export type ReadonlyShader = Readonly<Pick<Shader,
34
59
  typeof graphicsNative | typeof shaderId | typeof shaderTextures |
35
60
  'getNativeHandle'>>;
@@ -57,20 +82,51 @@ function numeric(value: Uniform): { type: number; data: Float32Array | Int32Arra
57
82
  throw new TypeError('Expected a Shader uniform value');
58
83
  }
59
84
 
60
- /** Native-owned program; source loading and compilation run asynchronously. */
85
+ /**
86
+ * Native-owned program; source loading and compilation run asynchronously.
87
+ * @zh 原生层拥有的程序;源码加载和编译异步执行。
88
+ * @ja ネイティブ所有のプログラム。ソースの読み込みとコンパイルは非同期に実行されます。
89
+ * @ko 네이티브 소유 프로그램입니다. 소스 로드와 컴파일은 비동기로 실행됩니다.
90
+ */
61
91
  export class Shader {
62
- /** 着色器阶段枚举。 */
92
+ /**
93
+ * Shader stage enumeration.
94
+ * @zh 着色器阶段枚举。
95
+ * @ja シェーダーステージの列挙型。
96
+ * @ko 셰이더 단계 열거형입니다.
97
+ */
63
98
  static readonly Type = ShaderType;
64
- /** uniform 纹理占位符,绘制时使用当前对象绑定的纹理。 */
99
+ /**
100
+ * Texture uniform placeholder using the texture bound to the current object
101
+ * at draw time.
102
+ * @zh uniform 纹理占位符,绘制时使用当前对象绑定的纹理。
103
+ * @ja 描画時に現在のオブジェクトにバインドされたテクスチャを使う uniform テクスチャのプレースホルダー。
104
+ * @ko 그릴 때 현재 객체에 바인딩된 텍스처를 사용하는 텍스처 uniform 자리표시자입니다.
105
+ */
65
106
  static readonly CurrentTexture: unique symbol = Symbol('Shader.CurrentTexture');
66
107
  readonly [graphicsNative]: NativeGraphicsHandle<'shader'>;
67
108
  readonly [shaderId]: number;
68
- /** OpenGL 程序标识的只读 Uint32 包装。 */
109
+ /**
110
+ * Read-only Uint32 wrapper for the OpenGL program identifier.
111
+ * @zh OpenGL 程序标识的只读 Uint32 包装。
112
+ * @ja OpenGL プログラム識別子の読み取り専用 Uint32 ラッパー。
113
+ * @ko OpenGL 프로그램 식별자의 읽기 전용 Uint32 래퍼입니다.
114
+ */
69
115
  private readonly program: Uint32Array;
70
- /** 已设置 uniform 的纹理引用,防止被 GC 回收。 */
116
+ /**
117
+ * Texture references set as uniforms, preventing garbage collection.
118
+ * @zh 已设置 uniform 的纹理引用,防止被 GC 回收。
119
+ * @ja GC による回収を防ぐ、uniform に設定されたテクスチャ参照。
120
+ * @ko GC 수거를 방지하는 uniform에 설정된 텍스처 참조입니다.
121
+ */
71
122
  private readonly textures = new Map<number, ReadonlyTexture>();
72
123
 
73
- /** 创建尚未编译程序的空着色器。 */
124
+ /**
125
+ * Creates an empty shader with no compiled program.
126
+ * @zh 创建尚未编译程序的空着色器。
127
+ * @ja コンパイル済みプログラムのない空のシェーダーを作成します。
128
+ * @ko 컴파일된 프로그램이 없는 빈 셰이더를 만듭니다.
129
+ */
74
130
  constructor() {
75
131
  const mapping = native.createShader(graphicsContext());
76
132
  this[graphicsNative] = mapping.handle;
@@ -82,17 +138,35 @@ export class Shader {
82
138
  return this.textures;
83
139
  }
84
140
 
85
- /** 异步编译文件;参数为文件及阶段、顶点/片元文件,或顶点/几何/片元文件。 */
141
+ /**
142
+ * Compiles files asynchronously; accepts a file and stage, vertex/fragment
143
+ * files, or vertex/geometry/fragment files.
144
+ * @zh 异步编译文件;参数为文件及阶段、顶点/片元文件,或顶点/几何/片元文件。
145
+ * @ja ファイルを非同期にコンパイルします。引数はファイルとステージ、頂点/フラグメントファイル、または頂点/ジオメトリ/フラグメントファイルです。
146
+ * @ko 파일을 비동기로 컴파일합니다. 인수는 파일과 단계, 꼭짓점/프래그먼트 파일 또는 꼭짓점/기하/프래그먼트 파일입니다.
147
+ */
86
148
  loadFromFile(...sources: Sources<string>): Promise<boolean> {
87
149
  return this.load(false, sources);
88
150
  }
89
151
 
90
- /** 异步编译 GLSL 源码;参数顺序同 loadFromFile,返回编译链接是否成功。 */
152
+ /**
153
+ * Compiles GLSL source asynchronously; argument order matches loadFromFile.
154
+ * Returns whether compilation and linking succeeded.
155
+ * @zh 异步编译 GLSL 源码;参数顺序同 loadFromFile,返回编译链接是否成功。
156
+ * @ja GLSL ソースを非同期にコンパイルします。引数順は loadFromFile と同じです。コンパイルとリンクが成功したかを返します。
157
+ * @ko GLSL 소스를 비동기로 컴파일합니다. 인수 순서는 loadFromFile과 같으며 컴파일 및 링크 성공 여부를 반환합니다.
158
+ */
91
159
  loadFromMemory(...sources: Sources<string>): Promise<boolean> {
92
160
  return this.load(true, sources);
93
161
  }
94
162
 
95
- /** 从输入流读取 UTF-8 GLSL 并异步编译,阶段顺序同 loadFromFile。 */
163
+ /**
164
+ * Reads UTF-8 GLSL from input streams and compiles asynchronously; stage
165
+ * order matches loadFromFile.
166
+ * @zh 从输入流读取 UTF-8 GLSL 并异步编译,阶段顺序同 loadFromFile。
167
+ * @ja 入力ストリームから UTF-8 GLSL を読み、非同期にコンパイルします。ステージ順は loadFromFile と同じです。
168
+ * @ko 입력 스트림에서 UTF-8 GLSL을 읽고 비동기로 컴파일합니다. 단계 순서는 loadFromFile과 같습니다.
169
+ */
96
170
  async loadFromStream(...sources: Sources<InputStream>): Promise<boolean> {
97
171
  const stages = this.stages(sources);
98
172
  const code: (string | null)[] = [ null, null, null ];
@@ -113,9 +187,22 @@ export class Shader {
113
187
  return this.compile(true, code);
114
188
  }
115
189
 
116
- /** 设置 uniform,number 默认为 float;纹理参数会保留引用,其他值同步复制。 */
190
+ /**
191
+ * Sets a uniform; number defaults to float. Texture arguments retain
192
+ * references; other values are copied synchronously.
193
+ * @zh 设置 uniform,number 默认为 float;纹理参数会保留引用,其他值同步复制。
194
+ * @ja uniform を設定します。number の既定は float です。テクスチャ引数は参照を保持し、他の値は同期的にコピーします。
195
+ * @ko uniform을 설정합니다. number의 기본 형식은 float입니다. 텍스처 인수는 참조를 유지하고 다른 값은 동기적으로
196
+ * 복사합니다.
197
+ */
117
198
  setUniform(name: string, value: Uniform): void;
118
- /** 设置数值 uniform,显式指定 GLSL float 或 int;先提交已录制绘制。 */
199
+ /**
200
+ * Sets a numeric uniform explicitly as GLSL float or int, first submitting
201
+ * recorded draws.
202
+ * @zh 设置数值 uniform,显式指定 GLSL float 或 int;先提交已录制绘制。
203
+ * @ja 記録済み描画を先に送信してから、GLSL float または int を明示して数値 uniform を設定します。
204
+ * @ko 기록된 그리기를 먼저 제출한 후 GLSL float 또는 int를 명시하여 숫자 uniform을 설정합니다.
205
+ */
119
206
  setUniform(name: string, value: number, type: 'float' | 'int'): void;
120
207
  setUniform(name: string, value: Uniform, scalarType?: 'float' | 'int'): void {
121
208
  nameString(name);
@@ -138,7 +225,13 @@ export class Shader {
138
225
  native.setShaderUniform(this[graphicsNative], name, type, data, false);
139
226
  }
140
227
 
141
- /** 同步上传同类型的 float、浮点向量或矩阵数组,先提交已录制绘制。 */
228
+ /**
229
+ * Synchronously uploads a homogeneous array of floats, floating-point vectors
230
+ * or matrices, first submitting recorded draws.
231
+ * @zh 同步上传同类型的 float、浮点向量或矩阵数组,先提交已录制绘制。
232
+ * @ja 記録済み描画を先に送信し、同じ型の float、浮動小数点ベクトル、または行列の配列を同期的にアップロードします。
233
+ * @ko 기록된 그리기를 먼저 제출한 후 동일 형식의 float, 부동소수점 벡터 또는 행렬 배열을 동기적으로 업로드합니다.
234
+ */
142
235
  setUniformArray(name: string, values: Float32Array | readonly ArrayElement[]): void {
143
236
  nameString(name);
144
237
  let type = 0;
@@ -160,12 +253,23 @@ export class Shader {
160
253
  native.setShaderUniform(this[graphicsNative], name, type, data, true);
161
254
  }
162
255
 
163
- /** 返回 OpenGL 程序标识;尚未编译成功时为 0。 */
256
+ /**
257
+ * Returns the OpenGL program identifier, or 0 if compilation has not
258
+ * succeeded.
259
+ * @zh 返回 OpenGL 程序标识;尚未编译成功时为 0。
260
+ * @ja OpenGL プログラム識別子を返します。コンパイルがまだ成功していなければ 0 です。
261
+ * @ko OpenGL 프로그램 식별자를 반환합니다. 아직 컴파일에 성공하지 않았으면 0입니다.
262
+ */
164
263
  getNativeHandle(): number {
165
264
  return this.program[0];
166
265
  }
167
266
 
168
- /** 为直接 OpenGL 操作绑定程序;null 解除绑定。 */
267
+ /**
268
+ * Binds a program for direct OpenGL operations; null unbinds it.
269
+ * @zh 为直接 OpenGL 操作绑定程序;null 解除绑定。
270
+ * @ja OpenGL 直接操作用にプログラムをバインドします。null はバインドを解除します。
271
+ * @ko 직접 OpenGL 작업을 위해 프로그램을 바인딩합니다. null은 바인딩을 해제합니다.
272
+ */
169
273
  static bind(shader: ReadonlyShader | null): void {
170
274
  if (shader !== null && !(shader instanceof Shader)) {
171
275
  throw new TypeError('Expected a Shader or null');
@@ -173,12 +277,27 @@ export class Shader {
173
277
  native.bindShader(shader?.[graphicsNative] ?? null);
174
278
  }
175
279
 
176
- /** 返回当前环境是否支持着色器。 */
280
+ /**
281
+ * Returns whether the current environment supports shaders.
282
+ * @zh 返回当前环境是否支持着色器。
283
+ * @ja 現在の環境がシェーダーに対応しているかを返します。
284
+ * @ko 현재 환경의 셰이더 지원 여부를 반환합니다.
285
+ */
177
286
  static isAvailable(): boolean { return native.isShaderAvailable(false); }
178
- /** 返回当前环境是否支持几何着色器。 */
287
+ /**
288
+ * Returns whether the current environment supports geometry shaders.
289
+ * @zh 返回当前环境是否支持几何着色器。
290
+ * @ja 現在の環境がジオメトリシェーダーに対応しているかを返します。
291
+ * @ko 현재 환경의 기하 셰이더 지원 여부를 반환합니다.
292
+ */
179
293
  static isGeometryAvailable(): boolean { return native.isShaderAvailable(true); }
180
294
 
181
- /** 将阶段参数标准化为 [vertex, geometry, fragment] 三元组。 */
295
+ /**
296
+ * Normalizes stage arguments into a [vertex, geometry, fragment] tuple.
297
+ * @zh 将阶段参数标准化为 [vertex, geometry, fragment] 三元组。
298
+ * @ja ステージ引数を [vertex, geometry, fragment] の組に正規化します。
299
+ * @ko 단계 인수를 [vertex, geometry, fragment] 튜플로 정규화합니다.
300
+ */
182
301
  private stages<T>(sources: Sources<T>): (T | null)[] {
183
302
  if (sources.length === 2 && typeof sources[1] === 'number') {
184
303
  if (!Number.isInteger(sources[1]) || sources[1] < 0 || sources[1] > 2) {
@@ -193,7 +312,12 @@ export class Shader {
193
312
  throw new TypeError('Expected a shader source and type, or two/three sources');
194
313
  }
195
314
 
196
- /** 从文件或内存加载源码并编译。 */
315
+ /**
316
+ * Loads source from files or memory and compiles it.
317
+ * @zh 从文件或内存加载源码并编译。
318
+ * @ja ファイルまたはメモリからソースを読み込み、コンパイルします。
319
+ * @ko 파일 또는 메모리에서 소스를 로드하고 컴파일합니다.
320
+ */
197
321
  private async load(memory: boolean, sources: Sources<string>): Promise<boolean> {
198
322
  const stages = this.stages(sources).map(source => {
199
323
  if (source === null) return null;
@@ -204,7 +328,12 @@ export class Shader {
204
328
  return this.compile(memory, stages);
205
329
  }
206
330
 
207
- /** 异步编译并链接着色器程序。 */
331
+ /**
332
+ * Compiles and links a shader program asynchronously.
333
+ * @zh 异步编译并链接着色器程序。
334
+ * @ja シェーダープログラムを非同期にコンパイルしてリンクします。
335
+ * @ko 셰이더 프로그램을 비동기로 컴파일하고 링크합니다.
336
+ */
208
337
  private compile(memory: boolean, sources: (string | null)[]): Promise<boolean> {
209
338
  return new Promise((resolve, reject) => {
210
339
  native.compileShader(memory, sources, (error, program) => {