Working with layers and windows

What is a layer?

A layer represents a framebuffer (fbdev) or under X11 a image which will be put to the XServer via XSHM or XVSHM. The resolution of a layer can be set in the diskorc file.

Graphics section from diskorc to setup the X11 single-layer mode

<graphics>
	<parameter name="backend"                    value="X11"         />
	<parameter name="outputtype"                 value="XSHM"        />
	<parameter name="xres"                       value="1024"        />
	<parameter name="yres"                       value="768"         />
	<parameter name="xpos"                       value="0"           />
	<parameter name="ypos"                       value="0"           />
	<parameter name="videolayerid"               value="0"           />
	<parameter name="videolayerpixelformat"      value="RGB32"       />
	<parameter name="videolayerbuffermode"       value="BACKSYSTEM"  />
	<parameter name="graphicslayerid"            value="0"           />
	<parameter name="graphicslayerpixelformat"   value="RGB32"       />
	<parameter name="graphicslayerbuffermode"    value="BACKSYSTEM"  />
</graphics>

What are windows?

In Disko we have four window types - Root, Main, Popup and Child windows. Windows are containers for widgets or Child windows. Layers and windows

Root, Main and Popup windows will be displayed on a layer. Child windows can be used within these three windows. Only one Root and Main window can be displayed at the same time. Root windows will normally be used to display media streams such as TV, DVD, Video. Main windows normally shows the switcher and the context menu.

The size of windows can be set in pixels or in percent. The percent value is related to the layer size for Root, Main and Popup windows. The size of a Child window is related to the size of the parent window. You should use percent values in your application wherever possible. So the port to different layer resolutions will be alleviated. For example to get a full screen window you should use 100% for it's width and height. So it will be dynamically fit to the layer size. 

<mainwindow name="mywindow" w="100%" h="100%">
	<button name="button1" bgcolor="#800000ff" selbgcolor="#ff0000ff"/>
	<button name="button2" bgcolor="#008000ff" selbgcolor="#00ff00ff"/>
	<button name="button3" bgcolor="#000080ff" selbgcolor="#0000ffff"/>
</mainwindow>

Video and Graphics layer

Any application based on the Disko framework is a two layer application. This is independent from the underlaying hardware, framebuffer, etc. We use the video layer to display different kind of media streams and the graphics layer for the On-Screen-Display. In the diskorc file you specify, if your system supports (and if you want to use) two layers. In single-layer mode, the video and graphics layer will be automatically merged without changing your application.

Main and Popup windows will always be displayed on the graphics layer. Root windows can also be displayed on the graphics layer, but can be displayed on the video layer too (if two-layer mode is enabled in diskorc). You have to specify the MMSW_VIDEO flag if you want to play media streams on a MMSRootWindow which should be reside on the video layer (if two-layer mode is enabled in diskorc). 

// - construct the root window with MMSW_VIDEO flag
// - in two-layer-mode it will be displayed directly on the video layer
//   (layer surface will be used)
// - in single-layer-mode it will be displayed in the background
//   (lowest level in the window stack)
MMSRootWindow *window = new MMSRootWindow("", "100%", "100%",
                                          MMSALIGNMENT_CENTER, MMSW_VIDEO);
if (window) {
	// fill it white
	window->setBgColor(MMSFBColor(0xff,0xff,0xff,0xff));
	// show it
	window->show();
}

Single-layer mode

If you use the X11 backend or a framebuffer which supports only one layer, you configure the videolayer and the graphicslayer to the same id - normally set it to zero. It is also possible to setup the graphicslayer only. Then Disko assumes, that the video layer is the same. The above-named MMSW_VIDEO flag will be ignored.

Graphics section from diskorc to setup X11/XVSHM

<graphics>
	<parameter name="backend"         value="X11"            />
	<parameter name="outputtype"      value="XVSHM"          />
	<graphicslayer>
		<parameter name="id"          value="0"          />
		<parameter name="xres"        value="800"        />
		<parameter name="yres"        value="600"        />
		<parameter name="xpos"        value="0"          />
		<parameter name="ypos"        value="0"          />
		<parameter name="pixelformat" value="YV12"       />
		<parameter name="options"     value=""           />
		<parameter name="buffermode"  value="BACKSYSTEM" />
	</graphicslayer>
</graphics>

Two-layer mode

In this mode, the media streams can be put directly to the separate video layer. The blending of video and OSD will be done by the hardware. The layer settings are dependent on the backend (FBDEV, X11, DFB) and the particular outputtype (STDFB, OMAPFB, XVSHM, XSHM, DAVINCIFB, MATROXFB, ...). It is possible to use different resolutions for both layers.

Graphics section from diskorc to setup the davinci framebuffer with video and transparent OSD layer 

    <graphics>
        <parameter name="backend"         value="FBDEV"      />
        <parameter name="outputtype"      value="DAVINCIFB"  />
        <graphicslayer>
            <parameter name="id"          value="0"          />
            <parameter name="xres"        value="720"        />
            <parameter name="yres"        value="480"        />
            <parameter name="xpos"        value="0"          />
            <parameter name="ypos"        value="0"          />
            <parameter name="pixelformat" value="ARGB3565"   />
            <parameter name="options"     value=""           />
            <parameter name="buffermode"  value="BACKSYSTEM" />
        </graphicslayer>
        <videolayer>
            <parameter name="id"          value="1"          />
            <parameter name="xres"        value="640"        />
            <parameter name="yres"        value="480"        />
            <parameter name="xpos"        value="0"          />
            <parameter name="ypos"        value="0"          />
            <parameter name="pixelformat" value="YUY2"       />
            <parameter name="options"     value=""           />
            <parameter name="buffermode"  value="BACKSYSTEM" />
        </videolayer>
    </graphics>

Note

For applications it is not recommended to put decoded stream data directly to the surface of the video layer. Applications should always use Root windows with the MMSW_VIDEO flag for that. You can get access to the surface of the window and play streams on it or use the Disko media classes MMSAV, MMSTV, MMSDVD and MMSVideo to play your media sources to your Root window.

Example: playing a video

Using the Disko framework it is very simple to play any media sources. Here we show the usage of the MMSVideo class which is derived from MMSAV class. At first we create a new Root window, make it visible and construct a new MMSVideo class with it. MMSVideo will use the surface of the window to display the stream. This code works with any layer settings from diskorc (especially single- or two-layer mode). In two-layer mode the decoded stream will be directly put to the video layer. 

// - construct the root window with MMSW_VIDEO flag
// - in two-layer-mode it will be displayed directly on the video layer
//   (layer surface will be used)
// - in single-layer-mode it will be displayed in the background
//   (lowest level in the window stack)
MMSRootWindow *window = new MMSRootWindow("", "100%", "100%",
                                          MMSALIGNMENT_CENTER, MMSW_VIDEO);
MMSVideo *video = NULL;
if (window) {
    // show it
    window->show();
    // construct video class
    video = new MMSVideo(window);
}
if (video) {
    // play a video
    video->startPlaying("videofile_or_uri");
}