XAppCaptureRecordTimespan

Article
06/22/2023

Makes a GameDVR recording. There is no UI to indicate that such a recording is being made. The user does not have access to the recording. At most 2 such recordings can be made at any given time. Once 2 recordings are made, XAppCaptureCloseLocalStream will need to be called to close & delete a recording before another recording can be made.

Syntax

HRESULT XAppCaptureRecordTimespan(
  const SYSTEMTIME * startTimestamp,
  uint64_t durationInMilliseconds,
  XAppCaptureLocalResult * result
)

Parameters

startTimestamp _In_opt_
Type: const SYSTEMTIME *

The timestamp to start recording from. This parameter can be null, in which case the system will automatically calculate the proper start time to be able to record past activities that are durationInMilliseconds long from now.

durationInMilliseconds _In_
Type: uint64_t

Length of recording in milliseconds.

result _Out_
Type: XAppCaptureLocalResult *

On function completion, contains the capture results.

Return value

Type: HRESULT

Function result.

The function will return E_ACCESSDENIED if the user's GameDVR setting forbids games from making captures.

Remarks

There are two ways to pass in the startTimestamp parameter.

In the first, null is passed. The system will automatically calculate the timestamp and record past activities that are durationInMilliseconds long from now.

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

if (SUCCEEDED(XAppCaptureRecordTimespan(nullptr, durationInMs, &appCaptureLocalResult)))
{
    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);
}

In the second, you must calculate your desired start timestamp by converting SYSTEMTIME or FILETIME to ULARGE_INTEGER, doing the required arithmetic, then converting ULARGE_INTEGER back to SYSTEMTIME.

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 };
    /* 8 seconds, for example. You should call XAppCaptureGetVideoCaptureSettings() to make sure there's sufficient duration available */
    uint64_t durationInMs = 8000;
    FILETIME now;
    ULARGE_INTEGER calculatedStartTimestamp;
    SYSTEMTIME startTimestampAsSystemTime;

    GetSystemTimeAsFileTime(&now);
    SubtractMsDurationFromFileTimeToULarge(&now, durationInMs, &calculatedStartTimestamp));
    ULargeToSystemTime(calculatedStartTimestamp, &startTimestampAsSystemTime));

    if (SUCCEEDED(XAppCaptureRecordTimespan(&startTimestampAsSystemTime, durationInMs, &appCaptureLocalResult)))
    {
        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);
    }
}

See XAppCaptureLocalResult

Requirements

Header: XAppCapture.h

Library: xgameruntime.lib

Supported platforms: Windows, Xbox One family consoles and Xbox Series consoles

Share via