Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

ImporterMesh

繼承: Resource < RefCounted < Object

在匯入過程中,包含基於頂點陣列的幾何體的 Resource。

說明

ImporterMesh 是一種 Resource(資源),類似於 ArrayMesh。它包含基於頂點陣列的幾何體,並被劃分為若干個 表面(surfaces)。每個表面都包含一個完全獨立的陣列,以及一個用於繪製它的材質。從設計角度來看,擁有多個表面的網格優於單個表面的網格,因為在 3D 編輯軟體中建立的物件通常包含多種材質。

與其執行時對應的 ArrayMesh 不同,ImporterMesh 包含的是在經歷各種匯入步驟(例如 LOD 和陰影網格生成)之前的原始網格資料。若要修改表面資料,可以呼叫 clear(),然後為每個表面呼叫 add_surface()。

方法

void

add_blend_shape(name: String)

void

add_surface(primitive: PrimitiveType, arrays: Array, blend_shapes: Array[Array] = [], lods: Dictionary = {}, material: Material = null, name: String = "", flags: int = 0)

void

clear()

ImporterMesh

from_mesh(mesh: Mesh) static

void

generate_lods(normal_merge_angle: float, normal_split_angle: float, bone_transform_array: Array)

int

get_blend_shape_count() const

BlendShapeMode

get_blend_shape_mode() const

String

get_blend_shape_name(blend_shape_idx: int) const

Vector2i

get_lightmap_size_hint() const

ArrayMesh

get_mesh(base_mesh: ArrayMesh = null)

Array

get_surface_arrays(surface_idx: int) const

Array

get_surface_blend_shape_arrays(surface_idx: int, blend_shape_idx: int) const

int

get_surface_count() const

int

get_surface_format(surface_idx: int) const

int

get_surface_lod_count(surface_idx: int) const

PackedInt32Array

get_surface_lod_indices(surface_idx: int, lod_idx: int) const

float

get_surface_lod_size(surface_idx: int, lod_idx: int) const

Material

get_surface_material(surface_idx: int) const

String

get_surface_name(surface_idx: int) const

PrimitiveType

get_surface_primitive_type(surface_idx: int)

ImporterMesh

merge_importer_meshes(importer_meshes: Array[ImporterMesh], relative_transforms: Array[Transform3D], deduplicate_surfaces: bool = true) static

void

set_blend_shape_mode(mode: BlendShapeMode)

void

set_lightmap_size_hint(size: Vector2i)

void

set_surface_material(surface_idx: int, material: Material)

void

set_surface_name(surface_idx: int, name: String)


方法說明

void add_blend_shape(name: String) 🔗

為將使用 add_surface() 新增的混合形狀新增名稱。必須在表面被新增之前調用。


void add_surface(primitive: PrimitiveType, arrays: Array, blend_shapes: Array[Array] = [], lods: Dictionary = {}, material: Material = null, name: String = "", flags: int = 0) 🔗

建立新的曲面。Mesh.get_surface_count() 的返回值將成為此曲面的 surf_idx。

曲面會以 primitive 指定的圖元型別進行繪製,可為 PrimitiveType 中的任一值。

arrays 是「陣列的陣列」。在 Mesh.ARRAY_MAX 個元素中,每個元素要嘛包含由 ArrayType 相對應成員所描述的曲面資料,要嘛為未使用時的 null。例如,arrays[0] 為頂點陣列;此子陣列為必填,其餘則為可選。若加上索引陣列,即會進入「索引模式」,此時頂點與其他陣列成為資料來源,而索引陣列決定頂點次序。除非使用 Mesh.ARRAY_INDEX,否則所有子陣列長度必須等於頂點陣列長度(或為其整數倍,當一個頂點對應多個子陣列元素時),或保持空陣列。

blend_shapes 是每個混合形狀的頂點資料陣列。其結構與 arrays 相同,但僅當 arrays 內有設定 Mesh.ARRAY_VERTEX、Mesh.ARRAY_NORMAL 或 Mesh.ARRAY_TANGENT 時,對應項目才會被設定;其餘皆為 null。

lods 為字典,鍵值為 float、內容為 PackedInt32Array。每一項代表此曲面的一級 LOD,其中值為該 LOD 使用的 Mesh.ARRAY_INDEX 陣列,鍵值大致對應開始啟用該 LOD 的距離;鍵越大,啟用距離亦越遠。

flags 為多個旗標的位元 OR:對於每個使用中的自訂通道,將 ArrayCustomFormat 的值左移 ARRAY_FORMAT_CUSTOMn_SHIFT;亦可加入 Mesh.ARRAY_FLAG_USE_DYNAMIC_UPDATE、Mesh.ARRAY_FLAG_USE_8_BONE_WEIGHTS、Mesh.ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY。

注意:使用索引時建議僅使用點、線或三角形圖元。


void clear() 🔗

從該 ImporterMesh 中,移除所有表面和混合形狀。


ImporterMesh from_mesh(mesh: Mesh) static 🔗

通過將給定 Mesh 的所有表面、混合形狀、材質和中繼資料複製到一個新的 ImporterMesh 物件中,將其轉換為 ImporterMesh 物件。


void generate_lods(normal_merge_angle: float, normal_split_angle: float, bone_transform_array: Array) 🔗

為這個 ImporterMesh 生成所有 LOD。

normal_merge_angle 以度為單位,用法與 lods 的匯入器設定相同。

normal_split_angle 未使用,僅為相容舊版本 API 而保留。

生成的 LOD 的數量可以使用 get_surface_lod_count() 訪問,每個 LOD 在 get_surface_lod_size() 和 get_surface_lod_indices() 中可用。

bone_transform_array 是一個 Array,可以是空的,也可以包含 Transform3D,每個網格的骨骼 ID 在生成 LOD 網格變化時將應用網格蒙皮。這通常用於解釋網格本身與其蒙皮資料之間的縮放差異。


int get_blend_shape_count() const 🔗

返回該網格包含的混合形狀的數量。


BlendShapeMode get_blend_shape_mode() const 🔗

返回該網格的混合形狀模式。


String get_blend_shape_name(blend_shape_idx: int) const 🔗

回傳此索引處混合形狀的名稱。


Vector2i get_lightmap_size_hint() const 🔗

返回該網格的大小提示,用於在 UV 空間中展開光照貼圖。


ArrayMesh get_mesh(base_mesh: ArrayMesh = null) 🔗

將該 ImporterMesh 表示的網格資料作為一個可用的 ArrayMesh 返回。

這個方法快取了返回的網格,後續的呼叫將返回快取的資料,直到 clear() 被呼叫。

如果還沒有快取並且提供了 base_mesh,則 base_mesh 將被使用並被改變。


Array get_surface_arrays(surface_idx: int) const 🔗

回傳構成請求表面的頂點、法線、UV 等的陣列。參見 add_surface()。


Array get_surface_blend_shape_arrays(surface_idx: int, blend_shape_idx: int) const 🔗

為一個表面請求的混合形狀索引,返回一組混合形狀陣列。


int get_surface_count() const 🔗

返回該網格擁有的表面數。


int get_surface_format(surface_idx: int) const 🔗

返回該網格擁有的表面的格式。


int get_surface_lod_count(surface_idx: int) const 🔗

返回該網格在給定表面上保留的 lod 數。


PackedInt32Array get_surface_lod_indices(surface_idx: int, lod_idx: int) const 🔗

返回表面的 lod 的索引緩衝區。


float get_surface_lod_size(surface_idx: int, lod_idx: int) const 🔗

返回為一個表面啟動 lod 的螢幕比率。


Material get_surface_material(surface_idx: int) const 🔗

返回給定面的 Material 材質。面將由該材質來渲染。


String get_surface_name(surface_idx: int) const 🔗

取得此曲面設定的名稱。


PrimitiveType get_surface_primitive_type(surface_idx: int) 🔗

返回所請求表面的基元型別(參見 add_surface())。


ImporterMesh merge_importer_meshes(importer_meshes: Array[ImporterMesh], relative_transforms: Array[Transform3D], deduplicate_surfaces: bool = true) static 🔗

將多個 ImporterMesh 合併為單個 ImporterMesh。每個輸入網格將由 relative_transforms 陣列中對應的 Transform3D 進行變換,該陣列的大小必須與 importer_meshes 相同。支援負縮放,並且網格資料中的纏繞順序將被修正以適應此情況。

如果 deduplicate_surfaces 為 true 且多個網格具有同名且格式相同的表面,則在合併網格時這些表面將被合併在一起,並使用第一個匹配表面的材質。這有助於減少生成網格中的表面數量,並避免材質重複。包含骨骼權重的表面將永遠不會被去重。如果 deduplicate_surfaces 為 false,表面將始終被保持分離,並被賦予唯一的名稱。

警告: 混合形狀(Blend shapes)和細節層次(LODs)不受支援,將會被丟棄。請勿使用此函式來丟棄混合形狀和 LOD,因為未來可能會增加對它們的支援。


void set_blend_shape_mode(mode: BlendShapeMode) 🔗

設定混合形狀模式。


void set_lightmap_size_hint(size: Vector2i) 🔗

設定該網格的大小提示,以便在 UV 空間中展開光照貼圖。


void set_surface_material(surface_idx: int, material: Material) 🔗

設定給定面的 Material 材質。該面將會使用此材質渲染。


void set_surface_name(surface_idx: int, name: String) 🔗

為指定曲面設定名稱。