GPU 컴퓨트
BASIC에서 WGSL 컴퓨트 셰이더를 실행하는 법을 다룹니다. 스토리지 버퍼, 파이프라인, 프레임 순서에 따른 디스패치, 메모리블록으로 읽어 오기, GPU 컴퓨트가 없는 타깃을 위한 CPU 대체 경로를 설명합니다.
한 줄 요약#
BASIC은 WebGPU 컴퓨트 셰이더를 실행할 수 있습니다. GPU의 버퍼에 숫자를 넣고, 작은 WGSL 프로그램을 그 모든 숫자에 한꺼번에 실행하고, 결과를 메모리블록으로 읽어 옵니다. Compute 카테고리의 14개 명령어가 이 일을 전부 합니다.
⚠️ 엔진 전용입니다. GPU 컴퓨트는 WebGPU 컴퓨트를 지원하는 GPU와 브라우저에서, 에디터의 Play를 눌렀을 때 동작합니다. HTML 내보내기와 Bevy 빌드에는 없습니다. 의존하기 전에 CPU 대체 경로를 먼저 작성하세요.
사용할 수 있는 경우#
먼저
ComputeSupported()를 호출하세요. 모든 타깃에서 답하며, 다른 모든 Compute 명령어는 이것이 1을 반환했다고 가정합니다.
| 프로그램이 실행되는 곳 | ComputeSupported() | 다른 Compute 명령어 |
|---|---|---|
| 엔진, 컴퓨트가 있는 WebGPU | 1 | 동작함 |
| 엔진, 컴퓨트가 없는 GPU 또는 브라우저 | 0 | 버퍼나 셰이더를 만들거나 디스패치하면 WebGPU compute is unavailable on this runtime target or GPU로 멈춤 |
| HTML 내보내기 | 0 | … is recognized but has no HTML export implementation (Compute)로 멈춤 |
| Bevy, 네이티브 또는 wasm | 0 | 내보내기의 변환 보고서가 빌드 전에 프로그램이 호출하는 Compute 명령어를 나열함. 그래도 실행되는 호출은 기능 오류로 멈춤 |
조용한 에뮬레이션은 없습니다. Compute 명령어는 GPU에서 실행되거나, 타깃 이름을 알려 주는 오류로 멈춥니다. 패턴은 항상 같습니다. ComputeSupported()를 검사하고, 0이면 CPU 경로를 택하세요(아래의 대체 경로 패턴 참고).
구성 요소#
| 단계 | 명령어 | 얻는 것 |
|---|---|---|
| 1. 데이터를 메모리블록에 넣기 | CreateMemblock, MemblockFloat, MemblockInt | CPU의 바이트 |
| 2. 스토리지 버퍼 만들기 | CreateComputeBuffer | 버퍼 id |
| 3. 업로드 | ComputeBufferFromMemblock | GPU의 바이트 |
| 4. 커널 컴파일 | CreateComputeShader | 셰이더 id |
| 5. 버퍼 바인딩 | ComputeShaderBuffer | |
| 6. 실행 | ComputeDispatchAsync | 잡 id |
| 7. 읽어 오기 | ComputeBufferReadAsync | 잡 id. 그 숫자가 메모리블록 id |
6단계와 7단계는 잡을 반환하며, 다른 비동기 명령어와 같은 잡입니다. PlatformJobDone, PlatformJobError, PlatformJobResultNumber로 폴링하세요.
스토리지 버퍼#
buffer = CreateComputeBuffer(<elementCount>, <type$>)
CreateComputeBuffer(<bufferId>, <elementCount>, <type$>)
ComputeBufferFromMemblock(<buffer>, <memblock>)
- 요소 타입은 세 가지:
"f32","i32","u32". 셋 모두 4바이트입니다. 요소가n개인 버퍼는n * 4바이트입니다. - 메모리블록은 버퍼의 크기와 정확히 같아야 합니다. 16바이트 버퍼에는 16바이트 메모리블록이 들어갑니다. 더도 덜도 안 됩니다. 다르면 프로그램이 멈춥니다.
- 바이트는 있는 그대로 복사됩니다.
f32값은MemblockFloat로,i32와u32값은MemblockInt로0, 4, 8…오프셋에 쓰세요. - 버퍼 하나는 최대 128 MiB를 담습니다. 모바일 GPU의 공통 최솟값입니다.
- 두 번째 형태는 직접 고른 id를 받으며, 사용 중이 아니어야 합니다.
| 명령어 | 결과 |
|---|---|
ComputeBufferSize(b) | 바이트 단위 크기 |
ComputeBufferElementCount(b) | 요소의 수 |
ComputeBufferType(b) | "f32", "i32", "u32" |
ComputeBufferExists(b) | 1 또는 0 |
DeleteComputeBuffer(b) | 해제 |
WGSL 파이프라인#
shader = CreateComputeShader(<wgsl$>, <bindingsJson$> [, <entryPoint$>])
CreateComputeShader(<shaderId>, <wgsl$>, <bindingsJson$> [, <entryPoint$>])
ComputeShaderBuffer(<shader>, <name$>, <buffer>)
-
커널은 날것의 WGSL입니다. GLSL이 아니며 변환되지 않습니다.
@compute진입점이 있어야 하며, 다른 이름을 주지 않으면 이름은main입니다. -
바인딩 JSON은 각 WGSL 변수를 슬롯에 대응시킵니다. WGSL에 선언된 그대로입니다.
{"data": {"group": 0, "binding": 0}}스토리지 변수마다 항목 하나, 최소 하나, 같은 슬롯을 두 번 쓰면 안 됩니다.
-
ComputeShaderBuffer는 WGSL 이름으로 버퍼를 변수에 바인딩합니다. -
스토리지 버퍼만 바인딩할 수 있습니다. 유니폼도 텍스처도 없습니다. 시간 간격 같은 파라미터를 넘기려면 그것만을 위한 작은 스토리지 버퍼에 넣으세요.
-
CreateComputeShader는 개요만 검사합니다. 소스에@compute가 있는지, JSON이 유효한지, 슬롯이 서로 다른지입니다. WGSL 자체는 백그라운드에서 컴파일되며, WGSL 오류는 디스패치 잡에서PlatformJobError로 돌아옵니다.
BASIC 문자열에서는 JSON의 따옴표를 \"로 쓰세요.
bindings$ = "{\"data\":{\"group\":0,\"binding\":0}}"
Console(bindings$) ' {"data":{"group":0,"binding":0}}
| 명령어 | 결과 |
|---|---|
ComputeShaderExists(s) | 1 또는 0 |
DeleteComputeShader(s) | 해제 |
디스패치와 프레임에서의 위치#
job = ComputeDispatchAsync(<shader>, <groupsX> [, <groupsY> [, <groupsZ>]])
인자는 요소 수가 아니라 워크그룹 수입니다. @workgroup_size(64)에 요소가 n개이면 (n + 63) DIV 64개의 그룹을 요청하고, 커널이 끝을 넘는 인덱스를 건너뛰게 하세요.
디스패치는 호출할 때 실행되지 않습니다. 큐에 쌓이고, 큐는 다음 프레임이 그려지기 직전에 GPU로 보내집니다.
- 큐는 순서를 유지합니다. 연달아 요청한 두 디스패치는, 두 번째 커널의 파이프라인이 먼저 준비되더라도 그 순서로 실행됩니다. 두 번째 커널은 첫 번째가 쓴 것을 읽을 수 있습니다.
- 작업이 보내지면 잡이 끝납니다.
PlatformJobDone으로 기다린 다음PlatformJobError를 확인하세요(성공이면 비어 있음). - 10초가 지나도 준비되지 않은 파이프라인은 잡을 실패시킵니다.
- 기다리려면 기다릴 수 있는 프로그램이어야 합니다. 흔한 루프는
WHILE PlatformJobDone(job) = 0 … Sync() … ENDWHILE입니다. 그Sync()는 실제로 양보해야 합니다. 프로그램에DO … LOOP나END가 있거나, 루프가 레이블 안에 있어야 합니다. 그렇지 않으면 탭이 멈춥니다. 게임 루프를 참고하세요.
메모리블록으로 읽어 오기#
job = ComputeBufferReadAsync(<buffer>)
job = ComputeBufferReadAsync(<buffer>, <newMemblockId>)
memblock = PlatformJobResultNumber(job)
- 읽기는 버퍼의 바이트로 새 메모리블록을 만듭니다. 잡의 숫자가 그 id입니다.
- 두 번째 형태는 그 id를 직접 고르며, id는 비어 있어야 합니다. 이미 있는 메모리블록으로 읽으면 프로그램이 멈춥니다. 먼저 삭제하세요.
- ⚠️ 읽기는 디스패치 뒤에 대기열로 쌓이지 않습니다. 디스패치 잡이 끝난 뒤에 시작하세요. 그렇지 않으면 커널이 실행되기 전의 데이터를 읽게 됩니다.
- 메모리블록은 최대 100 000 000바이트를 담습니다. 따라서 읽어 오는 버퍼는 25 000 000개 요소 미만이어야 하며, 이는 버퍼가 담을 수 있는 128 MiB보다 작습니다.
- 더 이상 필요 없는 메모리블록을 삭제하고, 끝난 잡은
PlatformJobRelease로 해제하세요.
전체 예제#
버퍼 하나에 커널 둘을 씁니다. 첫 번째는 각 값을 두 배로 만들고, 두 번째는 1을 더합니다. 둘 다 한꺼번에 큐에 쌓이며, 큐의 순서가 결과를 보장합니다.
' 1, 2, 3, 4가 GPU에서 3, 5, 7, 9가 됩니다.
IF ComputeSupported() = 0
Console("No WebGPU compute on this target")
END
ENDIF
' 데이터: f32 값 네 개, 각각 4바이트.
input = CreateMemblock(16)
FOR i = 0 TO 3
MemblockFloat(input, i * 4, i + 1)
NEXT
' 같은 바이트 크기의 스토리지 버퍼를 만들고 메모리블록으로 채움.
buffer = CreateComputeBuffer(4, "f32")
ComputeBufferFromMemblock(buffer, input)
' 첫 줄들을 공유하는 두 커널. 요소마다 호출 하나.
head$ = "@group(0) @binding(0) var<storage, read_write> data: array<f32>; "
head$ = head$ + "@compute @workgroup_size(64) "
head$ = head$ + "fn main(@builtin(global_invocation_id) id: vec3<u32>) { "
head$ = head$ + "if (id.x >= arrayLength(&data)) { return; } "
bindings$ = "{\"data\":{\"group\":0,\"binding\":0}}"
doubler = CreateComputeShader(head$ + "data[id.x] = data[id.x] * 2.0; }", bindings$)
adder = CreateComputeShader(head$ + "data[id.x] = data[id.x] + 1.0; }", bindings$)
ComputeShaderBuffer(doubler, "data", buffer)
ComputeShaderBuffer(adder, "data", buffer)
' 둘 다 큐에 쌓음. 다음 프레임이 그려지기 전에 이 순서로 실행됨.
groups = (4 + 63) DIV 64
job1 = ComputeDispatchAsync(doubler, groups)
job2 = ComputeDispatchAsync(adder, groups)
WHILE PlatformJobDone(job2) = 0
Sync()
ENDWHILE
IF PlatformJobError(job1) <> "" OR PlatformJobError(job2) <> ""
Console("dispatch failed: " + PlatformJobError(job1) + PlatformJobError(job2))
END
ENDIF
' 읽어 옴. 잡의 숫자가 새 메모리블록의 id.
readJob = ComputeBufferReadAsync(buffer)
WHILE PlatformJobDone(readJob) = 0
Sync()
ENDWHILE
result = PlatformJobResultNumber(readJob)
FOR i = 0 TO 3
Console(Str(MemblockFloat(result, i * 4))) ' 3, 그다음 5, 7, 9
NEXT
' 모두 해제.
DeleteMemblock(result)
DeleteMemblock(input)
DeleteComputeShader(doubler)
DeleteComputeShader(adder)
DeleteComputeBuffer(buffer)
END
동작하게 만드는 요소:
END줄들.WHILE루프 안에서Sync()가 양보하게 해 줍니다. 없으면 프로그램에DO루프도END도 없어서 루프가 탭을 멈추게 합니다.job2만 기다리면 충분합니다. 큐는 순서대로 실행되므로, 두 번째 디스패치가 보내졌다면 첫 번째도 보내진 것입니다.- 읽기는 디스패치가 끝난 뒤에 시작합니다.
arrayLength(&data)가 끝을 지킵니다. 64개 워크그룹은 64개의 호출을 실행하지만, 요소가 있는 것은 처음 4개뿐입니다.
대체 경로 패턴#
두 경로 모두 데이터를 메모리블록에 두세요. GPU 경로는 그것을 업로드하고 다시 읽어 오며, CPU 경로는 그 자리에서 작업합니다. 분기 뒤의 모든 코드는 같습니다.
' 값 1024개를 두 배로: 가능하면 GPU에서, 아니면 CPU에서.
count = 1024
data = CreateMemblock(count * 4)
FOR i = 0 TO count - 1
MemblockFloat(data, i * 4, i)
NEXT
IF ComputeSupported()
GOSUB DoubleOnGpu
ELSE
DoubleOnCpu(data, count)
ENDIF
Console(Str(MemblockFloat(data, 10 * 4))) ' 20, 어느 경로에서든
END
FUNCTION DoubleOnCpu(mem, n)
FOR k = 0 TO n - 1
MemblockFloat(mem, k * 4, MemblockFloat(mem, k * 4) * 2)
NEXT
ENDFUNCTION
DoubleOnGpu:
buf = CreateComputeBuffer(count, "f32")
ComputeBufferFromMemblock(buf, data)
wgsl$ = "@group(0) @binding(0) var<storage, read_write> data: array<f32>; "
wgsl$ = wgsl$ + "@compute @workgroup_size(64) "
wgsl$ = wgsl$ + "fn main(@builtin(global_invocation_id) id: vec3<u32>) { "
wgsl$ = wgsl$ + "if (id.x >= arrayLength(&data)) { return; } "
wgsl$ = wgsl$ + "data[id.x] = data[id.x] * 2.0; }"
kernel = CreateComputeShader(wgsl$, "{\"data\":{\"group\":0,\"binding\":0}}")
ComputeShaderBuffer(kernel, "data", buf)
job = ComputeDispatchAsync(kernel, (count + 63) DIV 64)
WHILE PlatformJobDone(job) = 0
Sync()
ENDWHILE
' 같은 id로 읽어 옴: 먼저 해제하고, 읽기가 다시 만들게 함.
DeleteMemblock(data)
readJob = ComputeBufferReadAsync(buf, data)
WHILE PlatformJobDone(readJob) = 0
Sync()
ENDWHILE
DeleteComputeShader(kernel)
DeleteComputeBuffer(buf)
RETURN
- GPU 경로는
FUNCTION이 아니라 레이블입니다.FUNCTION은 기다릴 수 없기 때문입니다. 기다리는 레이블로의GOSUB에는 프로그램에DO루프나END가 필요합니다. - CPU 경로는 일반
FUNCTION입니다. 기다리지 않습니다. - 실제 프로그램에서는 전체 예제처럼 기다린 뒤마다
PlatformJobError도 확인하세요.
GPU 코드를 내보내기에서 완전히 빼려면 #IF ENGINE과 #ENDIF 사이에 두세요. 에디터는 ENGINE을 정의하고, HTML과 Bevy 빌드는 정의하지 않습니다. 전처리기를 참고하세요.
수명#
- Stop은 모든 것을 파괴합니다. 프로그램이 멈추면 버퍼와 셰이더가 해제되고, 다음 실행에서 id는 다시 1부터 시작합니다.
- Stop 시점에 아직 큐에 있는 디스패치는
Compute session ended before queued work was dispatched로 실패합니다. - 실행 중에 필요 없어진 것을 삭제하세요. 프로그램이 실행되는 동안 GPU 메모리는 자동으로 수거되지 않습니다.
클래식 방언과의 차이#
AGK, DarkBASIC, PureBasic에는 GPU 컴퓨트가 없습니다. 이것은 WebGPU 위에 만든 aukimi의 추가 기능입니다. 그쪽에서 오신 분께 두 가지 결과가 따릅니다.
- 커널은 WGSL입니다. WebGPU의 셰이딩 언어입니다. GLSL 컴퓨트 셰이더는 로드되지 않습니다.
- 모든 것이 비동기입니다. 디스패치와 읽어 오기는 프레임에 걸쳐 기다리는 잡이며, GPU가 끝날 때까지 막는 호출이 아닙니다.
Compute 명령어#
| 명령어 | 역할 |
|---|---|
ComputeSupported() | 이 타깃이 컴퓨트를 실행할 수 있으면 1, 아니면 0 |
CreateComputeBuffer | f32, i32, u32의 스토리지 버퍼를 만듦 |
DeleteComputeBuffer | 버퍼를 해제 |
ComputeBufferExists | 버퍼가 있으면 1 |
ComputeBufferSize | 바이트 단위 크기 |
ComputeBufferElementCount | 요소의 수 |
ComputeBufferType | 요소 타입 |
ComputeBufferFromMemblock | 정확한 크기의 메모리블록을 업로드 |
ComputeBufferReadAsync | 버퍼를 새 메모리블록으로 읽어 옴, 잡으로 |
CreateComputeShader | WGSL 커널을 컴파일 |
DeleteComputeShader | 커널을 해제 |
ComputeShaderExists | 커널이 있으면 1 |
ComputeShaderBuffer | 버퍼를 WGSL 변수에 바인딩 |
ComputeDispatchAsync | 실행을 큐에 쌓음, 잡으로 |
제한과 흔한 걸림돌#
- 먼저
ComputeSupported()를 검사하고, CPU 경로를 작성하세요. - 업로드용 메모리블록의 크기는 버퍼와 정확히 같아야 합니다.
- 디스패치 수는 워크그룹 수입니다. WGSL에서 배열의 끝을 지키세요.
- 읽기를 시작하기 전에 디스패치 잡을 기다리세요.
- 읽어 올 id는 비어 있어야 합니다. 이전 메모리블록을 먼저 삭제하세요.
- 기다리는 루프의
Sync()는 양보해야 합니다.DO … LOOP,END, 또는 레이블이 필요합니다. - 스토리지 버퍼만 됩니다. 파라미터는 그것만을 위한 작은 버퍼에 넣으세요.