mmr_output_attach()

Attach an output.

Synopsis:

#include <mm/renderer/renderer.h>

int mmr_output_attach(mmr_context_t *ctxt,
                      const char *url,
                      const char *type)

Since:

BlackBerry 10.0.0

Arguments:

ctxt: A context handle.

url: The URL of the new output.

type: The output type. Possible values are "audio", "video", "subpicture" and "file".

Library:

libmmrndclient (For the qcc command, use the -l mrndclient option to link against this library)

Description:

Attach an output and return its output ID (a non-negative integer, unique for this context). An output can be an audio or video device, or a file. The types of outputs attached to a context may affect the set of operations that the context will allow. For instance, when "playing" to a file, seeking or trick play may not be supported.

Attaching multiple outputs of the same type is not supported. Attaching or detaching outputs while the context has an input is not supported, either.

To set up a video with closed captions, you need to attach two outputs to the context, one of the "video" type and the other of the "subpicture" type, where the subpicture window is positioned on top of the output window. The captions are sent to the subpicture output, which allows the closed caption text to be seen in front of the video, which can still be seen through the transparent background of the subpicture.

Valid URLs for the "audio" output type are in one of the following forms:

audio:name, where name is one of the audio device names defined by the AUDIO_DEVICE_NAMES set of string constants, which is listed in the Audio Manager Library reference.

snd:device, where device is the path of an audio output device, such as /dev/snd/pcmPreferredp. This URL format produces behavior similar to the audio: format, except that the Audio Manager is bypassed and so you can't provide hints such as the audio type to control audio routing.

The mm-renderer service opens the device named in the URL. Client applications can use audio:default to specify automated routing for the audio stream. When a non-default device is named, the audio stream routing depends solely on that device. For instance, the removal of the device could result in no audio being output, or an error returned to the client.

Note: Not all defined audio devices may work with the current application. It is the client's responsibility to determine if a particular device is supported before trying to use it.

Valid output URLs for the "video" and "subpicture" output types are of the following form:

screen:?wingrp=window_group&winid=window_id&nodstviewport=1&initflags=invisible

In the video URL:

window_group is the window group name of the application's top-level window
window_id is the window ID for the window where the video output will be rendered
The parameter setting nodstviewport=1 is optional, and forces mm-renderer to never directly modify the destination viewport of the window. This avoids conflicts between simultaneous application manipulation and mm-renderer manipulation of the destination viewport.
The parameter setting initflags=invisible is optional, and causes the window to be invisible upon creation. This flag allows you to adjust window properties such as size, position, and z-order before making it visible.

Valid output URLs for the "file" output type are of the form file:path, where path is the full filepath. The file: prefix is optional. The following file types (and their extensions, which must be present in the URL) are supported:

Waveform Audio File Format (.wav)
MPEG 4 Audio (.m4a)
Adaptive Multi-Rate (.amr)
3GPP file format (.3gp)
Adaptive Multi-Rate Wideband (.awb)
Qualcomm PureVoice (.qcp)

mm-renderer will reject any file: output URLs that do not contain one of the listed file extensions.

Note: When using the BlackBerry 10 Device Simulator, the output file must be a .wav file. To test other output file formats, you must use real hardware.

Returns:

A non-negative output ID on success, -1 on failure (use mmr_error_info()).