Interface IGraphicsModule
interface IGraphicsModule
Extends com.amazon.apmf.IStandard
Top-level graphics module and factory for all graphics components.
IGraphicsModule is the canonical entry point into the graphics API domain. It
provides the factory methods for creating display controllers, GPU
devices, windows, media and streaming surfaces, graphics buffers, color
converters, and related graphics objects.
Default Component: /com.amazon.kepler.graphics
Example usage:
Methods
createDisplayControllerForApp()
Creates a display controller to access various display and other display related resources. This API is targeted for App component clients.IDisplayController*createDisplayControllerForApp(com.amazon.kepler.runtime.IComponentInstance*componentInstance,IDisplayControllerListener?listener)
Parameters
componentInstance
com.amazon.kepler.runtime.IComponentInstance* — Required
the app component that owns this display controller.
listener
IDisplayControllerListener? — Optional
optional IDisplayControllerListener; pass null to create a controller
without display controller event callbacks.
Returns
IDisplayController*
IDisplayController device which can query mode and other display information
Throws
DeviceError— if display subsystem is not in valid stateInvalidArgumentError— if an input argument is non-null but otherwise invalidNullPointerError— if a required (non-null) input argument is nullOutOfMemoryError— if device is out of memory
createDisplayControllerForSystemClients()
Creates a display controller to access various display and other display related resources. This API is targeted for system services.IDisplayController*createDisplayControllerForSystemClients(IDisplayControllerListener?listener)
Parameters
listener
IDisplayControllerListener? — Optional
optional IDisplayControllerListener; pass null to create a controller
without display controller event callbacks.
Returns
IDisplayController*
IDisplayController device which can query mode and other display information
Throws
DeviceError— if display subsystem is not in valid stateInvalidArgumentError— if an input argument is non-null but otherwise invalidOutOfMemoryError— if device is out of memory
createGpuDeviceUsingOpenGlesApi()
Creates a GPU device for rendering, returning the latest version of OpenGL ES supported by the system. See [IGpuDevice#getRenderingCapabilities].IGpuDevice*createGpuDeviceUsingOpenGlesApi(IDisplayController*device)
Parameters
device
IDisplayController* — Required
display device
Returns
IGpuDevice*
IGpuDevice that renders using the OpenGL ES API
Throws
DeviceError— if display subsystem is not in valid stateNullPointerError— if a required (non-null) input argument is nullOutOfMemoryError— if device is out of memory
createGpuDeviceUsingVulkanApi()
Creates a GPU device for rendering using the Vulkan API, returning the latest version of Vulkan supported by the system. See [IGpuDevice#getRenderingCapabilities]. The Vulkan API is not supported on current platforms; on such platforms this method always throws DeviceError. Use createGpuDeviceUsingOpenGlesApi for GPU rendering until Vulkan support is added.IGpuDevice*createGpuDeviceUsingVulkanApi(IDisplayController*device)
Parameters
device
IDisplayController* — Required
display device
Returns
IGpuDevice*
IGpuDevice that renders using the Vulkan API
Throws
DeviceError— if the Vulkan API is not supported on the current platform, or if the display subsystem is not in a valid stateOutOfMemoryError— if device is out of memory
createWindow()
Creates a Window and attaches it to a GPU device for rendering. Window is created by default as opaque. If requested width and height are both zero, then a full-screen window based on ICanvasConfig size is created. If both are non-zero, then display-subsystem would try to respect the size but it may be overridden by the Window Manager. Register an [IResizeListener] via [IWindow#addResizeListener] to observe the actual size of the window. The same is true for position as well. Default position is (0,0) and requested position(non zero x and y) may be overridden by the Window Manager. Register an [IPositionListener] via [IWindow#addPositionListener] to observe the actual position. Position and size are expected in logical pixels as per ICanvasConfig.IWindow*createWindow(IDisplayController*device,stringtitle,WindowRolewindowRole,i32requestedWidth,i32requestedHeight,i32requestedPosX,i32requestedPosY)
Parameters
device
IDisplayController* — Required
display device
title
string — Required
Window title
windowRole
WindowRole — Required
Window role
requestedWidth
i32 — Required
Requested width
requestedHeight
i32 — Required
Requested height
requestedPosX
i32 — Required
Requested position ‘x’ (top left)
requestedPosY
i32 — Required
Requested position ‘y’ (top left)
Returns
IWindow*
IWindow with title and appId set
Throws
DeviceError— if display subsystem is not in valid stateNullPointerError— if any input argument is null pointer while a non-null one is expectedInvalidArgumentError— if any input argument is invalidOutOfMemoryError— if device is out of memory
createMediaSurface()
Creates a media surface which can be used to show media buffers for a window.IMediaSurface*createMediaSurface(IDisplayController*device,i64windowHandle)
Parameters
device
IDisplayController* — Required
display subsystem instance
windowHandle
i64 — Required
handle of the window where the source of buffers will be presented.
Returns
IMediaSurface*
IMediaSurface
Throws
DeviceError— if display subsystem is not in valid stateNullPointerError— if any input argument is null pointer while a non-null one is expectedInvalidArgumentError— if any input argument is invalidOutOfMemoryError— if device is out of memory
createTargetProperties()
Creates a TargetProperties for use with [IMediaSurface#presentBuffer].ITargetProperties*createTargetProperties()
Returns
ITargetProperties*
ITargetProperties
Throws
OutOfMemoryError— if device is out of memory
createGraphicsBuffer()
Creates a graphics buffer.com.amazon.kepler.buffer.IBufferGroup*createGraphicsBuffer(i32width,i32height,BufferPixelFormat*format,BufferMime*mimeType,BufferUsage*usage)
Parameters
width
i32 — Required
Buffer width
height
i32 — Required
Buffer height
format
BufferPixelFormat* — Required
Buffer format
mimeType
BufferMime* — Required
Buffer MIME type
usage
BufferUsage* — Required
Buffer usage
Returns
com.amazon.kepler.buffer.IBufferGroup*
IBufferGroup representing a graphics buffer
Throws
DeviceError— if display subsystem is not in valid stateNullPointerError— if any input argument is null pointer while a non-null one is expectedInvalidArgumentError— if any input argument is invalidOutOfMemoryError— if device is out of memory
createGraphicsBufferFromFdMetadata()
Creates a graphics buffer from a list of file descriptors and associated metadata.com.amazon.kepler.buffer.IBufferGroup*createGraphicsBufferFromFdMetadata(com.amazon.apmf.IFileDescriptor*[]fdList,GraphicsBufferGroupData*graphicsBufferGroupData)
Parameters
fdList
com.amazon.apmf.IFileDescriptor*[] — Required
list of FD
graphicsBufferGroupData
GraphicsBufferGroupData* — Required
graphics buffer group data containing meta data about the buffer
Returns
com.amazon.kepler.buffer.IBufferGroup*
IBufferGroup representing a graphics buffer
Throws
DeviceError— if display subsystem is not in valid stateNullPointerError— if any input argument is null pointer while a non-null one is expectedInvalidArgumentError— if any input argument is invalidOutOfMemoryError— if device is out of memory
createColorConverter()
Creates a color converter interface which can be used to convert a buffer of a specific source format to another destination buffer of a different formatIColorConverter*createColorConverter(IDisplayController*device,IColorConversionListener*listener)
Parameters
device
IDisplayController* — Required
display device
listener
IColorConversionListener* — Required
color converter listener. Result of asynchronous operations are notified via IColorConversionListener.
Returns
IColorConverter*
IColorConverter converter object
Throws
DeviceError— if display subsystem is not in valid stateNullPointerError— if any input argument is null pointer while a non-null one is expectedInvalidArgumentError— if any input argument is invalidOutOfMemoryError— if device is out of memory
createStreamingSurface()
Creates a streaming surface which represents a special kind of surface for presenting 3D content coming as media frames. This surface is typically associated with applications which present 3D content which has been rendered somewhere else outside the application process.IStreamingSurface*createStreamingSurface(IDisplayController*displayController,i64windowHandle)
Parameters
displayController
IDisplayController* — Required
display controller object. [IGraphicsModule#createDisplayControllerForApp]
windowHandle
i64 — Required
handle of the window where the source of buffers will be presented. [IWindow#getHandle].
Returns
IStreamingSurface*
IStreamingSurface The surface to present media buffers
Throws
DeviceError— if display subsystem is not in valid stateNullPointerError— if any input argument is null pointer while a non-null one is expectedInvalidArgumentError— if any input argument is invalidOutOfMemoryError— if device is out of memory
createMemoryStats()
Creates a MemoryStats interface which can be used to get memory related stats of the client invoking this API.IMemoryStats*createMemoryStats()
Returns
IMemoryStats*
IMemoryStats object
Throws
OutOfMemoryError— if device is out of memory
