Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases

Console

as

Get Started
Design and Develop
Publish
Reference
Support
Native
Skip to main content

​
Interface IMediaSurface

interface IMediaSurface
Extends com.amazon.apmf.IStandard A high level interface for clients to queue media Buffers for presentation. Any media player can use this interface to present its buffers.

​
Methods

​
setQueueState()

void setQueueState(MediaSurfaceQueueState state)
Client can use this to discard/pause/resume frame presentation

​
Parameters

state
MediaSurfaceQueueState — Required the state want to change to. [MediaSurfaceQueueState]

​
Throws

​
presentBuffer()

PresentResult presentBuffer(com.amazon.kepler.buffer.IBufferGroup* buffer, GraphicsFrameMetadata? graphics_frame_data, ITargetProperties? properties, i64 ptsInNanoSeconds, i64 durationInNanoSeconds)
Queue buffer for presentation. BufferTargetProperties defines the orientation, aspect ratio which needs to be handled before presenting this buffer. In cases where buffer gets rejected due to any reason, release and present buffer events won’t be sent to the application. PresentResult can be used to detect such scenarios. Clients can optionally use the presentation timestamp protocol (PTS) to have more fine grained control to define the time window in which a buffer can be present on the screen. PTS helps display server to determine what is the earliest time a buffer can be presented or if it is too late for a buffer to be presented (i.e discard it). The effective time window essentially becomes timeptsInNanoSeconds, timeptsInNanoSeconds + durationInNanoSeconds.

​
Parameters

buffer
com.amazon.kepler.buffer.IBufferGroup* — Required Buffer you want to present.
graphics_frame_data
GraphicsFrameMetadata? — Optional Frame data for the buffer.
properties
ITargetProperties? — Optional Present properties can be null and it will use default target properties: origin is top left, no rotation, no scaling and target rectangle is considered as the size of current media surface.
ptsInNanoSeconds
i64 — Required The earliest presentation time of the corresponding frame in nanoseconds. This timestamp must be an absolute value in displayClock domain. Can be set to 0 to disable PTS.
durationInNanoSeconds
i64 — Required Expected duration of the frame to be displayed in nanoseconds. Can be set to 0 to disable PTS.

​
Returns

PresentResult The result of present

​
Throws

​
convertAndPresentBuffer()

PresentResult convertAndPresentBuffer(com.amazon.kepler.buffer.IBufferGroup* rgb_buffer, com.amazon.kepler.buffer.IBufferGroup* alpha_buffer, GraphicsFrameMetadata? graphics_frame_data)
Queues buffer for presentation. RGB and alpha values are rendered into one buffer and presented. In cases where buffers are rejected due to any reason, release and present buffer events won’t be sent to the application. PresentResult can be used to detect such scenarios

​
Parameters

rgb_buffer
com.amazon.kepler.buffer.IBufferGroup* — Required Buffer of RGB channels
alpha_buffer
com.amazon.kepler.buffer.IBufferGroup* — Required Buffer of alpha channel
graphics_frame_data
GraphicsFrameMetadata? — Optional Frame data for both rgb_buffer and alpha_buffer- expected to have same frame data.

​
Returns

PresentResult The result of present

​
Throws

​
getSurfaceControl()

ISurfaceControl* getSurfaceControl()
get surface control associated to current rendering surface

​
Returns

ISurfaceControl* ISurfaceControl

​
Throws

  • DeviceError — if IMediaSurface is not in valid state

​
addBufferReleaseListener()

com.amazon.apmf.ISubscription* addBufferReleaseListener(IBufferReleaseListener* listener)
Add buffer release listener when buffer is not used for display. The listener will continue to receive events until ISubscription#unsubscribe() is called or until the event source is destroyed.

​
Parameters

listener
IBufferReleaseListener* — Required Listener interface

​
Returns

com.amazon.apmf.ISubscription* ISubscription related to this listener interface

​
Throws

​
enablePtsSync()

void enablePtsSync(i32 fpsN, i32 fpsD)
Enable Synchronous mode that will enforce strict display/presentation time based on client provided presentation time stamps (PTS). Once set, the client is expected to provide the FrameTimeStamp meta in each presentBuffer(). Display subsystem will disable the ptsSync if the client requests a presentBuffer() without providing the presentation timestamp. This is deprecated. Please use [ISurfaceControl#setPreferredRefreshRateInMillihertz]. The fpsN/fpsD represents the Numerator/Denominator of the source frame rate (rate at which a media stream expected to present frames). These are optional parameters, but the recommendation is to provide them if available.

​
Parameters

fpsN
i32 — Required Numerator of the source frame rate
fpsD
i32 — Required Denominator of the source frame rate

​
Throws

​
getClockId()

DisplayClockId getClockId()
Clients that enabled PTS Sync for MediaSurface should be using this API to get the clockId and expected to provide timestamp in graphics clock domain. The clock identifier value is one of the clockid_t values accepted by clock_gettime(). clock_gettime() is defined by POSIX.1-2001.

​
Returns

DisplayClockId clock id

​
Throws

  • DeviceError — if IMediaSurface is not in valid state

​
getId()

i32 getId()
Query the Id of current IMediaSurface, this id is unique in all IMediaSurfaces.

​
Returns

i32 id of current IMediaSurface

​
Throws

  • DeviceError — if IMediaSurface is not in valid state

​
rebindWindow()

void rebindWindow(i64 sharedWindowHandle)
This can be used to rebind the MediaSurface to a Window in case of remote surface.

​
Parameters

sharedWindowHandle
i64 — Required window handle

​
Throws

Last modified on October 29, 2026