uk.co.caprica.vlcj.player.embedded
Class EmbeddedMediaPlayer

java.lang.Object
  extended by uk.co.caprica.vlcj.player.MediaPlayer
      extended by uk.co.caprica.vlcj.player.embedded.EmbeddedMediaPlayer
Direct Known Subclasses:
LinuxEmbeddedMediaPlayer, MacEmbeddedMediaPlayer, WindowsEmbeddedMediaPlayer

public abstract class EmbeddedMediaPlayer
extends MediaPlayer

Implementation of a media player that renders video to an embedded Canvas component.

This implementation supports the use of an 'overlay' window that will track the video surface position and size. Such an overlay could be used to paint custom graphics over the top of the video.

The overlay window should be non-opaque - support for this depends on the JVM, desktop window manager and graphics device hardware and software.

The overlay also has some significant limitations, it is a component that covers the video surface component and will prevent mouse and keyboard events from being processed by the video surface. Workarounds to delegate the mouse and keyboard events to the underlying Canvas may be possible but that is a responsibility of the overlay component itself and not these bindings.

The overlay will also 'lag' the main application frame when the frame is dragged - the event used to track the frame position does not fire until after the window drag operation has completed (i.e. the mouse pointer is released).

A further limitation is that the overlay will not appear when full-screen exclusive mode is used - if an overlay is required in full-screen mode then the full-screen mode must be simulated (by re-sizing the main window, removing decorations and so on).

If an overlay is used, then because the window is required to be non-opaque then it will appear in front of all other desktop windows, including application dialog windows. For this reason, it may be necessary to disable the overlay while displaying dialog boxes, or when the window is deactivated.

The overlay implementation in this class simply keeps a supplied window in sync with the video surface. It is the responsibility of the client application itself to supply an appropriate overlay component.

Finally, the overlay is experimental and support for the overlay may be changed or removed.


Field Summary
 
Fields inherited from class uk.co.caprica.vlcj.player.MediaPlayer
libvlc
 
Constructor Summary
EmbeddedMediaPlayer(libvlc_instance_t instance)
          Create a new media player.
EmbeddedMediaPlayer(libvlc_instance_t instance, FullScreenStrategy fullScreenStrategy)
          Create a new media player.
 
Method Summary
 void enableOverlay(boolean enable)
          Enable/disable the overlay component if there is one.
 java.awt.Window getOverlay()
          Get the overlay component.
 java.awt.image.BufferedImage getVideoSurfaceContents()
          Get the contents of the video surface component.
 boolean isFullScreen()
          Test the current full-screen mode.
protected abstract  void nativeSetVideoSurface(libvlc_media_player_t instance, java.awt.Canvas videoSurface)
          Template method for setting the video surface natively.
protected  void onBeforePlay()
          Allow sub-classes to do something just before the video is started.
 boolean overlayEnabled()
          Check whether or not there is an overlay component currently enabled.
 void setFullScreen(boolean fullScreen)
          Set full-screen mode.
 void setOverlay(java.awt.Window overlay)
          Set a new overlay component.
 void setVideoSurface(java.awt.Canvas videoSurface)
          Set the component used to render video.
 void toggleFullScreen()
          Toggle whether the video display is in full-screen or not.
 
Methods inherited from class uk.co.caprica.vlcj.player.MediaPlayer
addMediaOptions, addMediaPlayerEventListener, canPause, cycleSpu, enableLogo, enableMarquee, getAspectRatio, getAudioChannel, getAudioDelay, getAudioDescriptions, getAudioTrack, getAudioTrackCount, getBrightness, getChapter, getChapterCount, getChapterDescriptions, getContrast, getCropGeometry, getFps, getGamma, getHue, getLength, getMediaPlayerState, getMediaState, getMediaStatistics, getPosition, getRate, getSaturation, getScale, getSnapshot, getSpu, getSpuCount, getSpuDescriptions, getTime, getTitle, getTitleCount, getTitleDescriptions, getVideoDescriptions, getVideoDimension, getVideoOutputs, getVideoTrack, getVideoTrackCount, getVolume, isAdjustVideo, isMute, isPlayable, isPlaying, isSeekable, mediaPlayerInstance, menuActivate, menuDown, menuLeft, menuRight, menuUp, mute, mute, nextChapter, nextFrame, onAfterRelease, pause, play, playMedia, playMedia, playNextSubItem, prepareMedia, prepareMedia, previousChapter, release, removeMediaPlayerEventListener, saveSnapshot, saveSnapshot, selectAudioOutput, setAdjustVideo, setAspectRatio, setAudioChannel, setAudioDelay, setAudioTrack, setBrightness, setChapter, setContrast, setCropGeometry, setDeinterlace, setEnableKeyInputHandling, setEnableMouseInputHandling, setGamma, setHue, setLogoFile, setLogoLocation, setLogoOpacity, setLogoOpacity, setLogoPosition, setMarqueeColour, setMarqueeColour, setMarqueeLocation, setMarqueeOpacity, setMarqueeOpacity, setMarqueeSize, setMarqueeText, setMarqueeTimeout, setPause, setPlaySubItems, setPosition, setRate, setSaturation, setScale, setSpu, setStandardMediaOptions, setTime, setTitle, setVideoTrack, setVolume, skip, skip, stop
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

EmbeddedMediaPlayer

public EmbeddedMediaPlayer(libvlc_instance_t instance)
Create a new media player.

Full-screen will not be supported.

Parameters:
instance - libvlc instance

EmbeddedMediaPlayer

public EmbeddedMediaPlayer(libvlc_instance_t instance,
                           FullScreenStrategy fullScreenStrategy)
Create a new media player.

Parameters:
instance - liblc instance
fullScreenStrategy -
Method Detail

setVideoSurface

public void setVideoSurface(java.awt.Canvas videoSurface)
Set the component used to render video.

Setting the video surface on the native component is actually deferred so the component used as the video surface need not be visible and fully realised before calling this method.

Parameters:
videoSurface - component to render video to

toggleFullScreen

public void toggleFullScreen()
Toggle whether the video display is in full-screen or not.

This method defers to the full-screen strategy implementation.


setFullScreen

public void setFullScreen(boolean fullScreen)
Set full-screen mode.

This method defers to the full-screen strategy implementation.

Parameters:
fullScreen - true for full-screen, otherwise false

isFullScreen

public boolean isFullScreen()
Test the current full-screen mode.

This method defers to the full-screen strategy implementation.

Returns:
true if full-screen is active, otherwise false

getVideoSurfaceContents

public java.awt.image.BufferedImage getVideoSurfaceContents()
Get the contents of the video surface component.

This implementation uses the AWT Robot class to capture the contents of the video surface component.

The size of the returned image will match the current size of the video surface.

Since this implementation uses the AWT Robot class to make a screen capture, care must be taken when invoking this method to ensure that nothing else is overlaying the video surface!

Returns:
current contents of the video surface

getOverlay

public java.awt.Window getOverlay()
Get the overlay component.

Returns:
overlay component, may be null

setOverlay

public void setOverlay(java.awt.Window overlay)
Set a new overlay component.

The existing overlay if there is one will be disabled.

The new overlay will not automatically be enabled.

Parameters:
overlay - overlay component

enableOverlay

public void enableOverlay(boolean enable)
Enable/disable the overlay component if there is one.

Parameters:
enable - whether to enable the overlay or disable it

overlayEnabled

public boolean overlayEnabled()
Check whether or not there is an overlay component currently enabled.

Returns:
true if there is an overlay enabled, otherwise false

onBeforePlay

protected void onBeforePlay()
Description copied from class: MediaPlayer
Allow sub-classes to do something just before the video is started.

Overrides:
onBeforePlay in class MediaPlayer

nativeSetVideoSurface

protected abstract void nativeSetVideoSurface(libvlc_media_player_t instance,
                                              java.awt.Canvas videoSurface)
Template method for setting the video surface natively.

Implementing classes should override this method to invoke the appropriate libvlc method to set the video surface.

Parameters:
instance - media player instance
videoSurface - video surface component

(C)2010 Caprica Software Limited