> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XAppCaptureRecordTimespan

> XAppCaptureRecordTimespan

# XAppCaptureRecordTimespan

进行 GameDVR 录制。没有 UI 提示正在进行此类录制。用户无法访问该录制。任意时刻最多可以有 2 个此类录制。一旦创建了 2 个录制，就需要调用 [XAppCaptureCloseLocalStream](/reference/system/xappcapture/functions/xappcapturecloselocalstream) 关闭并删除一个录制后，才能进行另一个录制。这可用于捕获过去或将来的活动。

## Syntax

```cpp theme={null}
HRESULT XAppCaptureRecordTimespan(
  const SYSTEMTIME * startTimestamp,
  uint64_t durationInMilliseconds,
  XAppCaptureLocalResult * result
)
```

### Parameters

*startTimestamp* \_In\_opt\_\
类型：const SYSTEMTIME \*

开始录制的时间戳。此参数可以为 null，此时系统会自动将开始时间计算为过去的 *durationInMilliseconds*，录制中将包含过去的活动。

*durationInMilliseconds* \_In\_\
类型：uint64\_t

录制的长度（以毫秒为单位）。

*result* \_Out\_\
类型：XAppCaptureLocalResult \*

在函数完成时，包含捕获结果。有关如何读取生成的录制，请参阅 [XAppCaptureReadLocalStream](/reference/system/xappcapture/functions/xappcapturereadlocalstream)。

### Return value

类型：HRESULT

函数结果。

如果用户的 GameDVR 设置禁止游戏进行捕获，则该函数将返回 E\_ACCESSDENIED。

## Remarks

有两种方式传入 *startTimestamp* 参数以录制过去的活动。

第一种方式是传入 null。系统会自动计算时间戳，并录制从现在起过去 *durationInMilliseconds* 长的活动。

<Note>当分配的空间被填满时，较旧的剪辑将被删除以为新剪辑腾出空间。请使用 [PLS](/reference/system/xpersistentlocalstorage/xpersistentlocalstorage_members)（持久本地存储）、已连接存储（例如 [XGameSave](/reference/system/xgamesave/xgamesave_members) 或 [XGameSaveFiles](/reference/system/xgamesavefiles/xgamesavefiles_members)）或类似的存储系统，以在设定的时间段内保留剪辑。</Note>

```cpp theme={null}
XAppCaptureLocalResult appCaptureLocalResult = { 0 };
uint64_t durationInMs = 5000; /* 5 seconds, for example */

if (SUCCEEDED(XAppCaptureRecordTimespan(nullptr, durationInMs, &appCaptureLocalResult))) // record the past 5000ms (startTimestamp is calculated automatically)
{
    appLog.AddLog("StartTimestamp: %llu, Duration (ms): %llu, File Size (bytes): %llu, Width: %d, Height: %d, Encoding: %d, Color Format: %d\n", appCaptureLocalResult.clipStartTimestamp, appCaptureLocalResult.durationInMilliseconds, appCaptureLocalResult.fileSizeInBytes,
        appCaptureLocalResult.width, appCaptureLocalResult.height, appCaptureLocalResult.encoding, appCaptureLocalResult.colorFormat);
}
```

在第二种方式中，你必须通过将 SYSTEMTIME 或 FILETIME 转换为 ULARGE\_INTEGER、执行必要的算术运算、然后将 ULARGE\_INTEGER 转换回 SYSTEMTIME，来计算所需的开始时间戳。

```cpp theme={null}
void SubtractMsDurationFromFileTimeToULarge(_In_ FILETIME* pFileTime, _In_ uint64_t durationInMs, _Out_ ULARGE_INTEGER* pUlResultingTime)
{
    ULARGE_INTEGER fileTimeAsUlarge;

    fileTimeAsUlarge.LowPart = pFileTime->dwLowDateTime;
    fileTimeAsUlarge.HighPart = pFileTime->dwHighDateTime;

    // Convert ms to 100 ns intervals, the convention used by FILETIME
    pUlResultingTime->QuadPart = fileTimeAsUlarge.QuadPart - (durationInMs * 10000LL);
}

void ULargeToSystemTime(_In_ ULARGE_INTEGER ulInputTime, _Out_ SYSTEMTIME* pOutputTime)
{
    FILETIME inputAsFiletime;

    inputAsFiletime.dwLowDateTime = ulInputTime.LowPart;
    inputAsFiletime.dwHighDateTime = ulInputTime.HighPart;

    FileTimeToSystemTime(&inputAsFiletime, pOutputTime);
}

void YourFunction()
{
    XAppCaptureLocalResult appCaptureLocalResult = { 0 }; 
    uint64_t durationInMs = 8000; /* 8 seconds, for example */
    FILETIME now;
    ULARGE_INTEGER calculatedStartTimestamp;
    SYSTEMTIME startTimestampAsSystemTime;
    XAppCaptureVideoCaptureSettings captureSettings = { 0 };

    GetSystemTimeAsFileTime(&now);
    SubtractMsDurationFromFileTimeToULarge(&now, durationInMs, &calculatedStartTimestamp);
    ULargeToSystemTime(calculatedStartTimestamp, &startTimestampAsSystemTime);
    
    if (SUCCEEDED(XAppCaptureGetVideoCaptureSettings(&captureSettings)) && captureSettings.isCaptureByGamesAllowed && (captureSettings.maxRecordTimespanDurationInMs >= durationInMs)){
        if (SUCCEEDED(XAppCaptureRecordTimespan(&startTimestampAsSystemTime, durationInMs, &appCaptureLocalResult))) // record 8000ms starting from 8000ms before now (calculated manually)
        {
            appLog.AddLog("StartTimestamp: %llu, Duration (ms): %llu, File Size (bytes): %llu, Width: %d, Height: %d, Encoding: %d, Color Format: %d\n", appCaptureLocalResult.clipStartTimestamp, appCaptureLocalResult.durationInMilliseconds, appCaptureLocalResult.fileSizeInBytes,
                appCaptureLocalResult.width, appCaptureLocalResult.height, appCaptureLocalResult.encoding, appCaptureLocalResult.colorFormat);
        }
    }
}
```

XAppCaptureRecordTimespan 也可以用于录制接下来 *durationInMilliseconds* 毫秒的活动，方法是将 *startTimestamp* 指定为当前系统时间。

```cpp theme={null}
XAppCaptureLocalResult appCaptureLocalResult = { 0 }; 
uint64_t durationInMs = 10000; /* 10 seconds, for example */
SYSTEMTIME nowStartTimestamp;
XAppCaptureVideoCaptureSettings captureSettings = { 0 };

GetSystemTime(&nowStartTimestamp);

if (SUCCEEDED(XAppCaptureGetVideoCaptureSettings(&captureSettings)) && captureSettings.isCaptureByGamesAllowed){
    if (SUCCEEDED(XAppCaptureRecordTimespan(&nowStartTimestamp, durationInMs, &appCaptureLocalResult))) // record the next 10 seconds starting now
    {
        appLog.AddLog("StartTimestamp: %llu, Duration (ms): %llu, File Size (bytes): %llu, Width: %d, Height: %d, Encoding: %d, Color Format: %d\n", appCaptureLocalResult.clipStartTimestamp, appCaptureLocalResult.durationInMilliseconds, appCaptureLocalResult.fileSizeInBytes,
            appCaptureLocalResult.width, appCaptureLocalResult.height, appCaptureLocalResult.encoding, appCaptureLocalResult.colorFormat);
    }
}
```

请参阅 [XAppCaptureLocalResult](/reference/system/xappcapture/structs/xappcapturelocalresult) 和 [XAppCaptureReadLocalStream](/reference/system/xappcapture/functions/xappcapturereadlocalstream)

## Requirements

**头文件：** XAppCapture.h

**库：** xgameruntime.lib

**受支持的平台：** XBOX One 系列主机和 XBOX Series 主机

## See also

[XAppCapture members](/reference/system/xappcapture/xappcapture_members)


## Related topics

- [XAppCaptureLocalResult](/zh-CN/reference/system/xappcapture/structs/xappcapturelocalresult.md)
- [XAppCaptureReadLocalStream](/zh-CN/reference/system/xappcapture/functions/xappcapturereadlocalstream.md)
- [XAppCaptureGetVideoCaptureSettings](/zh-CN/reference/system/xappcapture/functions/xappcapturegetvideocapturesettings.md)
- [XAppCapture](/zh-CN/reference/system/xappcapture/xappcapture_members.md)
- [面向 GDK 的 Unity C# API 包装器](/zh-CN/build/gdk-and-engines/unity/unity-api-wrappers.md)