Amazon AppStream
Developer Guide

This documentation is for an older version of Amazon AppStream. For information about the latest version, see the Amazon AppStream 2.0 Developer Guide.

Streaming Video to a Client

In order to stream video frames to the client, your application calls the XStxServerSetVideoSource function of the XStxServer object to specify the source of video frames. For more information, see Initializing a Client Session. You must also define the mode that your application will use to stream frames to the client.

Choosing a Video Mode

To support a variety of applications, Amazon AppStream provides three strategies for streaming video:

  • Push with frame-rate blocking—Calls to XStxServerPushVideoFrame() will block until enough time has elapsed to gate the video frame rate of the application to that specified by XStxIVideoSourceFcnSetFrameRate(). The amount of time blocked varies dynamically with changes to the target frame rate and the time it takes to generate frames. To use this strategy, set the video mode to XSTX_VIDEO_MODE_PUSH_BLOCKING.

  • Push immediately—Calls to XStxServerPushVideoFrame() will return immediately. If calls are received faster than the frame rate indicated by the last call to XStxIVideoSourceFcnSetFrameRate() then frames will be dropped from the video stream to achieve the target frame rate. To use this strategy, set the video mode to XSTX_VIDEO_MODE_PUSH_IMMEDIATE.

  • Pull—Video frames will be pulled from the application by calls to XStxIVideoSourceFcnGetFrame(). The thread making those calls will delay as necessary to limit the frame rate. The application is free to perform operations on this thread as long as it returns before the next frame is due. To use this strategy, set the video mode to XSTX_VIDEO_MODE_PULL.

The sample application uses the immediate push mode, as shown in the following excerpt from main.cpp. This file is in the <SDK_dir>\example_src\server\windows\SimpleDirectXServer directory.

static XStxResult getVideoMode(void* context, XStxVideoMode* mode) { // We push frames to AppStream when we want to. // AppStream will adapt by dropping frames if we're too fast *mode = XSTX_VIDEO_MODE_PUSH_IMMEDIATE; return XSTX_RESULT_OK; }

Choosing a Color Subsampling Rate

Amazon AppStream streams the video at the YUV420 color subsampling rate to client applications. You can set your streaming application to stream video at the YUV444 color subsampling rate to a client application running on supported devices. The streaming application calls the XStxServerAddChromaSamplingOption() function to notify Amazon AppStream that the streaming application supports the YUV444 color subsampling option. The client application calls a similar function to also notify Amazon AppStream that the client application supports the YUV444 color subsampling option.

When the client application connects to the streaming application, Amazon AppStream compares the color subsampling options available on the client application and the streaming application. Amazon AppStream then selects the highest color resolution supported by both applications and then informs both applications which color sampling option will be used for the session. Amazon AppStream then calls the XStxIServerListener2FcnServerConfigurationSettingsReceived callback function that the streaming application supplied and passes a structure with the XStxChromaSampling setting.


Streaming at the YUV444 subsampling rate requires higher bandwidth availability than the YUV420 rate.

The following code excerpt demonstrates how to use the YUV444 color subsampling option.

/** * Inform the server of server application's chroma sampling capability. * You can call this as many times as you want for each chroma sampling * listed in XStxChromaSampling. If this method is never called, then * XSTX_CHROMA_SAMPLING_YUV420 will be used by default chroma sampling. * Register a callback function at XStxIVideoSourceFcnSetChromaSampling * so that STX server can notify server application which chroma sampling * will be used for streaming. * @param[in] serverHandle The handle of the server. * @param[in] chromaSampling The chroma sampling scheme. Look at XStxAPI.h * @return This function will return one of these values. * Return code | Description * ----------------------------- | ------------------------------------------- * XSTX_RESULT_OK | The operation is successful. * XSTX_RESULT_INVALID_HANDLE | serverHandle is invalid. * XSTX_RESULT_INVALID_ARGUMENTS | chromaSampling is not recognized. */ XSTX_API_EXTERN XStxResult XSTX_API XStxServerAddChromaSamplingOption( XStxServerHandle serverHandle, XStxChromaSampling chromaSampling);

Sending Frames to the Client

If you are converting an existing application to work with Amazon AppStream streaming, you will need to redirect the video output to streaming clients instead of displaying video on the local machine. The following excerpt is from the render function in main.cpp and shows the changes you would make to render the video to clients instead of a local machine.

... EnterCriticalSection(&g_frameCriticalSection); // Don't want to be interrupted now // Copy back buffer data. Can also use D3DXLoadSurfaceFromSurface if we need to resize/change pixel format g_D3DDevice->GetRenderTargetData(g_backBuffer, g_memBuffer); D3DLOCKED_RECT lockedRect; g_memBuffer->LockRect(&lockedRect, NULL, D3DLOCK_READONLY); // Convert to YUV so we can supply it to AppStream switch (g_chromaSamplingType) { case XSTX_CHROMA_SAMPLING_YUV420: convertToYUV420((unsigned char*)lockedRect.pBits, WINDOW_WIDTH, WINDOW_HEIGHT, 2, 1, 0, 4, lockedRect.Pitch, g_videoFrame.mPlanes); break; case XSTX_CHROMA_SAMPLING_YUV444: convertToYUV444((unsigned char*)lockedRect.pBits, WINDOW_WIDTH, WINDOW_HEIGHT, 2, 1, 0, 4, lockedRect.Pitch, g_videoFrame.mPlanes); break; default: assert(!"Unknown chroma sampling type"); // Make sure we don't get an unknown chroma sampling type } g_memBuffer->UnlockRect(); XStxServerPushVideoFrame(g_serverHandle, &g_videoFrame); // Push the video frame LeaveCriticalSection(&g_frameCriticalSection); ...