GPU 컴퓨트

BASIC에서 WGSL 컴퓨트 셰이더를 실행하는 법을 다룹니다. 스토리지 버퍼, 파이프라인, 프레임 순서에 따른 디스패치, 메모리블록으로 읽어 오기, GPU 컴퓨트가 없는 타깃을 위한 CPU 대체 경로를 설명합니다.

한 줄 요약#

BASIC은 WebGPU 컴퓨트 셰이더를 실행할 수 있습니다. GPU의 버퍼에 숫자를 넣고, 작은 WGSL 프로그램을 그 모든 숫자에 한꺼번에 실행하고, 결과를 메모리블록으로 읽어 옵니다. Compute 카테고리의 14개 명령어가 이 일을 전부 합니다.

⚠️ 엔진 전용입니다. GPU 컴퓨트는 WebGPU 컴퓨트를 지원하는 GPU와 브라우저에서, 에디터의 Play를 눌렀을 때 동작합니다. HTML 내보내기와 Bevy 빌드에는 없습니다. 의존하기 전에 CPU 대체 경로를 먼저 작성하세요.

사용할 수 있는 경우#

먼저 ComputeSupported()를 호출하세요. 모든 타깃에서 답하며, 다른 모든 Compute 명령어는 이것이 1을 반환했다고 가정합니다.

프로그램이 실행되는 곳ComputeSupported()다른 Compute 명령어
엔진, 컴퓨트가 있는 WebGPU1동작함
엔진, 컴퓨트가 없는 GPU 또는 브라우저0버퍼나 셰이더를 만들거나 디스패치하면 WebGPU compute is unavailable on this runtime target or GPU로 멈춤
HTML 내보내기0… is recognized but has no HTML export implementation (Compute)로 멈춤
Bevy, 네이티브 또는 wasm0내보내기의 변환 보고서가 빌드 전에 프로그램이 호출하는 Compute 명령어를 나열함. 그래도 실행되는 호출은 기능 오류로 멈춤

조용한 에뮬레이션은 없습니다. Compute 명령어는 GPU에서 실행되거나, 타깃 이름을 알려 주는 오류로 멈춥니다. 패턴은 항상 같습니다. ComputeSupported()를 검사하고, 0이면 CPU 경로를 택하세요(아래의 대체 경로 패턴 참고).

구성 요소#

단계명령어얻는 것
1. 데이터를 메모리블록에 넣기CreateMemblock, MemblockFloat, MemblockIntCPU의 바이트
2. 스토리지 버퍼 만들기CreateComputeBuffer버퍼 id
3. 업로드ComputeBufferFromMemblockGPU의 바이트
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
CreateComputeBufferf32, i32, u32의 스토리지 버퍼를 만듦
DeleteComputeBuffer버퍼를 해제
ComputeBufferExists버퍼가 있으면 1
ComputeBufferSize바이트 단위 크기
ComputeBufferElementCount요소의 수
ComputeBufferType요소 타입
ComputeBufferFromMemblock정확한 크기의 메모리블록을 업로드
ComputeBufferReadAsync버퍼를 새 메모리블록으로 읽어 옴, 잡으로
CreateComputeShaderWGSL 커널을 컴파일
DeleteComputeShader커널을 해제
ComputeShaderExists커널이 있으면 1
ComputeShaderBuffer버퍼를 WGSL 변수에 바인딩
ComputeDispatchAsync실행을 큐에 쌓음, 잡으로

제한과 흔한 걸림돌#

  • 먼저 ComputeSupported()를 검사하고, CPU 경로를 작성하세요.
  • 업로드용 메모리블록의 크기는 버퍼와 정확히 같아야 합니다.
  • 디스패치 수는 워크그룹 수입니다. WGSL에서 배열의 끝을 지키세요.
  • 읽기를 시작하기 전에 디스패치 잡을 기다리세요.
  • 읽어 올 id는 비어 있어야 합니다. 이전 메모리블록을 먼저 삭제하세요.
  • 기다리는 루프의 Sync()는 양보해야 합니다. DO … LOOP, END, 또는 레이블이 필요합니다.
  • 스토리지 버퍼만 됩니다. 파라미터는 그것만을 위한 작은 버퍼에 넣으세요.