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

# XUserGetGamerPictureAsync

> XUserGetGamerPictureAsync

# XUserGetGamerPictureAsync

以非同步方式擷取特定使用者的玩家圖片。

## 語法

```cpp theme={null}
HRESULT XUserGetGamerPictureAsync(  
         XUserHandle user,  
         XUserGamerPictureSize pictureSize,  
         XAsyncBlock* async  
)  
```

### 參數

*user*   \_In\_\
類型：XUserHandle

要擷取其玩家圖片的使用者。

*pictureSize*   \_In\_\
類型：[XUserGamerPictureSize](/zh-TW/reference/system/xuser/enums/xusergamerpicturesize)

要擷取的玩家圖片大小。

*async*   \_Inout\_\
類型：[XAsyncBlock\*](/zh-TW/reference/system/xasync/structs/xasyncblock)

用於輪詢呼叫狀態及擷取呼叫結果的 [XAsyncBlock](/zh-TW/reference/system/xasync/structs/xasyncblock)。

### 傳回值

類型：HRESULT

HRESULT 成功或錯誤碼。\
如需錯誤碼清單，請參閱[錯誤碼](/zh-TW/reference/errorcodes)。

## 備註

「顯示名稱與玩家圖片」XR 列出了使用者名稱和虛擬人偶影像顯示方式的特定需求。
如需詳細資訊，請參閱 XBOX One 遊戲和中樞應用程式的 XBOX 需求 [(XBOX 開發人員下載->合作夥伴、發行和發行管理資訊->XGD 合作夥伴文件)](https://www.microsoft.com/software-download/devcenter)。

若要擷取呼叫 [XUserGetGamerPictureAsync](/zh-TW/reference/system/xuser/functions/xusergetgamerpictureasync) 的結果，請呼叫
[XUserGetGamerPictureResult](/zh-TW/reference/system/xuser/functions/xusergetgamerpictureresult)。

若要擷取 [XUserGetGamerPictureResult](/zh-TW/reference/system/xuser/functions/xusergetgamerpictureresult) 擷取
[XUserGetGamerPictureAsync](/zh-TW/reference/system/xuser/functions/xusergetgamerpictureasync) 所傳回之玩家圖片所需的緩衝區大小，請呼叫
[XUserGetGamerPictureResultSize](/zh-TW/reference/system/xuser/functions/xusergetgamerpictureresultsize)。

傳回的玩家圖片格式為 .PNG 格式影像。圖片大小最多可達 2^32
位元組。

下列範例示範如何載入玩家圖片。

```cpp theme={null}
HRESULT LoadGamerPicComplete(XAsyncBlock* abResult)
{
    try
    {
        struct CreateTextureContext
        {
            User* This;
            ImTextureID TextureId;
            std::vector<unsigned char> GamerpicBuffer;
        };

        auto context = std::make_unique<CreateTextureContext>();
        context->This = this;
        context->TextureId = IMTEXTUREID_INVALID;

        // Get the buffer size and set up a buffer to contain it
        size_t bufferSize;
        RETURN_IF_FAILED(XUserGetGamerPictureResultSize(abResult, &bufferSize));
        context->GamerpicBuffer.resize(bufferSize);

        size_t bufferUsed;
        RETURN_IF_FAILED(XUserGetGamerPictureResult(
            abResult,
            context->GamerpicBuffer.size(),
            context->GamerpicBuffer.data(),
            &bufferUsed));
        FAIL_FAST_HR_IF(E_UNEXPECTED, bufferSize != bufferUsed);

        // Create some async work to create a dx texture off the UI thread
        // and then set the texture id back on the UI thread
        auto abCreateTexture = std::make_unique<XAsyncBlock>();
        ZeroMemory(abCreateTexture.get(), sizeof(*abCreateTexture));
        abCreateTexture->queue = abResult->queue;
        abCreateTexture->context = context.get();

        // Set the texture id in the completion on the UI thread
        abCreateTexture->callback = [](XAsyncBlock* ab)
        {
            auto context = static_cast<CreateTextureContext*>(ab->context);
            context->This->_textureId = context->TextureId;
            delete context;
            delete ab;
        };

        // Worker will create the texture on a work thread
        auto createTextureWorker = [](XAsyncBlock* ab) -> HRESULT
        {
            auto context = static_cast<CreateTextureContext*>(ab->context);
            auto dimension = GetDimensionFromSize(GamerPicSize);
            RETURN_IF_FAILED(CreateTextureFromPng(context->GamerpicBuffer.data(), context->GamerpicBuffer.size(), &context->TextureId));
            return S_OK;
        };

        // Create the texture on a work thread
        if (SUCCEEDED_LOG(XAsyncRun(abCreateTexture.get(), createTextureWorker)))
        {
            context.release();
            abCreateTexture.release();
        }
    }
    CATCH_RETURN();
    return S_OK;
}

HRESULT LoadGamerPicAsync(XTaskQueueHandle queue, uint32_t cancelTime = 0)
{
    auto asyncBlock = std::make_shared<XAsyncBlock>();
    ZeroMemory(asyncBlock.get(), sizeof(*asyncBlock));
    asyncBlock->queue = queue;

    struct GamerPicContext
    {
        User* User;
        std::shared_ptr<XAsyncBlock> AsyncBlock;
    };

    auto context = std::make_unique<GamerPicContext>();
    context->User = this;
    context->AsyncBlock = asyncBlock;
    asyncBlock->context = context.get();

    asyncBlock->callback = [](XAsyncBlock* ab)
    {
        std::unique_ptr<GamerPicContext> context(reinterpret_cast<GamerPicContext*>(ab->context));
        LOG_IF_FAILED(context->User->LoadGamerPicComplete(ab));
    };

    if (cancelTime != 0)
    {
        std::thread cancelThread(
            [asyncBlock]()
        {
            std::this_thread::sleep_for(std::chrono::milliseconds(5000));
            XAsyncCancel(asyncBlock.get());
        });

        cancelThread.detach();
    }

    if (SUCCEEDED_LOG(XUserGetGamerPictureAsync(_handle.get(), GamerPicSize, asyncBlock.get())))
    {
        context.release();
    }

    return S_OK;
}
```

## 需求

**標頭：** XUser.h

**程式庫：** xgameruntime.lib

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

## 概念文件

* [非同步程式設計設計目標與改進](/zh-TW/build/core-features/common/async/async-whitepaper)

## 另請參閱

[XUser](/zh-TW/reference/system/xuser/xuser_members)

[XUserGetGamerPictureResult](/zh-TW/reference/system/xuser/functions/xusergetgamerpictureresult)

[XUserGetGamerPictureResultSize](/zh-TW/reference/system/xuser/functions/xusergetgamerpictureresultsize)


## Related topics

- [XUserGetGamerPictureAsync](/reference/system/xuser/functions/xusergetgamerpictureasync.md)
- [XUserGamerPictureSize](/reference/system/xuser/enums/xusergamerpicturesize.md)
- [XUserGetGamerPictureResultSize](/reference/system/xuser/functions/xusergetgamerpictureresultsize.md)
- [XUserGetGamerPictureResult](/reference/system/xuser/functions/xusergetgamerpictureresult.md)