You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/kcl/modules.md
+95
Original file line number
Diff line number
Diff line change
@@ -109,3 +109,98 @@ Coordinate systems:
109
109
-`zoo` (the default), forward: -Y, up: +Z, handedness: right
110
110
-`opengl`, forward: +Z, up: +Y, handedness: right
111
111
-`vulkan`, forward: +Z, up: -Y, handedness: left
112
+
113
+
### Performance
114
+
115
+
Parallelized foreign-file imports now let you overlap file reads, initialization,
116
+
and rendering. To maximize throughput, you need to understand the three distinct
117
+
stages—reading, initializing (background render start), and invocation (blocking)
118
+
—and structure your code to defer blocking operations until the end.
119
+
120
+
#### Foreign Import Execution Stages
121
+
122
+
1.**Import (Read) Stage**
123
+
```norun
124
+
import "tests/inputs/cube.step" as cube
125
+
```
126
+
- Reads the file from disk and makes its API available.
127
+
-**Does _not_** start Engine rendering or block your script.
128
+
129
+
2.**Initialization (Background Render) Stage**
130
+
```norun
131
+
import "tests/inputs/cube.step" as cube
132
+
133
+
myCube = cube // <- This line starts background rendering
134
+
```
135
+
- Invoking the imported symbol (assignment or plain call) triggers Engine rendering _in the background_.
136
+
- This kick‑starts the render pipeline but doesn’t block—you can continue other work while the Engine processes the model.
137
+
138
+
3.**Invocation (Blocking) Stage**
139
+
```norun
140
+
import "tests/inputs/cube.step" as cube
141
+
142
+
myCube = cube
143
+
144
+
myCube
145
+
|> translate(z=10) // <- This line blocks
146
+
```
147
+
- Any method call (e.g., `translate`, `scale`, `rotate`) waits for the background render to finish before applying transformations.
148
+
- This is the only point where your script will block.
149
+
150
+
> **Nuance:** Foreign imports differ from pure KCL modules—calling the same import symbol multiple times (e.g., `screw` twice) starts background rendering twice.
151
+
152
+
#### Best Practices
153
+
154
+
##### 1. Defer Blocking Calls
155
+
Initialize early but delay all transformations until after your heavy computation:
156
+
```norun
157
+
import "tests/inputs/cube.step" as cube // 1) Read
158
+
159
+
myCube = cube // 2) Background render starts
160
+
161
+
162
+
// --- perform other operations and calculations or setup here ---
163
+
164
+
165
+
myCube
166
+
|> translate(z=10) // 3) Blocks only here
167
+
```
168
+
169
+
##### 2. Encapsulate Imports in Modules
170
+
Keep `main.kcl` free of reads and initialization; wrap them:
171
+
172
+
```norun
173
+
// imports.kcl
174
+
import "tests/inputs/cube.step" as cube // Read only
175
+
176
+
177
+
export myCube = cube // Kick off rendering
178
+
```
179
+
180
+
```norun
181
+
// main.kcl
182
+
import myCube from "imports.kcl" // Import the initialized object
Both calling methods right on `cube` immediately or leaving an implicit import without assignment introduce blocking.
202
+
203
+
#### Future Improvements
204
+
205
+
Upcoming releases will auto‑analyze dependencies and only block when truly necessary. Until then, explicit deferral and modular wrapping give you the best performance.
"// Change the appearance of an imported model.\n\n\nimport \"tests/inputs/cube.sldprt\" as cube\n\ncube\n// |> appearance(\n// color = \"#ff0000\",\n// metalness = 50,\n// roughness = 50\n// )"
0 commit comments