// Copyright 2015 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef CHROMECAST_PUBLIC_AVSETTINGS_H_
#define CHROMECAST_PUBLIC_AVSETTINGS_H_
#include <stdint.h>
#include <string>
#include <vector>
#include "chromecast_export.h"
#include "output_restrictions.h"
#include "task_runner.h"
namespace chromecast {
// Pure abstract interface to get and set media-related information. Each
// platform must provide its own implementation.
// All functions except constructor and destructor are called in one thread.
// All delegate functions can be called by platform implementation on any
// threads, for example, created by platform implementation internally.
class AvSettings {
public:
// Defines whether or not the cast receiver is the current active source of
// the screen. If the device is connected to HDMI sinks, it may be unknown.
// GENERATED_JAVA_ENUM_PACKAGE: com.google.android.apps.mediashell.avsettings
enum ActiveState {
UNKNOWN,
STANDBY, // Screen is off
INACTIVE, // Screen is on, but cast receiver is not active
ACTIVE, // Screen is on and cast receiver is active
};
// Audio codec supported by the device (or HDMI sink).
// GENERATED_JAVA_ENUM_PACKAGE: com.google.android.apps.mediashell.avsettings
enum AudioCodec {
AC3 = 1 << 0,
DTS = 1 << 1,
DTS_HD = 1 << 2,
EAC3 = 1 << 3,
LPCM = 1 << 4,
MPEG_H_AUDIO = 1 << 5,
// All known audio codecs.
ALL = AC3 | DTS | DTS_HD | EAC3 | LPCM | MPEG_H_AUDIO
};
// Defines the type of audio volume control of the device.
// GENERATED_JAVA_ENUM_PACKAGE: com.google.android.apps.mediashell.avsettings
enum AudioVolumeControlType {
UNKNOWN_VOLUME,
// MASTER_VOLUME: Devices of CEC audio controls is a master volume system,
// i.e the system volume is changed, but not attenuated,
// e.g. normal TVs, audio devices.
MASTER_VOLUME,
// ATTENUATION_VOLUME: Devices which do not do CEC audio controls,
// e.g. Chromecast.
ATTENUATION_VOLUME,
// FIXED_VOLUME: Devices which have fixed volume, e.g. Nexus Player.
FIXED_VOLUME,
};
enum class HdmiContentType {
NO_DATA_TYPE,
GAME_TYPE,
};
// Defines the status of platform wake-on-cast feature.
enum WakeOnCastStatus {
WAKE_ON_CAST_UNKNOWN, // Should only been used very rarely when platform
// has error to get the status.
WAKE_ON_CAST_NOT_SUPPORTED, // Platform doesn't support wake-on-cast.
WAKE_ON_CAST_DISABLED,
WAKE_ON_CAST_ENABLED,
};
// GENERATED_JAVA_ENUM_PACKAGE: com.google.android.apps.mediashell.avsettings
enum Event {
// This event shall be fired whenever the active state is changed including
// when the screen turned on, when the cast receiver (or the device where
// cast receiver is running on) became the active input source, or after a
// call to TurnActive() or TurnStandby().
// WakeSystem() may change the active state depending on implementation.
// On this event, GetActiveState() will be called on the thread where
// Initialize() was called.
ACTIVE_STATE_CHANGED = 0,
// This event shall be fired whenever the audio codecs supported by the
// device (or HDMI sinks connected to the device) are changed.
// On this event, GetAudioCodecsSupported(), GetMaxAudioChannels(), and
// GetSpatialRenderingAudioCodecs() be called on the thread where
// Initialize() was called.
AUDIO_CODECS_SUPPORTED_CHANGED = 2,
// This event shall be fired whenever the screen information of the device
// (or HDMI sinks connected to the device) are changed including screen
// resolution, HDCP version and supported EOTFs.
// On this event, GetScreenResolution(), GetHDCPVersion() and
// GetSupportedEotfs(), GetScreenWidthMm(), GetScreenHeightMm() will be
// called on the thread where Initialize() was called.
SCREEN_INFO_CHANGED = 3,
// This event should be fired whenever the active output restrictions on the
// device outputs change. On this event, GetOutputRestrictions() will be
// called on the thread where Initialize() was called.
OUTPUT_RESTRICTIONS_CHANGED = 4,
// This event shall be fired whenever the type of volume control provided
// by the device is changed, for e.g., when the device is connected or
// disconnected to HDMI sinks
AUDIO_VOLUME_CONTROL_TYPE_CHANGED = 5,
// This event shall be fired whenever wake-on-cast status is changed by
// platform.
WAKE_ON_CAST_CHANGED = 6,
// This event shall be fired whenever the volume step interval provided
// by the device is changed, for e.g. when connecting to an AVR setup
// where step interval should be 1%.
AUDIO_VOLUME_STEP_INTERVAL_CHANGED = 7,
// This event shall be fired whenever the HDR output type changes.
// On this event, GetHdrOutputType() will be called on the thread where
// Initialize() was called.
HDR_OUTPUT_TYPE_CHANGED = 8,
// This event should be fired when the device is connected to HDMI sinks.
HDMI_CONNECTED = 100,
// This event should be fired when the device is disconnected to HDMI sinks.
HDMI_DISCONNECTED = 101,
// This event should be fired when an HDMI error occurs.
HDMI_ERROR = 102,
// This event should be fired when the display brightness is changed.
DISPLAY_BRIGHTNESS_CHANGED = 200,
};
// Delegate to inform the caller events. As a subclass of TaskRunner,
// AvSettings implementation can post tasks to the thread where Initialize()
// was called.
class Delegate : public TaskRunner {
public:
// This may be invoked to posts a task to the thread where Initialize() was
// called.
bool PostTask(Task* task, uint64_t delay_ms) override = 0;
// This must be invoked to fire an event when one of the conditions
// described above (Event) happens.
virtual void OnMediaEvent(Event event) = 0;
// This should be invoked when a key is pressed.
// |key_code| is a CEC code defined in User Control Codes table of the CEC
// specification (CEC Table 30 in the HDMI 1.4a specification).
virtual void OnKeyPressed(int key_code) = 0;
// This should be invoked when a key is released.
virtual void OnKeyReleased(int key_code) = 0;
protected:
~Delegate() override {}
};
virtual ~AvSettings() {}
// Initializes avsettings and starts delivering events to |delegate|.
// |delegate| must not be null.
virtual void Initialize(Delegate* delegate) = 0;
// Finalizes avsettings. It must assume |delegate| passed to Initialize() is
// invalid after this call and stop delivering events.
virtual void Finalize() = 0;
// Returns current active state.
virtual ActiveState GetActiveState() = 0;
// Turns the screen on. Sets the active input to the cast receiver iff
// switch_to_cast == true.
// If successful, it must return true and fire ACTIVE_STATE_CHANGED.
virtual bool TurnActive(bool switch_to_cast) = 0;
// Turns the screen off (or stand-by). If the device is connecting to HDMI
// sinks, broadcasts a CEC standby message on the HDMI control bus to put all
// sink devices (TV, AVR) into a standby state.
// If successful, it must return true and fire ACTIVE_STATE_CHANGED.
virtual bool TurnStandby() = 0;
// Requests the system where cast receiver is running on to be kept awake for
// |time_ms|. If the system is already being kept awake, the period should be
// extended from |time_ms| in the future.
// It will be called when cast senders discover the cast receiver while the
// system is in a stand-by mode (or a deeper sleeping/dormant mode depending
// on the system). To respond to cast senders' requests, cast receiver needs
// the system awake for given amount of time. The system should not turn
// screen on.
// Returns true if successful.
virtual bool KeepSystemAwake(int time_ms) = 0;
// Sets screen (backlight) brightness.
// |brightness|: Range is 0.0 (off) to 1.0 (max).
// |smooth|: If true, will gradually change brightness in a ramp. If true and
// unsupported, returns false and does nothing. If false, sets brightness
// immediately. If another ramp is already in progress, it is cancelled and a
// new one is started from the current brightness of the display.
// If the implementation rounds to discrete values, it should round up so that
// non-0 |brightness| values don't turn off the display.
// Returns false if set fails. Returns true otherwise.
// Not all displays support this function.
static CHROMECAST_EXPORT bool SetDisplayBrightness(float brightness,
bool smooth)
__attribute__((weak));
// Gets the current screen (backlight) brightness.
// |brightness|: Range is 0.0 (off) to 1.0 (max).
// Returns false and does not modify |brightness| if get fails.
// Returns true and sets |brightness| to the current brightness otherwise.
// Not all displays support this function.
static CHROMECAST_EXPORT bool GetDisplayBrightness(float* brightness)
__attribute__((weak));
// Gets the nits output by the display at 100% brightness.
// |nits|: The maximum brightness in nits.
// Returns false and does not modify |nits| if get fails.
// Returns true and sets |nits| on success.
// Not all displays support this function.
static CHROMECAST_EXPORT bool GetDisplayMaxBrightnessNits(float* nits)
__attribute__((weak));
// Set Hdmi content type. Return false if such operation fails. The operation
// fails if unexpected errors occur, or if the desired |content_type| is not
// supported by Hdmi sink, in which case implementation shall return false
// without actually setting the content type.
// This function should only be implemented on HDMI platforms.
static CHROMECAST_EXPORT bool SetHdmiContentType(HdmiContentType content_type)
__attribute__((weak));
// Gets the HDMI latency in microseconds.
// Returns valid values when HDMI is connected.
// Returns 0 when HDMI is not connected or when the latency cannot be
// measured.
// This function should only be implemented on HDMI platforms.
static CHROMECAST_EXPORT int GetHdmiLatencyUs() __attribute__((weak));
// Gets the EDID ID string.
// Returns the valid EDID ID when HDMI is connected.
// Returns an empty string when HDMI is not connected or when the EDID info
// cannot be correctly parsed.
// This function should only be implemented on HDMI platforms.
static CHROMECAST_EXPORT std::string GetEdidId() __attribute__((weak));
// Returns true if this is an HDMI platform.
// This function should only be implemented on HDMI platforms.
static CHROMECAST_EXPORT bool IsHdmiPlatform() __attribute__((weak));
// Returns the type of volume control, i.e. MASTER_VOLUME, FIXED_VOLUME or
// ATTENUATION_VOLUME. For example, normal TVs, devices of CEC audio
// controls, and audio devices are master volume systems. The counter
// examples are Chromecast (which doesn't do CEC audio controls) and
// Nexus Player which is fixed volume.
virtual AudioVolumeControlType GetAudioVolumeControlType() = 0;
// Retrieves the volume step interval in range [0.0, 1.0] that specifies how
// much volume to change per step, e.g. 0.05 = 5%. Returns true if a valid
// interval is specified by platform; returns false if interval should defer
// to default values.
//
// Current default volume step intervals per control type are as follows:
// - MASTER_VOLUME: 0.05 (5%)
// - ATTENUATION_VOLUME: 0.02 (2%)
// - FIXED_VOLUME: 0.01 (1%)
// - UNKNOWN_VOLUME: 0.01 (1%)
virtual bool GetAudioVolumeStepInterval(float* step_inteval) = 0;
// Gets audio codecs supported by the device (or HDMI sinks).
// The result is an integer of OR'ed AudioCodec values.
virtual int GetAudioCodecsSupported() = 0;
// Returns a bitmap of audio codecs that the device (or HDMI sinks) can
// render spatially.
static CHROMECAST_EXPORT int GetSpatialRenderingAudioCodecs()
__attribute__((weak));
// Gets maximum number of channels for given audio codec, |codec|.
virtual int GetMaxAudioChannels(AudioCodec codec) = 0;
// Retrieves the resolution of screen of the device (or HDMI sinks).
// Returns true if it gets resolution successfully.
virtual bool GetScreenResolution(int* width, int* height) = 0;
// Retrieves the refresh rate of screen of the device (or HDMI sinks) in
// millihertz.
// Returns true if it gets refresh rate successfully.
// TODO(jiaqih): Update to virtual function in next API update.
static CHROMECAST_EXPORT bool GetRefreshRateMillihertz(int* refresh_rate)
__attribute__((weak));
// Returns the current HDCP version multiplied by ten (so, for example, for
// HDCP 2.2 the return value is 22). The return value should by 0 if HDCP is
// not supported. Or TV_PLATFORM_NO_HDCP for platforms like CastTV that
// support equivalent content protection without HDCP.
enum { TV_PLATFORM_NO_HDCP = 99 };
virtual int GetHDCPVersion() = 0;
// Supported Electro-Optical Transfer Function (EOTF) reported by the device.
// The values are according to Table 8 in CTA-861.3 (formerly CEA-861.3).
// GENERATED_JAVA_ENUM_PACKAGE: com.google.android.apps.mediashell.avsettings
enum Eotf {
EOTF_SDR = 1 << 0,
EOTF_HDR = 1 << 1,
EOTF_SMPTE_ST_2084 = 1 << 2,
EOTF_HLG = 1 << 3,
};
// Returns a set of flags, defined in the Eotf enum above, indicating support
// of different EOTFs by the device or HDMI sink.
virtual int GetSupportedEotfs() = 0;
enum DolbyVisionCapFlags {
DOLBY_SUPPORTED = 1 << 0,
DOLBY_4K_P60_SUPPORTED = 1 << 1,
DOLBY_422_12BIT_SUPPORTED = 1 << 2,
};
// Returns a set of flags, defined in the DolbyVisionCapFlags enum above,
// indicating support for DolbyVision and various DV-related features.
virtual int GetDolbyVisionFlags() = 0;
// Returns physical screen size in millimeters.
virtual int GetScreenWidthMm() = 0;
virtual int GetScreenHeightMm() = 0;
// If supported, retrieves the restrictions active on the device outputs (as
// specified by the PlayReady CDM; see output_restrictions.h). If reporting
// output restrictions is unsupported, should return false.
virtual bool GetOutputRestrictions(
OutputRestrictions* output_restrictions) = 0;
// If supported, sets which output restrictions should be active on the device
// (as specified by the PlayReady CDM; see output_restrictions.h). The device
// should try to apply these restrictions and fire OUTPUT_RESTRICTIONS_CHANGED
// if they result in a change of active restrictions.
virtual void ApplyOutputRestrictions(
const OutputRestrictions& restrictions) = 0;
// Returns current Wake-On-Cast status from platform.
virtual WakeOnCastStatus GetWakeOnCastStatus() = 0;
// Enables/Disables Wake-On-Cast status.
// Returns false if failed or not supported.
virtual bool EnableWakeOnCast(bool enabled) = 0;
// Supported HDR output modes.
// GENERATED_JAVA_ENUM_PACKAGE: com.google.android.apps.mediashell.avsettings
enum HdrOutputType {
HDR_OUTPUT_SDR, // not HDR
HDR_OUTPUT_HDR, // HDR with static metadata
HDR_OUTPUT_DOLBYVISION // DolbyVision output
};
// Gets the current HDR output type.
virtual HdrOutputType GetHdrOutputType() = 0;
// Sets the HDMI video mode according to the given parameters:
// |allow_4k|: if false, the resolution set will not be a 4K resolution.
// |optimize_for_fps|: *Attempts* to pick a refresh rate optimal for the
// given content frame rate. |optimize_for_fps| is expressed as framerate
// * 100. I.e. 24hz -> 2400, 23.98hz -> 2398, etc. Values <= 0 are ignored.
// |output_type|: if set to HDR_OUTPUT_DOLBYVISION, the video mode set will
// be a DV supported resolution. If set to HDR_OUTPUT_HDR, the video mode set
// will be a 10-bit or greater video mode.
//
// Returns:
// - true if HDMI video mode change is beginning. Caller should wait for
// SCREEN_INFO_CHANGED event for mode change to complete.
// - false if no HDMI video mode change has begun. This could be because
// HDMI is disconnected, or the current resolution is already good for the
// given parameters, or no valid resolution with the given parameters is
// found (ie. setting require_dolby_vision/require_hdr to true when the
// sink doesn't support those features).
//
// Non-HDMI devices should return false.
virtual bool SetHdmiVideoMode(bool allow_4k,
int optimize_for_fps,
HdrOutputType output_type) = 0;
// Returns true if the HDMI sink supports the specified HDR output type in
// the current HDMI mode. Returns false otherwise.
//
// Non-HDMI devices should return false.
virtual bool IsHdrOutputSupportedByCurrentHdmiVideoMode(
HdrOutputType output_type) = 0;
};
// Entrypoint for overridable AvSettings shared library.
class CHROMECAST_EXPORT AvSettingsShlib {
public:
static AvSettings* Create(const std::vector<std::string>& argv);
};
} // namespace chromecast
#endif // CHROMECAST_PUBLIC_AVSETTINGS_H_
Codebase Browser
chromium