sfml.js 1.0.0 → 1.1.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 (313) hide show
  1. package/README.ja.md +10 -9
  2. package/README.ko.md +10 -9
  3. package/README.md +10 -9
  4. package/README.zh-CN.md +10 -9
  5. package/binding.gyp +23 -16
  6. package/dist/audio/effect-processor.js +9 -3
  7. package/dist/audio/input-sound-file.js +41 -15
  8. package/dist/audio/listener.js +33 -11
  9. package/dist/audio/music.js +41 -18
  10. package/dist/audio/output-sound-file.js +4 -2
  11. package/dist/audio/playback-device.js +11 -3
  12. package/dist/audio/sound-buffer-recorder.js +8 -5
  13. package/dist/audio/sound-buffer.js +40 -17
  14. package/dist/audio/sound-file-factory.js +21 -9
  15. package/dist/audio/sound-file-reader.js +21 -7
  16. package/dist/audio/sound-recorder.js +36 -15
  17. package/dist/audio/sound-source.js +117 -40
  18. package/dist/audio/sound-stream.js +14 -5
  19. package/dist/audio/sound.js +9 -4
  20. package/dist/audio/value.js +42 -16
  21. package/dist/graphics/blend-mode.js +2 -1
  22. package/dist/graphics/boolean-vector.d.ts +1 -2
  23. package/dist/graphics/boolean-vector.js +19 -9
  24. package/dist/graphics/color.js +2 -1
  25. package/dist/graphics/convex-shape.js +7 -3
  26. package/dist/graphics/font.js +52 -23
  27. package/dist/graphics/glsl-matrix.js +8 -3
  28. package/dist/graphics/glsl.js +47 -16
  29. package/dist/graphics/glyph.js +27 -10
  30. package/dist/graphics/image.js +30 -14
  31. package/dist/graphics/rect.js +15 -8
  32. package/dist/graphics/render-states.js +18 -9
  33. package/dist/graphics/render-target.js +49 -23
  34. package/dist/graphics/render-texture.js +24 -12
  35. package/dist/graphics/render-window.js +6 -3
  36. package/dist/graphics/shader.js +67 -32
  37. package/dist/graphics/shape.js +25 -13
  38. package/dist/graphics/sprite.js +19 -9
  39. package/dist/graphics/stencil-mode.js +10 -6
  40. package/dist/graphics/swap.js +2 -1
  41. package/dist/graphics/text.js +123 -48
  42. package/dist/graphics/texture.js +48 -24
  43. package/dist/graphics/transform.js +29 -13
  44. package/dist/graphics/transformable.js +2 -1
  45. package/dist/graphics/vertex-array.js +40 -18
  46. package/dist/graphics/vertex-buffer.js +39 -19
  47. package/dist/graphics/vertex.js +6 -3
  48. package/dist/graphics/view.js +30 -14
  49. package/dist/index.d.ts +4 -4
  50. package/dist/internal/audio-codec-registry.js +12 -6
  51. package/dist/internal/audio-input-stream.js +2 -1
  52. package/dist/internal/audio-music-pump.js +58 -24
  53. package/dist/internal/audio-recorder-session.js +17 -7
  54. package/dist/internal/audio-worker-session.js +28 -10
  55. package/dist/internal/audio-worker.js +40 -21
  56. package/dist/internal/glsl-value.d.ts +3 -1
  57. package/dist/internal/glsl-value.js +18 -8
  58. package/dist/internal/graphics-state.js +29 -15
  59. package/dist/internal/input-stream.d.ts +3 -1
  60. package/dist/internal/input-stream.js +16 -7
  61. package/dist/internal/numeric-properties.js +2 -1
  62. package/dist/internal/render-states.js +2 -1
  63. package/dist/internal/scalar.js +22 -13
  64. package/dist/internal/shaped-glyph.d.ts +3 -1
  65. package/dist/internal/shaped-glyph.js +12 -4
  66. package/dist/internal/struct-view.d.ts +3 -1
  67. package/dist/internal/struct-view.js +3 -1
  68. package/dist/internal/transformable.js +2 -1
  69. package/dist/network/common.js +23 -11
  70. package/dist/network/dns.js +25 -17
  71. package/dist/network/ftp.js +43 -18
  72. package/dist/network/http.js +126 -56
  73. package/dist/network/ip-address.js +50 -25
  74. package/dist/network/packet.js +63 -25
  75. package/dist/network/sftp.js +175 -74
  76. package/dist/network/socket-selector.js +28 -14
  77. package/dist/network/socket.js +71 -30
  78. package/dist/network/tcp-listener.js +42 -19
  79. package/dist/network/tcp-socket.js +111 -53
  80. package/dist/network/tls-material.js +2 -1
  81. package/dist/network/udp-socket.js +68 -33
  82. package/dist/system/angle.js +2 -1
  83. package/dist/system/clock.js +4 -2
  84. package/dist/system/err.js +5 -2
  85. package/dist/system/file-input-stream.js +8 -4
  86. package/dist/system/input-stream.js +6 -3
  87. package/dist/system/operators.d.ts +1 -1
  88. package/dist/system/operators.js +90 -50
  89. package/dist/system/sleep.js +4 -2
  90. package/dist/system/time.js +12 -6
  91. package/dist/system/vector2.js +6 -7
  92. package/dist/system/vector3.js +11 -6
  93. package/dist/window/clipboard.js +2 -1
  94. package/dist/window/context.js +10 -5
  95. package/dist/window/cursor.js +2 -1
  96. package/dist/window/event.js +9 -5
  97. package/dist/window/mouse.js +4 -2
  98. package/dist/window/video-mode.js +2 -1
  99. package/dist/window/window.js +19 -12
  100. package/native/addon.cc +25 -12
  101. package/native/audio-binding.cc +266 -126
  102. package/native/audio-codec-binding.cc +147 -77
  103. package/native/audio-device-binding.cc +76 -49
  104. package/native/audio-file-binding.cc +116 -67
  105. package/native/audio-recorder-binding.cc +147 -98
  106. package/native/audio-recorder.h +1 -1
  107. package/native/audio-state.h +53 -30
  108. package/native/audio-stream-binding.cc +148 -94
  109. package/native/audio-stream.h +5 -4
  110. package/native/audio-worker-binding.cc +163 -81
  111. package/native/audio-worker.h +35 -19
  112. package/native/batch-drawable.cc +29 -16
  113. package/native/batch-drawable.h +11 -8
  114. package/native/context-binding.cc +40 -27
  115. package/native/context-settings.h +15 -8
  116. package/native/deferred-delete.cc +9 -6
  117. package/native/deferred-delete.h +7 -8
  118. package/native/error-stream-binding.cc +42 -28
  119. package/native/font-binding.cc +89 -48
  120. package/native/graphics-binding.cc +122 -72
  121. package/native/graphics-state.h +50 -36
  122. package/native/image-binding.cc +38 -24
  123. package/native/image-state.h +26 -18
  124. package/native/input-binding.cc +42 -27
  125. package/native/render-window-binding.cc +38 -23
  126. package/native/shader-binding.cc +115 -50
  127. package/native/shape-binding.cc +94 -49
  128. package/native/shape-state.h +18 -9
  129. package/native/shaped-glyph-storage.h +9 -5
  130. package/native/stream-binding.cc +143 -117
  131. package/native/system-binding.cc +17 -12
  132. package/native/text-binding.cc +68 -35
  133. package/native/text-state.h +25 -18
  134. package/native/texture-binding.cc +42 -33
  135. package/native/texture-resource.h +20 -12
  136. package/native/time-value.h +3 -1
  137. package/native/transformable-binding.cc +12 -6
  138. package/native/transformable-state.h +6 -6
  139. package/native/value-binding.h +46 -28
  140. package/native/value-layout.h +10 -10
  141. package/native/values-binding.cc +29 -23
  142. package/native/vertex-binding.cc +18 -12
  143. package/native/vertex-buffer-binding.cc +38 -24
  144. package/native/vertex-storage.h +2 -2
  145. package/native/view-data.h +4 -3
  146. package/native/window-binding.cc +75 -45
  147. package/native/window-event.h +20 -11
  148. package/native/window-owner.h +15 -12
  149. package/package.json +40 -48
  150. package/src/audio/effect-processor.ts +9 -3
  151. package/src/audio/input-sound-file.ts +108 -36
  152. package/src/audio/listener.ts +39 -13
  153. package/src/audio/music.ts +112 -47
  154. package/src/audio/output-sound-file.ts +40 -11
  155. package/src/audio/playback-device.ts +23 -8
  156. package/src/audio/sound-buffer-recorder.ts +35 -13
  157. package/src/audio/sound-buffer.ts +166 -58
  158. package/src/audio/sound-file-factory.ts +127 -49
  159. package/src/audio/sound-file-reader.ts +49 -15
  160. package/src/audio/sound-recorder.ts +100 -34
  161. package/src/audio/sound-source.ts +142 -45
  162. package/src/audio/sound-stream.ts +15 -5
  163. package/src/audio/sound.ts +12 -4
  164. package/src/audio/value.ts +89 -26
  165. package/src/graphics/blend-mode.ts +3 -1
  166. package/src/graphics/boolean-vector.ts +56 -26
  167. package/src/graphics/color.ts +3 -1
  168. package/src/graphics/convex-shape.ts +10 -3
  169. package/src/graphics/font.ts +171 -50
  170. package/src/graphics/glsl-matrix.ts +9 -3
  171. package/src/graphics/glsl.ts +81 -35
  172. package/src/graphics/glyph.ts +67 -26
  173. package/src/graphics/image.ts +119 -45
  174. package/src/graphics/rect.ts +56 -24
  175. package/src/graphics/render-states.ts +31 -14
  176. package/src/graphics/render-target.ts +197 -81
  177. package/src/graphics/render-texture.ts +36 -12
  178. package/src/graphics/render-window.ts +9 -3
  179. package/src/graphics/shader.ts +186 -61
  180. package/src/graphics/shape.ts +93 -35
  181. package/src/graphics/sprite.ts +64 -25
  182. package/src/graphics/stencil-mode.ts +12 -6
  183. package/src/graphics/swap.ts +3 -2
  184. package/src/graphics/text.ts +229 -74
  185. package/src/graphics/texture.ts +180 -61
  186. package/src/graphics/transform.ts +132 -47
  187. package/src/graphics/transformable.ts +3 -1
  188. package/src/graphics/vertex-array.ts +87 -35
  189. package/src/graphics/vertex-buffer.ts +97 -33
  190. package/src/graphics/vertex.ts +9 -3
  191. package/src/graphics/view.ts +59 -21
  192. package/src/index.ts +101 -23
  193. package/src/internal/audio-codec-registry.ts +18 -6
  194. package/src/internal/audio-input-stream.ts +6 -2
  195. package/src/internal/audio-music-pump.ts +116 -41
  196. package/src/internal/audio-native.ts +249 -96
  197. package/src/internal/audio-recorder-session.ts +68 -24
  198. package/src/internal/audio-worker-session.ts +65 -21
  199. package/src/internal/audio-worker.ts +85 -41
  200. package/src/internal/glsl-value.ts +26 -11
  201. package/src/internal/graphics-state.ts +57 -20
  202. package/src/internal/input-stream.ts +23 -10
  203. package/src/internal/native.ts +252 -99
  204. package/src/internal/numeric-properties.ts +2 -1
  205. package/src/internal/render-states.ts +3 -1
  206. package/src/internal/scalar.ts +33 -14
  207. package/src/internal/shaped-glyph.ts +25 -12
  208. package/src/internal/struct-view.ts +40 -13
  209. package/src/internal/transformable.ts +3 -1
  210. package/src/network/common.ts +35 -11
  211. package/src/network/dns.ts +95 -38
  212. package/src/network/ftp.ts +129 -47
  213. package/src/network/http.ts +232 -77
  214. package/src/network/ip-address.ts +118 -48
  215. package/src/network/packet.ts +161 -54
  216. package/src/network/sftp.ts +498 -168
  217. package/src/network/socket-selector.ts +66 -26
  218. package/src/network/socket.ts +133 -46
  219. package/src/network/tcp-listener.ts +78 -29
  220. package/src/network/tcp-socket.ts +240 -95
  221. package/src/network/tls-material.ts +6 -2
  222. package/src/network/udp-socket.ts +147 -53
  223. package/src/system/angle.ts +3 -1
  224. package/src/system/clock.ts +12 -4
  225. package/src/system/err.ts +5 -2
  226. package/src/system/file-input-stream.ts +12 -4
  227. package/src/system/input-stream.ts +9 -3
  228. package/src/system/operators.ts +290 -115
  229. package/src/system/sleep.ts +6 -2
  230. package/src/system/time.ts +18 -6
  231. package/src/system/timeout-with-predicate.ts +19 -8
  232. package/src/system/vector2.ts +101 -49
  233. package/src/system/vector3.ts +85 -36
  234. package/src/window/clipboard.ts +3 -1
  235. package/src/window/context.ts +15 -5
  236. package/src/window/cursor.ts +3 -1
  237. package/src/window/event.ts +26 -12
  238. package/src/window/mouse.ts +6 -2
  239. package/src/window/video-mode.ts +3 -1
  240. package/src/window/window.ts +119 -37
  241. package/test/native/audio-probes.cc +74 -36
  242. package/test/native/deferred-delete-probes.cc +17 -11
  243. package/test/native/drawable-probes.cc +70 -36
  244. package/test/native/exception-probes.cc +14 -9
  245. package/test/native/image-probes.cc +20 -10
  246. package/test/native/matrix-probes.cc +8 -4
  247. package/test/native/network-oracle.cc +17 -11
  248. package/test/native/render-texture-probes.cc +33 -24
  249. package/test/native/shader-probes.cc +9 -9
  250. package/test/native/shape-probes.cc +37 -23
  251. package/test/native/sprite-probes.cc +41 -25
  252. package/test/native/system-probes.cc +58 -35
  253. package/test/native/text-probes.cc +77 -44
  254. package/test/native/texture-probes.cc +43 -26
  255. package/test/native/time-probes.cc +18 -12
  256. package/test/native/transform-probes.cc +15 -10
  257. package/test/native/transformable-probes.cc +23 -17
  258. package/test/native/value-oracle.h +9 -4
  259. package/test/native/value-probes.cc +31 -23
  260. package/test/native/vertex-array-probes.cc +22 -14
  261. package/test/native/vertex-buffer-probes.cc +28 -17
  262. package/test/native/view-probes.cc +29 -17
  263. package/test/native/window-probes.cc +66 -33
  264. package/tools/ensure-sfml.cjs +9 -0
  265. package/tools/generate-network-constants.cjs +11 -6
  266. package/tools/generate-window-constants.cjs +31 -12
  267. package/docs/README.ja.md +0 -30
  268. package/docs/README.ko.md +0 -30
  269. package/docs/README.md +0 -30
  270. package/docs/README.zh-CN.md +0 -30
  271. package/docs/api.ja.md +0 -84
  272. package/docs/api.ko.md +0 -84
  273. package/docs/api.md +0 -81
  274. package/docs/api.zh-CN.md +0 -81
  275. package/docs/audio.ja.md +0 -249
  276. package/docs/audio.ko.md +0 -251
  277. package/docs/audio.md +0 -252
  278. package/docs/audio.zh-CN.md +0 -252
  279. package/docs/concepts.ja.md +0 -130
  280. package/docs/concepts.ko.md +0 -130
  281. package/docs/concepts.md +0 -131
  282. package/docs/concepts.zh-CN.md +0 -131
  283. package/docs/development.ja.md +0 -144
  284. package/docs/development.ko.md +0 -144
  285. package/docs/development.md +0 -146
  286. package/docs/development.zh-CN.md +0 -146
  287. package/docs/getting-started.ja.md +0 -154
  288. package/docs/getting-started.ko.md +0 -154
  289. package/docs/getting-started.md +0 -156
  290. package/docs/getting-started.zh-CN.md +0 -156
  291. package/docs/graphics.ja.md +0 -256
  292. package/docs/graphics.ko.md +0 -254
  293. package/docs/graphics.md +0 -255
  294. package/docs/graphics.zh-CN.md +0 -257
  295. package/docs/network.ja.md +0 -214
  296. package/docs/network.ko.md +0 -216
  297. package/docs/network.md +0 -218
  298. package/docs/network.zh-CN.md +0 -218
  299. package/docs/system.ja.md +0 -169
  300. package/docs/system.ko.md +0 -171
  301. package/docs/system.md +0 -173
  302. package/docs/system.zh-CN.md +0 -173
  303. package/docs/window.ja.md +0 -138
  304. package/docs/window.ko.md +0 -140
  305. package/docs/window.md +0 -141
  306. package/docs/window.zh-CN.md +0 -141
  307. package/native/exception-boundary.h +0 -97
  308. package/native/numeric-fields.h +0 -96
  309. package/native/shared-handle.h +0 -107
  310. package/test/tsconfig.json +0 -8
  311. package/tools/configure-lsp.cjs +0 -23
  312. package/tools/lib_downloader.cjs +0 -92
  313. package/tools/lib_downloader_urls.cjs +0 -23
@@ -1,254 +0,0 @@
1
- # Graphics
2
-
3
- [English](graphics.md) / [简体中文](graphics.zh-CN.md) / [日本語](graphics.ja.md) / **한국어**
4
-
5
- > Image/Texture로 리소스를 준비하고, Sprite, Shape, Text 또는 정점으로 장면을 구성한 뒤 RenderWindow나 RenderTexture에 그리기를 맡깁니다.
6
-
7
- [API 안내](api.ko.md) · [창과 이벤트](window.ko.md) · [그리기 스냅샷](concepts.ko.md#draw-snapshots)
8
-
9
- ## Image: CPU 픽셀
10
-
11
- Image는 RGBA8 픽셀을 저장하며, `.pixels`는 네이티브 할당을 직접 매핑한 Uint8Array입니다.
12
-
13
- ```typescript
14
- import { Image, Color, Vector2u } from 'sfml.js';
15
-
16
- const image = new Image(new Vector2u(64, 64), Color.White);
17
- image.setPixel(new Vector2u(0, 0), Color.Red);
18
- image.pixels[3] = 128;
19
- if (!await image.saveToFile('image.png')) throw new Error('Cannot save image');
20
- ```
21
-
22
- | 인터페이스 | 동작 |
23
- | --- | --- |
24
- | 빈 생성자, 크기와 색상, 크기와 RGBA 바이트, 복사 생성자 | 독립적인 픽셀 리소스 생성 |
25
- | `loadFromFile/Memory/Stream()` | 비동기 로딩, boolean 반환 |
26
- | `saveToFile()`/`saveToMemory(format)` | 비동기 인코딩. 각각 boolean/바이트 또는 undefined 반환 |
27
- | `getSize()`, `getPixel()`, `setPixel()` | 크기 및 단일 픽셀 작업 |
28
- | `pixels`/`getPixelsPtr()` | 쓰기 가능한 뷰/읽기 전용 타입 뷰. 후자는 빈 이미지에서 undefined |
29
- | `resize(size, color?)` | 다시 할당하고 채움. 크기가 같아도 이전 내용을 유지하지 않음 |
30
- | `copy()`, `createMaskFromColor()`, `flipHorizontally()`, `flipVertically()` | 영역 복사, 마스크, 뒤집기 |
31
-
32
- 원본 RGBA 입력 길이는 너비 × 높이 × 4여야 하며, 생성 시 복사합니다. 성공적으로 다시 로드하거나 resize한 뒤에도 이전 뷰는 이전 할당의 수명을 계속 유지합니다. 로딩 실패 시에는 현재 이미지를 유지합니다. 픽셀 buffer를 분리하거나 크기를 바꾸지 마세요.
33
-
34
- 비동기 메모리 로딩은 호출 시 인코딩된 입력을 복사하고, 비동기 저장은 호출 시 픽셀을 복사합니다. 읽기, 디코딩, 인코딩은 백그라운드에서 실행하지만 스냅샷에는 여전히 메인 스레드 비용이 발생합니다. 입력 스트림 사용 규칙은 [System](system.ko.md#input-streams)을 참고하세요.
35
-
36
- ## Texture: GPU 텍스처
37
-
38
- ```typescript
39
- import { Texture, Sprite } from 'sfml.js';
40
-
41
- const texture = new Texture();
42
- if (!await texture.loadFromFile('sprite.png')) {
43
- throw new Error('Cannot load sprite.png');
44
- }
45
- texture.setSmooth(true);
46
- const sprite = new Sprite(texture);
47
- ```
48
-
49
- 빈 생성자는 비동기 로딩에 적합합니다. `new Texture(size)`는 GPU 저장소를 할당하고, `new Texture(image)`는 디코딩된 이미지를 업로드하며, `new Texture(sourceTexture)`는 GPU 내용을 복사합니다. 마지막 두 방식은 파일을 읽지 않습니다.
50
-
51
- | 인터페이스 | 동작 |
52
- | --- | --- |
53
- | `loadFromFile/Memory/Stream(source, sRgb?, area?)` | 비동기 디코딩 후 호출 스레드에서 업로드. area는 IntRect |
54
- | `loadFromImage(image, sRgb?, area?)` | 동기식 업로드, boolean 반환 |
55
- | `update(pixels)`/`update(pixels, size, dest)` | 전체/부분 RGBA 업로드 |
56
- | `update(imageOrTextureOrWindow, dest?)` | 소스 내용 복사 |
57
- | `resize(size, sRgb?)` | 저장소 재생성. 성공 후 픽셀은 정의되지 않음 |
58
- | `copyToImage()` | 동기식 GPU 읽어오기로 독립적인 Image 생성 |
59
- | `assign(source)`/`swap(other)` | 독립 복사/내용 교환. 대상 객체의 정체성은 유지 |
60
- | `setSmooth()`/`setRepeated()` | 부드러운 샘플링/반복 샘플링 |
61
- | `generateMipmap()` | mipmap 생성. 내용 업데이트 후 다시 생성해야 함 |
62
- | `getNativeHandle()`/`Texture.bind()` | OpenGL 이름/현재 컨텍스트에 바인딩 |
63
- | `Texture.getMaximumSize()` | 현재 장치의 최대 텍스처 변 길이 |
64
-
65
- 로딩 실패 시 이전 내용을 유지합니다. 여러 로딩은 완료 순서대로 적용되므로, 순서를 확정하려면 하나씩 await하세요. GPU 업로드와 읽어오기는 동기식 작업이며, 큰 텍스처는 호출 스레드를 점유합니다.
66
-
67
- 부분 update는 크기를 조정하거나 자르지 않으며, 대상 영역이 범위를 벗어나면 예외가 발생합니다. 로딩 시 자르기 사각형의 어느 한쪽 크기가 0이면 전체 이미지를 사용합니다. 그 밖의 비어 있지 않은 영역은 이미지 범위에 맞게 조정하며, 잘못된 음수 크기나 범위를 벗어난 시작점은 거부합니다.
68
-
69
- 텍스처 크기를 바꿔도 Sprite의 텍스처 사각형은 자동으로 바뀌지 않습니다. 전체 이미지가 필요하면 `sprite.setTexture(texture, true)`를 호출하세요. 텍스처 내용이나 샘플링 설정을 수정하기 전에 바인딩은 이전 상태에 의존하는 그리기를 제출합니다.
70
-
71
- ## Sprite와 변환
72
-
73
- Sprite는 Texture나 다른 Sprite에서 생성해야 합니다. Sprite를 복사하면 외형과 변환을 복사하고 같은 텍스처를 참조합니다.
74
-
75
- | 인터페이스 | 의미 |
76
- | --- | --- |
77
- | `setPosition()`/`move()` | 위치 및 상대 이동, Vector2f |
78
- | `setRotation()`/`rotate()` | 각도 및 상대 회전, Angle |
79
- | `setScale()`/`scale()`, `setOrigin()` | 배율과 원점, Vector2f |
80
- | `getTransform()`/`getInverseTransform()` | 캐시된 읽기 전용 행렬. 조회 시 업데이트 |
81
- | `setTexture(texture, resetRect?)` | 텍스처 전환. 기본적으로 텍스처 사각형 유지 |
82
- | `setTextureRect(rect)` | 사각형 복사. 음수 크기로 뒤집기 가능 |
83
- | `setColor(color)` | 색상 및 alpha 변조 |
84
- | `getLocalBounds()`/`getGlobalBounds()` | 로컬/자체 변환 적용 후의 축 정렬 경계 |
85
-
86
- 변환 getter가 반환하는 위치, 배율, 원점, 각도는 독립적인 값입니다. 수정 후에는 setter로 다시 써야 합니다. 반면 `getTextureRect()`는 읽기 전용 실시간 뷰를 반환하며, 이후 setter가 이를 업데이트합니다.
87
-
88
- global bounds에는 draw에 전달한 바깥쪽 RenderStates가 포함되지 않습니다. Shape와 Text도 같은 변환 인터페이스를 제공합니다.
89
-
90
- ## Shape
91
-
92
- ```typescript
93
- import { CircleShape, RectangleShape, Vector2f, Color } from 'sfml.js';
94
-
95
- const circle = new CircleShape({ radius: 24, pointCount: 48 });
96
- circle.setFillColor(Color.Cyan);
97
- circle.setOutlineColor(Color.White);
98
- circle.setOutlineThickness(2);
99
- const rectangle = new RectangleShape(new Vector2f(120, 40));
100
- rectangle.setPosition(new Vector2f(60, 20));
101
- ```
102
-
103
- ConvexShape는 점 개수를 받은 뒤 `setPoint()`로 볼록 다각형 정점을 채웁니다. 세 가지 도형 모두 같은 타입의 복사 생성자, 텍스처, 채우기, 윤곽선, 경계 조회를 지원합니다.
104
-
105
- 사용자 정의 도형은 Shape를 상속하여 `getPointCount()`와 `getPoint()`를 구현하고, 점 집합이 바뀐 뒤 protected `update()`를 호출합니다. 점 집합은 볼록 도형 조건을 만족해야 합니다. update가 지오메트리를 생성하며, 그리기를 제출할 때 JS 점 메서드를 다시 조회하지 않습니다.
106
-
107
- 윤곽선 두께는 음수일 수 있습니다. miter limit의 기본값은 10이고 최솟값은 1입니다. 지오메트리, 윤곽선 두께, miter limit를 변경하기 전에 이전 지오메트리를 참조하는 명령을 먼저 제출합니다.
108
-
109
- ## Font, Glyph, Text
110
-
111
- ```typescript
112
- import { Font, Text, TextStyle, LineAlignment, Color, Vector2f } from 'sfml.js';
113
-
114
- const font = new Font();
115
- if (!await font.openFromFile('font.ttf')) throw new Error('Cannot open font');
116
- const text = new Text({ font, string: 'Hello\nSFML', characterSize: 30 });
117
- text.setPosition(new Vector2f(20, 30));
118
- text.setStyle(TextStyle.Bold);
119
- text.setLineAlignment(LineAlignment.Center);
120
- text.setFillColor(Color.White);
121
- ```
122
-
123
- Font의 로딩 메서드는 `openFromFile/Memory/Stream()`이며 loadFromFile이 아닙니다. 로딩 실패 시 이전 폰트를 유지합니다. 메모리 입력은 네이티브 측에서 보유합니다. 파일 방식에서는 폰트를 사용하는 동안 원본 파일에 접근할 수 있어야 합니다.
124
-
125
- Font는 글리프, 커닝, 줄 간격, 어센더와 디센더, 밑줄 메트릭을 제공합니다. `getGlyph()`는 Unicode 코드 포인트로, `getGlyphById()`는 폰트 내부 번호로 조회합니다. `getTexture(size)`는 글리프가 추가됨에 따라 커지는 읽기 전용 아틀라스를 반환합니다.
126
-
127
- Text는 폰트, 문자열, 글자 크기, 간격, 채우기, 윤곽선, 스타일, 줄 정렬, 자소 묶음, 텍스트 방향 설정을 지원합니다. `getShapedGlyphs()`는 글리프 목록을 반환하고, `setGlyphPreProcessor()`는 글리프별 외형을 조절할 수 있게 합니다.
128
-
129
- `getShapedGlyphs()`와 전처리 콜백의 cluster는 JS UTF-16 인덱스를 사용합니다. 예를 들어 `A😀中`의 인덱스는 0, 1, 3입니다. 사용 중단 예정인 `findCharacterPos()`는 Unicode 코드 포인트 인덱스를 사용합니다. 전처리 콜백에서는 현재 Text의 레이아웃 속성을 다시 수정하거나 지오메트리를 조회할 수 없습니다.
130
-
131
- `getVertexData()`와 `getOutlineVertexData()`는 편집 가능한 정점을 제공합니다. 수정은 이후 draw에 영향을 주며, 레이아웃을 다시 계산하면 새 지오메트리가 생성됩니다. 이전 뷰는 원래 할당의 수명을 유지합니다. 각 draw는 정점 스냅샷을 저장합니다.
132
-
133
- ## View와 좌표
134
-
135
- View는 중심, 크기, 회전, viewport, scissor를 제어합니다.
136
-
137
- ```typescript
138
- import { RenderTexture, View, Vector2u, Vector2f } from 'sfml.js';
139
-
140
- const target = new RenderTexture(new Vector2u(800, 600));
141
- const camera = new View(target.getDefaultView());
142
- camera.move(new Vector2f(100, 0));
143
- camera.zoom(0.5);
144
- target.setView(camera);
145
- ```
146
-
147
- setView는 값으로 복사합니다. `getView()`와 `getDefaultView()`는 안정적인 읽기 전용 참조를 반환하므로, 수정하려면 View로 복사하세요.
148
-
149
- `mapPixelToCoords(Vector2i, view?)`는 픽셀을 월드 좌표로, `mapCoordsToPixel(Vector2f, view?)`는 반대 방향으로 변환합니다. view를 생략하면 현재 뷰를 사용합니다.
150
-
151
- viewport와 scissor는 대상 전체에 대한 정규화된 사각형을 사용합니다. scissor는 `[0, 1]` 범위에 있어야 하며, draw, clear, clearStencil 모두에 영향을 줍니다.
152
-
153
- ## RenderTexture와 오프스크린 합성
154
-
155
- ```typescript
156
- import { RenderTexture, Vector2u, Sprite, Color } from 'sfml.js';
157
-
158
- const source = new RenderTexture(new Vector2u(64, 64));
159
- source.clear(Color.Red);
160
- source.display();
161
-
162
- const output = new RenderTexture(new Vector2u(128, 128));
163
- output.clear();
164
- output.draw(new Sprite(source.getTexture()));
165
- output.display();
166
- await output.getTexture().copyToImage().saveToFile('offscreen.png');
167
- ```
168
-
169
- `getTexture()`는 안정적인 읽기 전용 GPU 텍스처 뷰를 반환합니다. 픽셀을 복사하거나 암묵적으로 display를 호출하지 않습니다. `flush()`는 그리기만 제출하므로 새 내용을 샘플링하기 전에는 여전히 display가 필요합니다. 같은 대상에서 자신의 텍스처를 직접 샘플링할 수 없습니다.
170
-
171
- `resize(size, settings?)`가 성공하면 현재 뷰와 기본 뷰를 초기화하며, 픽셀 내용은 정의되지 않습니다. 실패하면 원래 대상을 유지합니다. 기존 텍스처 뷰는 계속 유효하지만, 연결된 Sprite의 텍스처 사각형은 필요에 따라 다시 설정해야 합니다.
172
-
173
- ContextSettings는 depthBits, stencilBits, antiAliasingLevel, majorVersion, minorVersion, attributeFlags, sRgbCapable을 지원합니다. 실제 기능은 드라이버의 영향을 받으며, SFML Graphics에는 호환 OpenGL 컨텍스트가 필요합니다.
174
-
175
- ## Drawable과 RenderStates
176
-
177
- 사용자 정의 복합 객체는 Drawable을 상속하여 동기식 protected draw를 구현합니다. 호출할 때마다 독립적인 RenderStates 값 복사본을 받지만, 리소스 참조는 계속 공유합니다.
178
-
179
- ```typescript
180
- import { Drawable, RenderTarget, RenderStates, Transformable } from 'sfml.js';
181
-
182
- class Group extends Drawable {
183
- /** 복합 객체의 로컬 변환입니다. */
184
- readonly pose = new Transformable();
185
-
186
- /** 순서대로 그릴 자식 객체를 보관합니다. */
187
- constructor(readonly children: Drawable[]) { super(); }
188
-
189
- /** 로컬 변환을 부모 상태에 합성한 뒤 각 자식 객체를 그립니다. */
190
- protected draw(target: RenderTarget, states: RenderStates): void {
191
- states.transform.combine(this.pose.getTransform());
192
- for (const child of this.children) target.draw(child, states);
193
- }
194
- }
195
- ```
196
-
197
- | RenderStates 필드 | 기본값 |
198
- | --- | --- |
199
- | transform | 항등 변환 |
200
- | blendMode | BlendAlpha |
201
- | stencilMode | 기본 StencilMode |
202
- | coordinateType | CoordinateType.Pixels |
203
- | texture/shader | null |
204
-
205
- draw는 RenderStates, 상태 옵션 또는 개별 Transform, Texture, Shader, BlendMode, StencilMode 등을 받습니다. Sprite와 Shape는 자신의 텍스처와 좌표 모드를 사용합니다.
206
-
207
- 스텐실 마스크를 사용하려면 대상에 stencilBits가 있어야 합니다. `clear(color, stencil)`은 색상과 스텐실을 함께 지우고, `clearStencil()`은 스텐실만 지웁니다. BlendMode는 Alpha, Add, Multiply, Min, Max, None 프리셋을 제공합니다.
208
-
209
- ## 정점과 GPU 버퍼
210
-
211
- ```typescript
212
- import { VertexArray, Vertex, PrimitiveType, Vector2f, Color } from 'sfml.js';
213
-
214
- const triangle = new VertexArray(PrimitiveType.Triangles, 3);
215
- triangle.setVertex(0, new Vertex(new Vector2f(10, 10), Color.Red));
216
- triangle.setVertex(1, new Vertex(new Vector2f(100, 10), Color.Green));
217
- triangle.setVertex(2, new Vertex(new Vector2f(10, 100), Color.Blue));
218
- triangle.getVertex(1).position.x = 120;
219
- ```
220
-
221
- VertexArray는 get/setVertex, append, resize, clear, getBounds와 반복을 지원합니다. draw는 연속된 정점의 스냅샷을 즉시 저장하므로, 이후 수정하거나 용량을 늘려도 이미 기록된 화면은 바뀌지 않습니다. 구조를 수정한 뒤에는 멤버를 다시 가져오고, 순회 중에는 구조를 수정하지 마세요.
222
-
223
- SFML 3은 Points, Lines, LineStrip, Triangles, TriangleStrip, TriangleFan을 지원합니다. 여러 사각형을 삼각형으로 구성하여 하나의 VertexArray에 넣으면 실제 SFML draw 호출 수를 줄일 수 있습니다.
224
-
225
- VertexBuffer는 정점을 GPU에 저장합니다. 먼저 `create(count)`, 이어서 `update(vertices)`를 호출하고 둘의 불리언 반환값을 확인하세요. Usage에는 Stream, Dynamic, Static이 있습니다. 범위 그리기에는 `target.draw(buffer, firstVertex, vertexCount, states?)`를 사용합니다.
226
-
227
- `assign()`은 GPU 데이터, 프리미티브, usage를 깊은 복사합니다. `update(sourceBuffer)`는 데이터를 복사하되 대상의 프리미티브와 usage를 유지합니다. `swap()`은 리소스를 교환합니다. 저장소를 수정하기 전에 이전 그리기를 제출합니다. GL 이름은 바뀔 수 있으므로 사용 전에 다시 가져오세요.
228
-
229
- ## Shader, Transform, GLSL
230
-
231
- Shader는 비동기 `loadFromFile/Memory/Stream()`을 사용하며, 단일 단계 또는 vertex/fragment/geometry 조합을 지원합니다. 다시 로드하는 데 성공하면 프로그램을 교체하고 uniform 상태를 비우며, 실패하면 이전 프로그램을 유지합니다.
232
-
233
- `setUniform()`은 number, boolean, Glsl 벡터/행렬, Texture, `Shader.CurrentTexture`를 받습니다. number의 기본값은 float이며, 정수에는 세 번째 인수로 `'int'`를 사용합니다. uniform 수정 전에 기존 그리기를 제출합니다.
234
-
235
- `Glsl.Vec2/3/4`, `Ivec2/3/4`, `Bvec2/3/4`는 GLSL 벡터에 대응합니다. Mat3/Mat4는 배열, 같은 크기의 행렬, Transform에서 생성하며, `.array`는 열 우선 Float32Array입니다. 4차원 벡터와 행렬에는 범용 벡터 산술 연산자를 제공하지 않습니다.
236
-
237
- Transform은 이동, 회전, 크기 조절, combine을 지원하며, 제자리에서 수정하고 자신을 반환합니다. 합성은 오른쪽 곱셈이므로 `translate(...).scale(...)`는 점에 먼저 크기 조절을 적용한 뒤 이동을 적용합니다. getMatrix는 읽기 전용 실시간 배열을 반환합니다. 특이 행렬의 역행렬을 구하면 독립적인 항등 변환을 반환합니다.
238
-
239
- `Shader.isAvailable()`, `isGeometryAvailable()`, `VertexBuffer.isAvailable()`로 기능을 확인할 수 있습니다. Texture/Shader/VertexBuffer의 bind를 직접 사용하기 전에 기존 SFML 명령을 명시적으로 제출하세요.
240
-
241
- ## 예제와 성능 검증
242
-
243
- [예제 목록](../examples/README.ko.md)은 텍스처, 스프라이트, 텍스트, 정점, 복합 객체 그리기, 오프스크린 합성을 위한 독립 진입점을 제공합니다.
244
-
245
- 빌드 후 `tools/benchmark-image.cjs`, `tools/benchmark-drawable.cjs`, `tools/benchmark-vertex-array.cjs`를 실행하여 현재 구현을 측정할 수 있습니다. 벤치마크의 호출 스레드 시간에는 기록, 제출, 드라이버 작업이 포함되므로, 이를 GPU 시간이나 실제 게임 프레임 레이트로 곧바로 해석해서는 안 됩니다.
246
-
247
- <a id="sfml-cpp-reference"></a>
248
- ## SFML C++ 레퍼런스
249
-
250
- - 이미지와 그리기 객체: [Image](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Image.html), [Texture](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Texture.html), [Sprite](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Sprite.html), [Shape](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Shape.html), [Drawable](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Drawable.html).
251
- - 텍스트와 카메라: [Font](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Font.html), [Text](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Text.html), [View](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1View.html).
252
- - 렌더링과 지오메트리: [RenderTexture](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1RenderTexture.html), [RenderTarget](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1RenderTarget.html), [Shader](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Shader.html), [VertexArray](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1VertexArray.html), [VertexBuffer](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1VertexBuffer.html).
253
-
254
- 렌더링 개념은 업스트림 C++ 문서를 참고하세요. 리소스 생성과 로딩, 그리기 스냅샷의 동작은 이 JS 가이드의 규칙을 따릅니다.
package/docs/graphics.md DELETED
@@ -1,255 +0,0 @@
1
- # Graphics
2
-
3
- **English** · [简体中文](graphics.zh-CN.md) · [日本語](graphics.ja.md) · [한국어](graphics.ko.md)
4
-
5
- > Prepare assets with Image/Texture, organize scenes with Sprite, Shape, Text or vertices, then draw them with RenderWindow or RenderTexture.
6
-
7
- [API guide](api.md) · [Windows and events](window.md) · [Draw snapshots](concepts.md#draw-snapshots)
8
-
9
- ## Image: CPU pixels
10
-
11
- Image stores RGBA8 pixels; `.pixels` is a Uint8Array mapped directly to the native allocation:
12
-
13
- ```typescript
14
- import { Image, Color, Vector2u } from 'sfml.js';
15
-
16
- const image = new Image(new Vector2u(64, 64), Color.White);
17
- image.setPixel(new Vector2u(0, 0), Color.Red);
18
- image.pixels[3] = 128;
19
- if (!await image.saveToFile('image.png')) throw new Error('Cannot save image');
20
- ```
21
-
22
- | API | Behavior |
23
- | --- | --- |
24
- | Default construction, size and color, size and RGBA bytes, copy construction | Create an independent pixel resource |
25
- | `loadFromFile/Memory/Stream()` | Asynchronous loading; returns boolean |
26
- | `saveToFile()`/`saveToMemory(format)` | Asynchronous encoding; returns boolean/bytes or undefined, respectively |
27
- | `getSize()`, `getPixel()`, `setPixel()` | Size and single-pixel operations |
28
- | `pixels`/`getPixelsPtr()` | Writable view/read-only typed view; the latter is undefined for an empty image |
29
- | `resize(size, color?)` | Reallocate and fill; old contents are not preserved even when the size is unchanged |
30
- | `copy()`, `createMaskFromColor()`, `flipHorizontally()`, `flipVertically()` | Region copying, masking and flipping |
31
-
32
- Raw RGBA input must have a length of width * height * 4 and is copied during construction. After a successful reload or resize, old views keep the old allocation alive; a failed load preserves the current image. Do not detach or resize the pixel buffer.
33
-
34
- Asynchronous memory loading copies encoded input at call time; asynchronous saving copies the pixels at call time. Reading, decoding and encoding run in the background, but taking snapshots still has a main-thread cost. See [System](system.md#input-streams) for input-stream rules.
35
-
36
- ## Texture: GPU textures
37
-
38
- ```typescript
39
- import { Texture, Sprite } from 'sfml.js';
40
-
41
- const texture = new Texture();
42
- if (!await texture.loadFromFile('sprite.png')) {
43
- throw new Error('Cannot load sprite.png');
44
- }
45
- texture.setSmooth(true);
46
- const sprite = new Sprite(texture);
47
- ```
48
-
49
- Default construction suits asynchronous loading; `new Texture(size)` allocates GPU storage, `new Texture(image)` uploads a decoded image, and `new Texture(sourceTexture)` copies GPU contents. The latter two do not read files.
50
-
51
- | API | Behavior |
52
- | --- | --- |
53
- | `loadFromFile/Memory/Stream(source, sRgb?, area?)` | Decode asynchronously and upload on the calling thread; area is an IntRect |
54
- | `loadFromImage(image, sRgb?, area?)` | Synchronous upload; returns boolean |
55
- | `update(pixels)`/`update(pixels, size, dest)` | Upload all/a region of RGBA pixels |
56
- | `update(imageOrTextureOrWindow, dest?)` | Copy source contents |
57
- | `resize(size, sRgb?)` | Recreate storage; pixel contents are undefined on success |
58
- | `copyToImage()` | Synchronous GPU readback into an independent Image |
59
- | `assign(source)`/`swap(other)` | Independent copy/content swap, preserving target object identity |
60
- | `setSmooth()`/`setRepeated()` | Smooth/repeated sampling |
61
- | `generateMipmap()` | Generate mipmaps; regenerate after updating contents |
62
- | `getNativeHandle()`/`Texture.bind()` | OpenGL name/binding in the current context |
63
- | `Texture.getMaximumSize()` | Maximum texture side length on the current device |
64
-
65
- Failed loads preserve old contents. Multiple loads take effect in completion order; await sequentially for a deterministic order. GPU upload and readback are synchronous, and large textures occupy the calling thread.
66
-
67
- Partial update does not scale or crop, and an out-of-bounds destination region throws. Loading uses the full image if either dimension of the crop rectangle is zero; other nonempty regions are adjusted to image bounds. Invalid negative sizes or out-of-bounds origins are rejected.
68
-
69
- Texture size changes do not automatically update a Sprite's texture rectangle; call `sprite.setTexture(texture, true)` when you need the full image. Before changing texture contents or sampling settings, the binding submits draws that depend on the old state.
70
-
71
- ## Sprite and transforms
72
-
73
- Sprite must be constructed from a Texture or another Sprite. Copying a Sprite copies its appearance and transform while referencing the same texture.
74
-
75
- | API | Semantics |
76
- | --- | --- |
77
- | `setPosition()`/`move()` | Position and relative movement, using Vector2f |
78
- | `setRotation()`/`rotate()` | Angle and relative rotation, using Angle |
79
- | `setScale()`/`scale()`, `setOrigin()` | Scale and origin, using Vector2f |
80
- | `getTransform()`/`getInverseTransform()` | Cached read-only matrices, updated when queried |
81
- | `setTexture(texture, resetRect?)` | Switch texture, preserving the texture rectangle by default |
82
- | `setTextureRect(rect)` | Copy the rectangle; negative sizes can flip the image |
83
- | `setColor(color)` | Color and alpha modulation |
84
- | `getLocalBounds()`/`getGlobalBounds()` | Local/own-transformed axis-aligned bounds |
85
-
86
- Transform getters return independent position, scale, origin and angle values. Write changes back through setters. In contrast, `getTextureRect()` returns a read-only live view that subsequent setters update.
87
-
88
- Global bounds do not include outer RenderStates passed to draw. Shape and Text provide the same transform APIs.
89
-
90
- ## Shape
91
-
92
- ```typescript
93
- import { CircleShape, RectangleShape, Vector2f, Color } from 'sfml.js';
94
-
95
- const circle = new CircleShape({ radius: 24, pointCount: 48 });
96
- circle.setFillColor(Color.Cyan);
97
- circle.setOutlineColor(Color.White);
98
- circle.setOutlineThickness(2);
99
- const rectangle = new RectangleShape(new Vector2f(120, 40));
100
- rectangle.setPosition(new Vector2f(60, 20));
101
- ```
102
-
103
- ConvexShape accepts a point count; then use `setPoint()` to fill in the convex polygon's vertices. All three shape classes support same-type copy construction, textures, fills, outlines and bounds queries.
104
-
105
- For a custom shape, extend Shape, implement `getPointCount()` and `getPoint()`, and call protected `update()` after changing the points. The point set must form a convex shape. update generates geometry; submitting a draw does not query the JS point methods again.
106
-
107
- Outline thickness may be negative; the miter limit defaults to 10 and has a minimum of 1. Commands referencing old geometry are submitted before geometry, outline thickness or the miter limit changes.
108
-
109
- ## Font, Glyph and Text
110
-
111
- ```typescript
112
- import { Font, Text, TextStyle, LineAlignment, Color, Vector2f } from 'sfml.js';
113
-
114
- const font = new Font();
115
- if (!await font.openFromFile('font.ttf')) throw new Error('Cannot open font');
116
- const text = new Text({ font, string: 'Hello\nSFML', characterSize: 30 });
117
- text.setPosition(new Vector2f(20, 30));
118
- text.setStyle(TextStyle.Bold);
119
- text.setLineAlignment(LineAlignment.Center);
120
- text.setFillColor(Color.White);
121
- ```
122
-
123
- Font loads through `openFromFile/Memory/Stream()`, not loadFromFile. Failed loads preserve the old font. Memory input is held natively; for file input, keep the source file available while the font is in use.
124
-
125
- Font provides glyphs, kerning, line spacing, ascent, descent and underline metrics. `getGlyph()` queries by Unicode code point, while `getGlyphById()` queries by the font's internal identifier; `getTexture(size)` returns a read-only atlas that grows as glyphs are added.
126
-
127
- Text supports font, string, character size, spacing, fill, outline, style, line alignment, grapheme grouping and text direction settings. `getShapedGlyphs()` returns a glyph list; `setGlyphPreProcessor()` can adjust appearance per glyph.
128
-
129
- The cluster values from `getShapedGlyphs()` and preprocessing callbacks use JS UTF-16 indices: for example, `A😀中` gives 0, 1 and 3. The deprecated `findCharacterPos()` uses Unicode code-point indices. Preprocessing callbacks must not modify layout properties or query geometry on the current Text.
130
-
131
- `getVertexData()` and `getOutlineVertexData()` provide editable vertices. Changes affect subsequent draws; relayout generates new geometry, while old views keep the original allocation alive. Each draw saves a vertex snapshot.
132
-
133
- ## View and coordinates
134
-
135
- View controls the center, size, rotation, viewport and scissor:
136
-
137
- ```typescript
138
- import { RenderTexture, View, Vector2u, Vector2f } from 'sfml.js';
139
-
140
- const target = new RenderTexture(new Vector2u(800, 600));
141
- const camera = new View(target.getDefaultView());
142
- camera.move(new Vector2f(100, 0));
143
- camera.zoom(0.5);
144
- target.setView(camera);
145
- ```
146
-
147
- setView copies by value. `getView()` and `getDefaultView()` return stable read-only references; copy into a View when you need to make changes.
148
-
149
- `mapPixelToCoords(Vector2i, view?)` converts pixels to world coordinates; `mapCoordsToPixel(Vector2f, view?)` performs the reverse conversion. Omitting view uses the current view.
150
-
151
- viewport and scissor use normalized rectangles relative to the entire target. scissor must lie within `[0, 1]` and affects draw, clear and clearStencil.
152
-
153
- ## RenderTexture and off-screen composition
154
-
155
- ```typescript
156
- import { RenderTexture, Vector2u, Sprite, Color } from 'sfml.js';
157
-
158
- const source = new RenderTexture(new Vector2u(64, 64));
159
- source.clear(Color.Red);
160
- source.display();
161
-
162
- const output = new RenderTexture(new Vector2u(128, 128));
163
- output.clear();
164
- output.draw(new Sprite(source.getTexture()));
165
- output.display();
166
- await output.getTexture().copyToImage().saveToFile('offscreen.png');
167
- ```
168
-
169
- `getTexture()` returns a stable read-only GPU texture view; it neither copies pixels nor implicitly calls display. `flush()` only submits draws; display is still required before sampling new contents. A target cannot directly sample its own texture.
170
-
171
- Successful `resize(size, settings?)` resets the current and default views and leaves pixel contents undefined; failure preserves the original target. Existing texture views remain valid, but associated Sprites' texture rectangles must be reset as needed.
172
-
173
- ContextSettings supports depthBits, stencilBits, antiAliasingLevel, majorVersion, minorVersion, attributeFlags and sRgbCapable. Actual capabilities depend on the driver; SFML Graphics requires a compatibility OpenGL context.
174
-
175
- ## Drawable and RenderStates
176
-
177
- Custom composite objects extend Drawable and implement synchronous protected draw. Each call receives an independent RenderStates value copy, while resource references remain shared:
178
-
179
- ```typescript
180
- import { Drawable, RenderTarget, RenderStates, Transformable } from 'sfml.js';
181
-
182
- class Group extends Drawable {
183
- /** Local transform of the composite object. */
184
- readonly pose = new Transformable();
185
-
186
- /** Retain child objects in drawing order. */
187
- constructor(readonly children: Drawable[]) { super(); }
188
-
189
- /** Combine the local transform with the parent state, then draw each child. */
190
- protected draw(target: RenderTarget, states: RenderStates): void {
191
- states.transform.combine(this.pose.getTransform());
192
- for (const child of this.children) target.draw(child, states);
193
- }
194
- }
195
- ```
196
-
197
- | RenderStates field | Default |
198
- | --- | --- |
199
- | transform | Identity transform |
200
- | blendMode | BlendAlpha |
201
- | stencilMode | Default StencilMode |
202
- | coordinateType | CoordinateType.Pixels |
203
- | texture/shader | null |
204
-
205
- draw accepts RenderStates, state options, or individual Transform, Texture, Shader, BlendMode, StencilMode and similar values. Sprite and Shape use their own textures and coordinate modes.
206
-
207
- Stencil masking requires stencilBits on the target. `clear(color, stencil)` clears both color and stencil, while `clearStencil()` clears only stencil. BlendMode provides Alpha, Add, Multiply, Min, Max and None presets.
208
-
209
- ## Vertices and GPU buffers
210
-
211
- ```typescript
212
- import { VertexArray, Vertex, PrimitiveType, Vector2f, Color } from 'sfml.js';
213
-
214
- const triangle = new VertexArray(PrimitiveType.Triangles, 3);
215
- triangle.setVertex(0, new Vertex(new Vector2f(10, 10), Color.Red));
216
- triangle.setVertex(1, new Vertex(new Vector2f(100, 10), Color.Green));
217
- triangle.setVertex(2, new Vertex(new Vector2f(10, 100), Color.Blue));
218
- triangle.getVertex(1).position.x = 120;
219
- ```
220
-
221
- VertexArray supports get/setVertex, append, resize, clear, getBounds and iteration. draw immediately saves a contiguous vertex snapshot; later edits or capacity growth do not change recorded output. Reacquire members after structural changes, and do not change the structure during iteration.
222
-
223
- SFML 3 supports Points, Lines, LineStrip, Triangles, TriangleStrip and TriangleFan. Organize multiple squares as triangles in one VertexArray to reduce actual SFML draw calls.
224
-
225
- VertexBuffer stores vertices on the GPU; call `create(count)`, then `update(vertices)`, checking both boolean return values. Usage provides Stream, Dynamic and Static. Draw a range with `target.draw(buffer, firstVertex, vertexCount, states?)`.
226
-
227
- `assign()` deep-copies GPU data, primitive type and usage; `update(sourceBuffer)` copies data while preserving the target's primitive type and usage; `swap()` exchanges resources. Old draws are submitted before storage changes. GL names may change, so reacquire them before use.
228
-
229
- ## Shader, Transform and GLSL
230
-
231
- Shader uses asynchronous `loadFromFile/Memory/Stream()`, supporting a single stage or vertex/fragment/geometry combinations. A successful reload replaces the program and clears uniform state; failure preserves the old program.
232
-
233
- `setUniform()` accepts number, boolean, Glsl vectors/matrices, Texture and `Shader.CurrentTexture`. number defaults to float; use the third argument `'int'` for integers. Existing draws are submitted before uniforms change.
234
-
235
- `Glsl.Vec2/3/4`, `Ivec2/3/4` and `Bvec2/3/4` correspond to GLSL vectors. Mat3/Mat4 are constructed from arrays, same-size matrices or Transform; `.array` is a column-major Float32Array. Four-dimensional vectors and matrices do not provide the general vector arithmetic operators.
236
-
237
- Transform supports translation, rotation, scaling and combine, modifying and returning itself. Composition uses right multiplication: `translate(...).scale(...)` scales a point first, then translates it. getMatrix returns a read-only live array; inverting a singular matrix returns an independent identity transform.
238
-
239
- Query capabilities through `Shader.isAvailable()`, `isGeometryAvailable()` and `VertexBuffer.isAvailable()`. Explicitly submit existing SFML commands before directly using Texture/Shader/VertexBuffer bind.
240
-
241
- ## Examples and performance verification
242
-
243
- The [examples directory](../examples/README.md) provides separate entry points for textures, sprites, text, vertices, composite drawing and off-screen composition.
244
-
245
- After building, run `tools/benchmark-image.cjs`, `tools/benchmark-drawable.cjs` and `tools/benchmark-vertex-array.cjs` to measure the current implementation. Calling-thread time in these benchmarks includes recording, submission and driver work; it cannot be treated directly as GPU time or actual game frame rate.
246
-
247
- <a id="sfml-cpp-reference"></a>
248
-
249
- ## SFML C++ reference
250
-
251
- - Images and drawables: [Image](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Image.html), [Texture](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Texture.html), [Sprite](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Sprite.html), [Shape](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Shape.html) and [Drawable](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Drawable.html).
252
- - Text and cameras: [Font](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Font.html), [Text](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Text.html) and [View](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1View.html).
253
- - Rendering and geometry: [RenderTexture](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1RenderTexture.html), [RenderTarget](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1RenderTarget.html), [Shader](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Shader.html), [VertexArray](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1VertexArray.html) and [VertexBuffer](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1VertexBuffer.html).
254
-
255
- Use these original C++ references for rendering concepts. Resource construction, asynchronous loading and draw snapshots follow this JavaScript guide and the [core concepts](concepts.md#draw-snapshots), not C++ constructor or immediate-drawing assumptions.