[UE5/Plugin] TurboSequence 심층 분석

Github

LukasFratzl/TurboSequence: Skeletal Based GPU Crowds for UE5 🚀

개요

TurboSequence는 Niagara Mesh Particles를 사용하되, Skeletal Mesh가 아닌 Static Mesh를 렌더링합니다. 핵심 트릭은 애니메이션 데이터를 텍스처에 베이크하고, GPU Compute Shader + Vertex Shader에서 실시간 스키닝을 수행하는 것입니다.

왜 Niagara SkeletalMesh Instance가 아닌가?

Niagara의 SkeletalMesh 렌더러는 내부적으로 각 인스턴스마다 개별 draw call을 발생시킵니다. TurboSequence는 이를 우회하여:

• Static Mesh를 Niagara Mesh Particles로 렌더링 (단일 instanced draw call)
• 애니메이션을 GPU에서 계산하여 CPU 오버헤드 제거

---

파이프라인 전체 구조

1단계: 오프라인 변환 (Content Pipeline)

// TurboSequence_ControlPanelLibrary_Lf.cpp - ConvertSkeletalMeshToTurboSequence_BlueprintThreadSafe

1.1 Static Mesh 생성

// 원본 Skeletal Mesh의 각 LOD를 Static Mesh로 변환
for (int32 i = 0; i < SkeletalMesh->GetLODNum(); ++i)
{
    UStaticMesh* StaticMesh = NewObject<UStaticMesh>();
    // Skeletal Mesh의 정점 데이터를 Static Mesh로 복사
    // 본 웨이트는 제거되고 Bind Pose 정점만 저장
}

1.2 애니메이션 라이브러리 텍스처 생성

// TurboSequence_Helper_Lf.cpp - CreateAnimationLibraryTexture2D

핵심은 모든 애니메이션 프레임의 본 Transform을 텍스처에 베이크:

텍스처 구조:
- Width: NumBones * 3 (각 본당 3픽셀 = Rotation Quat + Translation + Scale)
- Height: TotalAnimationFrames (모든 애니메이션의 모든 프레임)
- Format: RGBA16F (고정밀도)

예시:
- 본 50개, 애니메이션 10개 (각 100프레임) = 150x1000 텍스처
- Pixel[0-2, FrameY] = Bone0의 Rotation(RGBA), Translation(RGB), Scale(RGB)
- Pixel[3-5, FrameY] = Bone1의 데이터...

텍스처 픽셀 인코딩:

// 각 본의 Transform을 3개 픽셀에 저장
FLinearColor RotationPixel = FLinearColor(Quat.X, Quat.Y, Quat.Z, Quat.W);
FLinearColor TranslationPixel = FLinearColor(Pos.X, Pos.Y, Pos.Z, 0);
FLinearColor ScalePixel = FLinearColor(Scale.X, Scale.Y, Scale.Z, 0);

1.3 본 웨이트 텍스처 생성

// 각 정점의 본 인덱스와 웨이트를 텍스처에 저장
// Width: NumVertices
// Height: 1
// RGBA: (BoneIndex0, Weight0, BoneIndex1, Weight1)

---

2단계: 런타임 CPU (Game Thread)

// TurboSequence_Manager_Lf.cpp

2.1 인스턴스 스폰

FTurboSequence_MinimalMeshData_Lf AddSkinnedMeshInstance_GameThread(...)
{
    // 1. MeshAsset에서 Static Mesh + 텍스처 참조 가져오기
    // 2. Niagara System에 인스턴스 추가 준비
    // 3. GPU에 전달할 메타데이터 구성
    FTurboSequence_MinimalMeshData_Lf Data;
    Data.AnimationStartFrame = 0;
    Data.AnimationEndFrame = 100;
    Data.CustomData = FVector4f(...); // Niagara User Parameter로 전달
    return Data;
}

2.2 애니메이션 업데이트 (Concurrent)

void UpdateMeshAnimation_Concurrent(...)
{
    // CPU에서는 메타데이터만 업데이트 (어떤 애니메이션, 어떤 프레임)
    Instance.AnimationStartFrame = NewAnimStartFrame;
    Instance.AnimationTime += DeltaTime;
    // 실제 본 계산은 GPU에서 수행
}

2.3 Solve (Game Thread)

void SolveMeshes_GameThread(float DeltaTime, ...)
{
    // 1. CPU에서 업데이트된 모든 인스턴스 데이터를 모음
    // 2. Niagara System에 인스턴스 데이터 전달
    // 3. GPU Compute Shader 디스패치 스케줄링
    
    for (UpdateGroup : UpdateGroups)
    {
        NiagaraComponent->SetCustomData(InstanceData); // GPU로 전송
        DispatchComputeShaders(UpdateGroup);
    }
}

---

3단계: 런타임 GPU - Compute Shader

// Shaders/Private/BoneSettings_CS_Lf.usf

3.1 본 데이터 준비 Compute Shader

[numthreads(64, 1, 1)]
void BoneSettings_CS_Lf(uint3 ThreadId : SV_DispatchThreadID)
{
    uint InstanceID = ThreadId.x;
    
    // 1. 인스턴스 메타데이터 로드 (Niagara User Parameters)
    float AnimTime = InstanceAnimTimes[InstanceID];
    int StartFrame = InstanceStartFrames[InstanceID];
    int EndFrame = InstanceEndFrames[InstanceID];
    
    // 2. 현재 프레임 계산
    float FrameFloat = StartFrame + (AnimTime * FPS);
    int Frame0 = floor(FrameFloat);
    int Frame1 = ceil(FrameFloat);
    float BlendAlpha = frac(FrameFloat);
    
    // 3. 애니메이션 라이브러리 텍스처에서 본 Transform 샘플링
    for (int BoneIdx = 0; BoneIdx < NumBones; BoneIdx++)
    {
        // 텍스처 UV 계산
        float U0 = (BoneIdx * 3.0f) / TextureWidth;
        float V0 = Frame0 / TextureHeight;
        float V1 = Frame1 / TextureHeight;
        
        // 본 Transform 로드 (3픽셀 = Rotation, Translation, Scale)
        float4 Rot0 = AnimLibraryTexture.SampleLevel(Sampler, float2(U0, V0), 0);
        float4 Trans0 = AnimLibraryTexture.SampleLevel(Sampler, float2(U0 + 1.0/Width, V0), 0);
        float4 Scale0 = AnimLibraryTexture.SampleLevel(Sampler, float2(U0 + 2.0/Width, V0), 0);
        
        float4 Rot1 = AnimLibraryTexture.SampleLevel(Sampler, float2(U0, V1), 0);
        float4 Trans1 = AnimLibraryTexture.SampleLevel(Sampler, float2(U0 + 1.0/Width, V1), 0);
        float4 Scale1 = AnimLibraryTexture.SampleLevel(Sampler, float2(U0 + 2.0/Width, V1), 0);
        
        // 4. 프레임 보간
        float4 FinalRot = QuatSlerp(Rot0, Rot1, BlendAlpha);
        float3 FinalTrans = lerp(Trans0.xyz, Trans1.xyz, BlendAlpha);
        float3 FinalScale = lerp(Scale0.xyz, Scale1.xyz, BlendAlpha);
        
        // 5. 결과를 Per-Instance 본 버퍼에 저장 (다음 단계에서 사용)
        OutBoneTransforms[InstanceID * NumBones + BoneIdx] = 
            ComposeTransform(FinalRot, FinalTrans, FinalScale);
    }
}

3.2 메시 단위 Compute Shader

// Shaders/Private/MeshUnit_CS_Lf.usf
[numthreads(64, 1, 1)]
void MeshUnit_CS_Lf(uint3 ThreadId : SV_DispatchThreadID)
{
    uint InstanceID = ThreadId.x;
    
    // 추가 메시별 로직 (LOD 선택, 가시성 등)
    // 실제 정점 스키닝은 Vertex Shader에서 수행
}

---

4단계: 런타임 GPU - Vertex Shader (Material)

// Shaders/Private/GPU_VertexSkinning_VS_Lf.ush
// Material Function: MF_TurboSequence_PositionOffset_Lf에서 호출

정점 스키닝 수행

float3 TurboSequence_VertexSkinning(
    float3 LocalPosition,
    uint VertexID,
    uint InstanceID)
{
    // 1. 본 웨이트 텍스처에서 해당 정점의 영향받는 본 정보 로드
    float4 BoneWeightData = BoneWeightTexture.Load(int3(VertexID, 0, 0));
    int BoneIndex0 = int(BoneWeightData.x);
    float Weight0 = BoneWeightData.y;
    int BoneIndex1 = int(BoneWeightData.z);
    float Weight1 = BoneWeightData.w;
    
    // 2. Compute Shader에서 계산한 본 Transform 로드
    float4x4 BoneMatrix0 = BoneTransforms[InstanceID * NumBones + BoneIndex0];
    float4x4 BoneMatrix1 = BoneTransforms[InstanceID * NumBones + BoneIndex1];
    
    // 3. 정점에 본 Transform 적용 (스키닝)
    float3 SkinnedPos0 = mul(float4(LocalPosition, 1.0), BoneMatrix0).xyz;
    float3 SkinnedPos1 = mul(float4(LocalPosition, 1.0), BoneMatrix1).xyz;
    
    // 4. 웨이트 블렌딩
    float3 FinalPosition = SkinnedPos0 * Weight0 + SkinnedPos1 * Weight1;
    
    // 5. World Position Offset으로 출력
    return FinalPosition - LocalPosition; // Offset 반환
}

Material Graph 연결

Material:
  World Position Offset Pin <- MF_TurboSequence_PositionOffset_Lf 출력
  ├─ VertexID (Vertex Interpolator)
  ├─ InstanceID (Niagara Mesh Particles 자동 제공)
  └─ Bone Transform Buffer (Compute Shader 출력)

---

5단계: Niagara Instanced Rendering

// Niagara System이 최종 렌더링 수행
NiagaraRenderer->DrawInstances(
    StaticMesh,                    // 변환된 Static Mesh
    Material,                      // 커스텀 스키닝 Material
    InstanceCount,                 // 10k-50k 인스턴스
    PerInstanceData                // Compute Shader 결과
);

핵심: Niagara는 하나의 DrawIndexedInstanced 호출로 모든 인스턴스를 렌더링. GPU는 각 인스턴스마다 Vertex Shader를 실행하며, 그 안에서 본 스키닝이 발생.

---

GPU 메모리 레이아웃

GPU Memory:
├─ Animation Library Texture (VRAM)
│  └─ 150x1000x8bytes = ~1.2MB (본 50개, 프레임 1000개 기준)
├─ Bone Weight Texture (VRAM)
│  └─ NumVertices x 16bytes (정점당 4개 float)
├─ Bone Transform Buffer (Compute Shader 출력)
│  └─ NumInstances x NumBones x 64bytes (4x4 행렬)
│     예: 10k instances x 50 bones = ~30MB
└─ Static Mesh Vertex/Index Buffers (VRAM)
   └─ 표준 Static Mesh 데이터

---

성능 최적화 원리

왜 빠른가?

1. Draw Call 극소화
   • 기존: 10k 인스턴스 = 10k draw calls
   • TurboSequence: 10k 인스턴스 = 1 draw call (아키타입당)
2. CPU 부하 이동
   • 기존: CPU에서 본 행렬 계산 → GPU로 전송
   • TurboSequence: CPU는 메타데이터만 업데이트, GPU가 모든 계산 수행
3. 메모리 대역폭 최적화
   • 애니메이션 데이터를 텍스처 압축으로 전송
   • 본당 3픽셀(48바이트) vs 기존 본 행렬(64바이트)

트레이드오프

장점:

• 수만 개 인스턴스를 단일 draw call로 렌더링
• CPU 오버헤드 거의 없음
• 애니메이션 블렌딩도 GPU에서 가능

단점:

• Static Mesh 변환 필요 (오프라인 작업)
• 텍스처 메모리 사용 (애니메이션마다 텍스처 생성)
• 복잡한 애니메이션 블렌딩 제한 (CPU 로직 필요 시 병목)
• 본 개수 제한 (30-75개 권장, 텍스처 크기 이슈)

---

코드 흐름 요약

1. [Editor] Skeletal Mesh → Static Mesh + Animation Textures
2. [CPU GameThread] Spawn Instances → Update Animation Meta
3. [CPU GameThread] SolveMeshes → Dispatch Compute Shaders
4. [GPU Compute] BoneSettings_CS → Calculate Bone Transforms per Instance
5. [GPU Compute] MeshUnit_CS → LOD/Visibility processing
6. [GPU Vertex] Material Vertex Shader → Skinning per Vertex
7. [GPU Raster] Niagara Instanced Draw Call → Final Render

---

실제 구현 확인 파일

• Compute Shader: Shaders/Private/BoneSettings_CS_Lf.usf, MeshUnit_CS_Lf.usf
• Vertex Shader: Shaders/Private/GPU_VertexSkinning_VS_Lf.ush
• Material Functions: MF_TurboSequence_PositionOffset_Lf.uasset
• Texture 생성: Source/TurboSequence_Lf/Private/TurboSequence_Helper_Lf.cpp::CreateAnimationLibraryTexture2D
• Compute Dispatch: Source/TurboSequence_Lf/Private/TurboSequence_Manager_Lf.cpp::SolveMeshes_GameThread

이 구조로 Niagara의 Static Mesh Instancing + GPU Compute Skinning을 결합하여 대규모 크라우드 렌더링을 달성합니다.