Release 2.1.8
A42334_4
 Library |
 Product |
 Contents |
 Index |
| Oracle
Video Client Software Guide Release 2.1.8 A42334_4 |
|
The Oracle Video Custom Control is an OCX (OLE Custom Extension) that defines methods, properties, and events that you can incorporate into an Oracle Power Objects, Oracle Forms, or Visual Basic application. This chapter is intended for developers that want to add video capabilities to their OCX compliant applications.
There are 16-bit and 32-bit versions of OCX. The 16-bit version (mmvx.dll) is for use by Windows for Workgroups clients, and works with other 16-bit applications (such as Visual Basic 16-bit, Oracle Forms, etc.). The 32-bit version (mmvx32.ocx) is for use by Windows 95 clients, and works with 32-bit applications.
This chapter contains these sections:
Different client platforms have their Oracle files installed in different areas. For this reason, file paths will be given relative to the variable location %ORACLE_HOME%, which should be read as the directory where you installed the Client.
When you install the Oracle Video Client software, sample applications for Oracle Power Objects, Oracle Forms, and Microsoft Visual Basic are installed in the directory %ORACLE_HOME%\vc21\demo. See Appendix A for more information about the sample applications.
The OCX interface for Oracle Power Objects and Microsoft Visual Basic are fairly similar and are presented in this chapter. The interface for Oracle Forms is somewhat different, so information about using the Oracle Video Custom Control from Oracle Forms is presented in Chapter 5, Working with Oracle Forms.
Before you can use the Oracle
Video Custom Control, it must be available to your application. To see
if the control is available, start Oracle Power Objects or Microsoft Visual
Basic and verify that the movie icon (shown here) is visible.
If the movie icon is not visible, use the steps described in the following sections to add the icon.
Before you load the Oracle Video Custom Control, start a new form within the Oracle Power Objects application. See the Oracle Power Objects User's Guide for more information.
To load the Oracle Video Custom Control 32-bit (mmvx32.ocx) or 16-bit (mmvx.dll):
The custom control is called when you click on the movie icon in the Object Palette. Usually it is located in %ORACLE_HOME%\vc21\mmvx\mmvx32.ocx (32-bit) or %ORACLE_HOME%\vc21\mmvx\mmvx.dll (16-bit)
The Oracle Installer registers the Oracle Video Custom Control in the Windows registry during installation.
When you begin a new project, the movie icon is not visible in the Toolbox. You will have to load the custom control for each new project:
If the Oracle Video Custom Control is not available in the Custom Controls dialog window:
Once it is loaded, you can use the Oracle Video Custom Control as you would any other item in the Oracle Power Objects Palette or Visual Basic Toolbox.
You can have only one active Oracle Video Custom Control in any one application. Also, only one active application can use the Oracle Video Custom Control at one time.
In Oracle Power Objects:
In Microsoft Visual Basic:
This tutorial is designed to guide you, step by step, through creating a simple Oracle Video Client application in Oracle Power Objects and Visual Basic. You can use the finished application as a starting point for developing other, more elaborate applications.
The finished application (Figure 4-2) enables users to select and play videos from a local hard disk or a networked video server. The user can use the play, pause, stop, beginning, and end controls when viewing the video and the slider control to seek to any location in the video. If the slider control is used while viewing a file, the video frame is not updated until play is resumed.
The Oracle Video Custom Control must be loaded in Oracle Power Objects or Visual Basic before you begin this tutorial. See Loading the Oracle Video Custom Control on page 4-2 for more information on this.
When you first open the Oracle Video Custom Control, you might not be able to see the controls if the initial size of the object is too small. If necessary, click on the control and drag the corners to resize it in the application window.
ocx1.ImportFileAs
ocx1.ImportStreamAs
Form1.CloseWindow
This is all you need to do to use video in your application.
You can also use the features of the Oracle Video Custom Control to create much richer applications. For example, you can use the Play, Pause, and Stop methods (along with the PositionFrames or PositionTime properties) to create your own start, pause, seek, and stop buttons.
When you first open the Oracle Video Custom Control, you might not be able to see the controls if the initial size of the object is too small. If necessary, click on the control and drag the corners to resize it in the application window.
Next, add two buttons to the form. One button, labeled Local Videos, will display a list of videos available on the local hard disk. The other, labeled Server Videos, will display videos available from the video server.
mmvx1.ImportFileAs
mmvx1.ImportStreamAs
end
This is all you need to do to use video in your application.
You can also use the features of the Oracle Video Custom Control to create much richer applications. For example, you can use the Play, Pause, and Stop methods (along with the PositionFrames or PositionTime properties) to create your own start, pause, seek, and stop buttons.
Normally, when you play a video, you:
If you use Play without a Prepare, the Play method performs an implicit Prepare. However, there are performance reasons for using Prepare first. As part of its operation, the Prepare method performs some important actions that enhance a subsequent Play method:
Video data is also pre-loaded when you change the current position in a video.
The Prepare method does not return until it has set up the connection. But because the pre-load is performed asynchronously, a Prepare method followed immediately by a Play is just as fast as a Play with an implicit Prepare (because Play still has to wait for enough video data to arrive at the client to begin playing).
The advantage of using Prepare is that you can use it to prepare video data before the user is actually ready to play that data. For instance, you can use the Prepare method in a Oracle Power Objects OnLoad script or while the user is performing other actions before playing the next video.
However, whenever video is streaming (whether pre-loading or actually playing), other network traffic can interfere with the delivery of the video stream. It is not a good idea to Prepare a video and then perform some network-intensive operation before using Play. Similarly, too much general system activity while streaming can cause dropped packets of video information, which can lead to video glitches (inconsistencies in video playback).
The Oracle Video Custom Control provides these methods:
|
|
|
|
|
|
|
|
|
|
|
|
Most of the descriptions in this section include examples in Visual Basic. For examples that show how Oracle Power Objects can use the Oracle Video Custom Control, see the sample code (described in Appendix A).
Shows the user the current version of the Oracle Video Custom Control. This Visual Basic code could be associated with a button labeled "About Box."
Private Sub Command1_Click()
mmvx1.AboutBox
End Sub
Presents a standard dialog window from which the user can pick a video on the local machine. When the user chooses a video and clicks on OK, ImportFileAs:
If the user clicks on Cancel, ImportFileAs returns False.
This sample code could be associated with a button that automatically plays the video the user picked.
Private Sub Command1_Click()
mmvx1.ImportFileAs
mmvx1.Play
End Sub
Presents a standard dialog window from which the user can pick a video from the Oracle Video Server. When the user chooses a video and clicks on OK, ImportStreamAs:
If the user clicks on OK when no video is selected, ImportFileSpec is set to a null string and ImportStreamAs returns True. If the user clicks on Cancel, ImportStreamAs returns False and set.
This code example, when associated with a Visual Basic button, invokes ImportStreamAs when the button is clicked:
Private Sub Command1_Click()
mmvx1.ImportStreamAs
End Sub
The dialog window from ImportStreamAs is shown in Figure 4-3.
Pauses a currently playing video. When the video pauses, the current frame remains displayed on the video screen.
If you alter the PositionFrames or PositionTime properties while an MPEG video is paused, the frame at the new time or frame location is not displayed until you start the video. See the PositionFrames and PositionTime properties for more information about those properties.
Here is an example of the Pause associated with a command button.
Private Sub Command1_Click()
mmvx1.Pause
End Sub
Starts playing a video at its current position. If you have just used the Prepare method or if there is an implicit prepare, the video starts at the beginning. If the video was paused or stopped, it resumes from the point at which it was paused.
When the video reaches the end, play stops as if the user had paused the video; the last frame is left on the video screen.
If you have not prepared the video, the Play method does an implicit Prepare. However, the video will begin to play much faster if you have pre-loaded the video data (see Pre-loading Video Data).
If the current position is at the end of the video, the Play method starts the video again at the beginning.
You could use the Play method as part of a scripted series of events in a computer-based training or kiosk-type application. For instance, part of an application script might display some text for the user, then prepare and play a video in a window beside the text.
mmvx1.ImportFileSpec = florence.mpi
mmvx1.ShowControls = False
mmvx1.Prepare
...display text about florence...
Delay 30
mmvx1.Play
...
Sub Delay (time)
...waits for *time* seconds before continuing...
End Sub
Opens a video file on the Oracle Video Server and establishes the link between the Oracle Video Client software and the file. Before using Prepare, you must specify the path to the video in the ImportFileSpec property. When the video is successfully prepared, the controls that are part of the Oracle Video Custom Control become enabled.
If the file doesn't exist or is not a valid video file, Prepare displays an error message and returns False.
If the ImportFileSpec property does not specify a video file, Prepare returns False.
If you use Prepare while a video is playing, the current video is immediately stopped and released before the new one is prepared.
Frees resources that the Prepare method used to prepare a video file.
If you use Prepare while an existing video is already prepared, the existing video is automatically released and the new video is prepared.
If you use Release while a video is playing, the video is stopped and released and the screen is blanked.
This script stops the video and releases the resources:
mmvx1.Stop
mmvx1.Release
Stops playing a video. When the video is stopped, the video screen goes blank and the position properties (PositionFrames and PositionTime) are not changed. Thus a subsequent Play method will restart the video at its current position.
Oracle Power Objects does not support the Stop method. Use the Pause or Release method to stop a video and release its resources. This is a known limitation in Oracle Power Objects and will be addressed in a future release. The user can still use the Stop button in the Oracle Video Custom Control play controls to stop the video.
In addition to the standard Visual Basic or Oracle Power Objects object properties, the Oracle Video Custom Control uses these properties to control aspects about the video, its playback, and its external appearance. All properties are writable, unless identified as "read-only".
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Specifies whether there is a border around the video screen. The border is 1 pixel wide. Possible values are:
|
0 - No border (default) |
1 - Border |
A read-only property that indicates whether the Oracle Video Custom Control has a video prepared or not. Possible values are:
|
0 - No video is prepared (default) |
non-zero - A video is prepared |
This code could be associated with a "Load Movie" button. It uses the ImportStreamAs method to load a video and then tests for the HasVideo property. When the HasVideo property is true, the Play button becomes visible.
Private Sub Command2_Click()
mmvx1.ImportStreamAs
If mmvx1.HasVideo = True Then
Command1.Visible = True
Else
Command1.Visible = False
End If
End Sub
A writable property that specifies the path to a video that you want to prepare or play. The path must be a valid MS-DOS file path or a valid Media Data Store path (for example /mds/movies/oracle1.mpi). The default is null.
If ImportFileSpec is not defined and you use the Prepare or Play method, the method returns False and the Prepare fails.
The difference in MPEG file naming conventions between files on the server and files on a local disk is significant:
The Oracle Video Client uses the file extension to determine where to look for a file (.mpi on the server; .mpg on a local disk). If the extension is incorrect, the Prepare will fail.
A read-only property that indicates the total length of the current video in number of frames. If no video is prepared, this property is set to 0.
A read-only property that indicates the total length of the current video in milliseconds. If no video is prepared, this property is set to 0.
Sets the volume to play the video. Possible values are integers between 0 and 9. 0 is no sound; 9 is maximum. The default is 6.
The Oracle Video Custom Control maintains the state of the PlayVolume property when you prepare another video. This means that the user doesn't have to reset the volume every time he or she views a new video. However, if the user exits the application and restarts it, the Oracle Video Custom Control will return the PlayVolume property to the default value of 6.
Displays the current position or specifies a new position (in frames). When used on the right side of an assignment statement, PositionFrames returns the current position; when used on the left side of an assignment statement, sets a new current position. The default value is 0.
If you use PositionFrames to set a new position of an MPEG file while the video is paused, the new position is not reflected on screen until the user starts to play the video at the new position. If the video is already playing when PositionFrames is set, the video will simply jump to the new position and resume playing at that new position.
If you specify a PositionFrames value that is greater than LengthFrames, the new position is at the end of the video; if you specify a PositionFrames that is less than zero, the new position is at the beginning of the video.
Displays the current position or specifies a new position (in milliseconds). When used on the right side of an assignment statement, PositionTime returns the current position; when used on the on the left side of an assignment statement, sets a new current position. The default value is 0.
When you use PositionTime to set a new position of an MPEG file while the video is paused, the new position is not reflected on screen until the user starts to play the video at the new position. If the video is already playing when PositionTime is set, the video will simply jump to the new position and resume playing at that new position.
If you specify a PositionTime value that is greater than LengthTime, the new position is at the end of the video; if you specify a PositionTime that is less than zero, the new position is at the beginning of the video.
Specifies whether all of the controls are visible or hidden. This is the master control. When ShowControls is True, selected controls are visible; when False, all controls are hidden. The default is True. The controls are shown in Figure 4-4.
If you set ShowControls to False, the ShowPosition, ShowVideoInfo, and ShowVolume properties are also set to False; if ShowControls is True, the other control properties can be set individually.
Specifies whether the position information is visible or hidden. When ShowPosition is True, the position information is visible; when False, the position information is hidden. If ShowControls is set to False, ShowPosition is also set to False. The default is True.
Specifies whether the format, time, and frame information is visible or hidden. When ShowVideoInfo is True, the format, time and frame information is visible; when False, the information is hidden. If ShowControls is set to False, ShowVideoInfo is also set to False. The default is True.
Specifies whether the volume control is visible or hidden. When ShowVolume is True, the volume control is visible; when False, the volume control is hidden. If ShowControls is set to False, ShowVolume is also set to False. The default is True.
Specifies (in milliseconds) the interval at which the time and frame information is updated in the Oracle Video Custom Control.
A reasonable range for this property is between 100 and 1000 milliseconds; the default value is 500 milliseconds. We do not recommend setting the interval to anything less than 100 milliseconds, because the multiple screen repaints necessary to update the position information will degrade video performance.
Indicates the format of the currently prepared video. This property is read-only. The possible value is MPG - MPEG-1 format.
The Oracle Video Custom Control uses MCI (Microsoft Media Control Interface) to display AVI and QuickTime videos. To view these videos, the appropriate MCI drivers must be installed on the client.
Events are messages that the Oracle Video Custom Control sends to your application. Your application can then perform specific actions in response to these events.
For example, the Stopped event is sent to your application when the video stops playing.
These events are defined by the Oracle Video Custom Control:
|
|
|
|
|
|
|
|
|
Sent to your application when the video stream reaches its end.
When a video stream reaches its end, it sends the Completed event and pauses. The video stream does not stop, nor does it send the Stopped event.
Completed is also sent when the stream is released (whether through an explicit Release, or an implicit Release that occurs when a new video is prepared).
In response to Completed, your application might want to use Stop to clear the video screen or use Prepare to prepare the next video ahead of time.
Sent to your application when the user clicks on the left mouse button while the cursor is over the video screen portion of the Oracle Video Custom Control.
Sent to your application when the video is started in response to a Play method.
When a paused video is resumed, the Oracle Video Custom Control does not send a corresponding PlayStarted event.
Sent to your application when the user clicks on the right mouse button while the cursor is over the video screen portion of the Oracle Video Custom Control.
Sent to your application when the video is stopped in response to a Stop method, or when it is paused in response to a Pause method. (See the note in PlayStarted about resuming a paused video.)
In response to the Stopped event, your application might want to prepare a new stream so that it will be ready to play when the user needs it.
|
 Copyright © 1997 Oracle Corporation. All Rights Reserved. |
|