在 Android NDK 上錄製時新增自訂資料

錄音與Playback API 可讓你錄製會議過程，並用來取代即時攝影機畫面。但這些錄音內容只包含影片和感應器資料。您也可將自訂資料新增至會話錄製中，並在播放期間將資料傳回給您，就像是相機影像的一部分。

ARCore 不會自動在錄製內容中加入任何自訂資料。相反地，此元件可在錄製時將自訂資料新增至 ARCore 影格，並在播放過程中從影格擷取相同的資料。您可以自行設計應用程式的程式，讓使用者能在繼續播放工作階段時取回所需資料。

自訂資料的用途

在錄製中加入自訂資料，為 AR 應用程式增添更多可能。以下是一些特定用途。

隨時隨地使用 AR

以往使用者只能在適當的位置使用 AR 功能。如果想將 AR 燈具放在客廳裡，他們必須實際站在那裡，看看燈具在那裡可能呈現的樣子。有了客製化軌道，他們只要錄製一次客廳內容，就能隨時將虛擬家具加到場景中。

共同打造 AR 體驗

如果沒有即時工作階段需求，使用者還能使用更多 AR 編輯功能，隨時隨地製作並存取獨特的 AR 內容。例如錄製指定環境、加入擴增實境效果，並與好友分享。

必要條件

請務必瞭解基本 AR 概念 以及如何在繼續操作前設定 ARCore 工作階段。

使用自訂資料記錄

使用自訂資料建立工作階段記錄。

使用自訂資料初始化錄製內容

如要初始化含有自訂資料的記錄，請按照下列步驟操作。如要開始、停止及查看錄製工作階段，請參閱「錄製及播放 AR 工作階段」。

  1. 取得 ArRecordingConfig。
  2. 使用自訂 UUID 建立新的 ArTrack。所有自訂資料都會儲存在這裡。
  3. 將 ArTrack 新增至您在工作階段設定期間建立的 ArRecordingConfig。
// Initialize a new track with a custom UUID.
// Make sure to save the UUID because it is the ID that you will use to get
// your data back during playback.
ArTrack* track = NULL;
ArTrack_create(ar_session, &track);
// String from UUID generator: de5ec7a4-09ec-4c48-b2c3-a98b66e71893
uint8_t uuid_byte_array[16] = {0xde, 0x5e, 0xc7, 0xa4, 0x09, 0xec,
                               0x4c, 0x48, 0xb2, 0xc3, 0xa9, 0x8b,
                               0x66, 0xe7, 0x18, 0x93};
ArTrack_setId(ar_session, track, uuid_byte_array);

// Add the ArTrack to the recording_config.
// recording_config must already be configured.
ArRecordingConfig_addTrack(ar_session, recording_config, track);
ArTrack_destroy(track);

所有新曲目都會視為不同的錄音，每首錄製曲目都含有專屬的 UUID。

選用：使用其他資料設定測試群組

為方便日後識別，您可以使用描述工作階段記錄的其他資料來設定測試群組。舉例來說，您可以新增附註，說明活動錄製地點和時間，藉此「標記」曲目：「下午在購物中心錄製這場活動」。

// Set additional data on this track.
// For example, describe where you recorded the session.
uint8_t metadata_size = 4;
uint8_t metadata[5] = "HOME";
ArTrack_setMetadata(ar_session, track, metadata, metadata_size);

選用：使用 MIME 類型設定音軌

如果您的應用程式需要與外部工具相容，您可以使用 MIME 類型設定測試群組，說明測試群組中記錄的資料類型。如果您未指定類型，系統會將資料歸類為 application/text。ARCore 在讀取資料時會忽略 MIME 類型。

// Set a MIME type for compatibility with external tools.
ArTrack_setMimeType(ar_session, track, "text/csv");

記錄自訂數據軌

所有自訂軌跡資料都會記錄在 ArFrame 中。AR 工作階段會使用 ArSession_update() 取得影格。將資料記錄在影格中的時間與播放期間資料傳回的時間相同。舉例來說，如果您在 00:07:02 使用「A」這個值呼叫 ArFrame_recordTrackData()，就能在播放該首曲目時，在 00:07:02 標記拿回「A」。

如要錄製自訂資料軌，請呼叫 ArFrame_recordTrackData()。

// Place an AR lamp in a room.
if (place_lamp_button_was_pressed) {
  uint8_t lamp_data[1] = {lamp_id};
  ArFrame_recordTrackData(ar_session, frame, uuid_byte_array, lamp_data,
                          /*payload_size=*/1);
}

播放自訂資料曲目

在播放期間從工作階段錄製中擷取自訂資料。

初始化播放

透過自訂資料初始化播放作業與初始化播放一般工作階段內容的播放相同。

傳回自訂資料

呼叫 ArFrame_getUpdatedTrackData() 即可擷取 ArFrame 上記錄的自訂資料。您可以從同一個影格擷取多個軌跡資料。舉例來說，如果你在錄影時在同一個影格中呼叫了 ArFrame_recordTrackData() 兩次，就會在播放期間傳回兩個 ArTrackData 例項。

// Create the container to hold the track data retrieved from the frame.
ArTrackDataList* fetched_track_data_list;
ArTrackDataList_create(ar_session, &fetched_track_data_list);

// Fetch the track data from the frame into the created container.
ArFrame_getUpdatedTrackData(ar_session, frame, uuid_byte_array,
                            fetched_track_data_list);

當 ArTrackData 位於容器物件中後，擷取自訂資料的位元組。

// Fetch the size of the track data list.
int32_t fetched_track_data_list_size;
ArTrackDataList_getSize(ar_session, fetched_track_data_list,
                        &fetched_track_data_list_size);

// Iterate through the list.
for (int i = 0; i < fetched_track_data_list_size; i++) {
  ArTrackData* fetched_track_data;
  ArTrackDataList_acquireItem(ar_session, fetched_track_data_list, i,
                              &fetched_track_data);
  // Process "fetched_track_data->sample" as desired
  ArTrackData_release(fetched_track_data);
}
ArTrackDataList_destroy(fetched_track_data_list);

後續步驟