001: /*
002: *
003: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
004: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
005: *
006: * This program is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU General Public License version
008: * 2 only, as published by the Free Software Foundation.
009: *
010: * This program is distributed in the hope that it will be useful, but
011: * WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: * General Public License version 2 for more details (a copy is
014: * included at /legal/license.txt).
015: *
016: * You should have received a copy of the GNU General Public License
017: * version 2 along with this work; if not, write to the Free Software
018: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
019: * 02110-1301 USA
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
022: * Clara, CA 95054 or visit www.sun.com if you need additional
023: * information or have any questions.
024: */
025:
026: package javax.microedition.media.control;
027:
028: import javax.microedition.media.MediaException;
029:
030: /**
031: * <code>VideoControl</code> controls the display of video.
032: * A <code>Player</code> which supports the playback of video
033: * must provide a <code>VideoControl</code> via its
034: * <code>getControl</code> and <code>getControls</code>
035: * method.
036: *
037: */
038: public interface VideoControl extends GUIControl {
039:
040: /**
041: * This defines a mode on how the video is displayed.
042: * It is used in conjunction with
043: * <a href="#initDisplayMode(int, java.lang.Object)">
044: * <code>initDisplayMode</code></a>.
045: * <p>
046: * <code>USE_DIRECT_VIDEO</code> mode can only be used
047: * on platforms with LCDUI support.
048: * <p>
049: * When <code>USE_DIRECT_VIDEO</code> is specified for
050: * <code>initDisplayMode</code>, the <code>arg</code>
051: * argument must not be null and must be a
052: * <code>javax.microedition.lcdui.Canvas</code> or a subclass of it.
053: * In this mode, the video is directly
054: * rendered onto the canvas. The region where the video
055: * is rendered can be set by the <code>setDisplayLocation</code>
056: * method. By default, the location is (0, 0).
057: * Drawing any graphics or rendering other video at the same
058: * region on the canvas may not be supported.
059: * <p>
060: * <code>initDisplayMode</code>
061: * returns <code>null</code> in this mode.
062: * <p>
063: * Here is one sample usage scenario:
064: * <pre>
065: * <code>
066: * javax.microedition.lcdui.Canvas canvas;
067: * // canvas must be created before being used in the following code.
068: *
069: * try {
070: * Player p = Manager.createPlayer("http://mymachine/abc.mpg");
071: * p.realize();
072: * VideoControl vc;
073: * if ((vc = (VideoControl)p.getControl("VideoControl")) != null) {
074: * vc.initDisplayMode(VideoControl.USE_DIRECT_VIDEO, canvas);
075: * vc.setVisible(true);
076: * }
077: * p.start();
078: * } catch (MediaException pe) {
079: * } catch (IOException ioe) {
080: * }
081: * </code>
082: * </pre>
083: * <p>
084: * Value 1 is assigned to <code>USE_DIRECT_VIDEO</code>.
085: */
086: int USE_DIRECT_VIDEO = 1;
087:
088: /**
089: * Initialize the mode on how the video is displayed.
090: * This method must be called before video can be displayed.
091: * <p>
092: * Two modes are defined:
093: * <ul>
094: * <li> <a href="GUIControl.html#USE_GUI_PRIMITIVE"><code>USE_GUI_PRIMITIVE</code></a> (inherited from GUIControl)
095: * <li> <a href="#USE_DIRECT_VIDEO"><code>USE_DIRECT_VIDEO</code></a>
096: * </ul>
097: * On platforms with LCDUI support, both modes must be supported.
098: *
099: * @param mode The video mode that determines how video is
100: * displayed. It can be <code>USE_GUI_PRIMITIVE</code>,
101: * <code>USE_DIRECT_VIDEO</code> or an implementation-
102: * specific mode.
103: *
104: * @param arg The exact semantics of this argument is
105: * specified in the respective mode definitions.
106: *
107: * @return The exact semantics and type of the object returned
108: * are specified in the respective mode definitions.
109: *
110: * @exception IllegalStateException Thrown if
111: * <code>initDisplayMode</code> is called again after it has
112: * previously been called successfully.
113: *
114: * @exception IllegalArgumentException Thrown if
115: * the <code>mode</code> or <code>arg</code>
116: * argument is invalid. <code>mode</code> must be
117: * <code>USE_GUI_PRIMITIVE</code>,
118: * <code>USE_DIRECT_VIDEO</code>, or a custom mode
119: * supported by this implementation.
120: * <code>arg</code> must conform to the
121: * conditions defined by the
122: * respective mode definitions.
123: * Refer to the mode definitions for the required type
124: * of <code>arg</code>.
125: */
126: Object initDisplayMode(int mode, Object arg);
127:
128: /**
129: * Set the location of the video with respect to
130: * the canvas where the video is displayed.
131: * <p>
132: * This method only works when the <code>USE_DIRECT_VIDEO</code>
133: * mode is set. In <code>USE_GUI_PRIMITIVE</code> mode,
134: * this call will be ignored.
135: * <p>
136: * The location is specified in pixel values relative to the
137: * upper left hand corner of the GUI object.
138: * <p>
139: * By default, video appears at location (0,0).
140: * <p>
141: * The location can be given in negative values or can be
142: * greater than the actual size of the canvas. When
143: * that happens, the video should be clipped to the
144: * boundaries of the canvas.
145: *
146: * @param x The x coordinate (in pixels) of the video location.
147: * @param y The y coordinate (in pixels) of the video location.
148: * @exception IllegalStateException Thrown if
149: * <code>initDisplayMode</code> has not been called.
150: */
151: void setDisplayLocation(int x, int y);
152:
153: /**
154: * Return the X-coordinate of the video with respect
155: * to the GUI object where the video is displayed.
156: * The coordinate is specified in pixel values relative to the
157: * upper left hand corner of the GUI object.
158: * <p>
159: * The return value is undefined if <code>initDisplayMode</code>
160: * has not been called.
161: *
162: * @return the X-coordinate of the video.
163: */
164: int getDisplayX();
165:
166: /**
167: * Return the Y-coordinate of the video with respective
168: * to the GUI object where the video is displayed.
169: * The coordinate is specified in pixel values relative to the
170: * upper left hand corner of the GUI object.
171: * <p>
172: * The return value is undefined if <code>initDisplayMode</code>
173: * has not been called.
174: *
175: * @return the Y-coordinate of the video.
176: */
177: int getDisplayY();
178:
179: /**
180: * Show or hide the video.
181: * <p>
182: * If <code>USE_GUI_PRIMITIVE</code> is set, the video by
183: * default is shown when the GUI primitive is displayed.
184: * If <code>USE_DIRECT_VIDEO</code> is set, the video by
185: * default is not shown when the canvas is displayed
186: * until <code>setVisible(true)</code> is called. If
187: * the canvas is removed from the screen, the video
188: * will not be displayed.
189: *
190: * @param visible Show the video if true, hide it otherwise.
191: * @exception IllegalStateException Thrown if
192: * <code>initDisplayMode</code> has not been called.
193: */
194: void setVisible(boolean visible);
195:
196: /**
197: * Resize the video image.
198: * <p>
199: * If the video mode is set to <code>USE_DIRECT_VIDEO</code>,
200: * setting the size of the video will not
201: * affect the size of the GUI object that the video is
202: * displayed.
203: * If the video is scaled to beyond the size of the
204: * GUI object, the video will be clipped.
205: * <p>
206: * If the video mode is set to <code>USE_GUI_PRIMITIVE</code>,
207: * Scaling the video will also scale the GUI object.
208: * <p>
209: * The actual scaling algorithm is left up
210: * to the underlying implementation. If
211: * the dimensions of the requested display size are smaller than
212: * the dimensions of the video clip, some implementations may
213: * choose to merely clip the video while other implementations
214: * may resize the video.
215: * <p>
216: * If the dimensions of the requested display size are bigger than
217: * the dimensions of the video clip, some implementations may
218: * resize the video while others may leave the video clip in the
219: * original size and just enlarge the display region. It is
220: * left up to the implementation
221: * where the video clip is placed in the display region in this
222: * instance (i.e., it can be in the center of the window or
223: * in a corner of the window).
224: *
225: * @param width Desired width (in pixels) of the display window
226: * @param height Desired height (in pixels) of the display window
227: * @exception IllegalArgumentException Thrown if the
228: * given <code>width</code> and <code>height</code> are
229: * non-positive values.
230: * @exception IllegalStateException Thrown if
231: * <code>initDisplayMode</code> has not been called.
232: * @exception MediaException Thrown if resizing is not supported or
233: * the operation failed due to hardware or software limitations.
234: */
235: void setDisplaySize(int width, int height) throws MediaException;
236:
237: /**
238: * Set the size of the render region for the video clip to be
239: * fullscreen. It is left up to the underlying implementation how
240: * fullscreen mode is
241: * implemented and what actual dimensions constitutes fullscreen.
242: * This is useful when the application does not know the actual
243: * width and height dimensions
244: * that are needed to make setDisplaySize(width, height) go to
245: * fullscreen mode.
246: * For example, on a device with a 400 pixel wide by 200 pixel
247: * high screen, a video
248: * clip that is 50 pixels wide by 100 pixels high in fullscreen
249: * mode may be
250: * 100 pixels wide by 200 pixels high if the underlying implementation
251: * wants
252: * to preserve the aspect ratio. In this case, an exception
253: * is not thrown.
254: * @param fullScreenMode Indicates whether or not to render
255: * in full screen mode
256: * @exception MediaException Thrown if resizing to full screen size
257: * is not supported.
258: * @exception IllegalStateException Thrown if
259: * <code>initDisplayMode</code> has not been called.
260: */
261: void setDisplayFullScreen(boolean fullScreenMode)
262: throws MediaException;
263:
264: /**
265: * Return the width of the source video. The
266: * width must be a positive number.
267: * @return the width of the source video
268: */
269: int getSourceWidth();
270:
271: /**
272: * Return the height of the source video. The
273: * height must be a positive number.
274: * @return the height of the source video
275: */
276: int getSourceHeight();
277:
278: /**
279: * Return the actual width of the current render video.
280: *
281: * @return width of the display video
282: * @exception IllegalStateException Thrown if
283: * <code>initDisplayMode</code> has not been called.
284: */
285: int getDisplayWidth();
286:
287: /**
288: * Return the actual height of the current render video.
289: *
290: * @return height of the display video
291: * @exception IllegalStateException Thrown if
292: * <code>initDisplayMode</code> has not been called.
293: */
294: int getDisplayHeight();
295:
296: /**
297: * Get a snapshot of the displayed content. Features and format
298: * of the captured image are specified by <code>imageType</code>.
299: * Supported formats can be queried from <code>System.getProperty</code>
300: * with
301: * <a href="../../../../overview-summary.html#video.snapshot.encodings">
302: * <code>video.snapshot.encodings</code></a> as the key.
303: * The first format in the supported list is the default capture format.
304: *
305: * @param imageType Format and resolution of the returned image.
306: * If <code>null</code> is given, the default capture format is used.
307: * @return image as a byte array in required format.
308: * @exception IllegalStateException Thrown if
309: * <code>initDisplayMode</code> has not been called.
310: * @exception MediaException Thrown if the requested format is
311: * not supported or the <code>Player</code> does not support
312: * snapshots.
313: * @exception SecurityException Thrown if the caller does
314: * not have the security permission to take the snapshot.
315: */
316: byte[] getSnapshot(String imageType) throws MediaException;
317: }
|