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

# XAppCaptureReadScreenshotStream

> XAppCaptureReadScreenshotStream

# XAppCaptureReadScreenshotStream

读取屏幕截图流。

## Syntax

```cpp theme={null}
HRESULT XAppCaptureReadScreenshotStream(  
         XAppCaptureScreenshotStreamHandle handle,  
         uint64_t startPosition,  
         uint32_t bytesToRead,  
         uint8_t* buffer,  
         uint32_t* bytesWritten  
)  
```

### Parameters

*handle*   \_In\_\
类型：XAppCaptureScreenshotStreamHandle

通过调用 [XAppCaptureOpenScreenshotStream](https://docs.xbox.com/zh-CN/reference/system/xappcapture/functions/xappcaptureopenscreenshotstream.md) 返回的屏幕截图流句柄。

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

流中开始读取的位置。

*bytesToRead*   \_In\_\
类型：uint32\_t

要读取的流中的字节数。

*buffer*   \_Out\_writes\_to\_(bytesToRead,*bytesWritten)\
类型：uint8\_t*

用于容纳 **XAppCaptureReadScreenshotStream** 读取的字节的缓冲区。

*bytesWritten*   \_Out\_\
类型：uint32\_t\*

实际写入到 *buffer* 的字节数。

### Return value

类型：HRESULT

函数结果。

## Remarks

> [!NOTE]
>
> 此函数在时间敏感线程上调用不安全。有关详细信息，请参阅[时间敏感线程](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)。

在读取屏幕截图之前，必须使用 [XAppCaptureOpenScreenShotStream](https://docs.xbox.com/zh-CN/reference/system/xappcapture/functions/xappcaptureopenscreenshotstream.md) 打开屏幕截图流。这将生成 *handle* 参数所需的 **XAppCaptureScreenshotStreamHandle**。然后可以调用此函数读取屏幕截图。使用 *startPosition* 和 *bytesToRead* 参数可以读取屏幕截图的某一部分，这对于每次读取大型流的一部分很有用。可以从 [XAppCaptureOpenScreenShotStream](https://docs.xbox.com/zh-CN/reference/system/xappcapture/functions/xappcaptureopenscreenshotstream.md) 的 *totalBytes* 输出参数获取流的总大小。输出参数 *buffer* 和 *bytesWritten* 有助于准确读取此函数返回的数据。读取屏幕截图数据后，使用 [XAppCaptureCloseScreenshotStream](https://docs.xbox.com/zh-CN/reference/system/xappcapture/functions/xappcaptureclosescreenshotstream.md) 关闭屏幕截图流，以避免内存泄漏。

```cpp theme={null}
const int MAX_DATA = 1024;

XAppCaptureTakeScreenshotResult takeScreenshotResult = {0};
XAppCaptureScreenshotStreamHandle handle = nullptr;
XAppCaptureScreenshotFormatFlag screenshotFormat = XAppCaptureScreenshotFormatFlag::SDR;

BYTE buffer[MAX_DATA];
HANDLE file = INVALID_HANDLE_VALUE;
UINT64 totalBytesRead = 0;
UINT64 totalBytesToRead = 0;
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;
}

/* T:\ is one example of a writeable local directory. Be aware that the T:\ drive can be invalidated on suspend or resume, and as such it's better to use Persistant Local Storage */
file = CreateFileA(hdrAvailable ? "T:\\MyScreenshot.jxr" : "T:\\MyScreenshot.png", GENERIC_READ | GENERIC_WRITE, 0, 0, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, 0);
if (file == INVALID_HANDLE_VALUE)
{
    /* You must always call XAppCaptureCloseScreenshotStream on an open XAppCaptureScreenshotStreamHandle to avoid a memory leak */
    FAILED_LOG(XAppCaptureCloseScreenshotStream(handle));
    return;
}

while (totalBytesRead < totalBytesToRead)
{
    uint32_t bytesRead = 0;
    uint32_t bytesWritten = 0;
    if (SUCCEEDED(XAppCaptureReadScreenshotStream(handle, totalBytesRead, sizeof(buffer), buffer, &bytesRead)))
    {
        WriteFile(file, buffer, bytesRead, &bytesWritten, NULL);

        totalBytesRead += bytesRead;
    }
    else
    {
        break;
    }
}

FAILED_LOG(XAppCaptureCloseScreenshotStream(handle));

CloseHandle(file);

```

## Requirements

**头文件：** XAppCapture.h

**库：** xgameruntime.lib

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

## Conceptual documentation

* [时间敏感线程](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## See also

[GameDVR 概述](https://docs.xbox.com/zh-CN/build/console-features/game-dvr/gamedvr-broadcast.md)\
[XAppCapture Members](https://docs.xbox.com/zh-CN/reference/system/xappcapture/xappcapture_members.md)\
[XAppCaptureOpenScreenShotStream](https://docs.xbox.com/zh-CN/reference/system/xappcapture/functions/xappcaptureopenscreenshotstream.md)\
[XAppCaptureTakeScreenshot](https://docs.xbox.com/zh-CN/reference/system/xappcapture/functions/xappcapturetakescreenshot.md)\
[XAppCaptureCloseScreenshotStream](https://docs.xbox.com/zh-CN/reference/system/xappcapture/functions/xappcaptureclosescreenshotstream.md)


## Related topics

- [XAppCaptureTakeScreenshot](https://docs.xbox.com/zh-CN/reference/system/xappcapture/functions/xappcapturetakescreenshot.md)
- [XAppCaptureScreenshotStream](https://docs.xbox.com/zh-CN/reference/system/xappcapture/structs/xappcapturescreenshotstream.md)
- [XAppCapture（API 内容）](https://docs.xbox.com/zh-CN/reference/system/xappcapture/xappcapture_members.md)
- [在 Unity 项目中使用 GDK API 的 C# 包装器](https://docs.xbox.com/zh-CN/build/gdk-and-engines/unity/unity-api-wrappers.md)
- [XAppCaptureOpenScreenshotStream](https://docs.xbox.com/zh-CN/reference/system/xappcapture/functions/xappcaptureopenscreenshotstream.md)