qnx neutrino composition manager · this guide describes how to use the qnx neutrino composition...

QNX Neutrino Composition ManagerDeveloper’s Guide

For QNX® Neutrino® 6.5.0

© 2010, QNX Software Systems GmbH & Co. KG.

© 2009– 2010 QNX Software Systems GmbH & Co. KG. All rights reserved.

Published under license by:

QNX Software Systems Co.175 Terence Matthews CrescentKanata, OntarioK2M 1W8CanadaVoice: +1 613 591-0931Fax: +1 613 591-3579Email: [email protected]: http://www.qnx.com/

Electronic edition published June 02, 2010.

QNX, Neutrino, Photon, Photon microGUI, Momentics, Aviage, and related marks, names, and logos are trademarks, registered in certain jurisdictions, of QNX SoftwareSystems GmbH & Co. KG. and are used under license by QNX Software Systems Co. All other trademarks belong to their respective owners.

Contents

About This Guide vWhat’s in this guide? vii

Typographical conventions vii

Note to Windows users viii

Technical support ix

Overview of the Composition Manager 11Communicating with applications 3

Handling composition 3

Enabling the HMI 4

Why use Composition Manager? 52Advantages of using multiple processes 7

Is Composition Manager right for you? 9

Understanding Composition 113Hardware level composition 14

Composited frame-buffer 14

Layers, WFD pipelines and EGL levels 15

Composition Modules 15

Cursors 15

io-winmgr 16

Configuring io-winmgr 194

Configuring Composition Manager 295

Working with External APIs 336OpenKODE 35

EGL 37

OpenGL ES 38

Using the Tutorials and Demos 397Demos 41

June 2, 2010 Contents iii


Tutorials 42

Community 42

Composition Manager Extensions 438KD_QNX_window 46

KD_QNX_input 56

What’s New 63AWhat’s new in Composition Manager for 6.5.0 65

iv Contents June 2, 2010

About This Guide

June 2, 2010 About This Guide v

© 2010, QNX Software Systems GmbH & Co. KG. Typographical conventions

What’s in this guide?This guide describes how to use the QNX Neutrino Composition Manager. TheComposition Manager is a hardware independent layer of abstraction thatencompasses all aspects of window management, such as window creation,realization, and destruction, as well as content updates inside the Human MachineInterface (HMI).

This table may help you find what you need in this book:

For information about: See:

Overview of the Composition Manager Overview

When to use Composition Manager Why use Composition Manager?

Understanding Composition Understanding Composition

Using io-winmgr io-winmgr

io-winmgr configuration settings Configuring io-winmgr

Example io-winmgr Configurations Example io-winmgr configurationsetups

Working with external APIs External APIs

Using the OpenKODE window classextension

KD_QNX_window

Using the OpenKODE input classextension

KD_QNX_input

Using the tutorials and demos Tutorials and Demos

What’s new in this release What’s new

Typographical conventionsThroughout this manual, we use certain typographical conventions to distinguishtechnical terms. In general, the conventions we use conform to those found in IEEEPOSIX publications. The following table summarizes our conventions:

Reference Example

Code examples if( stream == NULL )

Command options -lR

Commands make

continued. . .

June 2, 2010 About This Guide vii

Typographical conventions © 2010, QNX Software Systems GmbH & Co. KG.

Reference Example

Environment variables PATH

File and pathnames /dev/null

Function names exit()

Keyboard chords Ctrl-Alt-Delete

Keyboard input something you type

Keyboard keys Enter

Program output login:

Programming constants NULL

Programming data types unsigned short

Programming literals 0xFF, "message string"

Variable names stdin

User-interface components Cancel

We use an arrow (→) in directions for accessing menu items, like this:

You’ll find the Other... menu item under Perspective→Show View.

We use notes, cautions, and warnings to highlight important messages:

Notes point out something important or useful.

CAUTION: Cautions tell you about commands or procedures that may haveunwanted or undesirable side effects.!

WARNING: Warnings tell you about commands or procedures that could bedangerous to your files, your hardware, or even yourself.

Note to Windows usersIn our documentation, we use a forward slash (/) as a delimiter in all pathnames,including those pointing to Windows files.

We also generally follow POSIX/UNIX filesystem conventions.

viii About This Guide June 2, 2010

© 2010, QNX Software Systems GmbH & Co. KG. Technical support

Technical supportTo obtain technical support for any QNX product, visit the Support area on ourwebsite (www.qnx.com). You’ll find a wide range of support options, includingcommunity forums.

June 2, 2010 About This Guide ix

Chapter 1

Overview of the Composition Manager

June 2, 2010 Chapter 1 • Overview of the Composition Manager 1


The Composition Manager provides a uniform environment that lets media-richapplications share display hardware. It can scale from low-end platforms, where onlydisplay controller layers are available to do composition, to high-end platforms whereOpenGL ES or OpenVG can be used to combine windows. The Composition Managercommunicates with open standards APIs to make developing portable mediaapplications much easier. The Composition Manager also enables system integratorsor human-machine interface (HMI) programs to control the layout of windows on adisplay without modifying application source code.

The Composition Manager provides a lightweight composited windowing system.Unlike traditional windowing systems that arbitrate access to a single buffer associatedwith a display, a composited windowing system combines individual off-screen buffersholding window contents into one image that is associated with a display. Directing allrendering to off-screen buffers allows a more flexible use of window contents, withoutinvolving the applications that are rendering them. Windows can be moved around,zoomed in, zoomed out, rotated, or have transparency effects applied to them withoutrequiring the application to redraw or even be aware that such effects are taking place.

Communicating with applicationsThe Composition Manager uses a window manager, io-winmgr, to centralizewindow creation and destruction activities. The io-winmgr manager communicateswith external applications using industry-standard APIs.

Resource Manager and industry-standard APIs

OpenKODE is provided to create, realize, and destroy windows by sending messagesto the composition manager. The EGL API is used to handle the presentation ofwindow updates through eglSwapBuffers, which sends messages to the resourcemanager.

Handling compositionThe main responsibility of the Composition Manager is to combine all visible windowbuffers into one final image that is displayed. This can be achieved using severalclasses of hardware, including display controllers, 2D cores, vector graphics cores, 3Dprogrammable and non-programmable cores, or CPUs.

The Composition Manager can be configured to use available compositing hardware ina way that best meets the needs of a particular system. On some systems, that couldmean maximizing the use of layers available on a display controller. On the other

June 2, 2010 Chapter 1 • Overview of the Composition Manager 3


hand, if content updates are less frequent, it may be best, on some hardware, to use a2D core to do the composition. This lowers the overall memory bandwidth usage.

The Composition Manager redraws a scene whenever a visible window posts a contentupdate. To prevent unnecessary composition, windows with similar updatecharacteristics are composited at the same time. HMIs can also dynamically controlupdate rates in response to system loads. Hardware or software cursors can also beadded to a display.

Resource Manager

io-winmgr

Application

OpenKODE

EGL

libKD.so

libEGL.so

2D API(GF)

DC API

Resource Manager, industry-standard APIs, OpenWF

Enabling the HMIThe Composition Manager allows the HMI to interact with applications, withoutmanipulating the application itself, and without incurring any overhead from messagepassing.

The HMI can use Composition Manager APIs to receive events whenever a window iscreated, realized, or destroyed, or whenever properties for a given window arechanged. The API enables the HMI to change the properties of any application’swindow. This gives the HMI complete control over the layout of the display, withoutdirectly interacting with the application.

Resource Manager

io-winmgr

Application

OpenKODE

EGL

libKD.so

libEGL.so

HMI

OpenKODE

EGL

libKD.so

libEGL.so

flash-lite

2D API(GF)

DC API

Resource Manager, industry-standard APIs, HMI

In addition to modifying window properties, the HMI can call io-winmgr to accessapplication buffers. This allows the HMI to perform more sophisticated compositingor post-processing requirements. This includes 3D effects, lighting effects, or specialconversions.

4 Chapter 1 • Overview of the Composition Manager June 2, 2010

Chapter 2

Why use Composition Manager?

June 2, 2010 Chapter 2 • Why use Composition Manager? 5


Why should you use Composition Manager to create your HMI?

First, lets talk about the HMI that you are about to create. Will your HMI use onlysimple two-dimensional Flash animation, and will it require very little in the way ofprocessing power or complex graphical operations? If so, then you probably don’tneed to use Composition Manager. But lets say that your application will use multipleprocesses and need to operate reliably in a safety-critical environment. You’replanning on using the Flash player to provide a stylish UI. You’re using complicated,three-dimensional, processor-intensive animations, and you’re running a Web browseror perhaps a third-party flash application inside your HMI. You’re probably also usingtransparency effects or maybe your HMI requires some complex redraws or rotations.

If any the above is true, then Composition Manager is probably for you.

The Composition Manager allows you to create an HMI using multiple processes andmultiple graphic rendering engines. There are many advantages to creating HMIsusing multiple processes including:

Advantages of using multiple processesReuse of existing assets

You can design your main HMI using a single tool, such as Flash. You caninclude your own animations in your application, or reuse existing third-partyapplications such as a browsers, or maps.

Combining multiple graphic technologies

You can combine multiple graphic rendering engines to take advantage of thestrengths of each platform. Flash is a simple, easy to use language that allowsyou to quickly create stylish HMIs. For more complicated graphicsdevelopment, you can use the Native APIs like Open GL ES and Open VG. Thenative graphics APIs provide better performance than animations that are createdin Flash. You can even combine 2D and 3D graphics engines into a single HMI.

Abstraction of safety-critical processes

By using multple processes, you can isolate safety-critical processes fromgeneral HMI functionality. This allows you to validate system performance, andto ensure that your application will function in a reliable, predictable manner.

Abstraction of computationally-intensive processes

You can isolate expensive processes from basic HMI code. For example, youcan use native code to create an indicator service, which provides temporal cuesand feedback to the user whenever a slow process occurs. You can even runprocesses as separate threads. This allows you to set priority levels to ensure thatyour application utlizes system resources in order to execute in an expected,timely manner.

Isolation of untrusted processes

You can isolate potentially dangerous code by running untrusted processeswithin a sandbox.



You can use the Composition Manager to seamlessly combine multiple graphicprocesses into a single HMI. At runtime, animations and video output are sent to anoffscreen buffer. These offscreen buffers are not displayed, and are instead used as astaging area for animation. At display time, when an application requests it, theComposition Manager combines multiple offscreen buffers into a single image. Thisimage is then displayed by the device driver. Offscreen buffers can be combinedwithout changing the rendering application. At display time, you can define howbuffers are displayed by zooming in or out, scaling, or rotating image data. You canalso apply transparency effects (alpha blending or chroma key) to image data atdisplay time.

This flexibility allows the HMI to take over the compositing of a subprocess window,where a subprocess is one of the graphical processes that combine together to make upyour application. Using Composition Manager, the HMI can take control of theapplication’s rendering surfaces. For example, the main HMI can use simple,standards-based APIs to take control of a browser application running as a subprocess.The main HMI can define the window size and display properties of the subprocess, toensure that the browser appears properly in the main HMI window and that anycontent in the browser window is rendered properly to the display.

The following figure shows two simple processes that are composited at display time.On the left, the simple Flash HMI contains controls that can be used to view theanimation and a viewing window to contain an animation. On the right, thethree-dimensional gears animation is combined with the HMI to create the completeapplication.

8 Chapter 2 • Why use Composition Manager? June 2, 2010


Flash player

GF LibraryOpenGL ES

Graphics driver

Graphics hardware

3D Visualization program

GF

Library

Graphics driver

+ =

Compositing a simple HMI

Is Composition Manager right for you?So now get how composition works, but how do you know if Composition Manager isright for your application? The Composition Manager is scalable, meaning that youcan set the level of composition depending on the needs of your application. At themost basic level, the Composition Manager uses software-only composition. This issuitable for simple composition tasks. At the intermediate level, when supported by adevice driver, the Composition Manager can take advantage of layering. Some videocards support multiple layers, and multiple buffers. You can write to each layer, thencombine the layers at display time.

Finally, for applications that require complex graphical operations, you can usehardware accelerated options such as OpenGL ES, Open VG, or bit-blitting hardware.


Chapter 3

Understanding Composition

June 2, 2010 Chapter 3 • Understanding Composition 11


This chapter discusses the technical details of composition. It covers:

• Layers, WFD pipelines and EGL levels

• Composition Modules

• Cursors

There are two types of composition: composition at the hardware level using a displaycontroller’s layers and composition into a frame-buffer. Hardware-level compositioncan composite one buffer per layer, where a buffer is a window’s buffer or acomposited frame-buffer. Composited frame-buffers on the other hand, consist ofmultiple elements that are combined into a single frame-buffer that is then displayed.

A buffer belonging to a window that is displayed directly on a layer is said to beautonomous, since Composition Manager does not need to composite the window’sbuffers into a composited frame-buffer. For a window to run autonomously on a layer,the window’s buffer format must be supported by the layer it’s trying to be displayedon.

Hardware-level composition capabilities are controlled by a layer’s capabilities, whichtend to vary from platform to platform. The Composition Manager uses three forms oftransparency for layers. Each form determines how buffers on layers can becomposited.

The three forms of transparency are:

destination view port

Destination view ports have an implicit transparency in thatanything outside the view-port is transparent, allowing anycontent on layers below to be displayed.

source chroma Source chroma allows for pixels of a particular color to beinterpreted as transparent. Unlike a destination view-port, chromaallows for transparent pixels within the buffer.

source alpha blending

Source alpha allows for pixel blending based on the alpha channelof the pixel. Source alpha is the most powerful form oftransparency, since it allows for both semi-transparent orcompletely transparent pixels like chroma.

Many of these capabilities can be achieved when compositing windows into aframe-buffer. Using the same set of window properties, Composition Manager canprovide the same capabilities for windows regardless of whether they are compositedor running autonomously. However, when a window is composited, the contents of awindow’s buffer must be copied to the frame-buffer, which can negatively impactperformance. If a platform does not have enough layers to composite the number ofelements desired, or a layer does not support a particular behavior, it can still be donewith composition regardless of the hardware’s capabilities.



Composition can also provide additional flexibility. When using composition it’spossible to create windows with a buffer format which is not supported by a layer,since composition can convert the format when it copies the window buffer. It’s alsopossible to display a software cursor, or draw a background. Most importantly, it cancombine multiple windows in a single buffer which means a platform only requiresone layer.

Both solutions have multiple advantages and disadvantages, some of which are verysubtle, sometimes depending on the rate at which window’s contents are updated. Ingeneral, using hardware-level composition provides the best performance. However,depending on the frequency and size of updates to windows, composition cansometime display the same as layer, while using less bandwidth.

Here’s a quick list of advantages and disadvantages for both hardware-levelcomposition compared to composited frame-buffers:

Hardware level compositionAdvantages:

• Performs well

• Window buffers don’t need to be copied

• Does not require an abundance of of processing power

• Deals well with a high frequency of updates

Disadvantages:• Can only display one buffer per layer

• Layer capabilities vary greatly, and can sometimes be lacking

• Requires a great deal of memory bandwidth

Composited frame-bufferAdvantages:

• Can composite various buffers to be displayed with just a single layer

• Not limited by layer’s capabilities

• Requires less memory bandwidth if frequency of updates are low

• Can display a software cursor or background

Disadvantages:• Requires copy of buffers

• Requires processing power(CPU and, or GPU) to composite buffers

14 Chapter 3 • Understanding Composition June 2, 2010


Layers, WFD pipelines and EGL levelsNow that you have an understanding of how composition works, it’s important toknow how the OpenKODE/EGL APIs map to layers. Composition Managerimplements a subset of the OpenWFD specification which is another Khronos GroupAPI for communicating with display controllers. Composition Manager uses WFD tointeract with display controllers. Layers are exposed as wfd-pipelines, the onlydifference is that layers are indexed starting at 0, where as wfd-pipelines begin at 1(e.g. layer 0 is wfd-pipelines 1). Some WFD-related functionality is configurable viaconfiguration files such winmgr.conf or graphics.conf. Layer/Pipeline propertiessuch as chroma and source alpha blending are examples of configurable properties.For applications, the layer on which the window will be displayed on, is determined bythe EGL level attribute of a window’s egl configuration. The EGL level is an index tothe layer, which is also indexed starting at 0 (e.g. layer 0 is egl level 0 which iswfd-pipelines level 1).

Composition ModulesComposition Manager currently has three composition modules. The first, is the WFDmodule, which allows for hardware level composition as described in the previoussection. The second, is a GF composition module which takes advantage of any GFacceleration on a platform. The third module is a GLES2 composition module, whichcan take advantage of any GPU that supports open GL ES 2.0 to do composition.

CursorsIn the current version of Composition Manager, there are various ways to configure acursor. For example, you can configure a software cursor which must be on a planewhich is then composited. Another possible way to get a cursor is by placing ahardware cursor on a plane which has access to a wfd-pipeline. Keep in mindhowever, that access to the pipeline cannot be shared. Lastly, you can configure WFDto use the GF hardware cursor on the platform. This is done by configuring WFD touse the GF cursor as an additional pipeline. This gives Composition Manager accessto an additional pipeline for use as a cursor.


io-winmgr © 2010, QNX Software Systems GmbH & Co. KG.

Composition Manager

Syntax:io-winmgr [-c file] [-start] [-stop] [-d [file]]

[-quiet] [-sendev msg] [-sysres [file]][-verbose]

Runs on:Neutrino

Options:-c file Use the specified configuration file. If you don’t specify a

configuration file, the default configuration file/etc/system/config/winmgr.confwill be used.

-start Start an instance of the window manager.

You can run only a single instance of io-winmgr.

-stop Stop the current instance of the window manager.

-d [file] Dump the current state of the window manager to a file. If youdon’t specify a name, the window manager sends the output to./io-winmgr.dump.

-quiet Stop printing verbose information.

-sendev msg Send a message to the Composition Manager. The msg variablemust be one of the following:

type=close:[qid|wid]=(int)type=state:[qid|wid]=(int):index=(int):f=(float)type=state:[qid|wid]=(int):index=(int):i=(int)type=state:[qid|wid]=(int):index=(int):l=(long long int)type=input:[qid|wid]=(int):index=(int):f=(float)type=input:[qid|wid]=(int):index=(int):i=(int)type=input:[qid|wid]=(int):index=(int):l=(long long int)type=jog:[qid|wid]=(int):index=(int):count=(int)type=pointer:[qid|wid]=(int):index=(int):select=(int):x=(int):y=(int)type=stick:[qid|wid]=(int):index=(int):x=(int):y=(int):z=(int)type=keyboard:[qid|wid]=(int):flags=(uint):key_caps=(uint):key_scan=(uint):key_sym=(uint):modifiers=(uint)

-sysres [file] Dump the current state of the system to a file.

-verbose Print information about any received requests.

16 Chapter 3 • Understanding Composition June 2, 2010

© 2010, QNX Software Systems GmbH & Co. KG. io-winmgr

Description:The io-winmgr utility provides a level of absraction between the HMI player and anyapplication that’s running on the system. The io-winmgr manager centralizes allwindow creation, realization, destruction, and composition activities and allowsapplications and the HMI to be highly portable.

Examples:Start io-winmgr:

io-winmgr -start

Dump the current state to a file:

io-winmgr -d ./myoutput/dump

See also:Overview of the Composition Manager, Configuring io-winmgr


Chapter 4

Configuring io-winmgr

June 2, 2010 Chapter 4 • Configuring io-winmgr 19


The Composition Manager ( io-winmgr ) uses a configuration file to set HMI andapplication settings on startup. The configuration file contains the following sections:

Global settings Enables you to set global options.

Display settings Enables you to set display-specific options.

Window settings Enables you to set options that are specific to the HMI.

Each section must be contained within a set of begin and end tags. The followingexample shows the begin and end tags for the display section:

begin display...end display

It isn’t necessary for the sections to be in a particular order.

A configuration file must also define a plane. A plane represents a composition stage,or the area where the composition occurs.

The plane section has a begin and an end tag, just like a section:

begin plane...end plane

and must be placed within the display section.

By default, the configuration file is: /etc/system/config/winmgr.conf. You canmodify this configuration file, or create a new configuration file and use the -c optionto specify the location for the file.

Global settings

This section includes configuration items that have a global scope. In other words,they aren’t tied to a particular display, window class, or input device.

id = [0..99] Specifies the ID of the composition manager. This ID isappended to the device name that will be created.

For example, if set to 0, the composition manager will handlerequests sent to /dev/winmgr:0. It is recommended that youomit this directive and use the default ID. This default ID willensure that EGL connections established withEGL_DEFAULT_DEVICE_ID don’t return with an error. Thevalue for id must be a number between 0 and 99.

queue-incr-size = [size]

Indicates how much the event queue will grow when an eventneeds to be enqueued and the queue is full. The value must bepositive and non-zero.



queue-start-size = [size]

The size of an event queue at creation. If you set queue-start-sizeto 20, a queue with 20 events will be allocated for each newconnection that gets established.

window-incr-size = [size]

Determines the amount by which the window pool is grown whenit becomes full.

select-up-alpha-test = [on|off]

Indicates whether transparency lookups will occur for everypointer event, or just events which cause a change in button state.The default value is off.

Turning this option on can hinder performance.

input = [all|<attach_string>|none]

Indicates which devi input devices will be managed bycomposition manager.

Currently supported devices include touch screens, mice,keyboards, and control devices. When the the all option isspecified, composition manager scans the /dev/devinamespace, and attaches to all devices it supports, includingmultiple devices of the same type. You can specify an attachstring to provide more control over which devices will bemanaged by composition manager. The attach string consists of aspace separated list of devi dev entries. For example, input =

touch0 mouse0 keyboard0 keyboard1 control0

The none option, indicates that the composition manager will notmanage any devi input devices. The default value is none.

autofocus = [on|off]

Sets the focus policy when windows are created or destroyed.

When set to on, focus is assigned to newly created windowswhen they’re on top. When a window that has input focus isdestroyed, focus will also be assigned to the window directlyabove. When top-most windows get destroyed while they haveinput focus, the focus goes to the window below. Turningautofocus off removes these rules and requires a click or refocusfrom the window manager.

The default value is on.

pointer-qsize = [auto|1..]

Sets the size of queues allocated to hold pointer events.

22 Chapter 4 • Configuring io-winmgr June 2, 2010


Depending on system load and performance, pointer events maystart queueing up in the input driver. When this happens, it isimportant to rapidly empty events from this queue in order tominimise the latency between events, cursor updates, and actualpointer movements.

The value of this property determines the maximum number ofevents that can be read at once. The auto value indicates that thecomposition manager will grow the queue as events startqueueing up.

The default value is 1.

Display settings

You must define one display section for every display that will be handled by thecomposition manager.

Typically, a display entry in this configuration file will correspond to an actualphysical display device. When multiple displays are present on a system, you must usethe OpenWF display directives so that the Composition Manager can target eachdisplay. Otherwise, a single EGL display can be used.

id = [int] Specifies the ID of this display instance.

This ID corresponds to the KD_WINDOWPROPERTY_DISPLAY_QNXwindow attribute that must be used to make a window appear on aspecific display. For example, if id is set to 10, a window wouldhave to call kdSetWindowPropertyiv() with pname set toKD_WINDOWPROPERTY_DISPLAY_QNX and param pointing to avalue of 10 in order to put that window on this display.

By default, windows will be placed on the first display entry in thisconfiguration file, not on display ID 0.

The default ID is an auto-incremented integer that starts with 0.

cursor = [sw-square|sw-arrow|hw-arrow|off]

Indicates the shape of the cursor, if present.

If cursor is set to sw-square, a small square is drawn at thecoordinates of the relative pointer device.

The Composition Manager will use a hardware cursor if the value isset to hw-arrow.

The default value is off.

egl-display = [EGLNativeDisplayID|default]

The EGLNativeDisplayID that the Composition Manager shouldconnect to, or default to specify the default EGL display.



wfd-device = [WFDDeviceId|default]

The wfd-device entry associates a display section with a physicaldisplay.

You can use the sysres utility to generate a list of WFD devices,ports and pipelines available on a system. It isn’t necessary toprovide a wfd-device unless the Composition Manager musthandle multiple displays.

touch A space-separated list of devi indices used to set the display focusfor a given devi touch screen device.

For example:

touch = 2 3

mouse A space-separated list of devi indices used to set the display focusfor a given devi mouse.

For example:

mouse = 1

wfd-port = [WFDPortId|default]

This directive indicates which display port should be used to drivethe physical display.

You can use the sysres utility to generate a list of WFD devices,ports, and pipelines that are available on a system. The default valuecorresponds to the first port ID returned by WFD.

wfd-mode = [width] x [height] @ [refresh]

Use this directive to change the display mode.

This directive is necessary only if the display mode isn’t set whenthe Composition Manager starts up. The width and heightarguments indicate the display resolution. The refresh argument isthe update rate in frames per second. The default value is the currentdisplay mode.

Note that a specific display controller may not support allcombinations of resolutions and refresh rates.

# Set the display mode.wfd-mode = 640x480@60

begin plane A display must have at least one plane section. Aplane represents a composition stage.



egl-config = [EGLConfig|auto]

When the egl-config directive is present, theComposition Manager creates a target surfacewhere composition results can be saved. Thisallows several windows to share the same plane.The value of egl-config specifies which pixelformat is used to create the target buffer. Theegl-config argument must refer to an EGLconfiguration that supports native rendering, forexample EGL_NATIVE_RENDERABLE is set toEGL_TRUE.

You can use the sysres utility to generate a list ofEGL configuration IDs that can be used.

wfd-pipeline = [WFDPipelineID|default]

This directive associates a plane to a WFDpipeline, or layer.

Planes can be associated to WFD pipelineswhether they have target buffers or not (see theegl-config directive). A wfd-pipelinewithno egl-config can support one window. Whenmultiple windows are created on such planes, onlythe top-most window is visible.

Conversely, planes with target buffers that areassociated with WFD pipelines can support anynumber of windows simultaneously.

You can use the sysres utility to generate a list ofWFD devices, ports, and pipelines available on aparticular system.

source-alpha = [on|off]

When turned on, the values from alpha channelsare used to blend the contents of a window withother windows, or with the background beneath it.

Blending can still be performed even if this optionis not enabled when a target buffer is available (seeegl-config).

The option is ignored if the WFD pipeline does notsupport source alpha blending. The source-alphaand source-chroma options should not both beturned on. The option is also ignored if the planewas tied to a valid WFD pipeline ID.

source-chroma = [on|off]

When turned on, colors that correspond to thebackground color will be interpreted as transparent.



The option is ignored if the hardware doesn’tsupport source color transparency. Don’t turn onboth the source-chroma.

background = rrggbb

Specifies the background color for a plane.

The background color fills regions not occupied bywindows of the lower plane. The defaultbackground color is black, or 000000. Note thatcertain optimizations are available only if thebackground color is black.

Planes without target buffers can’t have abackground color. For planes where source colortransparency is enabled (see source-chroma),the background color directive specifies the sourcecolor that will be interpreted as transparent.

end plane

Window class settings

Classes can be used by system integrators to set default values for window propertiesthat can otherwise be configured differently from system to system. This works aslong as the application itself sets the class property, or in cases where a delegate doesit instead.

Each begin and end class directive defines a new class. Note that all fields areoptional. Only the fields specified in the class description will actually be copied intotheir corresponding window properties.

name = [string]

Indicates the name of the class. The class is used to identify a window. No twoclasses can share the same name. This string affects theKD_WINDOWPROPERTY_CLASS_QNXwindow property if a window wishes toinherit the values stored in this class.

caption = [string]

The caption string for any window deriving from this class.

This property isn’t used by the Composition Manager to provide a title bar. Itaffects the KD_WINDOWPROPERTY_CAPTIONwindow property.

delegate = [true|false]

The default value of the delegate flag for windows inheriting from this class.This affects the KD_WINDOWPROPERTY_DELEGATEwindow property, when it isset with kdSetWindowPropertybv() and read with kdGetWindowPropertybv().

visible = [true|false]

The default value of the visible flag for windows inheriting from this class.



This affects the KD_WINDOWPROPERTY_VISIBILITYwindow property.

source-alpha = [true|false]

The default value of the source alpha flag for windows inheriting from this class.

This affects the KD_WINDOWPROPERTY_SOURCE_ALPHA_QNXwindow property.

pointer-focus = [true|false]

Specifies that pointer focus will be assigned to any window that inherits fromthis class. This affects the KD_WINDOWPROPERTY_POINTER_FOCUS_QNXwindow property.

When pointer focus is assigned to a window, general focus cannot be re-assigned bymouse click.

focus = [true|false]

Specifies that general focus will be assigned to any window that inherits fromthis class. This affects the KD_WINDOWPROPERTY_FOCUS window property.

surface-size = [width] x [height]

Specifies a default buffer size for windows derived from this class.

This affects the KD_WINDOWPROPERTY_SURFACE_SIZE_QNXwindow property.

source-position = [x], [y]

Specifies a default source position for windows derived from this class.

This affects the KD_WINDOWPROPERTY_SOURCE_POSITION_QNXwindowproperty.

source-size = [width] x [height]

Specifies a default source size for windows derived from this class.

This affects the KD_WINDOWPROPERTY_SOURCE_SIZE_QNXwindow property.

window-position = [x], [y]

Specifies a default screen position for windows derived from this class.

This affects the KD_WINDOWPROPERTY_POSITION_QNXwindow property.

window-size = [width] x [height]

Specifies a default size for windows derived from this class.

This affects the KD_WINDOWPROPERTY_SIZEwindow property.

alpha = [0..255]

Global transparency value for windows derived from this class.

This affects the KD_WINDOWPROPERTY_ALPHA_QNXwindow property.

interval = [0..255]

Default swap interval for all windows inheriting from this class. This affects theKD_WINDOWPROPERTY_SWAP_INTERVAL_QNX window property.


Chapter 5

Configuring Composition Manager

June 2, 2010 Chapter 5 • Configuring Composition Manager 29


This section describes some example configurations for displays in io-winmgr.

io-winmgr configuration directives aren’t covered here. Refer to the winmgr.confconfiguration file for more information.

Configuration 1:

The following configuration provides access for applications to layer 0, as EGL level0:

begin displaybegin planewfd-pipeline = 1

end planeend display

Any windows that are created on this plane (or layer, or egl level) will runautonomously. Only one window can be displayed at a time. Visible windows arequeued up into a FIFO and only the first visible window is displayed. If the displayedwindow is destroyed, or if it’s visible is toggled to invisible the next window inthe FIFO will be displayed if a window is queued.

Configuration 2:

The following configuration is similar to the previous configuration, however anadditional plane corresponding to WFD pipeline 2 was added:


end planebegin planewfd-pipeline = 2source-alpha = on


Source alpha blending is also enabled on this pipeline. By adding another plane with apipeline, you can create two windows on separate layers that are accessible via EGLlevels 0 and 1. Source alpha is also enabled on wfd-pipeline 2 (egl level 1), whichmeans that any window that is placed on layer 1 will have a blended alpha channel.This is sample configuration provides a basic example of composition at the hardwarelevel.

To enable source alpha or source chroma on a pipeline, the corresponding layer mustsupport those capabilities.

June 2, 2010 Chapter 5 • Configuring Composition Manager 31


Configuration 3:

This configuration enables GF composition on layer 0. Any windows that are createdwith EGL level 0, will be composited by the GF composition module.

begin displaybegin planeegl-config = native rgba8888level = 0


Since Composition Manager is handling the composition of windows for this layer,multiple windows can be created on the same layer and can be composited togetherand displayed on a single layer. You can control window properties such as size,global alpha, source alpha blending, and visibility in order to get the desiredcomposited effect.

Configuration 4:

The following configuration describes composition using GLES2. GLES2compositing, source chroma, the background and a software cursor are all enabled onthe second layer.


end planebegin planeegl-config = glesv2 rgb565wfd-pipeline = 2source-chroma = onsw-cursor = onbackground = FFFFFF


Note that software cursors can only be placed on composited planes. Another planecorresponding to layer 0, is also enabled. This allows a GLES2 compositedframe-buffer to be composited at the hardware level with the autonomous windowbelow. Since source chroma is enabled, the background colour will be used as thetransparent colour key. Any pixels that match the background colour will betransparent.

32 Chapter 5 • Configuring Composition Manager June 2, 2010

Chapter 6

Working with External APIs

In this chapter. . .OpenKODE 35EGL 37OpenGL ES 38

June 2, 2010 Chapter 6 • Working with External APIs 33

© 2010, QNX Software Systems GmbH & Co. KG. OpenKODE

Applications communicate with the QNX Composition manager through open,standard APIs. For more information, refer to the third-party documentation for eachAPI:

OpenKODEhttp://www.khronos.org/openkode/

OpenKODE is a royalty-free open standard that increases the source portability ofmedia and graphics applications.

OpenKODE 1.0.2 header files on QNX Neutrino ( /usr/include/KD )

Header Files How to include Provider

kd.h #include <KD/kd.h> Khronos, modified by QNX

kdplatform.h Included by <KD/kd.h> Khronos

OpenKODE 1.0.2 libraries on QNX Neutrino

Location Name File

/usr/lib libKD.so.1 <Core KD/kd.h>

Note that only a subset of OpenKODE revision 1.0.2 is provided to interface with theQNX Composition Manager. This subset includes chapters: 5-Error, 7- Threads,8-Events, 10-Application startup and exit, 21-Input/output, and 22-Windowing. Thecomplete list of OpenKODE functions provided with libKD.so can be found at theend of this section.

This implementation also includes some QNX extensions. The KD_QNX_windowextension supplements the core windowing specification with additional windowproperties and events. The KD_QNX_input extension adds support for keyboards andassignment of focus on a per I/O group basis.

OpenKODE 1.0.2 Core Entry Points

Name Paragraph

kdGetError para 5.3.1

kdSetError para 5.3.2

kdWaitEvent para 8.4.1

kdSetEventUserptr para 8.4.2

continued. . .


OpenKODE © 2010, QNX Software Systems GmbH & Co. KG.

Name Paragraph

kdDefaultEvent para 8.4.3

kdPumpEvents para 8.4.4

kdInstallCallback para 8.4.5

kdCreateEvent para 8.4.6

kdPostEvent para 8.4.7

kdPostThreadEvent para 8.4.7

kdFreeEvent para 8.4.8

kdMain para 10.2.1

kdThreadAttrCreate para 7.3.1

kdThreadAttrFree para 7.3.2

kdThreadAttrSetDetachState para 7.3.3

kdThreadAttrSetStackSize para 7.3.4

kdThreadCreate para 7.3.5

kdThreadExit para 7.3.6

kdThreadJoin para 7.3.7

kdThreadDetach para 7.3.8

kdThreadSelf para 7.3.9

kdThreadMutexCreate para 7.3.11

kdThreadMutexFree para 7.3.12

kdThreadMutexLock para 7.3.13

kdThreadMutexUnlock para 7.3.14

kdThreadCondCreate para 7.3.15

kdThreadCondFree para 7.3.16

kdThreadCondSignal para 7.3.17

kdThreadCondBroadcast para 7.3.17

kdThreadCondWait para 7.3.18

kdGetTLS para 14.2.1

kdSetTLS para 14.2.2

kdCreateWindow para 22.4.1

continued. . .

36 Chapter 6 • Working with External APIs June 2, 2010

© 2010, QNX Software Systems GmbH & Co. KG. EGL

Name Paragraph

kdDestroyWindow para 22.4.2

kdSetWindowPropertybv para 22.4.3

kdSetWindowPropertyiv para 22.4.3

kdSetWindowPropertycv para 22.4.3

kdGetWindowPropertybv para 22.4.4

kdGetWindowPropertyiv para 22.4.4

kdGetWindowPropertycv para 22.4.4

kdRealizeWindow para 22.4.5

EGLhttp://www.khronos.org/egl/

EGL is an interface between Khronos rendering APIs and the underlying nativeplatform windowing system. The implementation of EGL 1.4 provided in this releaseisn’t compatible with previous versions of EGL 1.2 supplied with Advanced Graphics.The display_id argument to eglGetDisplay() is a numeric identifier, rather than agf_device_t handle, and the EGL_DEFAULT_DISPLAY constant is now anaccepted value. Both implementations will continue to be distributed to allow existingapplications to compile and run once the QNX Neutrino has been installed. Legacyapplications will get EGL 1.2 entry points from OpenGL ES 1.0 libraries, and new andupdated applications must link against libEGL.so to get the new entry points. Notethat only the new EGL 1.4 supports connections to the Composition Manager.

EGL 1.4 header files on QNX Neutrino ( /usr/include/EGL )


egl.h #include <EGL/egl.h> Khronos

eglplatform.h Included by egl.h Khronos, modified by QNX

eglext.h #include <EGL/eglext.h> Khronos

EGL 1.4 libraries on QNX Neutrino ( /usr/lib )

Name File

libEGL.so.1 EGL 1.4

continued. . .


OpenGL ES © 2010, QNX Software Systems GmbH & Co. KG.

Name File

libGLES_CL.so.1 Legacy EGL 1.2 with OpenGL ES 1.0 (Lite Profile)

libGLES_CM.so.1 Legacy EGL 1.2 with OpenGL ES 1.0 (Common Profile)

OpenGL EShttp://www.khronos.org/opengles/

OpenGL ES is a royalty-free, cross-platform API for full function 2D and 3D graphicson embedded systems.

OpenGL ES 1.0 Header Files on QNX Neutrino ( /usr/include/GLES )


gl.h #include <GLES/gl.h> Khronos

glext.h #include <GLES/glext.h> Khronos

OpenGL ES 1.0 Libraries on QNX Neutrino ( /usr/lib )

Name File

libEGL.so.1 EGL 1.4

libGLES_CL.so.1 Core with legacy EGL 1.2 (Lite Profile)

libGLES_CM.so.1 Core with legacy EGL 1.2 (Common Profile)

libGLESv1_CL.so.1 Core without EGL (Lite Profile)

libGLESv1_CM.so.1 Core without EGL (Common Profile)

38 Chapter 6 • Working with External APIs June 2, 2010

Chapter 7

Using the Tutorials and Demos

June 2, 2010 Chapter 7 • Using the Tutorials and Demos 39


We provide some demos and well documented tutorials that help you to understandhow the underlying code works, and let you build your own application using theComposition Manager.

DemosThe demonstration programs include EGL and OpenKODE versions of the gearsapplication. The gears application renders a set of animated gears onto the user’sdisplay.

To get the source code for the EGL and OpenKODE versions of the gears application,go to the Graphics project on our Foundry27 community website(http://community.qnx.com/sf/projects/graphics), and downloadapps/egl/demos/gles1-egl-gears/ andapps/egl/demos/demos/gles1-kd-gears/ from the source-code repository.

The gears application has the following usage information:

Options:

config=int A comma-separated list of optional configuration specifiers.

display=[int] EGL display id.

double-buffer Alternate between two rendering buffers.

global-alpha=[0..255]

The global transparency of the window.

interval=int The swap interval.

layer=int (OpenGL only)

Display contents on the specified layer.

pos=x,y The position of the viewport (if supported).

single-buffer Create a single rendering buffer.

size=widthxheight

The position of the viewport (if supported).

source-alpha Enable per-pixel alpha blending.

verbose Print an information string.

Notes:• The format string following the config option is a comma-separated list of

optional configuration specifiers. These include pixel format specification,multi-sampling specification, or an EGL configuration number. Configurationnumbers shouldn’t be used with other specifiers.

The syntax for each specifier is as follows:

June 2, 2010 Chapter 7 • Using the Tutorials and Demos 41


format=[rgba8888|rgba5551|rgb565|rgba4444]sampling=[int]x, e.g. 2x[int] (a valid EGL configuration number)A few examples:

-config=rgb565-config=rgba8888,4x-config=12

• If no specific EGL configuration is provided, the application will get the best pixelformat that can be rendered to with OpenGL ES and displayed on the layer.

• By default, the application will be displayed on the main layer.

• The default viewport size is full screen.

• The default viewport position is at (0,0).

• The default swap interval is 1.

• You can use the F key to pause and resume the animation of the gears.

• You can use the Escape key to exit the demo.

TutorialsIn addition to the demo applications, the Composition Manager provides a set ofwell-documented tutorials that guide you through the process of writing anapplication. In particular, the tutorials provide an example of vsync using each of theprovided external APIs.

The tutorials are provided in the following file locations: To get the tutorials, go to theGraphics project on our Foundry27 community website(http://community.qnx.com/sf/projects/graphics), and look for thefollowing directories in the source-code repository:

apps/egl/tutorials

Examples of vsync using EGL.

apps/kd/tutorials

Examples of vsync using OpenKODE.

CommunityDo you have questions? Do you want in on the latest Composition Manager news?

Check out the graphics project on Foundry 27: Graphics project homepage

Do you want to see what other people are doing with Composition Manager? Do youwant to share your experiences?

Check out the Composition Manager forum on Foundry 27: CompositionManager/Open KODE forum

42 Chapter 7 • Using the Tutorials and Demos June 2, 2010

Chapter 8

Composition Manager Extensions

June 2, 2010 Chapter 8 • Composition Manager Extensions 43


The Composition Manager provides the following extensions:

Extension Description

KD_QNX_window Defines the OpenKode representation ofa Composition Manager window class.

KD_QNX_input Extends the OpenKODE inputspecification to address issues such asfocus rules in a multi-window ormulti-display environment.


KD_QNX_window © 2010, QNX Software Systems GmbH & Co. KG.

The KD_QNX_window extension

Synopsis:KD_QNX_window {

kdSetWindowOrderQNX( KDWindow *window, KDWindow *above )kdPostWindowEventQNX( KDEvent *event, KDWindow *window )kdDuplicateWindowQNX(struct KDWindow *window, void *eventuserptr);KD_WINDOWPROPERTY_CLASS_QNXKD_WINDOWPROPERTY_ID_STRING_QNXKD_WINDOWPROPERTY_DISPLAY_QNXKD_WINDOWPROPERTY_POSITION_QNXKD_WINDOWPROPERTY_SOURCE_POSITION_QNXKD_WINDOWPROPERTY_SOURCE_SIZE_QNXKD_WINDOWPROPERTY_SURFACE_SIZE_QNXKD_WINDOWPROPERTY_ALPHA_QNXKD_WINDOWPROPERTY_DELEGATE_POINTER_QNXKD_WINDOWPROPERTY_DELEGATE_QNXKD_WINDOWPROPERTY_SOURCE_ALPHA_QNXKD_WINDOWPROPERTY_SENSITIVE_QNXKD_WINDOWPROPERTY_MANAGED_QNXKD_WINDOWPROPERTY_POINTER_FOCUS_QNXKD_WINDOWPROPERTY_SWAP_INTERVAL_QNXKD_WINDOWPROPERTY_BRIGHTNESS_QNXKD_WINDOWPROPERTY_CONTRAST_QNXKD_WINDOWPROPERTY_HUE_QNXKD_WINDOWPROPERTY_SATURATION_QNXKD_WINDOWPROPERTY_LEVEL_QNXKD_WINDOWPROPERTY_FREEZE_QNX

KD_EVENT_WINDOW_CREATE_QNXKD_EVENT_WINDOW_REALIZE_QNXKD_EVENT_WINDOW_PROPERTY_QNXKD_EVENT_WINDOW_CLOSE_QNX

}

Description:The KD_QNX_window extension defines the OpenKode representation of aComposition Manager window class.

The extension has the following members:

Functions:

kdPostWindowEventQNX( )

kdPostWindowEventQNX( KDEvent *event, KDWindow *window )

Post an event into another application’s queue.

*event A pointer to a KDEvent event.

*window A pointer to the window that will fire the event.

46 Chapter 8 • Composition Manager Extensions June 2, 2010

© 2010, QNX Software Systems GmbH & Co. KG. KD_QNX_window

This function posts the event pointed to by the event parameter, which is one returnedby kdCreateEvent (in the same thread), although the fields in the KDEvent structurecan have been altered to any values. If the timestamp field is 0,kdPostWindowEventQNX stores the current time at some point during thiskdPostWindowEventQNX() call (as returned by kdGetTimeUST()) in that field. Theevent is otherwise unaltered by kdPostWindowEventQNX().

The kdPostWindowEventQNX() function posts the event to the queue that’s associatedwith the window argument. The window argument may have been created in anythread of an application, or else must be the KDWindow field of a notification eventsent to a delegate thread. If the window argument is KD_NULL and the event argumentis an input or output event, then kdPostWindowEventQNX() posts the event to thequeue that’s associated with the window that currently has input focus for thatparticular type of event.

Any event type may be posted. The event may have any userptr value, even if theevent is of a type defined in the OpenKODE specification. Take care to set the userptrfield and event data to values that are expected by the application code that handles theevent type being posted.

Once the event has been passed to kdPostWindowEventQNX(), it’s “owned” by theOpenKODE Core event system. If the application attempts to access or free it after thecall to kdPostWindowEventQNX(), undefined behavior results. This is the case even ifthe call to kdPostWindowEventQNX() failed.

KDint32 kdSetWindowOrderQNX( )

KDint32 kdSetWindowOrderQNX( KDWindow *window, KDWindow *above )

Sets the z-order, or the position in the stack of windows, on the screen.

*window A pointer to the window for which you want to change to order.

*above A pointer to the window for which this window will appear above.

If the above argument is a valid window, kdSetWindowOrderQNX() places thewindow in the window argument directly below the above window argument.

The above argument can also be one of the following window constants:

KD_QNX_WINDOW_BOTTOM

Place the window below all windows on the same display

KD_QNX_LOWER Place the window below the window currently beneath it.

KD_QNX_RAISE Place the window above the window that is currently above it.

KD_QNX_WINDOW_TOP

Place the window above all windows on the same display.



The kdSetWindowOrderQNX() function returns an error if above is KD_QNX_LOWERand there are no windows below the window argument. Alternatively,kdSetWindowOrderQNX() returns an error if above is KD_QNX_RAISE and there areno windows above the window argument.

Properties:

KD_WINDOWPROPERTY_CLASS_QNX

Window class name.

Synopsis:

#define KD_WINDOWPROPERTY_CLASS_QNX 1001

Specifies the name of a window class that should be used to initialize awindow’s properties. It is a null-terminated UTF-8 string, and thus you set itwith kdSetWindowPropertycv() and read with kdGetWindowPropertycv(). Thedefault value is the empty string.

KD_WINDOWPROPERTY_ID_STRING_QNX

A String representing the id of the window. The ID is used to identify thewindow.

Synopsis:

#define KD_WINDOWPROPERTY_ID_STRING_QNX 1002

Provides a string that can be used by delegates to identify windows. It is anull-terminated UTF-8 string, and is set by kdSetWindowPropertycv(). Thedefault value is the empty string.

You can use the string in conjunction with the class name, or by itself, todetermine what a window is, which application created it, or which instance ofan application is updating a window.

KD_WINDOWPROPERTY_DISPLAY_QNX

Window display assignment.

Synopsis:

#define KD_WINDOWPROPERTY_DISPLAY_QNX 1003

Used to put a window on a particular display when multiple displays areavailable. It is an array of a single KDint32, and thus you set it withkdSetWindowPropertyiv() and read with kdGetWindowPropertyiv(). The valueof this property must correspond to the identification number of a display in theComposition Manager’s configuration file. The default value is the identificationnumber of the first display in the configuration file.

KD_WINDOWPROPERTY_POSITION_QNX

Used to position a window within a display.

Synopsis:



#define KD_WINDOWPROPERTY_POSITION_QNX 1004

It is an array of two KDint32 representing the x and y screen coordinates of theupper-left corner of the window. To set it use kdSetWindowPropertyiv() and readwith kdGetWindowPropertyiv(). Positive and negative values are accepted for xand y. The parts of a window that fall outside the boundaries of the display aresimply clipped out.

The default value is (0, 0).

KD_WINDOWPROPERTY_SOURCE_POSITION_QNX

Synopsis:

#define KD_WINDOWPROPERTY_SOURCE_POSITION_QNX 1005

Used to position the source rectangle within a larger window surface. It is anarray of two KDint32 representing the x and y buffer coordinates of theupper-left corner of the source rectangle. To set it, use kdSetWindowPropertyiv()and read with kdGetWindowPropertyiv(). Only positive values are accepted for xand y.

The rectangle defined by this property and theKD_WINDOWPROPERTY_SOURCE_SIZE_QNXmust be completely within thewindow surface. The default value is (0, 0).

When a window surface size is larger than the window size, an application canrender more content than is displayed and use the window source position tomove inside the window surface. Scrolling can be achieved without redrawingthe buffer as long as the window source rectangle stays inside the windowsurface.

KD_WINDOWPROPERTY_SOURCE_SIZE_QNX

Synopsis:

#define KD_WINDOWPROPERTY_SOURCE_SIZE_QNX 1006

Sets a window’s source rectangle size. It is an array of two KDint32

representing the width and height of the window’s source rectangle. To set it usekdSetWindowPropertyiv() and read it with kdGetWindowPropertyiv(). The x andy values must be positive. The source size can be smaller or larger than thewindow size. The rectangle defined by this property andKD_WINDOWPROPERTY_SOURCE_POSITION_QNXmust be completely withinthe window surface. The default value is the window size.

Choosing a source rectangle size that is smaller than the window size willproduce a digital zoom in effect. Using a source rectangle size that is larger thanthe window size will produce a zoom out effect.

KD_WINDOWPROPERTY_SURFACE_SIZE_QNX

Synopsis:

#define KD_WINDOWPROPERTY_SURFACE_SIZE_QNX 1007



Sets the size of a window’s buffers. It is an array of two KDint32 representingthe width and height of the window’s surfaces. To set it usekdSetWindowPropertyiv() and read it with kdGetWindowPropertyiv(). Both thewidth and height elements must be non-zero positive numbers. The surface sizecan be larger than the window size and window source size, but cannot besmaller than the window source size. The default value is the window sourcesize.

When a window surface size is larger than the window size, an application canrender more content than is displayed and can use the window source position tomove inside the window surface. Scrolling can be achieved without redrawingthe buffer as long as the window source rectangle stays inside the windowsurface.

KD_WINDOWPROPERTY_ALPHA_QNX

Window global transparency.

Synopsis:

#define KD_WINDOWPROPERTY_ALPHA_QNX 1008

Used to set the global transparency of a window. The value must be an array of asingle KDint32 between 0 and 255 inclusively. To set it usekdSetWindowPropertyiv() and read it with kdGetWindowPropertyiv().

The default value is opaque, or 255.

KD_WINDOWPROPERTY_DELEGATE_POINTER_QNX

Specify the userptr value supplied in delegate notification events.

Synopsis:

#define KD_WINDOWPROPERTY_DELEGATE_POINTER_QNX 1009

It is an array of a single KDint32. To set it use kdSetWindowPropertyiv() andread it with kdGetWindowPropertyiv(). The value of this property isuser-defined.

The default value is 0, or KD_NULL.

KD_WINDOWPROPERTY_DELEGATE_QNX

Indicates whether a window is a delegate or not, or if a window is handled by adelegate or not.

Synopsis:

#define KD_WINDOWPROPERTY_DELEGATE_QNX 1010

In the first case, it is an array of a single KDboolean. To set it usekdSetWindowPropertybv() and read it with kdGetWindowPropertybv().

The boolean has the value KD_TRUE if the window is a delegate, or KD_FALSE ifit is not. The default value is KD_FALSE. When a window is handled by adelegate window, the delegate property is an array of a single KDint32 that



contains the KDWindow pointer of that delegate window, which you can set withkdSetWindowPropertyiv() and read with kdGetWindowPropertyiv().

The default value is 0, or KD_NULL.

Normally, a thread starts by setting this property to KD_TRUE to become adelegate and start receiving notifications when other windows are created. Thethread can choose to respond to these events by setting the newly createdwindow’s delegate property to the delegate window’s KDWindow pointer. Once awindow is handled by a delegate, the delegate thread will receive notificationswhen the window is realized, closed, or when window properties are changed.The delegate thread is allowed to change window properties, send events towindows, and close windows that it handles. It can also take over thecompositing tasks normally handled by the Composition Manager to performmore sophisticated compositing effects.

KD_WINDOWPROPERTY_SOURCE_ALPHA_QNX

Indicates whether a window has per-pixel transparency or not.

Synopsis:

#define KD_WINDOWPROPERTY_SOURCE_ALPHA_QNX 1011

It is an array of a single KDboolean. You can set it withkdSetWindowPropertybv() and read it with kdGetWindowPropertybv(). Theboolean has the value KD_TRUE if the window’s alpha channel should be used toset transparency, otherwise KD_FALSE. The default value is KD_FALSE.

Setting this property to true enables per-pixel transparency for this window inthe QNX Composition Manager. The application is responsible for drawing thecorrect alpha values in its alpha channel.

KD_WINDOWPROPERTY_SENSITIVE_QNX

Indicates whether a window will get input focus when a pointer click event isdetected.

Synopsis:

#define KD_WINDOWPROPERTY_SENSITIVE_QNX 1012

It is an array of a single KDboolean. You can set it withkdSetWindowPropertybv() and read it with kdGetWindowPropertybv(). Theboolean has the value KD_TRUE if the window gets input focus when clicked on,otherwise KD_FALSE.

The default value is KD_TRUE.

KD_WINDOWPROPERTY_MANAGED_QNX

Used by delegates who wish to handle the compositing of windows instead ofthe Composition Manager.

#define KD_WINDOWPROPERTY_MANAGED_QNX 1013



It is an array of a single KDboolean. You can set it withkdSetWindowPropertybv() and read it with kdGetWindowPropertybv(). Thedefault value is KD_FALSE, indicating that the window is composited by theQNX Composition manager.

When a window is managed by a delegate, it is removed from the CompositionManager’s scene. The delegate is responsible for compositing all of its managedwindows. The delegate thread will receive notifications whenever managedwindows post updates.

KD_WINDOWPROPERTY_SWAP_INTERVAL_QNX

Used to set a swap interval for a window.

#define KD_WINDOWPROPERTY_SWAP_INTERVAL_QNX 1014

The swap interval is the minimum number of video frame periods per bufferswap. The value must be an array of a single KDint32 between 0 and 255inclusively. You can set it with kdSetWindowPropertyiv() and read it withkdGetWindowPropertyiv().

The default value is 1.

KD_WINDOWPROPERTY_POINTER_FOCUS_QNX

Indicates if a window has pointer focus.

#define KD_WINDOWPROPERTY_POINTER_FOCUS_QNX 1015

It is an array of a single KDboolean. You can set it withkdSetWindowPropertybv() and read it with kdGetWindowPropertybv(). Theboolean has the value KD_TRUE if the window has pointer focus assigned to it,otherwise KD_FALSE.

The default value is KD_FALSE.

When pointer focus is assigned to a window, general focus cannot be set via mouseclick.

KD_WINDOWPROPERTY_BRIGHTNESS_QNX

Indicates brightness level of the window.

#define KD_WINDOWPROPERTY_BRIGHTNESS_QNX 1016

Used to set the brightness level of a window. The value must be an array of asingle KDint32 between -255 and 255 inclusively. To set it usekdSetWindowPropertyiv() and read it with kdGetWindowPropertyiv().

The default brightness level is 0.

KD_WINDOWPROPERTY_CONTRAST_QNX

Indicates contrast level of the window.

#define KD_WINDOWPROPERTY_CONTRAST_QNX 1017



Used to set the contrast level of a window. The value must be an array of asingle KDint32 between -255 and 255 inclusively. To set it usekdSetWindowPropertyiv() and read it with kdGetWindowPropertyiv().

The default contrast level is 0.

KD_WINDOWPROPERTY_HUE_QNX

Indicates hue level of the window.

#define KD_WINDOWPROPERTY_HUE_QNX 1018

Used to set the hue level of a window. The value must be an array of a singleKDint32 between -255 and 255 inclusively. To set it usekdSetWindowPropertyiv() and read it with kdGetWindowPropertyiv().

The default hue level is 0.

KD_WINDOWPROPERTY_SATURATION_QNX

Indicates saturation level of the window.

#define KD_WINDOWPROPERTY_SATURATION_QNX 1019

Used to set the saturation level of a window. The value must be an array of asingle KDint32 between -255 and 255 inclusively. To set it usekdSetWindowPropertyiv() and read it with kdGetWindowPropertyiv().

The default saturation level is 0.

KD_WINDOWPROPERTY_LEVEL_QNX

Indicates the EGL level of the window.

#define KD_WINDOWPROPERTY_LEVEL_QNX 1020

Used to set the EGL level of a window. The value must be an array of a singleKDint32 between 0 and 255 inclusively. To set it use kdSetWindowPropertyiv()and read it with kdGetWindowPropertyiv().

The default EGL level is 0.

KD_WINDOWPROPERTY_FREEZE_QNX

Indicates whether a window’s updates are frozen.

#define KD_WINDOWPROPERTY_FREEZE_QNX 1021

It is an array of a single KDboolean. You can set it withkdSetWindowPropertybv() and read it with kdGetWindowPropertybv(). Theboolean has the value KD_TRUE if the window’s updates should be frozen,otherwise KD_FALSE. The default value is KD_FALSE.



Events:

KD_EVENT_WINDOW_CREATE_QNX

Notify delegates of the creation of a window.

Synopsis:

#define KD_EVENT_WINDOW_CREATE_QNX (KD_QNX_EVENT_UNDEFINED + 0)

This event is sent to all threads with windows registered as delegates that sharethe same display.

The event’s userptr field is set to KD_NULL.

The event data is in the event->data.windowcreateqnx element of theevent’s data union, which has the following type:

typedef struct KDEventWindowCreateQNX {struct KDWindow *window;KDint32 valid;KDint32 flags;KDint32 egl_config;void *userptr;

} KDEventWindowCreateQNX;

The egl_config field corresponds to the config argument supplied by theapplication to the kdCreateWindow() function. The userptr field corresponds tothe eventuserptr argument supplied by the application to thekdCreateWindow() function. The window member is a local copy of the newlycreated window. It can be used anywhere a KDWindow pointer is required.

KD_EVENT_WINDOW_REALIZE_QNX

Notify delegates of the realization of a window.

Synopsis:

#define KD_EVENT_WINDOW_REALIZE_QNX (KD_EVENT_UNDEFINED_QNX + 1)

This event type signals a window’s delegate that a window buffer has beencreated. There can be more than one realization notification if the applicationcreates multiple buffers to support a window.

The event’s userptr field is set to the window’s delegate pointer.

The event data is in the event->data.windowrealizeqnx element of theevent’s data union, which has the following type:

typedef struct KDEventWindowRealizeQNX {struct KDWindow *window;int sid;

} KDEventWindowRealizeQNX;

The sid field corresponds to a unique identifier for the buffer that was created.The delegate can use this sid to gain access to a window’s buffer if it wantsaccess the surface contents. The window member is a local copy of the windowthat was the subject of the realize request. It can be used anywhere a KDWindowpointer is required.



KD_EVENT_WINDOW_PROPERTY_QNX

Notify delegates of the change of a window’s properties.

Synopsis:

#define KD_EVENT_WINDOW_PROPERTY_QNX (KD_EVENT_UNDEFINED_QNX + 2)


The event data is in the event->data.windowpropertyqnx element of theevent’s data union, which has the following type:

typedef struct KDEventWindowPropertyQNX {struct KDWindow *window;KDint32 pname;

} KDEventWindowPropertyQNX;

The pname field identifies which window property was affected by the change.The delegate can use the window and pname member to get the new value for theproperty. The window member is a local copy of the window that was the subjectof the property change. It can be used anywhere a KDWindow pointer is required.

KD_EVENT_WINDOW_CLOSE_QNX

Notify delegates of the closing of a window.

Synopsis:

#define KD_EVENT_WINDOW_CLOSE_QNX (KD_EVENT_UNDEFINED_QNX + 3)


The event data is in the event->data.windowcloseqnx element of theevent’s data union, which has the following type:

typedef struct KDEventWindowCloseQNX {struct KDWindow *window;

} KDEventWindowCloseQNX;

The window field is a local copy of the window that was closed. It should nolonger be used wherever a KDWindow pointer is required because the window isclosed at that point.

See also:Working with External APIs, io-winmgr


KD_QNX_input © 2010, QNX Software Systems GmbH & Co. KG.

The KD_QNX_input extension

Description:The KD_QNX_input extension aims to extend the OpenKODE specification toaddress issues such as focus rules in a multi-window and/or multi-displayenvironment. The extension also adds support for a keyboard I/O group and keyboardevents, which are currently lacking in the OpenKODE 1.0.2 Core Specification.

In 6.5.0, KD QNX extension enums have been corrected to use the proper namingconventions. The naming convention KD_QNX_* has been changed to KD_*_QNX. Anyexisting 6.4.1 applications that have been built with the old KD headers will still bebinary compatible with applications that are created in 6.5.0 however, in order torebuild applications with the new 6.5.0 KD header, you must update all extensionenum references to the new format.

Functions:

kdOutputSetpQNX()

KDint32 kdOutputSetpQNX( KDint32 startidx, KDuint32 numidxs, const void *buffer);

Except for the data type that is operated on, this function behaves the same as thekdOutputSeti() and kdOutputSetf() OpenKODE Core functions. This function operateson const void * data types which allow you to pass opaque handles to objects tothe implementation for processing.

For example, the KD_IOGROUP_ASSIGN_GROUP_QNX I/O group has I/O items thatrequire a window handle to be passed as the output value:

kdOutputSetpQNX (KD_OUTPUT_ASSIGN_POINTER_QNX, 1, &kd_win);

On success, the function returns the number of outputs that were actually set.Otherwise, it returns -1 and stores one of the error codes listed below into the errorindicator returned by kdGetError().

The kdOutputSetpQNX() function returns the following error codes:

KD_ENOMEM Out of memory or other resource.

KD_EIO Non-specific error from I/O device.

Events:

KD_EVENT_KEYBOARD_QNX

Keyboard input event.

Synopsis:

#define KD_EVENT_KEYBOARD_QNX (KD_EVENT_UNDEFINED_QNX + 1000)

Fired when an input in the keyboard device changes.

The data is contained in the keyboardqnx element of the event data union, withthe type KDEventKeyboardQNX, with the following fields:


© 2010, QNX Software Systems GmbH & Co. KG. KD_QNX_input

typedef struct KDEventKeyboardQNX {KDint32 index;KDuint32 flags;KDuint32 modifiers;KDuint32 key_cap;KDuint32 key_scan;KDuint32 key_sym;

} KDEventKeyboardQNX;

index The index number of the input that actually changed.

flags The status of the key (e.g. key down or key repeat).

modifiers The key modifiers for the keyboard event. Some keys (for example,Shift or Num Lock) modify other keys. When a modifier key ispressed or released, it’s evaluated through a table and the modifiersfield is updated accordingly.

key_cap The unique scan code produced by the key, without any modifiers.

key_scan The hardware-dependent scan code for the key.

key_sym The value of the key with modifiers applied to it.

The key flags, modifiers, and keycodes which the system generates can be foundin sys/keycodes.h.

When any one of the application’s windows has input focus, the event is sent tothat window. The eventuserptr parameter supplied when the window wascreated is then used as the value of the userptr field of the input event. Theevent is sent to the queue for the thread that created the window.

I/O groups and items

The I/O groups and items that this extension introduces into OpenKODE by thisextension are listed in this section.

KD_IOGROUP_KEYBOARD_QNX

Synopsis:

#define KD_IOGROUP_KEYBOARD_QNX (KD_IO_UNDEFINED + 0x1000)#define KD_STATE_KEYBOARD_AVAILABILITY_QNX (KD_QNX_IOGROUP_KEYBOARD + 0)#define KD_INPUT_KEYBOARD_FLAGS_QNX (KD_QNX_IOGROUP_KEYBOARD + 1)#define KD_INPUT_KEYBOARD_MODIFIERS_QNX (KD_QNX_IOGROUP_KEYBOARD + 2)#define KD_INPUT_KEYBOARD_KEY_CAP_QNX (KD_QNX_IOGROUP_KEYBOARD + 3)#define KD_INPUT_KEYBOARD_KEY_SCAN_QNX (KD_QNX_IOGROUP_KEYBOARD + 4)#define KD_INPUT_KEYBOARD_KEY_SYM_QNX (KD_QNX_IOGROUP_KEYBOARD + 5)

Any time a key is pressed on the keyboard, a KD_EVENT_KEYBOARD_QNX event isgenerated that contains data associated with the key.

This I/O group can be a per-game-controller group: further groups with the samesemantics may appear at KD_IOGROUP_KEYBOARD_QNX + n *KD_IO_CONTROLLER_STRIDE (where n is 1 for the second controller, up to 63 for the64th controller, and KD_IO_CONTROLLER_STRIDE is 64).



I/O items

Index Type Range Usage

KD_STATE_KEYBOARD_AVAILABILITY_QNX Mandatory KDint32 state Availabilitybitmap

KD_INPUT_KEYBOARD_FLAGS_QNX KDuint32 input 0..+65535 Flags

KD_INPUT_KEYBOARD_MODIFIERS_QNX KDuint32 input 0..+65535 Modifiers

KD_INPUT_KEYBOARD_KEY_CAP_QNX KDuint32 input 0..+65535 key_cap

KD_INPUT_KEYBOARD_KEY_SCAN_QNX KDuint32 input 0..+65535 key_scan

KD_INPUT_KEYBOARD_KEY_SYM_QNX KDuint32 input 0..+65535 key_sym

When any keyboard inputs change, the KD_EVENT_KEYBOARD_QNX event isgenerated, rather than the normal KD_EVENT_INPUT.

KD_STATE_KEYBOARD_AVAILABILITY_QNX is a state with a constant value thatindicates, using a bitmap, which inputs are available. Bit n represents inputKD_INPUT_KEYBOARD_FLAGS_QNX + n, and is set to 1 if the input is available and 0if not, with unused bits set to 0. The value of the state is 0 if the group is temporarilyunavailable, 31 if available.

KD_QNX_IOGROUP_DISP_GROUP

I/O group for per-input I/O group display focus.

Synopsis:

#define KD_IOGROUP_DISP_GROUP_QNX (KD_IO_UNDEFINED + 0x500)#define KD_STATE_DISP_GROUP_AVAILABILITY_QNX (KD_QNX_IOGROUP_DISP_GROUP + 0)#define KD_OUTPUT_DISP_POINTER_QNX (KD_QNX_IOGROUP_DISP_GROUP + 1)#define KD_OUTPUT_DISP_JOGDIAL_QNX (KD_QNX_IOGROUP_DISP_GROUP + 2)#define KD_OUTPUT_DISP_KEYBOARD_QNX (KD_QNX_IOGROUP_DISP_GROUP + 3)#define KD_OUTPUT_DISP_MOUSE_QNX (KD_IOGROUP_DISP_GROUP_QNX + 4)#define KD_OUTPUT_DISP_TOUCH_QNX (KD_IOGROUP_DISP_GROUP_QNX + 5)

This I/O group defines outputs that give the ability to assign an input device’s displayfocus. The outputs take a display ID argument for which to set the display focus of theI/O group corresponding to the I/O items define (for example,KD_OUTPUT_DISP_POINTER_QNX corresponds to the KD_IOGROUP_POINTER). Thedisplay ID must correspond to the display ID specified in winmgr.conf or to asystem generated display ID. If the display ID argument is -1, focus will be reset to thedefault, which is to set display focus to the first display.

This I/O group supports stride. Any input device’s I/O groups that support stride,support corresponding I/O items. This allows your application to set focus to aparticular device when there is more than one device present. Additional I/O itemswill be present at the base offset of the device type multiplied by index of the device ×stride (for example, KD_OUTPUT_DISP_POINTER_QNX + index of keyboard ×KD_IO_CONTROLLER_STRIDE).



I/O items


KD_STATE_DISP_GROUP_AVAILABILITY_QNX mandatory KDint32 state Availabilitybitmap

KD_OUTPUT_DISP_POINTER_QNX KDint32 output -1..+32767 Display or-1 to reset todefault

KD_OUTPUT_DISP_JOGDIAL_QNX KDint32 output -1..+32767 Display or-1 to reset todefault

KD_OUTPUT_DISP_KEYBOARD_QNX KDint32 output -1..+32767 Display or-1 to reset todefault

KD_OUTPUT_DISP_MOUSE_QNX KDint32 output -1..+32767 Display or-1 to reset todefault

KD_OUTPUT_DISP_TOUCH_QNX KDint32 output -1..+32767 Display or-1 to reset todefault

KD_STATE_DISP_GROUP_AVAILABILITY_QNX is a state with a constant value thatindicates, using a bitmap, which outputs are available. Bit n represents outputKD_OUTPUT_DISP_POINTER_QNX + n, and is set to 1 if the output is available, and 0if not, with unused bits set to 0. The value of the state is:

0 The group is temporarily unavailable.

1 There’s a pointer present.

2 There’s a jogdial preset.

4 There’s a keyboard.

8 There’s a mouse.

16 There’s a touch screen.

31 A pointer, jogdial, keyboard, mouse, and touch screen are present.

KD_QNX_IOGROUP_ASSIGN_GROUP

I/O group for per-input I/O group window focus.

Synopsis:



#define KD_IOGROUP_ASSIGN_GROUP_QNX (KD_IO_UNDEFINED + 0)#define KD_STATE_ASSIGN_GROUP_AVAILABILITY_QNX (KD_IOGROUP_ASSIGN_GROUP_QNX + 0)#define KD_OUTPUT_ASSIGN_POINTER_QNX (KD_IOGROUP_ASSIGN_GROUP_QNX + 1)#define KDOUTPUT_ASSIGN_JOGDIAL_QNX_ (KD_IOGROUP_ASSIGN_GROUP_QNX + 2)#define KD_OUTPUT_ASSIGN_KEYBOARD_QNX (KD_IOGROUP_ASSIGN_GROUP_QNX + 3)#define KD_OUTPUT_ASSIGN_MOUSE_QNX (KD_IOGROUP_ASSIGN_GROUP_QNX + 4)#define KD_OUTPUT_ASSIGN_TOUCH_QNX (KD_IOGROUP_ASSIGN_GROUP_QNX + 5)

This I/O group defines outputs which give the ability to assign an input device’s focusto a specific window. The outputs take a window argument in order to set the focus ofthe I/O group corresponding to the I/O items define (for example,KD_OUTPUT_ASSIGN_JOGDIAL_QNX corresponds to the KD_IOGROUP_JOGDIAL).The window argument can have been created in any thread of an application, or mustbe the KDWindow field of a notification event sent to a delegate thread. If the windowargument is -1, focus will be reset to the default value, which is to obey global focus.

Global focus consists of the display that has current focus, and the window that hasfocus on that display. Global focus can be set with pointer devices by clicking andreleasing on the same window. When you set the focus to a particular window, itcauses it to obey the assignment of focus for that device.

This I/O group supports stride. Any input device’s I/O groups that support stride,support the corresponding I/O items. This lets your application set focus to aparticular device when there is more then one present. Additional I/O items will bepresent at the base offset of the device type multiplied by index of the device * stride(for example, KD_OUTPUT_ASSIGN_KEYBOARD_QNX + index of keyboard *KD_IO_CONTROLLER_STRIDE).

The absence of pointer devices is intentional, since they are used to set global focus.

I/O items


KD_STATE_ASSIGN_GROUP_AVAILABILITY_QNX mandatory KDint32 state Availabilitybitmap

KD_OUTPUT_ASSIGN_JOGDIAL_QNX KDint32 output -1..+32767 Windowor -1 toreset todefault

KD_OUTPUT_ASSIGN_KEYBOARD_QNX KDint32 output -1..+32767 Windowor -1 toreset todefault

continued. . .




KD_OUTPUT_ASSIGN_MOUSE_QNX KDint32 output -1..+32767 Windowor -1 toreset todefault

KD_OUTPUT_ASSIGN_TOUCH_QNX KDint32 output -1..+32767 Windowor -1 toreset todefault

KD_STATE_ASSIGN_GROUP_AVAILABILITY_QNX is a state with a constant valuethat indicates, using a bitmap, which outputs are available. Bit n represents outputKD_OUTPUT_ASSIGN_JOGDIAL_QNX + n, and is set to 1 if the output is available, and0 if not, with unused bits set to 0.

The value of the state is:

0 The group is temporarily unavailable.

1 There’s a jogdial preset.

2 There’s a keyboard.

8 There’s a mouse.

16 There’s a touch screen.

31 A pointer, jogdial, keyboard, mouse, and touch screen are present.

See also:Working with External APIs, KD_QNX_window, io-winmgr


Appendix A

What’s New

In this appendix. . .What’s new in Composition Manager for 6.5.0 65

June 2, 2010 Appendix: A • What’s New 63

© 2010, QNX Software Systems GmbH & Co. KG. What’s new in Composition Manager for 6.5.0

This appendix describes what’s new and changed in the QNX Composition Manager.

What’s new in Composition Manager for 6.5.0In 6.5.0, KD QNX extension enums have been corrected to use the proper namingconventions. The naming convention KD_QNX_* has been changed to KD_*_QNX. Anyexisting 6.4.1 applications that have been built with the old KD headers will still bebinary compatible with applications that are created in 6.5.0 however, in order torebuild applications with the new 6.5.0 KD header, you must update all extensionenum references to the new format.

Understanding Composition

We’ve added a new section to the documentation.

Why use Composition Manager?


Configuring Composition Manager


The following enums were added to kd_qnx_window:

KD_WINDOWPROPERTY_BRIGHTNESS_QNXKD_WINDOWPROPERTY_CONTRAST_QNXKD_WINDOWPROPERTY_HUE_QNXKD_WINDOWPROPERTY_SATURATION_QNXKD_WINDOWPROPERTY_LEVEL_QNXKD_WINDOWPROPERTY_FREEZE_QNX

The following #defines were added to kd_qnx_input:

#define KD_OUTPUT_DISP_MOUSE_QNX (KD_IOGROUP_DISP_GROUP_QNX + 4)#define KD_OUTPUT_DISP_TOUCH_QNX (KD_IOGROUP_DISP_GROUP_QNX + 5)#define KD_OUTPUT_ASSIGN_MOUSE_QNX (KD_IOGROUP_ASSIGN_GROUP_QNX + 4)#define KD_OUTPUT_ASSIGN_TOUCH_QNX (KD_IOGROUP_ASSIGN_GROUP_QNX + 5)

June 2, 2010 Appendix: A • What’s New 65

qnx neutrino composition manager · this guide describes how to use the qnx neutrino composition...

Documents