Notes:Mixer Usage

Screens and their Capabilities
On modern consumer electronic devices, each screen object typically supports a number of display layers, mixers and encoders. A screen’s IDirectFBScreen interface (obtained by calling the IDirectFB::GetScreen function with the associated screen id, such as DSCID_PRIMARY) can be used to determine its supported capabilities by calling the GetDescription function. The display layers supported by a screen can be determined programmatically using the EnumDisplayLayers function. Additional details regarding each supported capability (DFBScreenCapabilities) can be determined by using other related IDirectFBScreen interface query functions, such as GetMixerDescriptions (for DSCCAPS_MIXERS</TT>) and GetEncoderDescriptions</TT> (for DSCCAPS_ENCODERS</TT>).<BR>

Mixer Configuration
Each mixer is used to control the background color and which display layers are blended together (if they are explicitly used) and fed down the output display pipe as input to the associated encoder(s). Note: The mixer associated with an encoder can be specified using the SetEncoderConfiguration</TT> function if the encoder supports the DSECAPS_MIXER_SEL</TT> capability.<BR> <BR> Mixer configurations are specified by calling the IDirectFBScreen</TT> interface’s SetMixerConfiguration</TT> function. The following subsections provide more detail and how to setup the DFBScreenMixerConfig</TT> structure that is passed to the SetMixerConfiguration</TT> function for a specific mixer. The subsections assume that the flags</TT> field has been initially set to zero.<BR> <BR> Tip! Mixers provide the ability to dynamically hide display layers without releasing associated interface and surface references, and to easily show them again (when double/triple buffered the front buffer is used).<BR> <BR> Note: As with many other functions in the DirectFB API, multiple settings can be configured with a single call to the IDirectFBScreen::SetMixerConfiguration</TT> function by setting multiple DFBScreenMixerConfigFlags</TT> flags.<BR>

Background Color
A background color is configured by setting the DSMCONF_BACKGROUND</TT> flag in the flags</TT> field and the desired color in the background</TT> field.<BR> <BR> Note: Generally, the default background color is fully opaque black.<BR> <BR> Note: The configured display layer background is only applied to the first buffer used. To forcibly redraw the back buffer (or front-buffer if single buffered), set the background mode to DLBM_DONTCARE</TT> then reset the background mode to the desired setting such as <TT>DLBM_IMAGE</TT> or <TT>DLBM_COLOR</TT>.<BR>

Display Layer Visibility
Three ways are provided to control if display layers are potentially visible: all of them (called full tree), those defined as a set (called sub-tree via layer selection), or those that have a level less than or equal to some value (called sub-tree via level selection). If display layers are not potentially visible, they are completely hidden.<BR> <BR> Only one approach is used at a time. The approach used is configured by setting the <TT>DSMCONF_TREE</TT> flag in the <TT>flags</TT> field and the desired <TT>DFBScreenMixerTree</TT> approach in the <TT>tree</TT> field. Descriptions of each follow.<BR> <BR> Tip! By default, all display layers are made visible when first used if single buffered, or if double/triple buffered when their surface is first flipped. Improve visual quality by using a mixer to keep display layers hidden until they are fully setup and configured with the desired pixel formats, sizes, source rectangles, screen positions and images. Once configuration is complete, enable and show them with the mixer.<BR> <BR> Note: A display layer’s double/triple buffered surface is made visible when first used, instead of when it is first flipped if the <TT>directfbrc</TT> command <TT>init-layer=<Display Layer Id #></TT> command is used.<BR> <BR> This is the default behavior for the <TT>DLID_PRIMARY</TT> display layer unless it is overridden using the <TT>no-init-layer</TT> or <TT>no-init-layer=0</TT> commands in the <TT>/etc/directfbrc</TT> configuration file.<BR>

Full Approach
All display layers (if used) are made visible with the full tree approach (they are made potentially visible if not used yet or not flipped yet when double/triple buffered).<BR> <BR> It is configured fully by setting the <TT>DSMCONF_TREE</TT> flag in the <TT>flags</TT> field and the enumerator <TT>DSMT_FULL</TT> in the <TT>tree</TT> field.<BR> <BR> Note: This is the default display layer approach. As a result, mixer usage is completely optional.<BR>

Layer Selection Approach
A custom set of display layers (if used) are made visible with the sub-tree layer selection approach (they are made potentially visible if not used yet or not flipped yet when double/triple buffered). It is configured fully by setting the <TT>DSMCONF_TREE</TT> and <TT>DSMCONF_LAYERS</TT> flags in the <TT>flags</TT> field, the enumerator <TT>DSMT_SUB_LAYERS</TT> in the <TT>tree</TT> field and a set of display layer ID flags in the <TT>layers</TT> field.<BR> <BR> A variable of type <TT>DFBDisplayLayerIDs</TT> is used to track a custom set of display layer IDs stored as flags. Several C preprocessor macros are provided for initializing and manipulating DFBDisplayLayerIDs sets. They are defined in the <TT>directfb.h</TT> file and include:
 * 1) <TT>DFB_DISPLAYLAYER_IDS_EMPTY</TT><BR> Initialize or clear a set so that it includes no display layers (hides them all or prevents them all from being visible).
 * 2) <TT>DFB_DISPLAYLAYER_IDS_ADD</TT><BR> Adds a display layer to a set (make it visible or potentially visible).
 * 3) <TT>DFB_DISPLAYLAYER_IDS_REMOVE</TT><BR> Removes a display layer from a set (hide it or prevent it from being visible).
 * 4) <TT>DFB_DISPLAYLAYER_IDS_HAVE</TT><BR> Returns a non-zero value if the set includes the specified display layer.  Otherwise, zero is returned.

Layer Level Approach
Each display layer has a z-order or level associated with it that can be programmatically queried using the <TT>IDirectFBDisplayLayer::GetLevel</TT> function. The layer with the lowest level value is in the back when blended with the other layers and the one with the highest level value is in the front.<BR> <BR> A maximum level-based set of display layers (if used) are made visible with the sub-tree layer level approach (they are made potentially visible if not used yet or not flipped yet when double/triple buffered). It is configured fully by setting the <TT>DSMCONF_TREE</TT> and <TT>DSMCONF_LEVEL</TT> flags in the <TT>flags</TT> field, the enumerator <TT>DSMT_SUB_LEVEL</TT> in the <TT>tree</TT> field, and the desired maximum visible display layer level value in the <TT>level</TT> field.<BR> <BR> This approach can be useful if a high level layer has an overlay on it that needs to be removed temporarily. By setting the maximum visible level value lower than the overlay, the overlay and all other layers above it are hidden.<BR>