XAppCaptureOpenScreenshotStream

Article
06/22/2023

Opens a screenshot stream.

Syntax

HRESULT XAppCaptureOpenScreenshotStream(  
         const char* localId,  
         XAppCaptureScreenshotFormatFlag screenshotFormat,  
         XAppCaptureScreenshotStreamHandle* handle,  
         uint64_t* totalBytes  
)

Parameters

localId _In_
Type: char*

Local ID of the screenshot returned in XAppCaptureTakeScreenshotResult after calling XAppCaptureTakeScreenshot.

screenshotFormat _In_
Type: XAppCaptureScreenshotFormatFlag

Screenshot format flag returned in XAppCaptureTakeScreenshotResult after calling XAppCaptureTakeScreenshot.

handle _Out_
Type: XAppCaptureScreenshotStreamHandle*

Screenshot stream handle returned as a result of opening the stream.

totalBytes _Out_opt_
Type: uint64_t*

Total number of bytes in the stream.

Return value

Type: HRESULT

Function result.

Remarks

Note

This function isn't safe to call on a time-sensitive thread. For more information, see Time-sensitive threads.

Screenshots are not accessible from the game partition and so you must open a stream in order to retrieve screenshots taken by the user or with XAppCaptureTakeScreenshot. XAppCaptureTakeScreenshot returns a localID in its result which is used in this function to retrieve the proper screenshot. The localID will be valid as long as the screenshot is retained on disk. There is only a limited amount of space on the console in which screenshots are stored. Older screenshots will be deleted when the allotted space is filled. This could potentially cause the open screenshot function to miss on a localID. After opening the stream you may read the screenshot with XAppCaptureReadScreenShotStream. Finally every stream needs to be closed with XAppCaptureCloseScreenshotStream in order to avoid a memory leak.

XAppCaptureTakeScreenshotResult takeScreenshotResult = {0};
XAppCaptureScreenshotStreamHandle handle = nullptr;
UINT64 totalBytesToRead = 0;
XAppCaptureScreenshotFormatFlag screenshotFormat = XAppCaptureScreenshotFormatFlag::SDR;
bool hdrAvailable = false;

/* ... obtain takeScreenshotResult with XAppCaptureTakeScreenshot. Refer to corresponding documentation ... */

hdrAvailable = static_cast<bool>(takeScreenshotResult.availableScreenshotFormats & XAppCaptureScreenshotFormatFlag::HDR);

/* Note: It is optional to obtain the HDR screenshot, if HDR is available. You will need to call XAppCaptureOpenScreenshotStream twice to obtain both SDR and HDR screenshots */
if (hdrAvailable)
{
    screenshotFormat = XAppCaptureScreenshotFormatFlag::HDR;
}

if (FAILED_LOG(XAppCaptureOpenScreenshotStream(takeScreenshotResult.localId, screenshotFormat, &handle, &totalBytesToRead)))
{
    return;
}

appLog.AddLog("%I64d bytes returned\n", totalBytesToRead);

/* You must always call XAppCaptureCloseScreenshotStream on an open XAppCaptureScreenshotStreamHandle to avoid a memory leak */
if (handle != nullptr)
{
    XAppCaptureCloseScreenshotStream(handle);
}

Requirements

Header: XAppCapture.h

Library: xgameruntime.lib

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

Share via