This page provides a high-level overview of the entire Anbox Platform SDK API, including those defined in platform.h, audio_processor.h, graphics_processor.h sensor_processor.h and input_processor.h.

Introduction

The Anbox Platform SDK provides a class based C++ API to implement plugins in. The internal implementation wraps C-based API functions and exposes them for Anbox internal use. The platform plugin implementer only needs to use the stable C++ based API like anbox::Platform, anbox::InputProcessor, anbox::GraphicsProcessor, anbox::SensorProcessor, anbox::AudioProcessor, anbox::GpsProcessor and anbox::CameraProcessor. Any usage of the internal C exposed functions is not guaranteed to be stable and could break at any point.

The intent of the API design is to provide a platform implementation that the Anbox runtime calls into. The plugin shouldn't ever call into Anbox, instead Anbox will always call functions that the plugin implements. Internally this is accomplished with C style ABI compatibility with the exported functions that are dynamically loaded by Anbox. These C functions essentially call the methods of an instance of the anbox::Platform class. They are exported at compile time of the plugin, as the implementation of the SDK is compiled alongside the SDK using CMake interface targets.

The platform plugin should implement an inherited subclass of the anbox::Platform. The resulting platform plugin is a shared library that can be loaded dynamically by external platform instance at Anbox runtime. This dynamic library can have any other external libraries linked to it. The example Audio Streaming Platform platform uses libav (https://www.libav.org/) libraries to encode audio data sent from Anbox and stream it over RTP to an on demand connected client.

The plugin dynamic libary uses the AnboxPlatformDescriptor macro to describe basic information about the plugin needed by Anbox to load the plugin:

field	meaning
platform	The platform class implementation.
name	The name of the platform.
vendor	The vendor name of the platform.
description	The description of the platform.

This macro will generate and export 2 functions which the Anbox runtime then calls into. The 2 functions are an initialize function which creates an instance of the platform object the plugin describes and registers the object with Anbox, as well as a deinitialize function which destroys the object and unregisters the plugin. The name and vendor fields are also used by Anbox to verify platform API version, validate the plugin at external platform startup, and revoke the platform plugin access to Anbox platform if they are invalid.

Abstract classes

anbox::Platform, anbox::Platform::audio_processor, anbox::Platform::graphics_processor, anbox::Platform::sensor_processor, anbox::Platform::graphics_processor and anbox::Platform::input_processor are abstract base classes that are to be implemented by plugins to provide a custom platform, audio processor, and input processor. A platform plugin must implement each subclasses that implements all inherited abstract methods to become a concrete class.

The anbox::Platform class declares the following virtual functions:

The first pure virtual function, anbox::Platform::audio_processor(), returns the audio processor provided by the platform plugin as a anbox::AudioProcessor. Similarly, anbox::Platform::input_processor() returns the input processor as a anbox::InputProcessor, anbox::Platform::sensor_processor() returns the sensor processor as a anbox::Platform::SensorProcessor and anbox::Platform::graphics_processor() returns the graphics processor as a anbox::Platform::GraphicsProcessor. All of these subclasses have to be implemented as described below.

The pure virtual function anbox::Platform::get_config_item, takes a AnboxPlatformConfigurationKey, a data value pointer and a data_size as parameters, returning 0 when managing to retrieve configuration options provided by the platform plugin. This function makes it possible to pass the plugin-specific configurations to Anbox.

The available configuration keys that are supported by Anbox are as follows:

Configuration keys	Description
EGL_DRIVER_PATH	Path to the platform implementation of the EGL shared library
OPENGL_ES1_CM_DRIVER_PATH	Path to the platform implementation of the OpenGL ES 2.x shared library
DISPLAY_SPEC	Specification of parameters of the virtual display Anbox creates (NOTE: deprecated, it exists only for backward compatibility. Please use DISPLAY_SPEC2 instead.)
AUDIO_SPEC	Specification of parameters of the audio output Anbox creates
DISPLAY_SPEC2	Specification of parameters of the virtual display Anbox creates
AUDIO_INPUT_SPEC	Specification of parameters of the audio input Anbox creates

The function anbox::Platform::ready, is used to query the platform for its ready status, returning true once the platform plugin is ready to perform any further operation, otherwise false if it is not ready yet to be used. anbox::Platform::ready will be called in conjunction with anbox::Platform::wait_until_ready by Anbox to check the platform plugin status on startup. anbox::Platform::wait_until_ready should return an error when something goes wrong. Generally, it's useful to perform the long time or blocked operations in anbox::Platform::wait_until_ready instead of the platform constructor.

The func anbox::Platform::stop is used by Anbox to tell the platform implementation to stop all of its activity in preparation for Anbox to initiate its termination sequence. It is called before the Android container is terminated. The platform should not provide any further data after anbox::Platform::stop has succeeded and free up all resources.

The func anbox::Platform::handle_event is used by Anbox to fire some key events which are crucial for a platform initialization if some operations of the platform (E.g. trigger an action) or initialization routine requires Android container fully booted or all essential components of Anbox are fully initialized.

The events that are fired by Anbox event as follows:

Event type	Description
ANBOX_EVENT_TYPE_ANDROID_BOOT_FINISHED	Android container is fully booted
ANBOX_EVENT_TYPE_INITIALIZATION_FINISHED	All essential components of Anbox are fully initialized
ANBOX_EVENT_TYPE_TERMINATING	Android container is shutting down and Anbox is terminating all essential components

AudioProcessor

The anbox::AudioProcessor class declares the following virtual functions:

The first pure virtual function, anbox::AudioProcessor::process_data is deprecated and replaced by the second virtual function anbox::AudioProcessor::read_data, which takes a data pointer which is passed directly by Anbox representing a chunk of audio data and its size as parameters, returning the actual number of bytes processed by the platform plugin or an error code on failure. With this function, a plugin can perform audio encoding with a suitable audio format for the plugin and stream as needed by utilizing the 3rd-party libraries such as libav.

The third virtual function, anbox::AudioProcessor::read_data, takes a data pointer which is passed directly by Anbox representing an uninitialized chunk of audio data and its size as parameters, returning the number of actual bytes for the audio data that was read by the platform plugin. With this function, a plugin can perform audio recording with a suitable audio format for the plugin and stream as needed by utilizing the 3rd-party libraries such as libav.

The fourth virtual function, anbox::AudioProcessor::standby, will be called when an audio stream enters standby mode. If a platform is notified by Anbox that one audio stream is going to standby mode, it's always good to drain the audio buffer cached on the platform side since this reduces the accumulated latency efficiently.

The virtual function, anbox::AudioProcessor::need_silence_on_standby, will be called by Anbox whether to produce a silent audio stream while the audio output stream goes into the standby state. Producing a silent audio stream helps with the audio latency reduction when doing audio playback if no audio output device is installed on a platform.

InputProcessor

The anbox::InputProcessor class declares two pure virtual functions.

The first pure virtual function, anbox::InputProcessor::read_event, is called by Anbox to query the plugin for the next available event (represented as a AnboxInputEvent pointer). The received event is then forwarded to the Android container. The AnboxInputEvent is similar to the input_event that is defined in the Linux kernel API. The three member variables type, code and value have the same meaning as defined in the Linux kernel API. See also the Linux Kernel documentation (https://www.kernel.org/doc/Documentation/input/input.txt) for more details. The other two member variables device_type and device_id facilitate the event forwarding and can be specified by the plugin to tell Anbox what kind of device the event belongs to. For now, three types of input devices are supported in AnboxInputDeviceType

Pointer
Keyboard
Touch panel
Gamepad

The second pure virtual function, anbox::InputProcessor::inject_event, allows injecting an AnboxInputEvent into the platform and letting the InputProcessor handle the input events.
Note: This function is only used in the test suite to facilitate test automation tests and it is subject to change at any time.

GraphicsProcessor

The anbox::GraphicsProcessor class declares the following functions:

The function anbox::GraphicsProcessor::initialize is called when Anbox initializes its rendering pipeline and allows the platform customize certain parts. For example can the platform provide a EGLNativeDisplayType to connect EGL to a display.

The two functions anbox::GraphicsProcessor::begin_frame and anbox::GraphicsProcessor::finish_frame allow integration into the rendering process inside Anbox. anbox::GraphicsProcessor::begin_frame is called before a new frame is rendered and anbox::GraphicsProcessor::finish_frame before its being finish and eglSwapBuffers is called. This allows rendering an entire frame to a specific OpenGL framebuffer or texture in order to enable for example zero copy video encoding.

The function anbox::GraphicsProcessor::create_offscreen_surface allows a platform to create an offscreen EGL surface for the given display, configuration and attributes. If this virtual function is not overridden, Anbox will use eglCreatePbufferSurface as fallback. The surface created with anbox::GraphicsProcessor::create_offscreen_surface can be destroyed via anbox::GraphicsProcessor::destroy_offscreen_surface. If it's not overridden, Anbox will use eglDestroySurface as fallback.

SensorProcessor

The anbox::SensorProcessor class declares two pure virtual functions.

The first pure virtual function, anbox::Platform::supported_sensors(), returns a list of sensors the processor supports. Multiple sensor types can be specified by using the OR bitwise operator.

The second pure virtual function, anbox::SensorProcessor::read_data, is called by Anbox to query the plugin for available sensor data (represented as a AnboxSensorData). The received data is then forwarded to the Android container. AnboxSensorData consists of two member variables sensor_type, and an union data type, which consists of a variety of sensor data. E.g. the data type for 3-axis accelerometer sensor is AnboxSensorVector, which is a data structure represents acceleration along each device axis or current device rotation angles: azimuth, pitch, roll.

The available sensor types that are supported by Anbox are as follows:

Sensor type	Enum value	Data type
3-axis Accelerometer	(AnboxSensorType::ACCELERATION)	AnboxSensorVector
3-axis Gyroscope	(AnboxSensorType::GYROSCOPE)	AnboxSensorVector
3-axis Magnetic field	(AnboxSensorType::MAGNETOMETER)	AnboxSensorVector
Orientation	(AnboxSensorType::ORIENTATION)	AnboxSensorVector
Ambient Temperature	(AnboxSensorType::TEMPERATURE)	float
Proximity	(AnboxSensorType::PROXIMITY)	float
Light	(AnboxSensorType::LIGHT)	float
Pressure	(AnboxSensorType::PRESSURE)	float
Humidity	(AnboxSensorType::HUMIDITY)	float

The third pure virtual function, anbox::SensorProcessor::inject_data, allows injecting a AnboxSensorData into the platform and letting the SensorProcessor handle the sensor data.
Note: This function is only used in the test suite to facilitate test automation tests and it is subject to change at any time.

AnboxProxy

The anbox::AnboxProxy class provides a proxy layer that encapsulates callbacks that can be used by a platform to change Android system behaviors. E.g. change the screen orientation. The platform can invoke the callbacks which are provided by Anbox on demand when triggering an action or changing a behavior. The anbox::AnboxProxy class declares a few member functions.

The first member function, anbox::AnboxProxy::change_screen_orientation, can be used by platform plugin to change the screen orientation. For example, when a platform detect that screen rotation changes, it can call this function to change the screen orientation in Android container to honor the rotation detection on a platform plugin.

The available orientation types that are supported by Anbox are as follows:

Orientation type	Enum value
Portrait mode	(AnboxScreenOrientationType::PORTRAIT)
Landscape mode	(AnboxScreenOrientationType::LANDSCAPE)
Reversed portrait mode	(AnboxScreenOrientationType::PORTRAIT_REVERSED)
Reversed landscape mode	(AnboxScreenOrientationType::LANDSCAPE_REVERSED)

The second member function, anbox::AnboxProxy::set_change_screen_orientation_callback, is called by Anbox to set the screen orientation change callback function to the platform. The callback function will be invoked internally when anbox::AnboxProxy::change_screen_orientation is called by the platform plugin if it's registered by the Anbox. If the callback function is not registered properly by Anbox, the EINVAL error will be returned.

The third member function, anbox::AnboxProxy::change_display_density, can be used by platform plugin to adjust the display density to your preferred screen. When anbox::AnboxProxy::change_display_density is called by the platform plugin, a callback function which is registered by the Anbox via anbox::AnboxProxy::set_change_display_density_callback will be invoked internally. If the callback function is not registered properly by Anbox, the EINVAL error will be returned.

The fifth member function, anbox::AnboxProxy::change_display_size, can be used by platform plugin to adjust the display size to better fit the screen. When anbox::AnboxProxy::change_display_size is called by the platform plugin, a callback function which is registered by the Anbox via anbox::AnboxProxy::set_change_display_size_callback will be invoked internally. If the callback function is not registered properly by Anbox, the EINVAL error will be returned.

The anbox::AnboxProxy::send_message, can be used by a platform plugin to send a message from Anbox to the Platform. A common use case is that a message sent by an application running in the container is forwarded to a Platform via Anbox. And platform should get a response to the message and accurately reflect it on the UI or for further processing by the platform during the data transportation.

The anbox::AnboxProxy::trigger_action, can be used by a platform plugin to trigger an action to be executed within the Android container. The action script must be installed at the ANDROID_ROOTFS/system/bin/anbox/actions folder ahead of the execution. This can be done by utilizing the hooks of an addon.
Note: the function parameter args only stands for the parameter to action and unlike standard C the action name must not be included in the parameters. So does args_len only reflects the number of parameters, action_name must not be counted. Also the returned value 0 only implies the request to launch action is handled by Anbox successfully, it doesn't tell if the action is invoked successfully within the Android container or not. To check the actual error message if an action script is not executed successfully within the Android container, please view the log of anbox service unit.

GpsProcessor

The anbox::GpsProcessor class declares two pure virtual functions.

The first pure virtual function, anbox::GpsProcessor::read_data, is called by Anbox to query the plugin for the next available gps data (represented as a AnboxGpsData pointer), which is an NMEA sentences structure essentially. The received data is then forwarded to the Android container. The available gps NEMA sentences that are supported by Anbox are following:

GGA NEMA sentence
RMC NEMA sentence
GNSS NEMA sentence

Please check the NMEA standard sentences documentation (http://www.gpsinformation.org/dale/nmea.htm) for more details.

The second pure virtual function, anbox::GpsProcessor::inject_data, allows injecting an AnboxGpsData into the platform and letting the GpsProcessor handle the gps data.
Note: This function is only used in the test suite to facilitate test automation tests and it is subject to change at any time.

CameraProcessor

The anbox::CameraProcessor class declares a few virtual functions.

The first virtual function, anbox::CameraProcessor::get_device_specs, is called by Anbox to retrieve all the specifications of camera that the platform supports. The camera specifications will be forwarded to Android container by Anbox when the camera service in Android queries the information of the supported camera devices, like resolution, facing-mode, video frame color space format and video frame rate. The camera service can't get started successfully without proper camera specs and in order to send video frames to Android container via Anbox, providing proper camera specs is a must.

The the following video frame color formats are supported by Anbox to camera

Video color space format	Enum value
Standard YUV (4:2:0)	(AnboxVideoColorSpaceFormat::VIDEO_FRAME_FORMAT_YUV420)
Raw 32 bit RGBA	(AnboxVideoColorSpaceFormat::VIDEO_FRAME_FORMAT_RGBA)

The available camera facing modes are following:

Facing mode	Enum value
Front	(AnboxCameraFacingMode::CAMERA_FACING_MODE_FRONT)
Rear or back	(AnboxCameraFacingMode::CAMERA_FACING_MODE_REAR)

Whenever a camera-based Android application get started and be ready for receiving the video frame sending by a platform for preview, anbox::CameraProcessor::open_device will be called, the function arguments describe the current camera specification that Android application is using and the current camera sensor orientation as well.

The supported camera sensor orientations as follows:

Camera sensor orientation	Enum value
Camera in portrait mode	(AnboxCameraOrientation::CAMERA_ORIENTATION_PORTRAIT)
Camera in landscape mode	(AnboxCameraOrientation::CAMERA_ORIENTATION_LANDSCAPE)

Once anbox::CameraProcessor::open_device is called, a platform can send video frames by invoking the function anbox::CameraProcessor::read_frame. This function will give a proper video frame AnboxVideoFrame back to Anbox. The underlying color format and dimension of video frame buffer must be kept consistent with the camera specification that Android application is requesting (the first function parameter of anbox::CameraProcessor::open_device). And Anbox will release the video frame after it succeeds in passing the video frame to Android container(Camera HAL).

When a camera stops preview from an Android application, anbox::CameraProcessor::close_device will be called consequently. When a platform received this signal, it should stop sending video frames to Anbox immediately and any remaining video frames in the queue should be drop right away.

The last virtual function, anbox::CameraProcessor::inject_frame, allows injecting an AnboxVideoFrame into the platform
Note: This function is only used in the test suite to facilitate test automation tests and it is subject to change at any time.