CoreApplication.Restart Method (String, RestartImageInfo, IBuffer, RestartFlags, Object)

Use Restart in your title to terminate the current instance of the title and start a new instance.

A common use of Restart is when a title is structured to use different DLLs when playing different game modes, such as single player vs. multiplayer. Rather than loading DLLs for both modes at all times, title code can switch from one mode to the other by calling Restart and specifying in the uri parameters that indicate the new mode. When the title code restarts, it can load the appropriate DLLs for the new mode, and avoid loading DLLs that will not be used.

Note If multiple versions of the same title exist, for example release, debug, etc., the currently running version will be launched again when the title is restarted. This occurs even if a default App User Mode ID has been previously set using xbapp setdefaultapp.

Syntax

public:
static void Restart(
         String^ uri,
         RestartImageInfo restartInfo,
         IBuffer^ pixels,
         RestartFlags flags,
         Object^ context
)

Parameters

uri
Type: String

A deep linking URI.

restartInfo
Type: RestartImageInfo

Structure contianing the width, height and row pitch of the image pixels in the pixels argument.

pixels
Type: IBuffer

A buffer containing the pixel data for the restart image. The image should have a 16:9 aspect ratio to properly line up with where the game will render.

flags
Type: RestartFlags

Flags specifying the restart behavior.

context
Type: Object

Reserved for future use. Do not use this parameter.

Remarks

Example

The following example shows how to use the Restart method.

#include <windows.storage.streams.h>
#include <robuffer.h>

using namespace Windows::Storage::Streams;


// Put this class somewhere in a helper

class PixelBuffer :
  public RuntimeClass<RuntimeClassFlags<WinRtClassicComMix>,
  ABI::Windows::Storage::Streams::IBuffer,
  IBufferByteAccess>
{
public:
  PixelBuffer()
  {
    ZeroMemory(&_textureDesc, sizeof(_textureDesc));
    ZeroMemory(&_mappedData, sizeof(_mappedData));
  }

  HRESULT RuntimeClassInitialize(
    _In_ ID3D11DeviceContext* context,
    _In_ ID3D11Texture2D* sourceTexture
    )
  {
    if (context == nullptr || sourceTexture == nullptr)
    {
      return E_INVALIDARG;
    }

    ComPtr<ID3D11Device> device;

    // Create a CPU mappable staging texture of the desired pixel format.
    // D3D will convert most pixel formats during the copy.
    // Start by reading the desc from the source so we match dimensions

    _context = context;
    sourceTexture->GetDevice(&device);
    sourceTexture->GetDesc(&_textureDesc);

    _textureDesc.ArraySize = 1;
    _textureDesc.BindFlags = 0;
    _textureDesc.CPUAccessFlags = D3D11_CPU_ACCESS_READ;
    _textureDesc.Format = DXGI_FORMAT_B8G8R8A8_UNORM;
    _textureDesc.SampleDesc.Count = 1;
    _textureDesc.Usage = D3D11_USAGE_STAGING;

    HRESULT hr = device->CreateTexture2D(&_textureDesc, nullptr, &_staging);
    if (SUCCEEDED(hr))
    {
      // Copy render target to the staging texture
      context->CopyResource(_staging.Get(), sourceTexture);

      // Map the staging texture, and send to Restart
      hr = context->Map(_staging.Get(), 0, D3D11_MAP_READ, 0, &_mappedData);
    }

    return hr;
  }

  HRESULT GetRestartInfo(
    _Out_ RestartImageInfo* restartInfo
    )
  {
    if (restartInfo == nullptr)
    {
      return E_INVALIDARG;
    }

    restartInfo->Width = _textureDesc.Width;
    restartInfo->Height = _textureDesc.Height;
    restartInfo->RowPitch = _mappedData.RowPitch;

    return S_OK;
  }

  // IBuffer
  STDMETHODIMP get_Capacity(
    _Out_ UINT32* value
    )
  {
    return get_Length(value);
  }

  STDMETHODIMP get_Length(
    _Out_ UINT32* value
    )
  {
    if (value == nullptr)
    {
      return E_INVALIDARG;
    }
    *value = _mappedData.RowPitch * _textureDesc.Height;
    return S_OK;
  }

  STDMETHODIMP put_Length(
    _In_ UINT32 value
    )
  {
    UNREFERENCED_PARAMETER(value);
    return E_NOTIMPL;
  }

  // IBufferByteAccess
  STDMETHODIMP Buffer(
    _Out_ byte** value
    )
  {
    if (value == nullptr)
    {
      return E_INVALIDARG;
    }
    *value = reinterpret_cast<byte*>(_mappedData.pData);
    return S_OK;
  }

private:
  ~PixelBuffer()
  {
    if (_context != nullptr && _mappedData.pData != nullptr)
    {
      _context->Unmap(_staging.Get(), 0);
      ZeroMemory(&_mappedData, sizeof(_mappedData));
    }
  }

private:
  ComPtr<ID3D11DeviceContext> _context;
  ComPtr<ID3D11Texture2D> _staging;
  D3D11_TEXTURE2D_DESC _textureDesc;
  D3D11_MAPPED_SUBRESOURCE _mappedData;
};

HRESULT GetRestartInfoFromTexture(
  _In_ ID3D11DeviceContext* context,
  _In_ ID3D11Texture2D* texture,
  _Out_ RestartImageInfo* restartInfo,
  _Out_ IBuffer^* pixels
  )
 {
    if (context == nullptr || texture == nullptr || restartInfo == nullptr || pixels == nullptr)
    {
      return E_INVALIDARG;
    }
    ZeroMemory(restartInfo, sizeof(*restartInfo));

    ComPtr<PixelBuffer> buffer;
    HRESULT hr = MakeAndInitialize<PixelBuffer>(&buffer, context, texture);
    if (SUCCEEDED(hr))
    {
      hr = buffer->GetRestartInfo(restartInfo);
      if (SUCCEEDED(hr))
      {
        ComPtr<ABI::Windows::Storage::Streams::IBuffer> pixelBuffer;
        hr = buffer.As(&pixelBuffer);
        if (SUCCEEDED(hr))
        {
          *pixels = reinterpret_cast<IBuffer^>(pixelBuffer.Get());
        }
      }
    }
    return hr;
}

// Call this when you need to restart...

// Get data from back buffer and send to restart
RestartImageInfo restartInfo = {};
IBuffer^ pixels;
ComPtr<ID3D11Texture2D> backbuffer;
m_swapChain->GetBuffer(0, IID_PPV_ARGS(&backbuffer));
HRESULT hr = GetRestartInfoFromTexture(m_d3dContext.Get(), backbuffer.Get(), &restartInfo, &pixels);
if (SUCCEEDED(hr))
{
  CoreApplication::Restart(L"testrestart://foo", restartInfo, pixels, Windows::ApplicationModel::Core::RestartFlags::None, nullptr);
}

Requirements

Namespace: Windows.ApplicationModel.Core

Metadata: windows.winmd