vipmplaytut.mdl
Open this model

# MPlay Simulink® Tutorial

MPlay is an interactive visualization tool for viewing video from multimedia files, MATLAB® workspace variables, or Simulink® signals representing video data.

This tutorial provides an introduction to the use of MPlay for visualizing video in a Simulink model.

## Contents

- Getting Started
- Connecting to Simulink Signals
- Maintaining Simulink Connections
- Changing Simulink Connections
- Floating Connections
- Playback Options
- Multiple Instances of MPlay
- Docked Instances of MPlay
- Advanced Topic: Instrumentation Sets
- Advanced Topic: Signal Availability

## Getting Started

Before exploring the features of MPlay, open a Simulink model to use during this tutorial by typing

        vipmplaytut

Start the Simulink model now by pressing the Start simulation button.

Working with a partially complete Simulink model is typical of the engineering design experience in which a model is simulated periodically throughout its development. MPlay enables you to visualize signals during model construction, to confirm results and understand outcomes.

Next, launch an instance of MPlay from the MATLAB command line by typing

        mplay

In the next section, you learn how to connect MPlay to video signals in this Simulink model.

## Connecting to Simulink Signals

To view video signals using MPlay, you must

- select a video signal
- create a connection to MPlay

Select the Rotate block output by clicking on the output line. This is a bus signal labeled "VideoBus" and contains three color video components within it.

Now connect MPlay to the selected Simulink signal by pressing the Connect to Simulink signal button as highlighted below:

MPlay automatically recognizes the bus signal as a single RGB video signal and displays it as color video, as shown below. Notice that the title bar of the MPlay window changes to reflect the Simulink data connection.

Connection indicators

While MPlay is connected to a video signal, the block that generates the signal displays a small red symbol on its icon, as shown below, indicating it is connected to an external viewer.

Also, notice that the Connect to Simulink signal button changes its icon from a disconnected state

to a connected state

## Maintaining Simulink Connections

Changing simulation state

You can pause, stop, and restart the Simulink simulation while MPlay is connected to a signal. Video playback halts and resumes according to the state of the simulation.

For example, with MPlay still connected to the output of the Rotate block and with the simulation still running, hit the Stop simulation button. MPlay stops video playback. Re-start the simulation by hitting the Start simulation button. MPlay resumes playback of the signal to which it was previously connected.

Closing MPlay

Closing MPlay at any time does not stop a simulation in progress. You may launch and close MPlay as necessary to inspect simulation results as they progress.

Removing blocks and lines

If you remove the block driving the signal to which MPlay is connected and re-start the simulation, MPlay displays a message and automatically disconnects from the model.

## Changing Simulink Connections

To view another video signal, disconnect from the current signal, select a new signal and connect MPlay to it. There are actually two ways to accomplish this: selecting lines, and selecting blocks.

Selecting Lines

To change the current connection, select all three signals output by the RGB Video block. Click the Disconnect from Simulink signal button to disconnect from the current signal, and click it again to connect to the newly selected signal.

In order for MPlay to recognize a bus or a group of distinct signals as RGB video, there must be three signals with identical dimensions, data type, and frame rate.

Changing to an intensity signal works similarly. Click the Disconnect from Simulink signal, select the second signal output from the Bus Selector block, and click the Connect to Simulink signal button.

The MPlay display changes from an RGB video to an intensity display of the green color component, as shown above. Note that MPlay displays individual components of RGB video as intensity images.

Selecting Blocks

You can select Simulink blocks instead of lines. This may be simpler in terms of mouse navigation, and can be convenient when output lines are not present in a model under construction.

Connecting to a block implies a connection to all output signals from the block. If there is only one output signal, an intensity display will result unless the signal is a bus. If there are 3 output signals, or an appropriate bus signal, an RGB display will be attempted.

For example, disconnect from the current signal, and select the RGB Video source block (not the output line, but the block itself this time).

Click the Connect to Simulink signal button. MPlay is now connected to all three output ports of the RGB Video block. Note that the connection indicator does not appear on the RGB Video block because it is a subsystem. If you open the subsystem, you see the indicator on the Color Space Conversion block.

Notice that MPlay automatically adjusts for the change in video frame dimensions and data type when changing to this new data stream.

## Floating Connections

By default, MPlay attaches to a signal using a persistent connection, and requires manual disconnection from a signal in order to change to a new signal. An alternative method of changing signal connections is to use a floating connection.

When an instance of MPlay is changed to floating connection, its current signal connection is highlighted as if manually selected with the mouse. Now, any new selections made with the mouse cause an automatic re-connection attempt for that instance of MPlay; the selected video signal is displayed by MPlay automatically. You can switch to a floating connection from the Playback menu, or by pressing the button in the toolbar. When a persistent connection is made (and it is the default when first connecting MPlay to a signal), the button icon displays the persistent connection icon

The icon suggests the MPlay connection is "locked" to the output signal and does not change unless a manual disconnection is performed. When pressed, the button icon changes to the floating connection icon

This icon suggests the MPlay connection is "unlocked" and follows each mouse selection without further intervention. Try this now; change to a floating connection and select various blocks, signals, or groups of RGB signals in the model.

Deciding between Persistent and Floating connections

Floating connections can be very convenient when sequentially inspecting multiple video signals in a model as it is simulating. On the other hand, persistent connections are particularly useful when you wish to have one or more scopes "fixed" to certain video signals while you navigate through a model, or while changing various block parameters while the model runs. You may switch between a persistent and a floating connection at any time.

MPlay will remain in floating mode until you manually change it back to a persistent connection mode. If an inappropriate block or signal is selected with the mouse, or no signal is selected, an appropriate message is displayed in the MPlay window. Simply select another block or signal to view; MPlay will remain in floating mode regardless of the choice.

Only one instance of MPlay can utilize a floating connection to a given Simulink model. An instance of MPlay that has a floating connection will automatically switch to a persistent connection when another instance of MPlay is changed to floating connection mode.

## Playback Options

Stop simulation, Start/Pause simulation, and Simulate one step controls are provided for connections to Simulink signals. These controls are fully synchronized with the Simulink model, and with other MPlay instances connected to the same Simulink model.

In particular, you may single-step the model using the Simulate one step control, in order to view frame-by-frame updates to a video signal. You may also start a Simulink model by pressing the Simulate one step control; this will start the Simulink model and pause it immediately after the first frame of the video signal has been displayed.

All other tools, including zoom, export, and true-size views, are available for use with Simulink signal data.

## Multiple Instances of MPlay

Multiple MPlay instances can be opened at one time. This permits simultaneous viewing of Simulink video signals, and multimedia files and MATLAB variables resulting from the capture of Simulink video data.

To illustrate, make sure the Simulink tutorial model, `vipmplaytut`, is loaded and running, and an instance of MPlay is open.

For the first instance of MPlay, select the Rotate block output signal and click the Connect to Simulink signal button.

Open a second instance of MPlay by pressing the New MPlay button, as shown below.

Select all three signals output from the RGB Video block, and click the Connect to Simulink signal button.

Both instances are now displaying video signal data. You can use the Highlight Simulink signal button, shown below, to identify the block to which the MPlay instance is connected.

## Docked Instances of MPlay

You can dock MPlay instances in a workspace. Press the Dock MPlay button at the top right corner of an MPlay window.

The MPlay window now appears in the Scopes group container. Also press the Dock MPlay button on the second viewer.

By default, this Scopes group container is in the MATLAB Command Window, but you can undock the Scopes group container by pressing the Undock Scopes button at the top right of the container. The group container is now independent from the MATLAB Command Window.

Once docked, the Scopes group container displays the toolbar and menubar of the MPlay window with focus. If you open additional instances of MPlay from a docked instance, a new MPlay window appears in the Scopes group container.

Undocking and closing MPlay

You can undock any instance of MPlay by pressing the corresponding Undock MPlay button in the title bar of each docked instance.

If you close the Scopes group container, all docked instances of MPlay close. The Simulink model continues to run.

For more information on docking figures, see the on-line documentation for Docking Figures in the Desktop.

## Advanced Topic: Instrumentation Sets

You can save the configuration of multiple MPlay viewers that have been connected to Simulink signals and multimedia files. Configurations are retained as "instrumentation set" variables, and include the following settings:

- number of viewers,
- size and position,
- docking state, and
- data source connection.

Loading instrumentation sets allows you to quickly restore collections of MPlay instances, and is particularly useful for quickly exchanging different sets of MPlay viewers during model debugging and testing phases.

An example use of instrumentation sets follows. If you haven't done so already, open several instances of MPlay and connect them to the tutorial Simulink model (see Multiple instances of MPlay for example steps to accomplish this.)

Creating instrumentation sets

To create an instrumentation set, execute

        mplayisave

from the MATLAB command line. This saves an instrumentation set that retains the state of all open MPlay viewers. By default, the set is written to `mplay.iset`, although a file name can be optionally specified.

Now, close all open MPlay instances by executing

        mplayclose all

Without an instrumentation set, you would need to re-open multiple instances of MPlay, reconnecting each to the intended signals by hand. To automatically restore the set of MPlay instances and their connections, simply recall the instrumentation set by executing

        mplayiload

All previously opened instances of MPlay are restored and reconnected. Note that the Simulink model can be running throughout the create, close, and restore steps, allowing multiple instrumentation sets to be exchanged while the model simulates.

For example, load the example instrumentation set by typing

        mplayiload mplay_tut.iset

This restores a configuration of three MPlay viewers and reconnects two of them to certain Simulink signals. The third viewer is configured to show a multimedia file containing the original source data. All three viewers are positioned as they were when the instrumentation set was created. Although not shown in this example, docked viewers are also automatically captured and restored when present.

Using instrumentation sets from MPlay

You can save and load instrumentation sets directly from the MPlay GUI by choosing Load Set... and Save Set... from the File menu, shown below.

Recently saved or loaded instrumentation sets can be quickly reloaded by selecting the file from a list of recent files at the bottom of the menu.

## Advanced Topic: Signal Availability

Certain optimizations can prevent a signal from being available for visualization with MPlay. For example, turning on Block Reduction Optimization can cause multiple blocks and associated output signals to remain unused throughout model simulation. An improvement for model efficiency, such optimizations make data unavailable to MPlay during simulation for these signals.

To visualize signals that are subject to removal when model optimizations are enabled, a signal "Test Point" can be used to force selected signals to remain available.

Following is an example illustrating the use of signal Test Points. Load the tutorial model (`vipmplaytut`) and turn on Block Reduction Optimization which is found in the Optimizations panel of the Configuration Parameters dialog. Be sure to hit Apply on the dialog for the option to take effect.

Since this model is a simple cascade of unterminated blocks, the cascade is automatically "reduced" during simulation by this optimization and the associated signals are unavailable. To see this, start the simulation, select the Rotate block output and connect MPlay to the signal.

You will see a message indicating that the signal is unavailable.

To force the VideoBus signal to remain available while Block Reduction Optimization is enabled, add a Test Point to the signal. Do this by right-clicking on the VideoBus signal and choosing "Signal Properties..." from the context menu.

Turn on the Test point option and hit OK on the dialog. You will notice a small indicator on the VideoBus signal, reminding you that a Test Point has been added.

Now repeat the steps to visualize the signal with MPlay. Not only is the VideoBus signal available for visualization, but all signals leading up to this point in the model are available as well, since they are necessary for computing the data on the VideoBus signal.

Note that Test Points will disable certain model optimizations and should be employed only during model simulation and debugging. When you wish to generate optimized code for your model, for example, consider removing Test points to improve model efficiency.