Sceneform SDK cho Android có nguồn mở và được lưu trữ (github.com/google-ar/sceneform-android-sdk) với phiên bản 1.16.0.
Trang web này (developers.google.com/sceneform) đóng vai trò là kho lưu trữ tài liệu cho phiên bản trước, Sceneform SDK for Android 1.15.0.
Không sử dụng phiên bản 1.17.0 của Cấu phần phần mềm Maven của Sceneform.
Có thể sử dụng các cấu phần phần mềm Maven 1.17.1. Tuy nhiên, khác với phiên bản, các cấu phần phần mềm 1.17.1 giống với các cấu phần phần mềm 1.15.0.

Trang này được dịch bởi Cloud Translation API.

Tài liệu tham khảo về tệp tài sản biểu mẫu

Tệp Định nghĩa thành phần cảnh (*.sfa) là phần mô tả mà con người có thể đọc được về thành phần nhị phân cảnh dạng (*.sfb). Tệp này trỏ đến các mô hình, định nghĩa chất liệu và hoạ tiết trong tài sản nguồn của bạn, đồng thời cung cấp các tham số material cho tài liệu dựa trên vật lý của Sceneform.

Tệp này sẽ được tạo tự động trong lần nhập đầu tiên bằng trình bổ trợ Sceneform của Android Studio, nhưng bạn có thể điều chỉnh các thuộc tính này để thay đổi giao diện của thành phần. Tài liệu tham khảo này mô tả các thuộc tính mà bạn có thể định cấu hình để sửa đổi giao diện của tài sản. Các thuộc tính không bắt buộc không có trong sfa sẽ có giá trị mặc định. Cú pháp của sfa là jsonnet, một phần mở rộng của JSON.

Cú pháp

{
   materials: [
      {
         name: "<name>",
         parameters: [
            {
               <parameterName>: <parameterDefaultValue>,
            },
            …
         ],
         source: "path/to/source_material.sfm",
      },
      …
   ],
   model: {
      attributes: [
         "Position",
         "TexCoord",
         "Orientation",
      ],
      file: "path/to/source_asset.ext",
      name: "<Name>",
      scale: 1.0,
      recenter: false,
      smoothing_angle: 45.0,
      flip_texture_coordinates: false,
      fix_infacing_normals: false,
   },
   samplers: [
      {
         file: "path/to/source_texture.ext",
         name: "<name>",
         params: {
            usage_type: "Color",
            mag_filter: "Linear",
            min_filter: "NearestMipmapLinear",
            wrap_s: "Repeat",
            wrap_t: "Repeat",
         },
         pipeline_name: "<pipeline_name>",
      },
      …
   ]
}

Thuộc tính

materials[].parameters

Nội dung của khối này phụ thuộc vào định nghĩa của tài liệu do thuộc tính source chỉ định.

Đối với tài liệu mặc định (*.sfm), hãy xem danh sách các thông số được hỗ trợ:

Thành phần OBJ: obj_material.sfm
Tài sản FBX: fbx_material.sfm
Thành phần glTF: gltf_material.sfm

Đối với tài liệu tuỳ chỉnh (*.mat), danh sách các thông số được hỗ trợ được chỉ định trong tệp *.mat:

Xem tài liệu tham khảo về tài liệu tùy chỉnh

materials[].source: Chỉ định tệp định nghĩa material, tệp định nghĩa material mặc định (*.sfm) hoặc tệp định nghĩa material tuỳ chỉnh (*.mat).

model.attributes

Xác định tập hợp các luồng đỉnh đã xuất, được tính toán trong quá trình nhập mô hình nguồn. Các giá trị có thể là:

Giá trị	Nội dung mô tả
`"Color"`	Đỉnh `COLOR`.
`"Orientation"`	Đỉnh `TANGENT`.
`"Position"`	Đỉnh `POSITION`.
`"TexCoord"`	`TEXCOORD0`, tọa độ UV đầu tiên.

model.file: Thuộc tính bắt buộc, chứa đường dẫn hệ thống tệp đến tệp tài sản nguồn. Các định dạng hiện được hỗ trợ là *.fbx, *.obj, *.gltf, *.glb.

model.scale: Thuộc tính không bắt buộc, mặc định là 1.0. Kiểm soát quy mô của mô hình đã xuất so với nội dung của thành phần nguồn. Tỷ lệ 2.0 sẽ làm cho tài sản lớn gấp đôi.; Giá trị vị trí biểu mẫu được chỉ định theo mét. Để đáp ứng sự khác biệt giữa các đơn vị chuẩn, thuật ngữ tỷ lệ được tự động tính toán trong quá trình nhập ban đầu để giúp trục lớn nhất không nhỏ hơn 5 cm và trục nhỏ nhất không lớn hơn 1 m. Điều này là để phục vụ trải nghiệm nhập ban đầu; những giới hạn này không được thực thi.

model.recenter

Thuộc tính không bắt buộc, mặc định là false. Kiểm soát vị trí của hình học được xuất. Các giá trị có thể là:

Giá trị	Nội dung mô tả
`false`	Hình học sẽ được xuất dưới dạng đã tạo mà không cần chuyển đổi.
`true`	Trung tâm của hình sẽ được đặt ở gốc.
`"root"`	Hình học sẽ được xuất để căn giữa theo chiều ngang so với chiều gốc và được dịch chuyển theo chiều dọc để các đỉnh thấp nhất của nó ngang với vị trí gốc. Bạn có thể sử dụng ví dụ này để đảm bảo rằng một mô hình đã xuất có vị trí trên neo hoặc mặt phẳng sẽ đứng phía trên điểm neo này.
`{x:float, y:float, z:float}`	Hình học sẽ được xuất sao cho nguồn gốc được đặt theo điểm được chỉ định. `{x:0, y:0, z:0}` tương ứng với giá trị tối thiểu của hộp giới hạn theo trục của hình học. `{x:1, y:1, z:1}` tương ứng với giá trị tối đa của hộp giới hạn theo trục của hình học.}

model.smoothing_angle: Thuộc tính không bắt buộc chỉ định theo độ, mặc định là 45. Tài sản nguồn không có pháp tuyến trên mỗi đỉnh (ví dụ: obj) sẽ có các pháp tuyến trên mỗi đỉnh được tạo bằng smoothing_angle để giới hạn tập hợp các pháp tuyến mặt được sử dụng để tính toán một đỉnh thông thường. Các cạnh trong mô hình vượt quá góc này sẽ xuất hiện <39;hard & # 39; hoặc các cạnh không vượt quá sẽ xuất hiện mượt mà.

model.flip_texture_coordinates: Thuộc tính không bắt buộc, mặc định là false. Nếu là true, thì toạ độ dọc sẽ được đảo ngược ((u, v) -> (u, 1 - v)) trong quá trình nhập. Điều này giúp đáp ứng sự khác biệt trước đây giữa OpenGL/Direct3D.

model.fix_infacing_normals: Thuộc tính không bắt buộc, mặc định là false. Nếu là true, giá trị nhập sẽ cố gắng tìm và sửa cho các pháp tuyến gặp phải (pháp tuyến hướng ' vào ' bề mặt trái ngược với ' trong số # 39; bề mặt).

samplers[].params.usage_type: Xác định cách diễn giải thời gian chạy dữ liệu hình ảnh đã mã hoá. Sử dụng "Color" cho hoạ tiết hình ảnh sRGB. Sử dụng "Data" hoặc "Normal" để xử lý nội dung của hình ảnh như thể chúng nằm trong không gian tuyến tính. Giá trị mặc định là "Color".

samplers[].params.mag_filter

Xác định bộ lọc giảm thiểu được sử dụng khi mipmap được lấy mẫu lớn hơn kích thước pixel của việc lấy mẫu hình học. Giá trị mặc định là "Linear". Các giá trị có thể là:

Giá trị Nội dung mô tả

"Nearest" Tương ứng với GL_NEAREST. Trả về giá trị của phần tử hoạ tiết gần nhất (trong khoảng cách Manhattan) đến tâm của pixel được tạo hoạ tiết.

"Linear" Tương ứng với GL_LINEAR. Trả về giá trị trung bình có trọng số của 4 thành phần hoạ tiết gần nhất với tâm của pixel đang được tạo hoạ tiết. Các thành phần này có thể bao gồm các thành phần hoạ tiết đường viền, tuỳ thuộc vào giá trị của hoạ tiết wrap_s và hoạ tiết wrap_t và trên bản đồ chính xác.

Giá trị	Nội dung mô tả
`"Nearest"`	Tương ứng với `GL_NEAREST`. Trả về giá trị của phần tử hoạ tiết gần nhất (trong khoảng cách Manhattan) đến tâm của pixel được tạo hoạ tiết.
`"Linear"`	Tương ứng với `GL_LINEAR`. Trả về giá trị trung bình có trọng số của 4 thành phần hoạ tiết gần nhất với tâm của pixel đang được tạo hoạ tiết. Các thành phần này có thể bao gồm các thành phần hoạ tiết đường viền, tuỳ thuộc vào giá trị của hoạ tiết `wrap_s` và hoạ tiết `wrap_t` và trên bản đồ chính xác.

samplers[].params.min_filter

Xác định bộ lọc giảm thiểu được sử dụng khi mipmap được lấy mẫu lớn hơn kích thước pixel của việc lấy mẫu hình học. Giá trị mặc định là "NearestMipmapLinear". Các giá trị có thể là:

Giá trị	Nội dung mô tả
`"Nearest"`	Tương ứng với `GL_NEAREST`. Trả về giá trị của phần tử hoạ tiết gần nhất (trong khoảng cách Manhattan) đến giữa pixel được tạo hoạ tiết.
`"Linear"`	Tương ứng với `GL_LINEAR`. Trả về mức trung bình có trọng số của 4 phần tử hoạ tiết gần nhất với tâm của pixel đang được tạo hoạ tiết. Các đoạn này có thể bao gồm các phần tử hoạ tiết đường viền, tuỳ thuộc vào giá trị của hoạ tiết `wrap_s` và hoạ tiết `wrap_t` và trên bản đồ ánh xạ chính xác.
`"NearestMipmapNearest"`	Tương ứng với `GL_NEAREST_MIPMAP_NEAREST`. Chọn mipmap phù hợp nhất với kích thước pixel được tạo hoạ tiết và sử dụng tiêu chí `"Nearest"` (phần tử kết cấu gần tâm pixel nhất) để tạo ra giá trị hoạ tiết.
`"LinearMipmapNearest"`	Tương ứng với `GL_NEAREST_MIPMAP_LINEAR`. Chọn hai mipmap phù hợp nhất với kích thước của pixel được tạo hoạ tiết và sử dụng tiêu chí `"Nearest"` (phần tử kết cấu gần tâm pixel nhất) để tạo ra giá trị hoạ tiết từ mỗi mipmap. Giá trị hoạ tiết cuối cùng là giá trị trung bình có trọng số của hai giá trị đó.
`"LinearMipmapLinear"`	Tương ứng với `GL_LINEAR_MIPMAP_LINEAR`. Chọn hai mipmap phù hợp nhất với kích thước của pixel được tạo hoạ tiết và sử dụng tiêu chí `"Linear"` (trung bình có trọng số của bốn thành phần hoạ tiết gần trung tâm của pixel nhất) để tạo ra giá trị hoạ tiết từ mỗi mipmap. Giá trị hoạ tiết cuối cùng là giá trị trung bình có trọng số của hai giá trị đó.

samplers[].params.wrap_s

Thuộc tính không bắt buộc, mặc định là "Repeat". Kiểm soát hành vi gói theo chiều ngang.

Giá trị	Nội dung mô tả
`"ClampToBorder"`	Tương ứng với `GL_CLAMP_TO_BORDER`.
`"ClampToEdge"`	Tương ứng với `GL_CLAMP_TO_BORDER`.
`"MirroredRepeat"`	Tương ứng với `GL_MIRRORED_REPEAT`.
`"MirrorClampToEdge"`	Tương ứng với `GL_MIRROR_CLAMP_TO_EDGE`.
`"Repeat"`	Tương ứng với `GL_REPEAT`.

samplers[].params.wrap_t

Thuộc tính không bắt buộc, mặc định là "Repeat". Kiểm soát hành vi gói theo chiều dọc.

Giá trị	Nội dung mô tả
`"ClampToBorder"`	Tương ứng với `GL_CLAMP_TO_BORDER`.
`"ClampToEdge"`	Tương ứng với `GL_CLAMP_TO_BORDER`.
`"MirroredRepeat"`	Tương ứng với `GL_MIRRORED_REPEAT`.
`"MirrorClampToEdge"`	Tương ứng với `GL_MIRROR_CLAMP_TO_EDGE`.
`"Repeat"`	Tương ứng với `GL_REPEAT`.

Thông số cho tài liệu mặc định

Cảnh cung cấp ba định nghĩa mặc định quan trọng: một cho nội dung OBJ, một cho nội dung FBX và một cho nội dung glTF.

Phần này liệt kê các thông số quan trọng được hỗ trợ theo từng định nghĩa Material.

`obj_material.sfm`

Thông số	Giá trị	Nội dung mô tả
`baseColor`	`<sampler_name>`	Tính toán `baseColor` làm giá trị từ mẫu lấy mẫu màu nội suy.
	`null`	Tính `baseColor` dưới dạng màu nội suy hoặc màu trắng nếu không có màu nội suy.
`baseColorTint`	`<vec4>`	Áp dụng sắc thái màu cho giá trị `baseColor` được tính toán, được chỉ định là `[r, b, g, a]`.
`metallic`	`<float_value>`	Kiểm soát tính kim loại của chất liệu. Sử dụng `0.0` cho vật liệu phi kim loại. Sử dụng `1.0` cho vật liệu kim loại.
`roughness`	`<float_value>`	Kiểm soát độ nhám của chất liệu. Sử dụng giá trị thấp đối với chất liệu sáng bóng (`0.0` thể hiện chất liệu phản chiếu hoàn hảo). Sử dụng giá trị cao đối với chất liệu khuếch tán (`1.0` thể hiện chất liệu không có độ sáng).
`opacity`	`null`	Mờ hoàn toàn.
	`<float_value>`	Đã bật độ trong suốt. `1.0` hoàn toàn không trong suốt. `0.0` hoàn toàn trong suốt.

`fbx_material.sfm`

Thông số	Giá trị	Nội dung mô tả
`baseColor`	`<vec4>`	Một hệ số phủ màu dựa trên kết quả của `baseColorMap`, được chỉ định là `[r, g, b, a]`.
`baseColorMap`	`<sampler_name>`	Kết quả là giá trị của mẫu lấy mẫu `baseColorMap`.
	`null`	Chuyển thành màu trắng.
`normalMap`	`<sampler_name>`	Diễn giải kết quả mẫu dưới dạng không gian nội tuyến thông thường, được dùng trong tính toán ánh sáng.
	`null`	Hãy dùng một `[0, 0, 1]` không đổi làm không gian tiếp tuyến thông thường.
`metallic`	`<float_value>`	Tỷ lệ `metallicMap` để kiểm soát tính kim loại của vật liệu. Sử dụng `0.0` cho vật liệu phi kim loại Sử dụng `1.0` cho vật liệu kim loại.
`metallicMap`	`<sampler_name>`	Sử dụng giá trị kênh màu đỏ từ trình lấy mẫu làm giá trị `metallicMap` của chúng tôi.
	`null`	Sử dụng một `1.0` không đổi, để được chia tỷ lệ theo `metallic`.
`roughness`	`<float_value>`	Điều chỉnh tỷ lệ `roughnessMap` để kiểm soát độ nhám của vật liệu. Sử dụng độ nhám thấp cho vật liệu sáng bóng. Sử dụng độ nhám cao cho vật liệu khuếch tán.
`roughnessMap`	`<sampler_name>`	Sử dụng giá trị kênh màu đỏ từ trình lấy mẫu làm giá trị `roughnessMap` của chúng tôi.
	`null`	Sử dụng một `1.0` không đổi, để được chia tỷ lệ theo `roughness`.
`reflectance`	`<float_value>`	Kiểm soát độ phản chiếu của một chất liệu. Chế độ mặc định của `0.5` bao gồm hầu hết tất cả các chất liệu được phép.
`opacity`	`null`	Không có tùy chọn kiểm soát độ mờ rõ ràng. Nếu bạn chỉ định bản đồ độ mờ trong dữ liệu nguồn, thì chất liệu sẽ được kết xuất bằng tính năng kết hợp trong suốt.

`gltf_material.sfm`

Thông số	Giá trị	Nội dung mô tả
`baseColorFactor`	`<vec4>`	Một hệ số phủ màu dựa trên kết quả của `baseColor`, được chỉ định là `[r, g, b, a]`.
`normal`	`<sampler_name>`	Diễn giải kết quả mẫu dưới dạng thông thường không gian tiếp tuyến, sử dụng trong tính toán ánh sáng.
	`null`	Sử dụng một `[0, 0, 1]` không đổi làm không gian tiếp tuyến (tang-space) thông thường của chúng tôi.
`metallicFactor`	`<float_value>`	Tỷ lệ `metallicRoughness` để kiểm soát tính kim loại của vật liệu. Sử dụng `0.0` cho vật liệu phi kim loại. Sử dụng `1.0` cho vật liệu kim loại.
`roughnessFactor`	`<float_value>`	Điều chỉnh tỷ lệ `metallicRoughness` để kiểm soát độ nhám của vật liệu. Sử dụng độ nhám thấp cho vật liệu sáng bóng. Sử dụng độ nhám cao cho vật liệu khuếch tán.
`metallicRoughness`	`<sampler_name>`	Sử dụng kênh màu xanh lục từ bộ lấy mẫu cho độ nhám (điều chỉnh theo tỷ lệ `roughnessFactor`). Sử dụng kênh màu xanh dương của bộ lấy mẫu cho kim loại (chia theo tỷ lệ `metallicFactor`).
	`null`	Hãy sử dụng `metallicFactor` và `roughnessFactor`.
`occlusion`	`<sampler_name>`	Sử dụng kênh màu đỏ từ trình lấy mẫu để đổ bóng không gian.
	`null`	Nếu có hoạ tiết `metallicRoughness`, hãy sử dụng kênh màu đỏ để điều khiển môi trường xung quanh.
`emissiveFactor`	`<float_value>`	Điều chỉnh tỷ lệ `emissive` để kiểm soát sự phát thải của vật liệu. Hãy sử dụng `0.0` cho các vật liệu không tạo ra ánh sáng của riêng mình.
`emissive`	`<sampler_name>`	Sử dụng màu từ bộ lấy mẫu làm giá trị phát sáng của chúng tôi.
	`null`	Không phát thải.
`reflectance`	`<float_value>`	Kiểm soát phản chiếu của một chất liệu. Mặc định là `0.5` bao gồm hầu hết tất cả các chất liệu có thể sử dụng.

Nếu bạn chỉ định phiên bản alpha trong dữ liệu nguồn, thì vật liệu sẽ hiển thị bằng cách kết hợp mặt nạ. Nếu chế độ kết hợp được bật trên nội dung nguồn, thì độ trong suốt sẽ được bật.

Thay thế hoặc thêm hoạ tiết

Khối samplers xác định hoạ tiết nào có sẵn cho chất liệu. Các bản ghi mẫu lấy từ tài sản nguồn sẽ khai báo pipeline_name, nhờ đó, xác định chính xác các bản ghi đó bằng đường dẫn hình ảnh gốc trong tài sản nguồn. Trường file có thể thay đổi để chứa đường dẫn tệp tương đối app/. Ví dụ: mã:

  {
     file: "sampledata/models/textures/dandy_andy.png",
     name: "andy",
     pipeline_name: "andy.png",
  },

thay thế kết cấu nguồn, được gọi là andy.png trong các thành phần nguồn, với nội dung của tệp ./sampledata/models/textures/dandy_andy.png.

Các kết cấu được khai báo đầy đủ hoặc một phần trong tài sản nguồn có thể không được tự động nhập vào tài sản. Trong trường hợp đó, các kết cấu có thể được thêm vào SFA. Bạn có thể thêm hoạ tiết vào bất kỳ mô hình nào có TexCoord trong danh sách thuộc tính. Thay vì pipeline_name chỉ áp dụng cho các mẫu mẫu được nhập tự động, người dùng sẽ chỉ định một khối injections.

Hãy xem xét ví dụ về một FBX có thuộc tính TexCoord nhưng không có hoạ tiết. Bạn có thể thêm một tệp hình ảnh vào thư mục dự án và liên kết tệp đó trong một khối lấy mẫu mới, sau đó trong phần chèn sẽ khai báo việc sử dụng tệp đó là "Normal" như trong mã sau:

  {
     file: "sampledata/models/cragly_normal.png",
     name: "bumps",
     injections: [
       {usage: "Normal",},
     ],
  },

Tại thời điểm này, hoạ tiết có sẵn cho tài liệu của bạn. Để hiển thị mẫu, hãy đảm bảo rằng các tài liệu mẫu yêu cầu mẫu cho thông số normalMap (nếu không, mẫu sẽ không được sử dụng và sẽ bị loại bỏ). Tên của bumps trong khối lấy mẫu của chúng tôi có nghĩa là khối material của chúng tôi sẽ có mã như sau:

    {
      normalMap: 'bumps',
    },

Hiện có các cách sử dụng khối chèn là BaseColor, Metallic,Normal,Emissive, Roughness và Occlusion.