Harfang3D - 跨平台3D引擎插件库使用指南

Harfang3D是一个轻量级的跨平台3D引擎，支持Windows、Linux、macOS、Android和iOS平台。它提供了完整的3D渲染、物理模拟、音频处理和VR支持等功能。下面我将介绍如何在Go语言中使用Harfang3D。

安装Harfang3D

Harfang3D主要通过C++实现，但提供了Go绑定。首先需要安装Harfang3D的核心库：

1. 从官网(https://www.harfang3d.com)下载预编译库
2. 或者从源代码编译

对于Go绑定，可以使用cgo来调用Harfang3D的C接口。

基本使用示例

下面是一个简单的Go程序，展示如何初始化Harfang3D并创建一个窗口：

package main

/*
#cgo CFLAGS: -I/path/to/harfang/include
#cgo LDFLAGS: -L/path/to/harfang/lib -lharfang
#include <hg.h>
*/
import "C"
import "unsafe"

func main() {
	// 初始化Harfang3D
	C.hg_AddAssetsFolder(C.CString("assets"))
	
	// 创建窗口
	win := C.hg_NewWindow(C.CString("Harfang3D Go Example"), 1024, 768, 32, C.hg_Window_Normal)
	
	// 创建渲染器
	renderer := C.hg_NewRenderer()
	C.hg_ResetRenderer(renderer, win)
	
	// 主循环
	for C.hg_IsWindowOpen(win) == 1 {
		// 处理窗口事件
		C.hg_UpdateWindow(win)
		
		// 清除屏幕
		C.hg_SetViewClear(0, C.hg_CF_Color|C.hg_CF_Depth, 0x303050ff, 1.0, 0)
		
		// 开始帧
		C.hg_SceneReset(0, 1.0/60.0, C.hg_TimeSource_Engine)
		
		// 结束帧并交换缓冲区
		C.hg_Frame()
		C.hg_Flip(win)
	}
	
	// 清理资源
	C.hg_DestroyRenderer(renderer)
	C.hg_DestroyWindow(win)
}

3D场景创建

下面是一个更完整的例子，展示如何创建一个3D场景：

package main

/*
#cgo CFLAGS: -I/path/to/harfang/include
#cgo LDFLAGS: -L/path/to/harfang/lib -lharfang
#include <hg.h>
*/
import "C"
import "unsafe"

func main() {
	// 初始化
	C.hg_AddAssetsFolder(C.CString("assets"))
	win := C.hg_NewWindow(C.CString("3D Scene"), 1024, 768, 32, C.hg_Window_Normal)
	renderer := C.hg_NewRenderer()
	C.hg_ResetRenderer(renderer, win)
	
	// 创建场景
	scene := C.hg_NewScene()
	
	// 创建相机
	camera := C.hg_NewNodeWithName(scene, C.CString("camera"), C.hg_Matrix4Identity())
	C.hg_SetupPerspectiveCamera(scene, camera, 0.1, 1000.0, C.hg_Deg(45.0))
	C.hg_SetNodePosition(scene, camera, C.hg_Vec3(0, 1, -5))
	
	// 创建光源
	light := C.hg_NewNodeWithName(scene, C.CString("light"), C.hg_Matrix4Identity())
	C.hg_SetNodePosition(scene, light, C.hg_Vec3(0, 2, 0))
	C.hg_SetNodeRotation(scene, light, C.hg_Vec3(C.hg_Deg(45.0), C.hg_Deg(45.0), 0))
	C.hg_SetLight(scene, light, C.hg_LightModel_Linear, 100.0, C.hg_Color(1, 1, 1, 1))
	
	// 创建3D模型
	model := C.hg_NewNodeWithName(scene, C.CString("model"), C.hg_Matrix4Identity())
	C.hg_LoadModelFromAssets(scene, model, C.CString("model.geo"), C.CString("material.mat"))
	
	// 主循环
	for C.hg_IsWindowOpen(win) == 1 {
		C.hg_UpdateWindow(win)
		
		// 旋转模型
		rot := C.hg_GetNodeRotation(scene, model)
		rot.y += C.hg_TimeFromSec(1.0/60.0)
		C.hg_SetNodeRotation(scene, model, rot)
		
		// 渲染场景
		C.hg_SetViewClear(0, C.hg_CF_Color|C.hg_CF_Depth, 0x303050ff, 1.0, 0)
		C.hg_SubmitSceneToPipeline(0, scene, C.hg_IntRect(0, 0, 1024, 768), camera, nil)
		
		C.hg_Frame()
		C.hg_Flip(win)
	}
	
	// 清理
	C.hg_DestroyScene(scene)
	C.hg_DestroyRenderer(renderer)
	C.hg_DestroyWindow(win)
}

物理系统集成

Harfang3D集成了Bullet物理引擎，下面是如何使用物理系统的示例：

// 初始化物理系统
physics := C.hg_NewPhysicsSystem()
C.hg_InitPhysicsSystem(physics)

// 为场景节点添加刚体
ground := C.hg_NewNodeWithName(scene, C.CString("ground"), C.hg_Matrix4Identity())
C.hg_CreatePlane(physics, ground, C.hg_Vec3(0, 1, 0), 0) // 静态地面

// 创建动态刚体
box := C.hg_NewNodeWithName(scene, C.CString("box"), C.hg_Matrix4Identity())
C.hg_SetNodePosition(scene, box, C.hg_Vec3(0, 5, 0))
C.hg_CreateBox(physics, box, C.hg_Vec3(1, 1, 1), 1.0) // 1x1x1的盒子，质量1kg

// 在主循环中更新物理
C.hg_StepPhysicsSystem(physics, C.hg_TimeFromSec(1.0/60.0))

VR支持

Harfang3D支持OpenVR，下面是如何初始化VR系统的示例：

// 初始化VR
vr := C.hg_NewVRSystem()
if C.hg_InitVRSystem(vr) == 1 {
    // 创建VR渲染器
    vrRenderer := C.hg_NewVRRenderer()
    C.hg_ResetVRRenderer(vrRenderer, vr, renderer)
    
    // VR主循环
    for C.hg_IsWindowOpen(win) == 1 {
        // 更新VR状态
        C.hg_UpdateVRSystem(vr)
        
        // 渲染VR场景
        C.hg_SubmitSceneToVRPipeline(0, scene, vr, camera, nil)
        
        // 渲染VR镜面
        C.hg_RenderVREyesToDisplay(vrRenderer)
    }
    
    C.hg_DestroyVRRenderer(vrRenderer)
}
C.hg_DestroyVRSystem(vr)

注意事项

1. Harfang3D的Go绑定需要通过cgo调用C接口，因此需要正确配置C编译器和链接器
2. 资源路径需要正确设置，特别是模型和材质文件
3. 不同平台的编译配置可能不同，特别是Android和iOS
4. 性能关键部分可能需要直接使用C代码

Harfang3D提供了丰富的功能，包括：

• 3D渲染管线
• 物理模拟
• 音频处理
• 脚本系统
• VR/AR支持
• 多平台部署

更多详细用法可以参考官方文档和示例代码。