383 lines
11 KiB
C++
383 lines
11 KiB
C++
// Copyright Epic Games, Inc. All Rights Reserved.
|
|
|
|
#pragma once
|
|
|
|
#include "Containers/UnrealString.h"
|
|
#include "Containers/Array.h"
|
|
#include "Containers/Map.h"
|
|
#include "Internationalization/Text.h"
|
|
#include "Math/Interval.h"
|
|
#include "Math/IntPoint.h"
|
|
#include "Math/MathFwd.h"
|
|
#include "Misc/Paths.h"
|
|
#include "Misc/Timespan.h"
|
|
#include "Misc/Variant.h"
|
|
|
|
class FArchive;
|
|
|
|
class IMediaCache;
|
|
class IMediaControls;
|
|
class IMediaOptions;
|
|
class IMediaSamples;
|
|
class IMediaTracks;
|
|
class IMediaView;
|
|
class IMediaMetadataItem;
|
|
|
|
struct FGuid;
|
|
struct FMediaPlayerOptions;
|
|
|
|
/**
|
|
* Interface for media players.
|
|
*
|
|
* @see IMediaPlayerFactory
|
|
*/
|
|
class IMediaPlayer
|
|
{
|
|
public:
|
|
|
|
//~ The following methods must be implemented by media players
|
|
|
|
/**
|
|
* Close a previously opened media source.
|
|
*
|
|
* Call this method to free up all resources associated with an opened
|
|
* media source. If no media is open, this function has no effect.
|
|
*
|
|
* The media may not necessarily be closed after this function succeeds,
|
|
* because closing may happen asynchronously. Subscribe to the MediaClosed
|
|
* event to detect when the media finished closing. This events is only
|
|
* triggered if Close returns true.
|
|
*
|
|
* @see IsReady, Open
|
|
*/
|
|
virtual void Close() = 0;
|
|
|
|
/**
|
|
* Get the player's cache controls.
|
|
*
|
|
* The interface returned by this method must remain valid for the player's life time.
|
|
*
|
|
* @return Cache controls.
|
|
* @see GetControls, GetSamples, GetTracks, GetView
|
|
*/
|
|
virtual IMediaCache& GetCache() = 0;
|
|
|
|
/**
|
|
* Get the player's playback controls.
|
|
*
|
|
* The interface returned by this method must remain valid for the player's life time.
|
|
*
|
|
* @return Playback controls.
|
|
* @see GetCache, GetSamples, GetTracks, GetView
|
|
*/
|
|
virtual IMediaControls& GetControls() = 0;
|
|
|
|
/**
|
|
* Get debug information about the player and currently opened media.
|
|
*
|
|
* @return Information string.
|
|
* @see GetStats
|
|
*/
|
|
virtual FString GetInfo() const = 0;
|
|
|
|
/**
|
|
* Get the GUID for this player plugin.
|
|
*
|
|
* @return Media player GUID (usually corresponds to a player name)
|
|
* @see GetPlayerName
|
|
*/
|
|
virtual FGuid GetPlayerPluginGUID() const = 0;
|
|
|
|
/**
|
|
* Get the player's sample queue.
|
|
*
|
|
* The interface returned by this method must remain valid for the player's life time.
|
|
*
|
|
* @return Cache interface.
|
|
* @see GetCache, GetControls, GetTracks, GetView
|
|
*/
|
|
virtual IMediaSamples& GetSamples() = 0;
|
|
|
|
/**
|
|
* Get playback statistics information.
|
|
*
|
|
* @return Information string.
|
|
* @see GetInfo
|
|
*/
|
|
virtual FString GetStats() const = 0;
|
|
|
|
/**
|
|
* Get the player's track collection.
|
|
*
|
|
* The interface returned by this method must remain valid for the player's life time.
|
|
*
|
|
* @return Tracks interface.
|
|
* @see GetCache, GetControls, GetSamples, GetView
|
|
*/
|
|
virtual IMediaTracks& GetTracks() = 0;
|
|
|
|
/**
|
|
* Get the URL of the currently loaded media.
|
|
*
|
|
* @return Media URL.
|
|
*/
|
|
virtual FString GetUrl() const = 0;
|
|
|
|
/**
|
|
* Get the player's view settings.
|
|
*
|
|
* The interface returned by this method must remain valid for the player's life time.
|
|
*
|
|
* @return View interface.
|
|
* @see GetCache, GetControls, GetSamples, GetTracks
|
|
*/
|
|
virtual IMediaView& GetView() = 0;
|
|
|
|
/**
|
|
* Open a media source from a URL with optional parameters.
|
|
*
|
|
* The media may not necessarily be opened after this function succeeds,
|
|
* because opening may happen asynchronously. Subscribe to the MediaOpened
|
|
* and MediaOpenFailed events to detect when the media finished or failed
|
|
* to open. These events are only triggered if Open returns true.
|
|
*
|
|
* The optional parameters can be used to configure aspects of media playback
|
|
* and are specific to the type of media source and the underlying player.
|
|
* Check their documentation for available keys and values.
|
|
*
|
|
* @param Url The URL of the media to open (file name or web address).
|
|
* @param Options Optional media parameters.
|
|
* @return true if the media is being opened, false otherwise.
|
|
* @see Close, IsReady, OnOpen, OnOpenFailed
|
|
*/
|
|
virtual bool Open(const FString& Url, const IMediaOptions* Options) = 0;
|
|
|
|
/**
|
|
* Open a media source from a file or memory archive with optional parameters.
|
|
*
|
|
* The media may not necessarily be opened after this function succeeds,
|
|
* because opening may happen asynchronously. Subscribe to the MediaOpened
|
|
* and MediaOpenFailed events to detect when the media finished or failed
|
|
* to open. These events are only triggered if Open returns true.
|
|
*
|
|
* The optional parameters can be used to configure aspects of media playback
|
|
* and are specific to the type of media source and the underlying player.
|
|
* Check their documentation for available keys and values.
|
|
*
|
|
* @param Archive The archive holding the media data.
|
|
* @param OriginalUrl The original URL of the media that was loaded into the buffer.
|
|
* @param Options Optional media parameters.
|
|
* @return true if the media is being opened, false otherwise.
|
|
* @see Close, IsReady, OnOpen, OnOpenFailed
|
|
*/
|
|
virtual bool Open(const TSharedRef<FArchive, ESPMode::ThreadSafe>& Archive, const FString& OriginalUrl, const IMediaOptions* Options) = 0;
|
|
|
|
public:
|
|
|
|
//~ The following methods are optional
|
|
|
|
/**
|
|
* Open a media source from a URL with optional asset and player parameters.
|
|
*
|
|
*/
|
|
virtual bool Open(const FString& Url, const IMediaOptions* Options, const FMediaPlayerOptions* PlayerOptions)
|
|
{
|
|
return Open(Url, Options);
|
|
}
|
|
|
|
/**
|
|
* Get information about the media that is playing.
|
|
*
|
|
* @param InfoName Name of the information we want.
|
|
* @returns Requested information, or empty if not available.
|
|
* @see UMediaPlayer::GetMediaInfo.
|
|
*/
|
|
virtual FVariant GetMediaInfo(FName InfoName) const
|
|
{
|
|
return FVariant();
|
|
}
|
|
|
|
/**
|
|
* Gets the current metadata of the media source.
|
|
*
|
|
* Metadata is optional and if present is typically a collection of key/value items without a
|
|
* well defined meaning. It may contain information on copyright, album name, artist and such,
|
|
* but the availability of any item is not mandatory and the representation will vary with the
|
|
* type of media.
|
|
* Interpretation therefor requires the application to be aware of the type of media being loaded
|
|
* and the possible metadata it may carry.
|
|
*
|
|
* Metadata may change over time. Its presence or change is reported by a MetadataChanged event.
|
|
*/
|
|
virtual TSharedPtr<TMap<FString, TArray<TUniquePtr<IMediaMetadataItem>>>, ESPMode::ThreadSafe> GetMediaMetadata() const
|
|
{
|
|
return nullptr;
|
|
}
|
|
|
|
/**
|
|
* Get the human readable name of the currently loaded media source.
|
|
*
|
|
* Depending on the type of media source, this might be the name of a file,
|
|
* the display name of a capture device, or some other identifying string.
|
|
* If the player does not provide a specialized implementation for this
|
|
* method, the media name will be derived from the current media URL.
|
|
*
|
|
* @return Media source name, or empty text if no media is opened
|
|
* @see GetPlayerName, GetUrl
|
|
*/
|
|
virtual FText GetMediaName() const
|
|
{
|
|
const FString Url = GetUrl();
|
|
|
|
if (Url.IsEmpty())
|
|
{
|
|
return FText::GetEmpty();
|
|
}
|
|
|
|
return FText::FromString(FPaths::GetBaseFilename(Url));
|
|
}
|
|
|
|
/**
|
|
* Set the player's globally unique identifier.
|
|
*
|
|
* @param Guid The GUID to set.
|
|
*/
|
|
virtual void SetGuid(const FGuid& Guid)
|
|
{
|
|
// override in child classes if supported
|
|
}
|
|
|
|
/**
|
|
* Set the player's native volume if supported.
|
|
*
|
|
* @param Volume The volume to set.
|
|
* @return true on success, false otherwise.
|
|
*/
|
|
virtual bool SetNativeVolume(float Volume)
|
|
{
|
|
return false;
|
|
}
|
|
|
|
/**
|
|
* Notify player of last sample time of audio used.
|
|
*
|
|
* @param SampleTime The last audio sample dequeued by one of the audio sinks.
|
|
*/
|
|
virtual void SetLastAudioRenderedSampleTime(FTimespan SampleTime)
|
|
{
|
|
// override in child classes if supported
|
|
}
|
|
|
|
/**
|
|
* Tick the player's audio related code.
|
|
*
|
|
* This is a high-frequency tick function. Media players override this method
|
|
* to fetch and process audio samples, or to perform other time critical tasks.
|
|
*
|
|
* @see TickInput, TickFetch
|
|
*/
|
|
virtual void TickAudio()
|
|
{
|
|
// override in child class if needed
|
|
}
|
|
|
|
/**
|
|
* Tick the player in the Fetch phase.
|
|
*
|
|
* Media players may override this method to fetch newly decoded input
|
|
* samples before they are rendered on textures or audio components.
|
|
*
|
|
* @param DeltaTime Time since last tick.
|
|
* @param Timecode The current media time code.
|
|
* @see TickAudio, TickInput
|
|
*/
|
|
virtual void TickFetch(FTimespan DeltaTime, FTimespan Timecode)
|
|
{
|
|
// override in child class if needed
|
|
}
|
|
|
|
/**
|
|
* Tick the player in the Input phase.
|
|
*
|
|
* Media players may override this method to update their state before the
|
|
* Engine is being ticked, or to initiate the processing of input samples.
|
|
*
|
|
* @param DeltaTime Time since last tick.
|
|
* @param Timecode The current media time code.
|
|
* @see TickAudio, TickFetch
|
|
*/
|
|
virtual void TickInput(FTimespan DeltaTime, FTimespan Timecode)
|
|
{
|
|
// override in child class if needed
|
|
}
|
|
|
|
/**
|
|
* Flush sinks when seek begins
|
|
*
|
|
* @return true if sinks should be flushed when a seek starts
|
|
*/
|
|
virtual bool FlushOnSeekStarted() const
|
|
{
|
|
return false;
|
|
}
|
|
|
|
/**
|
|
* Flush sinks when seek ends
|
|
*
|
|
* @return true if sinks should be flushed when a seek finishes
|
|
*/
|
|
virtual bool FlushOnSeekCompleted() const
|
|
{
|
|
return true;
|
|
}
|
|
|
|
enum class EFeatureFlag
|
|
{
|
|
AllowShutdownOnClose = 0, //!< Allow player to be shutdown right after 'close' event is received from it
|
|
UsePlaybackTimingV2, //!< Use v2 playback timing and AV sync
|
|
UseRealtimeWithVideoOnly, //!< Use realtime rather then game deltatime to control video playback if no audio is present
|
|
AlwaysPullNewestVideoFrame, //!< Mediaframework will not gate video frame output with its own timing, but assumes "ASAP" as output time for every sample
|
|
PlayerUsesInternalFlushOnSeek, //!< The player implements an internal flush logic on seeks and Mediaframework will not issue an explicit Flush() call to it on seeks
|
|
IsTrackSwitchSeamless, //!< If track switching is seamless then a flush of sinks is not necessary.
|
|
PlayerSelectsDefaultTracks, //!< Whether or not the player selects suitable track defaults.
|
|
};
|
|
|
|
virtual bool GetPlayerFeatureFlag(EFeatureFlag /*flag*/) const
|
|
{
|
|
// Override in child class if needed.
|
|
return false;
|
|
}
|
|
|
|
class IAsyncResourceReleaseNotification
|
|
{
|
|
public:
|
|
virtual ~IAsyncResourceReleaseNotification() {}
|
|
virtual void Signal(uint32 ResourceFlags) = 0;
|
|
};
|
|
typedef TSharedRef<IAsyncResourceReleaseNotification, ESPMode::ThreadSafe> IAsyncResourceReleaseNotificationRef;
|
|
|
|
/**
|
|
* Set async resource release notification for use with IMediaPlayerLifecycleManagerDelegate
|
|
*/
|
|
virtual bool SetAsyncResourceReleaseNotification(IAsyncResourceReleaseNotificationRef AsyncDestructNotification)
|
|
{
|
|
// Override in child class if needed.
|
|
return false;
|
|
}
|
|
|
|
/*
|
|
* Return IMediaPlayerLifecycleManagerDelegate::ResourceFlags bitmask to indicate resource types recreated on a open call
|
|
*/
|
|
virtual uint32 GetNewResourcesOnOpen() const
|
|
{
|
|
// Override in child class if needed. Default assumes resources carry over (to a large degree) and are created per instance only
|
|
// (as a simplified model for older players)
|
|
return 0;
|
|
}
|
|
|
|
public:
|
|
|
|
/** Virtual destructor. */
|
|
virtual ~IMediaPlayer() { }
|
|
};
|