> ## 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.

# XAppCaptureReadScreenshotStream

> XAppCaptureReadScreenshotStream

# XAppCaptureReadScreenshotStream

讀取螢幕擷取畫面串流。

## 語法

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

### 參數

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

呼叫 [XAppCaptureOpenScreenshotStream](/zh-TW/reference/system/xappcapture/functions/xappcaptureopenscreenshotstream) 所傳回的螢幕擷取畫面串流控制代碼。

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

串流中開始讀取的位置。

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

要從串流中讀取的位元組數。

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

用來包含 **XAppCaptureReadScreenshotStream** 所讀取之位元組的緩衝區。

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

實際寫入 *buffer* 的位元組數。

### 傳回值

類型：HRESULT

函式結果。

## 備註

<Note>在時間敏感執行緒上呼叫此函式並不安全。如需詳細資訊，請參閱[時間敏感執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)。</Note>

讀取螢幕擷取畫面之前，您必須使用 [XAppCaptureOpenScreenShotStream](/zh-TW/reference/system/xappcapture/functions/xappcaptureopenscreenshotstream) 開啟螢幕擷取畫面串流。這會產生 *handle* 參數所需的 **XAppCaptureScreenshotStreamHandle**。接著您可以呼叫此函式來讀取螢幕擷取畫面。*startPosition* 和 *bytesToRead* 參數可讓您讀取螢幕擷取畫面的一部分，這在一次讀取大型串流的一部分時很有用。您可以從 [XAppCaptureOpenScreenShotStream](/zh-TW/reference/system/xappcapture/functions/xappcaptureopenscreenshotstream) 中的 *totalBytes* 輸出參數取得串流的總大小。輸出參數 *buffer* 和 *bytesWritten* 可協助您準確讀取此函式傳回的資料。讀取螢幕擷取畫面資料之後，請使用 [XAppCaptureCloseScreenshotStream](/zh-TW/reference/system/xappcapture/functions/xappcaptureclosescreenshotstream) 關閉螢幕擷取畫面串流，以避免記憶體流失。

```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);

```

## 需求

**標頭：** XAppCapture.h

**程式庫：** xgameruntime.lib

**支援的平台：** Windows、XBOX One 系列主機和 XBOX Series 主機

## 概念文件

* [時間敏感執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## 另請參閱

[GameDVR 概觀](/zh-TW/build/console-features/game-dvr/gamedvr-broadcast)\
[XAppCapture 成員](/zh-TW/reference/system/xappcapture/xappcapture_members)\
[XAppCaptureOpenScreenShotStream](/zh-TW/reference/system/xappcapture/functions/xappcaptureopenscreenshotstream)\
[XAppCaptureTakeScreenshot](/zh-TW/reference/system/xappcapture/functions/xappcapturetakescreenshot)\
[XAppCaptureCloseScreenshotStream](/zh-TW/reference/system/xappcapture/functions/xappcaptureclosescreenshotstream)


## Related topics

- [XAppCaptureReadScreenshotStream](/reference/system/xappcapture/functions/xappcapturereadscreenshotstream.md)
- [XAppCaptureScreenshotStream](/reference/system/xappcapture/structs/xappcapturescreenshotstream.md)
- [XAppCaptureTakeScreenshot](/reference/system/xappcapture/functions/xappcapturetakescreenshot.md)