Interface ISurfaceControl
interface ISurfaceControl
Extends com.amazon.apmf.IStandard
ISurfaceControl abstracts all common tasks for surfaces.
Methods
setPreferredRefreshRateInMillihertz()
Request the display server to switch to a new refresh rate desired by this surface. Please note, this is just a request and the display server may receive various refresh rate change requests from different surfaces at the same time. The final refresh rate determined by the display server will depend on which windows are currently visible, current set of all refresh rate change requests and other platform constraints. Clients can also pass a peak refresh rate which the display subsystem will use as an upper limit. This is an asynchronous API and a subsequent IDisplayListener.onRefreshRateChange() callback will be unconditionally called to inform clients whether a new refresh rate has been chosen or not. Based on the onRefreshRateChange() callback, clients can determine the chosen refresh rate and update their presentation timing based on that. Clients are recommended to switch to new presentation timing only after onRefreshRateChange() callback and shouldn’t assume that setPreferredRefreshRateInMillihertz() will actually cause a refresh rate change immediately. Clients should check first that global MRR state is enabled (i.e IDisplay#isMultipleRefreshRateEnabled must return true) and then choose one of the supported refresh rate from IDisplayConfig. getSupportedRefreshRatesInMillihertz while calling setPreferredRefreshRateInMillihertz. If MRR state is false and preferred refresh rate is not supported then client shouldn’t call this API. Clients need to subscribe for the IDisplayListener to be notified of actual refresh rate changes via ‘onRefreshRateChange()’ event. IMediaSurface clients are recommended to use ‘FIXED_SOURCE’ as MrrContentType and ‘ALWAYS’ as MrrTransitionMode. IGraphicsSurface clients can typically adapt their rendering rate hence they are suggested to use ‘ADAPTABLE_SOURCE’ as MrrContentType. Very rarely clients should use ‘SEAMLESS_REQUIRED’ as the benefit of switching to preferred refresh rate outweighs the drawback of few unintended frames. If calling setPreferredRefreshRateInMillihertz() didn’t result into new preferred refresh rate change, then ‘FIXED_SOURCE’ clients may have to perform pull down (potentially causing stuttering) using presentation timestamp (PTS) in IMediaSurface::presentBuffer(). to tell precisely the system when to present a frame.voidsetPreferredRefreshRateInMillihertz(i32preferredRefreshRate,i32peakRefreshRate,MrrContentTypecontentType,MrrTransitionModetransitionMode)
Parameters
preferredRefreshRate
i32 — Required
The new requested desired refresh rate in mHz (millihertz)
peakRefreshRate
i32 — Required
peak refresh rate in mHz (millihertz) requested by client.
contentType
MrrContentType — Required
Content type hint
transitionMode
MrrTransitionMode — Required
Transition mode hint
[MrrContentType] [MrrTransitionMode] [IDisplayListener]
Throws
DeviceError— if ISurfaceControl is not in valid stateInvalidArgumentError— if any input argument is invalid
