🔧 OPENRNDR 3D 아트워크 만들기

이 글은 OPENRNDR 0.5.0 기준 3D 아트워크를 다룹니다. 공식 가이드(3D graphics, Shade styles, Transformations, Render targets)와 ORX(orx-mesh-generators, orx-camera)를 근거로 작성했습니다.

OPENRNDR은 Blender나 Three.js처럼 완성된 3D 엔진·씬 그래프·GLTF 로더를 기본 제공하지 않습니다. 대신 다음 파이프라인을 프로그래밍으로 구성하여 제너레이티브 아트·절차적 3D 그래픽을 만들 수 있습니다.

Kotlin 수학 → Mesh / VertexBuffer → 3D transform → Camera → GLSL ShadeStyle → (RenderTarget) → 화면

기본 메시 생성 · 카메라 · VertexBuffer · 버텍스 변형 · ShadeStyle 조명/디스토션 · 깊이 버퍼 · 제너레이티브 3D 패턴을 다룹니다.

---

1. 공통 import

import org.openrndr.application
import org.openrndr.color.ColorRGBa
import org.openrndr.draw.*
import org.openrndr.math.Vector3
import org.openrndr.math.transforms.transform
import org.openrndr.extra.camera.Orbital
import org.openrndr.extra.camera.OrbitalCamera
import org.openrndr.extra.meshgenerators.boxMesh
import org.openrndr.extra.meshgenerators.sphereMesh
import kotlin.math.cos
import kotlin.math.sin

---

2. 3D 메시 생성

2.1 orx-mesh-generators 기본 primitive

orx-mesh-generators는 position·normal·texture coordinate가 포함된 VertexBuffer를 반환합니다. 대표 함수:

함수	설명
boxMesh(width, height, depth)	직육면체
sphereMesh(sides, segments, radius)	UV 구
cylinderMesh(sides, length, radius, ...)	원기둥
dodecahedronMesh(radius)	정십이면체
planeMesh(...)	평면
buildTriangleMesh { ... }	DSL로 여러 메시 조합

val cube = boxMesh(140.0, 70.0, 10.0)
val sphere = sphereMesh(32, 32, 0.6)

2.2 그리기: vertexBuffer

drawer.vertexBuffer(cube, DrawPrimitive.TRIANGLES)
drawer.vertexBuffer(sphere, DrawPrimitive.LINES)   // 와이어프레임

• DrawPrimitive.TRIANGLES, LINES, POINTS 등을 사용합니다.
• 같은 지오메트리를 여러 번 그릴 때는 인스턴싱(vertexBufferInstances)을 고려합니다.

2.3 직접 VertexBuffer 구성

수학으로 지오메트리를 만들 때 vertexFormat + vertexBuffer를 직접 사용합니다.

val geometry = vertexBuffer(vertexFormat {
    position(3)
    normal(3)
    // textureCoordinate(2)  // 필요 시
}, vertexCount)

geometry.put {
    // write(Vector3(...)) 등으로 채움
}

흐름은 수학적 geometry 생성 → VertexBuffer → GPU 렌더링입니다. 구체를 생성한 뒤 버텍스 위치를 함수로 변형하거나, ShadeStyle의 vertexTransform에서 변형하는 방식이 제너레이티브 3D와 잘 맞습니다.

2.4 buildTriangleMesh DSL (요약)

여러 프리미티브를 하나의 버퍼로 합칠 때:

val mesh = buildTriangleMesh {
    // rotate / translate 후
    box(2.0, 2.0, 2.0)
    // translate 후
    sphere(16, 16, 1.0)
}

(정확한 시그니처·헬퍼는 orx-mesh-generators 소스/데모를 참고하세요.)

---

3. 3D 카메라와 투영

3.1 perspective 투영 (저수준)

drawer.perspective(60.0, width * 1.0 / height, 0.01, 1000.0)
drawer.depthWrite = true
drawer.depthTestPass = DepthTestPass.LESS_OR_EQUAL

• FOV(도), 종횡비, near, far.
• 3D에서는 깊이 테스트/쓰기를 켜야 앞뒤 관계가 올바릅니다.

3.2 모델 변환

drawer.translate(0.0, 0.0, -150.0)
drawer.rotate(Vector3.UNIT_X, seconds * 15.0 + 30.0)
drawer.rotate(Vector3.UNIT_Y, seconds * 5.0 + 60.0)
drawer.vertexBuffer(cube, DrawPrimitive.TRIANGLES)

• translate / rotate / scale은 model 행렬에 적용됩니다.
• 변환은 아래에서 위로 읽히는 순서에 주의합니다. isolated { }로 범위를 제한하는 것이 안전합니다.

3.3 Orbital 카메라 (ORX)

마우스/키보드로 궤도를 도는 카메라가 필요할 때:

val cam = Orbital()
cam.eye = -Vector3.UNIT_Z * 150.0
extend(cam)

extend {
    drawer.fill = ColorRGBa.PINK
    // shadeStyle ...
    drawer.vertexBuffer(cube, DrawPrimitive.TRIANGLES)
}

또는 OrbitalCamera를 직접 쓰는 예 (공식 Shade styles 예제):

val camera = OrbitalCamera(Vector3.UNIT_Z, Vector3.ZERO)
extend(camera)
extend {
    camera.rotate(0.2, 0.0)
    // ...
}

• Orbital은 OrbitalCamera + 컨트롤을 묶은 편의 확장입니다.
• view/projection을 직접 관리하지 않아도 됩니다.

3.4 변환 파이프라인 요약

행렬	Drawer 연산 예
model	translate, rotate, scale
view	lookAt, 카메라 확장
projection	perspective, ortho

---

4. 깊이 버퍼와 RenderTarget

4.1 왜 depth가 필요한가

• 3D 객체의 앞뒤 가림을 올바르게 처리하려면 depth buffer가 필요합니다.
• Shape/ShapeContour를 RenderTarget에 그릴 때도 depth(스텐실)가 필요합니다.
• 화면 기본 타깃에도 3D를 그릴 때는 depthWrite / depthTestPass를 설정합니다.

4.2 오프스크린 3D

val rt = renderTarget(width, height) {
    colorBuffer()
    depthBuffer()   // 3D 필수
}

drawer.isolatedWithTarget(rt) {
    drawer.clear(ColorRGBa.BLACK)
    drawer.perspective(60.0, width * 1.0 / height, 0.01, 1000.0)
    drawer.depthWrite = true
    drawer.depthTestPass = DepthTestPass.LESS_OR_EQUAL
    // 메시 그리기
}
drawer.image(rt.colorBuffer(0))

• 렌더 타깃 크기가 창과 다르면 투영을 타깃에 맞춰야 합니다.

---

5. ShadeStyle로 조명과 버텍스 변형

5.1 개념

• ShadeStyle은 템플릿 셰이더에 GLSL 조각을 끼워 넣는 방식입니다.
• vertexTransform: 지오메트리 변형 (x_position, x_normal 등).
• fragmentTransform: 픽셀 색 (x_fill, x_stroke).
• 3D에서는 va_normal, v_worldPosition, v_worldNormal 등이 자주 쓰입니다.

5.2 간단한 디퓨즈 조명 (공식 3D 예제 기반)

fun main() = application {
    configure {
        multisample = WindowMultisample.SampleCount(4)
    }
    program {
        val cube = boxMesh(140.0, 70.0, 10.0)
        extend {
            drawer.perspective(60.0, width * 1.0 / height, 0.01, 1000.0)
            drawer.depthWrite = true
            drawer.depthTestPass = DepthTestPass.LESS_OR_EQUAL
            drawer.fill = ColorRGBa.PINK
            drawer.shadeStyle = shadeStyle {
                fragmentTransform = """
                    vec3 lightDir = normalize(vec3(0.3, 1.0, 0.5));
                    float l = dot(va_normal, lightDir) * 0.4 + 0.5;
                    x_fill.rgb *= l;
                """.trimIndent()
            }
            drawer.translate(0.0, 0.0, -150.0)
            drawer.rotate(Vector3.UNIT_X, seconds * 15 + 30)
            drawer.rotate(Vector3.UNIT_Y, seconds * 5 + 60)
            drawer.vertexBuffer(cube, DrawPrimitive.TRIANGLES)
        }
    }
}

5.3 버텍스 디스토션 (공식 Shade styles “3D mesh distortion”)

버텍스 위치를 시간에 따라 흔드는 예제입니다. 제너레이티브 3D의 핵심 패턴입니다.

fun main() = application {
    program {
        val sphere = sphereMesh(32, 32, 0.6)
        val style = shadeStyle {
            vertexTransform = """
                vec3 p = x_position * 8.0 + p_seconds;
                x_position.x += sin(p.y) * 0.1;
                x_position.y += sin(p.z) * 0.1;
                x_position.z += sin(p.x) * 0.1;
            """.trimIndent()
            fragmentTransform = """
                vec3 c = sin(v_worldPosition) * 0.5 + 0.5;
                x_fill = vec4(c, 1.0);
            """.trimIndent()
        }
        val camera = OrbitalCamera(Vector3.UNIT_Z, Vector3.ZERO)
        extend(camera)
        extend {
            camera.rotate(0.2, 0.0)
            style.parameter("seconds", seconds)
            drawer.shadeStyle = style
            drawer.vertexBuffer(sphere, DrawPrimitive.LINES)
        }
    }
}

• x_position을 바꾸면 지오메트리가 변형됩니다.
• v_worldPosition으로 월드 좌표 기반 색을 줄 수 있습니다.
• 파라미터는 Kotlin에서 parameter("seconds", seconds) → GLSL p_seconds.

5.4 버텍스 관련 주요 심볼

이름	단계	의미
x_position	vertex	변형 가능한 위치 (초기값 a_position)
x_normal	vertex	변형 가능한 법선
a_position / a_normal	vertex	원본 속성
va_normal	fragment	보간된 법선
v_worldPosition	fragment	월드 좌표 위치
v_worldNormal	fragment	월드 좌표 법선
p_*	양쪽	사용자 파라미터

법선을 크게 바꾸면 조명이 깨질 수 있으므로, 위치만 움직일 때도 필요하면 법선을 다시 계산하는 방식을 고려합니다.

5.5 CPU 쪽 버텍스 수정

ShadeStyle 대신 버퍼를 다시 채울 수도 있습니다.

geometry.put {
    // 매 프레임 또는 필요할 때만
    for (i in 0 until vertexCount) {
        write(modifiedPosition)
        // normal 등
    }
}

• 정점이 수천~수만 개일 때는 GPU vertexTransform이 유리한 경우가 많습니다.
• 한 번만 만들고 재사용하는 것이 기본입니다.

---

6. 인스턴싱과 배치

같은 메시를 여러 위치/색으로 그릴 때:

val transforms = vertexBuffer(vertexFormat {
    attribute("transform", VertexElementType.MATRIX44_FLOAT32)
    // attribute("color", VertexElementType.VECTOR4_FLOAT32)
}, instanceCount)

// transforms.put { write(matrix) ... }

drawer.shadeStyle = shadeStyle {
    vertexTransform = "x_modelMatrix *= i_transform;"
    // fragmentTransform = "x_fill = vi_color;"
}
drawer.vertexBufferInstances(
    listOf(mesh),
    listOf(transforms),
    DrawPrimitive.TRIANGLES,
    transforms.vertexCount
)

• i_ / vi_ 접두사로 인스턴스 속성에 접근합니다.
• 수천 개의 작은 메시를 개별 vertexBuffer 호출로 그리는 것보다 훨씬 효율적입니다.

---

7. 종합 예제: 회전하는 조명 큐브 + 디스토션 구

fun main() = application {
    configure {
        width = 960
        height = 540
        multisample = WindowMultisample.SampleCount(4)
    }
    program {
        val cube = boxMesh(80.0, 80.0, 80.0)
        val sphere = sphereMesh(48, 48, 1.0)

        val lightStyle = shadeStyle {
            fragmentTransform = """
                vec3 lightDir = normalize(vec3(0.4, 1.0, 0.3));
                float l = max(dot(va_normal, lightDir), 0.0) * 0.6 + 0.4;
                x_fill.rgb *= l;
            """.trimIndent()
        }

        val distortStyle = shadeStyle {
            vertexTransform = """
                vec3 p = x_position * 6.0 + p_time;
                x_position += 0.08 * vec3(sin(p.y), sin(p.z), sin(p.x));
            """.trimIndent()
            fragmentTransform = """
                vec3 c = 0.5 + 0.5 * sin(v_worldPosition * 2.0 + p_time);
                x_fill = vec4(c, 1.0);
            """.trimIndent()
        }

        val cam = Orbital()
        cam.eye = Vector3(0.0, 40.0, 220.0)
        extend(cam)

        extend {
            lightStyle.parameter("time", seconds)   // 필요 시
            distortStyle.parameter("time", seconds)

            drawer.clear(ColorRGBa.fromHex("#0d0d12"))
            drawer.depthWrite = true
            drawer.depthTestPass = DepthTestPass.LESS_OR_EQUAL

            drawer.isolated {
                drawer.shadeStyle = lightStyle
                drawer.fill = ColorRGBa.fromHex("#FFC0CB")
                drawer.translate(-90.0, 0.0, 0.0)
                drawer.rotate(Vector3.UNIT_Y, seconds * 25.0)
                drawer.vertexBuffer(cube, DrawPrimitive.TRIANGLES)
            }

            drawer.isolated {
                drawer.shadeStyle = distortStyle
                drawer.fill = ColorRGBa.WHITE
                drawer.translate(90.0, 0.0, 0.0)
                drawer.scale(50.0)
                drawer.vertexBuffer(sphere, DrawPrimitive.TRIANGLES)
            }
        }
    }
}

---

8. 자주 쓰는 패턴 요약

하고 싶은 일	사용할 기능
기본 박스/구 메시	boxMesh, sphereMesh → drawer.vertexBuffer
궤도 카메라	Orbital() 또는 OrbitalCamera + extend
앞뒤 가림	depthWrite = true, depthTestPass = LESS_OR_EQUAL
간단한 조명	fragmentTransform에서 va_normal 닷 프로덕트
버텍스 흔들기/파동	vertexTransform에서 x_position 수정 + p_time
월드 좌표 기반 색	v_worldPosition
같은 메시 다수	vertexBufferInstances + 인스턴스 속성
오프스크린 3D	renderTarget { colorBuffer(); depthBuffer() }
상태 격리	drawer.isolated { }

---

9. 성능 관점의 정리

1. 메시·스타일·타깃 생성 위치: boxMesh/sphereMesh, ShadeStyle, RenderTarget, 인스턴스 버퍼는 입력이 고정이면 extend 바깥에서 한 번만 생성합니다.
2. 드로우 콜: 동일 지오메트리는 인스턴싱을 우선합니다.
3. 버텍스 변형 위치: 매 프레임 CPU put보다 GPU vertexTransform이 유리한 경우가 많습니다. 정점 수가 많을수록 차이가 큽니다.
4. 셰이더 복잡도: fBm·다중 노이즈는 픽셀 수에 비례해 비용이 증가합니다. 큰 화면·고해상도에서는 반복 횟수를 줄입니다.
5. 상태 누수: shadeStyle, depth 설정, blendMode는 다음 그리기에 남습니다. isolated로 범위를 제한합니다.
6. 멀티샘플: WindowMultisample.SampleCount(4) 등으로 가장자리를 부드럽게 할 수 있습니다(성능 트레이드오프).

---

10. 문서에서 다루지 않은 항목

• GLTF/GLB 로더 및 씬 그래프 (코어에 없음. 직접 구현 또는 외부 도구)
• PBR·물리 기반 재질 시스템
• 스킨드 메시·본 애니메이션
• Compute shader로 VertexBuffer 채우기 (고급)
• orx-fx 후처리 체인 상세
• 3D 텍스트·복잡한 CSG

---

11. 검증 메모

항목	내용
코드 실행 여부	공식 가이드 3D graphics·Shade styles 3D mesh distortion 예제를 기반으로 함. 종합 예제·인스턴싱 조합 코드는 0.5.0에서 직접 실행 검증하지 않음
ORX import	boxMesh, sphereMesh, Orbital, OrbitalCamera 패키지는 IDE 자동 import로 확인
depth 기본값	3D 시 depthWrite/depthTestPass를 명시적으로 설정할 것
카메라 eye	Orbital의 초기 eye는 장면에 맞게 조정 필요
c_element / 인스턴스	배치·인스턴스 인덱스는 가이드 상수 정의에 근거. 실행으로 확인 권장
API 문서 버전	API 사이트 표기가 0.5.0-dev...여도 v0.5.0 릴리즈와 커밋이 일치하는 경우가 있음

---

12. 참고 자료

공식 가이드

• 3D graphics (가이드 소스 / 예제): openrndr-guide C170_TridimensionalGraphics.kt
• Shade styles: https://guide.openrndr.org/drawing/shadeStyles.html (3D mesh distortion 포함)
• Transformations: https://guide.openrndr.org/drawing/transformations.html
• Render targets: https://guide.openrndr.org/drawing/renderTargets.html
• Vectors: https://guide.openrndr.org/drawing/vectors.html

ORX

• orx-mesh-generators: 3D 메시 생성
• orx-camera: Orbital, OrbitalCamera

릴리즈·API

• OPENRNDR 0.5.0: https://github.com/openrndr/openrndr/releases/tag/v0.5.0
• API (openrndr-draw): https://api.openrndr.org/openrndr-draw/org.openrndr.draw/
• 예제 저장소: https://github.com/openrndr/openrndr-examples

---