WindML SDK 3.0 PROGRAMMER S GUIDE

Transcription

1 WindML SDK 3.0 PROGRAMMER S GUIDE

2 Copyright 2002 Wind River Systems, Inc. ALL RIGHTS RESERVED. No part of this publication may be copied in any form, by photocopy, microfilm, retrieval system, or by any other means now known or hereafter invented without the prior written permission of Wind River Systems, Inc. AutoCode, Embedded Internet, Epilogue, ESp, FastJ, IxWorks, MATRIX X, prism, prism+, psos, RouterWare, Tornado, VxWorks, wind, WindNavigator, Wind River Systems, WinRouter, and Xmath are registered trademarks or service marks of Wind River Systems, Inc. Attaché Plus, BetterState, Doctor Design, Embedded Desktop, Emissary, Envoy, How Smart Things Think, HTMLWorks, MotorWorks, OSEKWorks, Personal JWorks, psos+, psosim, psosystem, SingleStep, SNiFF+, VxDCOM, VxFusion, VxMP, VxSim, VxVMI, Wind Foundation Classes, WindC++, WindManage, WindNet, Wind River, WindSurf, and WindView are trademarks or service marks of Wind River Systems, Inc. This is a partial list. For a complete list of Wind River trademarks and service marks, see the following URL: Use of the above marks without the express written permission of Wind River Systems, Inc. is prohibited. All other trademarks mentioned herein are the property of their respective owners. Corporate Headquarters Wind River Systems, Inc. 500 Wind River Way Alameda, CA U.S.A. toll free (U.S.): 800/545-WIND telephone: 510/ facsimile: 510/ For additional contact information, please visit the Wind River URL: For information on how to contact Customer Support, please visit the following URL: WindML SDK Programmer s Guide, Sep 02 Part #: DOC ND-01

3 Contents 1 Overview Introduction WindML Architecture SDK Layer WindML Distribution Documentation... 4 Documentation Conventions Getting Started Introduction WindML 2.0 Compatibility Prerequisites WindML Setup Installation Configuration Overview... 8 VxWorks and BSP Configuration... 8 WindML Configuration... 9 Object and Library Files iii

4 WindML SDK 3.0 Programmer s Guide 2.3 Tutorial and Examples Before You Begin Introduction General WindML Setup Reading Events Example Programs Basic Graphics Rendering Bitmap Handling Cursor Handling Text Input and Output Handling General Demonstration Program Overlay, Alpha Blending, and Video Source Handling Double Buffer Handling Windowing Audio Demonstration Program Other Demonstration Program WindML Source Conventions Introduction Directory Contents Source Files Header Files Configuration Introduction Configuring the Operating System The Configuration Process Configuration Validation Configuration Files File Naming Conventions iv

5 Contents 4.3 Using the Build Dialog and Configuration Tool WindML Configurations Defining Saving Modifying Deleting Building WindML Libraries Using the Build Dialog Using Command Line Removing WindML Object Files Using the Build Dialog Using Command Line File Locations and Environment Variables VxWorks BSP Requirements Graphics Device Memory Mapping Physical Mapping Virtual Mapping Common BSP API Project Facility Linking the 2D Graphics Library Adding WAV or AU Audio Stream Support Defining WindML Device Support D Graphics Library Introduction Graphics Contexts Creation Routines Default Bitmap v

6 WindML SDK 3.0 Programmer s Guide 5.3 Drawing Primitives Drawing Primitive Routines Basic Drawing Example Batch Drawing Drawing on Display Example Text Rendering and Font Management Initializing a Font Driver Creating Fonts Font Types Encoding Fonts Drawing Text Rendering Font Example Bitmap Management Device Independent Bitmaps Device Dependent Bitmaps Creating a Bitmap Example Cursor Management Software and Hardware Cursors Cursor Image and Hot Spots Constraining and Freeing the Cursor Creating a Cursor Example Color Management Color Types Color Formats vi

7 Contents Indexed Color Management Referencing Specific CLUT Entries Color Cubes and Dithering Dynamic Color Allocation Set up a CLUT Example Region Management Clipping and View Ports Raster Operators Creating a Graphics Context Example Set up a Viewport Example Double Buffering Using Double Buffering Example Message and Input Services Introduction Messages Communicating Input Events Keyboard Messages Pointer Messages Identifying a Pointer Button Example The Input Service Message Queues The Default Message Queue Input Callbacks Windowing Introduction vii

8 WindML SDK 3.0 Programmer s Guide 7.2 The Window Containment Z-Order Output Drawing in a Window The MSG_DRAW Message Validation and Invalidation Drawing Modes Clipping Modes Input Synthesized Input Messages Keyboard Input Pointer Input Window Message Processing Callback Functions The WIN_MSG Structure Sending and Posting Messages Geometry Size and Position Changing Window Geometry Enforcing a Minimum Size Z-Order Activation Attributes State The Window Class Class Hierarchy Message Handling Class Data viii

9 Contents 7.4 The Window Manager The Root Window The Root Class Window Manager Callbacks Messages The Frame Class Creating Framed Windows Controlling Framed Windows Resources Cursors Fonts Colors Message Routing Routing Pointer Messages Routing Keyboard Messages The Windowing Application Application Callbacks Video Handling Introduction Video Overlays and Video Video Extension Configuration Using the Video Extension Video Operations Capturing a Video Image Video Extension Example Program ix

10 WindML SDK 3.0 Programmer s Guide 9 Image Handling Introduction JPEG Images Initialization Compression and Decompression Parameters Writing a JPEG Image to a DDB Saving a Bitmap as a JPEG Image Audio Handling Introduction Audio The DSP Device The Mixer Device WAV File Handling AU File Handling Resource Management Introduction General Resources Initialization Cleanup Memory Management Memory Pools Memory Macros x

11 Contents 11.4 Registry Registry Information Adding to Registry Finding Registry Entries Removing Registry Entries Compatibility with WindML Overlay Surfaces Creating an Overlay Accessing an Overlay Moving an Overlay Driver Information and Control Querying a Driver with uglinfo( ) Controlling a Font Driver Controlling an Input Driver Setting the Display Mode WindML Log Portability Introduction OS Abstraction Layer OS System Services A Glossary A.1 Introduction A.2 Acronyms A.3 Terms xi

12 WindML SDK 3.0 Programmer s Guide Index xii

13 1 Overview 1.1 Introduction The Wind River Multi-media Library (WindML) supports multimedia applications running on embedded systems. WindML is designed to provide foundation graphics, including mixing of video sources with graphics, and a framework in which you can develop standardized graphics and audio device drivers. For more information, see WindML DDK Programmer s Guide 3.0. WindML provides a high degree of architectural and hardware independence for application code. This portability results from WindML s modular design, which isolates all hardware functionality in a discrete set of API libraries. The WindML API libraries provide a consistent interface to graphics hardware across CPU architectures and operating systems. WindML also provides facilities to handle input devices, and process events from input devices. WindML implements the following design goals: Simplicity. Provides a robust set of graphics primitives, and basic video and audio functionality. Hardware Portability. Executes across a matrix of architectures. OS Portability. Ports across RTOS environments. Ease of Driver Development. Provides a robust mechanism to develop custom drivers for applications. 1

14 WindML SDK 3.0 Programmer s Guide 1.2 WindML Architecture WindML consists of two components: (1) Software Development Kit (SDK) You can use the SDK component to develop an application. It provides a comprehensive API set for graphics, input handling, multimedia, font, and memory management, allowing you to write hardware independent portable code for hardware platforms. For more information, see, SDK Layer, p.3. (2) Driver Development Kit (DDK) You can use the DDK component to implement drivers. It provides a complete set of reference drivers for common hardware configurations, and an API set so you can quickly bootstrap new drivers from the supplied generic drivers. The DDK is extensible and customizable. WindML provides the complete source code base so you can perform further customization. For more information, see WindML DDK Programmer s Guide 3.0. In Figure 1-1, the shaded boxes represent WindML components. There can be additional drivers or devices. WindML SDK has a multi-layered architecture which abstracts functionality into different layers as follows: Figure 1-1 Layered Architecture Application (Graphics, Audio, Video, and Event Services) VxWorks SDK (Hardware Independent Layer) Output Drivers Input Drivers Additional Drivers DDK (Hardware Dependent Layer) Output Device (Monitor) Input Device (Mouse) Additional Devices Hardware 2

15 1 Overview SDK Layer 1 The SDK layer defines an interface between the application code and the lower-level hardware drivers. This allows you to develop applications independently of the underlying hardware. The SDK provides the following API sets: resource initialization and cleanup routines for graphics chips multimedia API, which consists of several components such as: 2D graphics region management windowing color management overlay support video support JPEG support audio event services memory management extensions API device management The API libraries and routines are fully documented in HTML format online and in hard copy. For more information, see WindML API Reference WindML Distribution WindML can not provide out of the box support for all available graphics hardware. However, WindML was developed to support a diverse set of drivers, for a cross-section of graphics driver types including dedicated graphics processors, CPUs with on-chip LCD controllers, and input drivers. The WindML distribution consists of a documentation set and a software distribution. You can download the latest version of the WindML software and online documentation, and access the graphics driver repository, by logging into the Wind River Online Support Web site: For more information, see the WindML Release Notes

16 WindML SDK 3.0 Programmer s Guide Documentation WindML documentation is written as a supplement to existing Wind River documentation, including the Tornado Getting Started Guide, the Tornado User s Guide, the VxWorks Programmer s Guide, and the VxWorks Reference Manual. The WindML document set consists of: WindML SDK Programmer s Guide (this book in PDF) WindML DDK Programmer s Guide WindML API Reference WindML Release Notes NOTE: The WindML SDK Programmer s Guide and the WindML DDK Programmer s Guide provide a unique perspective for multimedia development based on an application versus driver development perspective. Additional API library and routine documentation is available. For more information, see WindML API Reference 3.0 or you can access API reference material online, in HTML format, through the Help menu of the Tornado IDE. Documentation Conventions This guide uses the following conventions for cross references, pathnames, and typography. Cross-References Pathnames Cross-references are to a named section elsewhere in this guide or the related documentation set. Forward slashes are used as pathname delimiters for both UNIX and Windows filenames. Typographical Conventions This guide uses the conventions shown in Table 1-1 to differentiate various elements. Parentheses are always included to indicate a subroutine name, as in printf( ). 4

17 1 Overview Table 1-1 Font Usage for Special Terms Term files, pathnames libraries, drivers host tools Example /etc/hosts ugllib, nfsdrv more, chkdsk 1 subroutines uglcoloralloc( ) boot commands p code display main ( ); keyboard input make CPU=MC display output value = 0 user-supplied parameters constants C keywords, cpp directives named key on keyboard control characters lower-case acronyms GUI titles and commands GUI menu path name INCLUDE_NFS #define RETURN CTRL+C fd Help Tornado>Help>Contents 5

18 WindML SDK 3.0 Programmer s Guide 6

19 2 Getting Started 2.1 Introduction This chapter describes how to set up, install, and configure WindML using a simple tutorial for new users. The tutorial demonstrates key features of WindML and its use in application development. The example programs do not present a total description of WindML capabilities. They serve as an introduction to some of the capabilities and provide insight into functionality your application must address WindML 2.0 Compatibility WindML 3.0 maintains as much WindML 2.0 compatibility as possible while expanding the capabilities. For example, the windowing API was modified to gain the benefits of application interoperability. For WindML 2.0 compatibility issues, refer to the WindML 3.0 Release Notes Prerequisites You should be familiar with the Wind River Tornado development environment and development tools, such as C compilers, debuggers, and build utilities. 7

20 WindML SDK 3.0 Programmer s Guide 2.2 WindML Setup Installation Before you install WindML 3.0, prepare for the installation by referring to the WindML Release Notes. After completing the preliminary steps, install WindML in a similar fashion to any Tornado-compatible product. For procedures to install a Tornado-compatible product, refer to the Tornado Getting Started Guide. After installation, the Tornado directory tree is populated with all directories and files associated with the product. NOTE: The product is a source-only product and therefore must be configured, compiled, and linked by the Tornado tools prior to use Configuration Overview You must configure the VxWorks kernel and WindML before proceeding. The section describes an example configuration so you can start using WindML. For detailed information on the configuration process and using the configuration tool, see 4. Configuration. VxWorks and BSP Configuration The VxWorks BSP, as distributed, is not set up to use WindML. The VxWorks BSP readiness to support WindML varies among Tornado versions and BSPs. A Tornado 2.2 BSP usually provides all necessary functionality for WindML while the earlier versions require some minor BSP modifications. The installdir/target/src/ugl/bsp/config/bspname directory contains requirements for the set up of a specific BSP to support WindML. The BSPs in this directory are valid for WindML, however, not all potential BSPs are in this directory. 8

21 2 Getting Started As there are similarities among BSPs, an examination of a BSP similar to the one you are using should provide a starting point for configuration. In general, you may be required to: Install required patches Configure the BSP to include the WindML components and any modifications as described in installdir/target/src/ugl/bsp/config/bspname Depending on the type of processor, establish memory mapping in the BSP memory-mapping table, sysphysmemdesc. For most BSPs, this is only required for pre-tornado 2.2. For more information on specific memory mapping requirements for a BSP, review the readme file in installdir/target/src/ugl/bsp/config/bspname. The general steps to configure a BSP for WindML are detailed in 4. Configuration. After you make the modifications, rebuild the BSP using the standard BSP building procedures described in the Tornado documentation. 2 WindML Configuration A WindML configuration must be defined, compiled, and linked. Use the WindML build dialog and configuration tool to define and then build WindML based on the configuration. The build dialog is launched with the Tornado Tool menu, Tools>WindML on Windows hosts, or from the WindML icon in the launch tray on Unix hosts. From the build dialog, you can launch the configuration tool, define a configuration, build WindML from a previously defined configuration, or remove all generated objects for a configuration. For more information on how to use the configuration tool, see 4.3 Using the Build Dialog and Configuration Tool, p.42. From the build dialog, the configuration tool can be launched. The configuration tool: maintains multiple WindML configurations restricts configurations to only specify legal configurations extends easily to include new drivers and feature selection NOTE: A WindML configuration is described in a configuration file. WindML has several common configuration files for many processor and graphics combinations. The filenames encode the target processor board name, device name, frame buffer mode, and resolution, as described in 2.2 WindML Setup, p.8. For requirements and limitations of a specific graphics device, see the text file in the installdir/target/h/ugl/driver/graphics/devicename directory. 9

22 WindML SDK 3.0 Programmer s Guide Prior to defining a WindML configuration, you must identify your hardware configuration and the type of: processor and tool chain required for the processor configuration. The tool chain identifies which gnu or Diab compiler, and linker are to be used as well as options such as little or big endian, and hardware or software floating point graphics device input devices and the I/O device names where the input device is connected to the target processor Example Configuration Perform the following steps as an example configuration for the tutorial and example programs provided in WindML. For more information, see 4.3 Using the Build Dialog and Configuration Tool, p.42. Step 1: Step 2: Step 3: Launch the Build Dialog from the Tornado Tool Menu. You can launch the Build Dialog from the Tools>WindML on Windows hosts, or from the WindML icon in the launch tray on Unix hosts. Launch the WindML Configuration Tool. 1. Click Configure from the build dialog. This launches the WindML configuration tool. 2. From the File menu, select New to create a new configuration, or Open to open an existing configuration. Select the Build Tab. Complete the following to select build options: 1. Select the type of processor for your target hardware. 2. Select the tool chain required for the target configuration. 3. Check the options to Build WindML Object and Build WindML examples. These options compile and link a downloadable WindML object and the example programs. 10

23 2 Getting Started Step 4: Step 5: Select the Devices Tab. Complete the following to select device options: 1. Select the type of Graphics Driver. 2. Select the type of output device, such as a flat panel display, and generic CRT monitor. 3. Set the Graphics Settings, consisting of the pixel format and resolution. If your hardware includes a resolution of 800x600 at a color depth of 16 bits per pixel, select that configuration for the graphics display. If your hardware does not support this configuration, select the closest configuration option as possible. The higher resolution and the number of bits per pixel provides the best environment for the example programs. To execute some of the example programs, there are specific requirements that must be met. For example, to demonstrate all features in the video example program, a pixel format must include alpha blending, such as ARGB Set the Pointer settings consisting pointer type and the I/O device where the pointer is attached to the target processor. 5. Set the Keyboard settings consisting of the keyboard type, keyboard mapping, and the I/O device where the keyboard is attached to the target processor. 6. Set the Audio settings. Select the Advanced Tab. Complete the following to select advanced features and memory options: 1. Select all available options for the graphics device driver. Some example programs require options which may not be available for all graphics device drivers. If your graphics device does not support these options, the example programs requiring then cannot be executed. 2. Select VxWorks System Pool for your Memory Options. 3. Select WWM as your Window Manager. 2 11

24 WindML SDK 3.0 Programmer s Guide Step 6: Step 7: Select the Bitmap Fonts Tab. Complete the following to select font options: 1. Check the option to Include Unicode Support. 2. Select Unlimited as your Font Glyph Cache Size. 3. Select All bitmap fonts. 4. Select Save, from the File menu, to save the configuration to the file system. Compile and Link WindML for the Specified Configuration. 1. Select the name you assigned to your configuration from the drop down list box. 2. Click Build to build the WindML configuration. A build window opens and the compile and link process begins. Object and Library Files After the build completes, the following object and library files are available in installdir/target/lib: WindML Archive Library This archive library contains all WindML objects for the specified configuration. A WindML application may be linked to the archive library to build a WindML object module consisting of only the WindML functionality that the application requires. The location of this archive module varies depending on the Tornado version, as in Table 2-1: Table 2-1 Archive Module Location Tornado Version 2.0.x and 2.1.x Directory installdir/target/lib/lib$(cpu)$(tool)ugl.a 2.2 installdir/target/lib/$(cpu_family)/$(cpu)/$(tool)/libwndml.a 12

25 2 Getting Started WindML Object Module Per Configuration This object file is a object module containing all WindML functionality for the specified configuration. The entire WindML application interface is present in this object file. The location of this object file varies depending on the Tornado version, as in Table 2-2: 2 Table 2-2 Object File Location Tornado Version 2.0.x and 2.1.x Directory installdir/target/lib/ugl$(cpu)$(tool).o 2.2 installdir/target/lib/$(cpu_family)/$(cpu)/$(tool)/wndml.o Downloadable WindML Example Programs The example programs are in installdir/target/lib/ugl$(cpu)$(tool)apps regardless of the Tornado version. There are two sets of examples programs: With the _ugl.o ending Already linked with all the functionality of WindML required to execute the example program. Without the _ugl.o ending Example programs require to be linked with the WindML library or the WindML object module. 13

26 WindML SDK 3.0 Programmer s Guide 2.3 Tutorial and Examples Before You Begin To proceed with the tutorial, you may select one of the following: Build a VxWorks image that includes the WindML object module. Using this technique, the VxWorks image includes all functionality so you can download and execute any WindML example program. Dynamically download the WindML object module followed by the example program you desire to execute. Dynamically download the example program pre-linked with the WindML library. That is, the example program with the _ugl.o ending. Each method is entirely valid and is a personal preference depending on how you use the Tornado environment. However, you can download only one example program at a time. To switch between examples, the previous example program must be unloaded and the new example program loaded Introduction Any WindML application must perform some common operations. This tutorial addresses the common operations which a WindML application must implement. After the tutorial, this chapter describes several of the WindML example programs that may be used as a basis for understanding WindML capabilities. These example programs demonstrate the fashion in which a WindML program may be written General WindML Setup Any WindML application must perform the following actions, regardless of the application: Initialize Obtain the resources and characteristics of the display Create graphics context Allocate the colors that the application uses 14

27 2 Getting Started Step 1: Initialize. The initialization process configures WindML as per the configuration specified with the WindML configuration tool. The items configured are as follows: Memory pool, if a private memory pool is specified Graphics device; which includes the device type in the specified mode such as pixel format, resolution, refresh rate, and optional features Keyboard device and the specified keyboard-mapping Pointer devices Audio devices Font engines and the specified fonts The initialization process is simple to accomplish. As in Example 2-1, your application calls the uglinitialize( ) function. 2 Example 2-1 Initialize WindML /* Initialize WindML */ if (uglinitialize()!= UGL_STATUS_OK) { /* Error WindML did not initialize */ } else { /* WindML sucessfully initialized */ } NOTE: You must call uglinitialize( ) before calling any WindML routines or results will be undefined and the expected operation will not take place. The return value from uglinitialize( ), which reflects whether the WindML configuration is properly initialized, is either a UGL_STATUS_OK or UGL_STATUS_ERROR. When uglinitialize( ) returns with a status of UGL_STATUS_OK, the configuration specified with the WindML configuration tool is properly initialized. Catastrophic error messages are logged to the WindML log and displayed as standard errors. The application suspends and there is no return. 15

28 WindML SDK 3.0 Programmer s Guide Step 2: Example 2-2 Obtain Resource Identifiers and Display Characteristics. After you initialize WindML, your application must obtain resource identifiers. Although the uglinitialize( ) function initializes the resources specified by your configuration, your application does not have access to those resources. To obtain access to the resources, your application must look up the resource identifiers in the WindML registry. Each WindML resource has a handle, called an identifier, for the resource. This resource identifier is used in the majority of WindML routines to identify the resource. To identify the resource, your application uses uglregistryfind( ). Example 2-2 illustrates how your application obtains the resource identifiers: Resource Identifiers /* Obtain the device identifier for the display */ devid = (UGL_DEVICE_ID)uglRegistryFind (UGL_DISPLAY_TYPE, 0, 0,0)->id; /* Obtain the resource identifier for the input service */ inputserviceid = (UGL_INPUT_SERVICE_ID)uglRegistryFind UGL_INPUT_SERVICE_TYPE, 0, 0,0)->id; /* Obtain the font driver identifier */ fontdrvid = (UGL_FONT_DRIVER_ID)uglRegistryFind (UGL_FONT_ENGINE_TYPE, 0, 0,0)->id; An application frequently requires information about the display where graphics are rendered, such as the width and height in pixels. If your application requires the dimensions of the display, use Example 2-3: Example 2-3 Display Characteristics /* Obtain the characteristics of the display */ uglinfo(devid, UGL_FB_INFO_REQ, &fbinfo); displaywidth = fbinfo.width; displayheight = fbinfo.height; Besides obtaining the dimensions of the display, you can use the uglinfo( ) function to query the graphics driver for other information. The call to uglinfo( ) uses the resource identifier for the graphics device obtained above, using the registry find routine, uglregistryfind( ). 16

29 2 Getting Started Step 3: Example 2-4 Example 2-5 Create a Graphics Context. Your application must create a graphics context after resource identifiers are obtained and before graphics are displayed. The graphics context defines the environment your application uses to define how graphics are rendered. The items defined in a graphics context include the following: Type of lines to be drawn Background and foreground colors Identification of a default bitmap, that is, a bitmap used as the destination for graphics rendering Identification of the font used for text display Raster operation to control how graphics are rendered such as simple copy to the display, or logical and with the display, and so on. A graphics context must be defined to perform any graphics rendering. The identifier for the graphics context is an input parameter to nearly all WindML routines that render graphics. To create a graphics context, your application would include a statement similar to Example 2-4. Creating Graphic Context /* Create a graphics context */ gc = uglgccreate(devid); The parameter, devid, identifies the device identifier for the graphics device found in the WindML registry. A graphics context is associated with a specific graphics device. An application may create and use multiple graphics contexts, each serving a different purpose that controls the process where graphics are rendered. After you create the graphics context, you may modify the graphics context to change the manner in which graphics primitives render, such as line width, foreground/background colors, and raster operations. Example 2-5 illustrates how you set the line width: Setting Line Width /* Use a dashed line for subsequent line drawing */ ugllinestyleset(gc, UGL_LINE_STYLE_DASHED); For a description of how to modify a graphics context, see 5.2 Graphics Contexts, p

30 WindML SDK 3.0 Programmer s Guide Step 4: Allocate Colors Used by the Application. Colors are represented in WindML using ARGB8888, which is a 32-bit format consisting of 8 bits for every alpha, red, green, and blue component. The color allocation process converts the color represented by the portable ARGB8888 format to that used by the graphics device. By representing colors in the ARGB8888 format, your application can execute in an environment where the graphics hardware may represent the color in any format. For example, your application may use graphics hardware that uses a color format of RGB565, or in another environment, a color format of ARGB4444. By using the portable color representation, your application does not have to make any adjustments for the different color formats used by the graphics hardware. The color allocation process provides a color that is represented in the portable ARGB8888 format and returns a corresponding color that represents the desired color on the graphics hardware. To create the color value in the portable ARGB8888 format, you can use one of the following two macros: UGL_MAKE_ARGB Create an ARGB8888 value from the components alpha, red, green, and blue. For example, to specify a magenta color with 50% alpha blending, your application can use the following macro: UGL_MAKE_ARGB( 0x80, 168, 0, 168 ) UGL_MAKE_RGB Create an ARGB8888 value from the components red, green, and blue. In this macro, the alpha channel is assumed to be full opaque a value of 0xff. For example, to specify a cyan color, your application would use the following macro: UGL_MAKE_RGB( 0, 168, 168) 18

31 2 Getting Started To allocate the color, which includes the conversion of the portable color to the device specific color representation, your application uses uglcoloralloc( ). Example 2-6 illustrates the process of allocating colors. 2 Example 2-6 Allocating Colors uglcoloralloc(devid, &colortable[black].rgbcolor, UGL_NULL, UGL_NULL, &colortable[black].uglcolor, 1); uglcoloralloc(devid, &colortable[blue].rgbcolor, UGL_NULL, UGL_NULL, &colortable[blue].uglcolor, 1); uglcoloralloc(devid, &colortable[green].rgbcolor, UGL_NULL, UGL_NULL, &colortable[green].uglcolor, 1); In Example 2-6, a color table with two fields exists -- the portable RGB color format and another field that contains the color value provided by the graphics hardware that corresponds to the specified RGB color. As usual, uglcoloralloc( ) requires the identifier for that graphics device, devid Reading Events A typical WindML application must process events, such as pointer and keyboard input data. Some WindML applications only display graphical images and do not have input devices. WindML uses the concept of a input service that collects and queues all WindML events. You must obtain the input service identifier to provide access to the input service. Step 2: Obtain Resource Identifiers and Display Characteristics., p.16 describes the process of obtaining the identifier for the input service. To read an item from the input queue, your application calls uglinputeventget( ). The first input event is read from the input event queue and returns to your application. If there is no event in queue, the routine waits for a specified amount of time prior to returning to your application. 19

32 WindML SDK 3.0 Programmer s Guide Example 2-7 illustrates the process to get an event from the event queue. Example 2-7 Get Event /* read an event from the event queue, if none available, then wait */ ustat = uglinputeventget (inputserviceid, &event, 100); /* If an event was present, then process the event*/ if (ustat = UGL_STATUS_Q_EMPTY) { /* Event is present, determine type and process */ switch (event.type) { case ET_POINTER: /* Pointer event */... break; case ET_KEYBOARD: /* Keyboard event */... break;... } } else /* no event is present */ In Example 2-7, uglinputeventget( ) is called specifying the input service identifier, inputserviceid, as the input event queue to be read. If there is an event pending, the event is placed in the event data structure, event. If an event is not available, uglinputeventget( ) enters a pending state waiting for event data to become available. In this case, the wait time is set to 100 milliseconds. 20

33 2 Getting Started Example Programs WindML is distributed with several example programs in installdir/target/src/ugl/example. These demonstration programs illustrate various operations that may be performed with the WindML API as follows: Basic graphics rendering such as lines, rectangles, and ellipses Test input and output Bitmap handling Video and audio Windowing 2 Each of these programs follows the initialization process described in General WindML Setup, p.14. There are minor variations in the way the setup phase is accomplished by the example program. You may want to examine the setup phase in each of the example programs and preview how setup can be accomplished. All example programs described in this chapter assume WindML is configured as in Example Configuration, p.10. The examples do not address the process when object files are downloaded or started as that process depends on how you choose to build WindML and use the Tornado environment. The example programs provide full source code and ample comments to demonstrate WindML functionality. To execute these example programs, complete the following: 1. Download the example program. 2. Start the program which is usually the name of the source file. 21

34 WindML SDK 3.0 Programmer s Guide Basic Graphics Rendering The basic graphics rendering example program demonstrates how WindML can be used to create basic shapes, such as lines, rectangles, and polygons. The source file for this program is located in installdir/target/src/ugl/example/basics. The object file is in installdir/target/lib/ugl$(cpu)$(tool)apps/wexbasics.o. A prelinked object file is in installdir/target/lib/ugl$(cpu)$(tool)apps/wexbasics_ugl.o. This example program demonstrates basic graphics rendering operations. After the application initializes, the example program performs the following operations: Line drawing including thin solid lines, thin dashed lines, thick solid lines, thick dashed lines, and lines of various colors. Rectangle drawing including those filled with a pattern Polygon drawing including fills Ellipses including closed, open, and arc ellipses Bitmap Handling One of the basic operations in any graphics program is the handling of bitmaps. In fact, WindML views the actual display as a bitmap. Bitmaps are divided into two types-- a Device Independent Bitmap (DIB), and a Device Dependent Bitmap (DDB). An application generally constructs DIBs so the application can easily be moved from one type of graphics hardware to another. Bitmaps are categorized as either a DIB or a DDB, and represented as the following: Monochrome the monochrome bitmap can be viewed as an array of bits where each bit corresponds to a single pixel. Monochrome bitmaps are usually used where the image has a foreground and background color. Color the color bitmap is an array of pixels where each pixel can be represented by any color the graphics hardware supports. 22

35 2 Getting Started Transparent the transparent bitmap can be viewed as a bitmap consisting of both a monochrome and color bitmap. The monochrome bitmap acts as a mask for the color bitmap. Wherever a pixel is set in the monochrome bitmap, the corresponding pixel in the color bitmap is acted on, such as being rendered to the display. The corresponding pixel in the color bitmap is not acted on if a position in the monochrome bitmap is clear. For example, when an image is transferred to the display, the previous value at the pixel location is retained if the corresponding pixel in the mask is cleared. Cursor the cursor bitmap is a special purpose transparent bitmap specifically designed for cursor images. For a detailed description of bitmaps in WindML, see 5. 2D Graphics Library. The bitmap handling example program demonstrates the way WindML can be used to create various bitmaps and to act upon those bitmaps. The source file for this program is in installdir/target/src/ugl/example/bitmaps. The object file is in installdir/target/lib/ugl$(cpu)$(tool)apps/ wexbitmap.o. A prelinked object file is in installdir/target/lib/ugl$(cpu)$(tool)apps/ wexbitmap_ugl.o. This example program demonstrates basic bitmap handling operations. After the application initializes, the example program performs the following operations: Creates the various DDBs from DIBs. 2 Transfers DDB from a source DDB to a destination DDB, when the destination DDB is the display, and when the destination DDB is an off-screen DDB. Transfers DDB from a source DDB to a destination DDB when the blitting includes a stretch. Updates an existing DDB with revised bitmap image. Cursor Handling Cursors are defined using a special purpose type of bitmap that lends itself to the needs of cursors. The cursor handling example program demonstrates how to create and manipulate cursors. The source file for this program is in installdir/target/src/ugl/example/cursors. The object file is in installdir/target/lib/ugl$(cpu)$(tool)apps/ wexcursr.o. The example program linked with the WindML archive library is in installdir/target/lib/ugl$(cpu)$(tool)apps/ wexcursr_ugl.o. 23

36 WindML SDK 3.0 Programmer s Guide This example program demonstrates several basic cursor handling operations. After the application initializes, the example program performs the following operations: Cursor is initialized. A cursor DDB is created from a cursor DIB. The active cursor image is set to the image created. Cursor is moved based on the receipt of pointer input events. Constraining the cursor to a location on the display. Text Input and Output Handling Most applications require the input of keyboard data and the display of text. The text input and output handling example program demonstrates how an application obtains keyboard information and how textual data is displayed. The source file for this program is in installdir/target/src/ugl/example/wextext. The object file is in installdir/target/lib/ugl$(cpu)$(tool)apps/ wextext.o. The example program linked with the WindML archive library is in installdir/target/lib/ugl$(cpu)$(tool)apps/ wextext_ugl.o. This example program demonstrates several basic keyboard input handling operations. After the application initializes, the example program: finds a font that matches a set of criteria such as face name and size creates the font so it can be used sets a font in the graphics context so the text drawing has a font to use. determines the length; that is, the number of pixels a text string requires. draws text to the display reads keyboard events from the event queue determines which key modifiers are set, such as control, num lock, and caps lock echos the read keyboard input to the display 24

37 2 Getting Started General Demonstration Program WindML is distributed with an example program that demonstrates several of its most common features. The source file for this program is in installdir/target/src/ugl/example/demo. The object file is in installdir/target/lib/ugl$(cpu)$(tool)apps/ugldemo.o. The example program linked with the WindML archive library is in installdir/target/lib/ugl$(cpu)$(tool)apps/ugldemo_ugl.o. This example program has a single parameter that specifies the process whereby the program proceeds from one graphics primitive to another. The parameter, when equal to 0, advances based on input from either the keyboard or the pointer button. If it is non-zero and positive, the parameter specifies the number of seconds to wait until the test advances to the next graphics primitive operation. If the parameter is 1, the program immediately moves from one graphics primitive operation to the next. For example, 2 ugldemo (-1) This causes the ugl demo program to demonstrate one graphics operation and proceed immediately to the next graphics primitive operation. This example program provides example code to demonstrate the following operations: Creating regions and specifying clipping regions Creating monochrome, color, and transparent bitmaps Cursor handling Writing a transparent bitmap directly to the display Blitting a color bitmap to the display Blitting a transparent bitmap to the display Drawing solid and dashed lines, both as a thin and wide lines Displaying rectangles, with and without a fill pattern Displaying polygons, with and without a fill pattern Drawing text Filling an ellipse Creating pie shapes Stretching blts Overlay, Alpha Blending, and Video Source Handling WindML provides the capability to define overlays when the graphics hardware supports the definition of overlays. Overlays are also referred to as supporting multiple planes. The planes are blended together in various fashions such as 25

38 WindML SDK 3.0 Programmer s Guide through plane ordering, color keying, and alpha blending. The type of overlay blending depends on the application and the type of hardware used. Hardware support must be present as WindML does not provide any capability for the use of blending planes with software. A common use of an overlay is to mix graphics with a video from a camera. For a detailed description of the handling of video source in an overlay, see 8. Video Handling. WindML is distributed with an example program that demonstrates the use of overlays in relation to the display of images from a video source. This is only one example of the use of an overlay. Overlays can also be used to blend graphics planes together; one for a background and another consisting of animated graphics. To use the video example program, the graphics hardware must provide support for video and overlays. These options are selected on the Advanced page of the WindML configuration tool. In addition, if alpha blending is used, a pixel format must be selected that includes an alpha channel, such as ARGB4444. The source file for this program is in installdir/target/src/ugl/example/video. The object file is in installdir/target/lib/ugl$(cpu)$(tool)apps/ uglvdemo.o. The example program linked with the WindML archive library is in installdir/target/lib/ugl$(cpu)$(tool)apps//uglvdemo_ugl.o. This example program demonstrates basic overlay handling and the use of the video API. This example program has two input parameters. The first identifies the mode the overlay surface employs and the second identifies a name of a file to be used if a video image is captured as a JPEG image. There are two modes that may be used, alpha blending (0) and color key (1). For example, the following starts the video example program in the alpha blending mode and JPEG images are saved to the file video.jpg: uglvdemo 0, video.jpg After the application initializes, the example program performs the following operations: Attaches the video extension to the graphics device. Creates an overlay surface and attaches to the primary frame buffer. Attaches the JPEG processing to the overlay surface. Enables video and display in the overlay using alpha blending or color key. Moves the overlay surface. Alters the attributes of the video source such as hue, brightness, and saturation. 26

39 2 Getting Started Scales a video source either up or down to fit in the overlay. Freezes the video stream. Captures the video as a JPEG image. Changes the degree of blending of the graphics and video planes, if using alpha blending. This example program accepts simple keyboard keys to control the operation of the program, as show in Table Table 2-3 Keyboard Keys Key a A b B c C f F h H j/j m/m q/q s S z Z Result Decrease the alpha level and turn off ball bounce Increase the alpha level and enable ball bounce Decrease brightness Increase the brightness Decrease the contrast Increase the contrast Freeze the video image Unfreeze the video image Decrease the hue Increase the hue Capture the image to the file specified as the input parameter to the program. Move the video image Quit program Decrease the saturation Increase the saturation Zoom out the image Zoom in the image 27

40 WindML SDK 3.0 Programmer s Guide Double Buffer Handling WindML, based on the graphics hardware, provides for double buffering of the graphics pages. Essentially, double buffering allows your application to write to a page while another page is displayed. This is used to reduce flicker when there are large amounts of graphics rendering operations taking place, as in the case of animation. WindML is distributed with a program that demonstrates double buffering capabilities. To use the WindML double buffering demonstration program, the graphics hardware must support the ability to switch graphics pages. If your graphics hardware supports double buffering, the double buffering checkbox on the Advanced page of the configuration tool does not appear dimmed. If your graphics hardware supports double buffering, the checkbox should be checked prior to saving and building WindML. The source file for this program is in installdir/target/src/ugl/example/dbuf. The object file is in installdir/target/lib/ugl$(cpu)$(tool)appswexdbuf.o. The example program linked with the WindML archive library is in installdir/target/lib/ugl$(cpu)$(tool)apps/wexdbuf_ugl.o. The example program presents a bouncing ball as a graphics image that is frequently updated. The program accepts keyboard and mouse events to turn double buffering on and off. If the double buffering is turned off, the display exhibits a noticeable flicker. When double buffering is turned on, the flicker is not present. This flicker arises when the graphics memory is updated and, at the same time, the graphics image is displayed. In double buffering the graphics page is updated only during the retrace period of the display. Thus, the flicker is not present since there is no active display during the vertical retrace time. The example program for double buffering illustrates the following operations: Checks if the graphics device supports double buffering Allocates a graphics for rendering graphics Sets a page as the active display page Sets a page as the active drawing page 28

41 2 Getting Started Windowing WindML provides a windowing API that allows multiple applications to cooperatively share the same display. Each application renders graphics to its own set of windows. The source files are in installdir/target/src/ugl/example/windemo. This example program consists of several source files that provide a menu system where a drop-down menu is used to launch other applications. The applications that can be launched include a hello application and a bouncing ball application. The object file is in installdir/target/lib/ugl$(cpu)$(tool)apps/windemo. The example program linked with the WindML archive library is in installdir/target/lib/ugl$(cpu)$(tool)apps/windemo_ugl.o. The windowing example program demonstrates the process to complete the following: Create windows Attach callbacks to a window Render graphics to a window Handle events directed to a window 2 Audio Demonstration Program WindML is distributed with an example program that demonstrates its audio capabilities. To use the WindML audio demonstration program, an audio device must be selected when WindML is configured. The source file is in installdir/target/src/ugl/example/audio. The object file is in installdir/target/lib/ugl$(cpu)$(tool)apps/sndplay.o. The example program linked with the WindML archive library is in installdir/target/lib/ugl$(cpu)$(tool)apps/sndplay_ugl.o. The audio program demonstrates the way an audio stream may be played. The audio stream may consist of either a 16-bit signed little endian wav formatted file, an 8-bit unsigned wav formatted file, or an 8-bit mu-law formatted au file. To start this program, a single parameter specifies the name of the audio sample file. For example: SndPlay ( jinglebell.wav ) 29

42 WindML SDK 3.0 Programmer s Guide This causes a file, jinglebells.wav, to be read from the file system and sent to the audio device. The demonstration program illustrates the following: Opening a audio file and parsing the audio sample to determine the type of audio stream, such as wav or au. Opening the audio device, both the DSP and the mixer. Setting up the audio drivers mode including au or wav audio format, number of channels of data such as mono or stereo, audio sample rate, buffering space, and volume. Setting the audio driver to either block on buffer full conditions or to use the select( ) mechanism Sending audio sample fragments to the audio driver for playing Other Demonstration Program WindML also has several other example programs you may want to examine for WindML application development concepts. The other example programs illustrate topics that include: JPEG image handling demonstrates how to display a JPEG image to the display that is present in a file and how to capture a JPEG image from an image on the display. For more information, see installdir/target/src/ugl/example/jpeg. Fonts demonstrates the process to query the font driver for the available fonts and to display each of the fonts supported by the font driver. For more information, see installdir/target/src/ugl/example/fonts. 30

43 3 WindML Source Conventions 3.1 Introduction This chapter describes the WindML source tree layout and suggests naming conventions for functions, macros, and other programming concepts. If you are an independent software vendor (ISV) extending WindML, you should install new components into the WindML source tree. Adhering to this convention provides a uniform experience as you work with WindML technology. Moreover it prevents additions or enhancements to the WindML source tree from interfering with one another. 31

44 WindML SDK 3.0 Programmer s Guide 3.2 Directory Contents WindML source tree, contents and directories are structured to isolate generic code from any architecture-specific or operating system-specific branches. This maximizes portability and provides a uniform directory structure for you to follow Source Files The src/ugl directory is the top-level source directory for WindML. The WindML source code is modularized into multiple directories for organization of source components. As depicted in Figure 3-1, the src directory includes the following subdirectories: Figure 3-1 Src Directory 32

45 3 WindML Source Conventions src/ugl/2d The files in this directory compose the WindML 2-D API layer. These libraries and subroutines support application programs that run on WindML.! CAUTION: As part of the developer license for WindML, you are not allowed to modify any of the WindML 2-D API routines. Any problem reports or enhancement requests related to the WindML 2-D source code can be submitted to the Wind River Customer Services at You can, however, add your own APIs and create driver code to suit your needs. 3 src/ugl/audio src/ugl/bsp src/ugl/bspext src/ugl/config src/ugl/driver This directory contains the code for the audio component of WindML. This directory contains BSP information, a readme file for the BSP, and any patches needed for a BSP to use WindML. This directory contains the code for extensions to the BSP required by WindML. This directory is only present for Tornado versions prior to Tornado 2.2. This directory contains configuration files for WindML. This directory contains driver code for the hardware platforms upon which WindML runs.this includes hardware-independent generic source code for WindML drivers and hardware-dependent drivers. The graphics directory contains the source code for drivers that output data to a display. The keyboard and pointer directories contain source code for drivers that read data from input devices for WindML. The font directory contains the source code for font drivers which implement the 2-D layer font related calls. 33

46 WindML SDK 3.0 Programmer s Guide src/ugl/example src/ugl/fonts src/ugl/input src/ugl/os src/ugl/util src/ugl/win This directory contains example programs using WindML. This directory contains the code for the fonts. This directory contains the code for WindML s event handling and input services API. The files in this directory contain implementations of the WindML OS API for various platforms. WindML takes advantage of optimized synchronization primitives provided by the underlying OS. If you are implementing a new OS port, those aspects of WindML that are OS-dependent are abstracted as part of an API defined in the uglos.h file of the target/h/ugl/ directory. This directory contains utility functions used by the WindML library and drivers. This directory contains the code for the windowing API layer of WindML. 34

47 3 WindML Source Conventions Header Files Table 3-1 lists the WindML definitions in header files located in the h/ugl directory: 3 Table 3-1 Header Files Name ugl.h uglclr.h ugldib.h uglevent.h uglfont.h uglgeom.h uglinfo.h uglinput.h uglkbdmap.h ugllist.h ugllog.h uglmedia.h uglmem.h uglmode.h uglmsgtypes.h uglos.h uglpage.h uglregion.h ugltypes.h uglucode.h Description All generic WindML definitions Definitions related to the WindML color management API Definitions for device-independent bitmaps (DIBs) WindML event, event handler, and event service definitions Definitions of the WindML font API Macros and definitions for clipping routines Definitions for WindML driver information retrieval API Definitions of the WindML input driver API Definitions for defining keyboard mappings to support various languages Definitions for WindML linked list support Definitions for UGLs error logging Definitions for UGLs Media layer Definitions for memory management Definitions for the graphics mode settings Definitions for the WindML messages queued through the input services OS definitions Definitions for double buffering Definitions to define WindML region handling API Definitions of all WindML data types Unicode definitions for WindML 35

48 WindML SDK 3.0 Programmer s Guide Table 3-1 Header Files Name uglugi.h uglwin.h Description Definitions for the output driver API Universal Graphics Interface Definitions for WindML windowing support As depicted in Figure 3-2, the following subdirectories are part of the h/ugl directory: Figure 3-2 Header Files h/ugl/audio h/ugl/bspext h/ugl/config This directory contains header files that define the sound API and for processing streams audio. This directory contains header files for board functions or extensions to the Board Support Package (BSP) required by WindML. This directory contains header files which configure the WindML library for particular hardware and OS. 36

49 3 WindML Source Conventions h/ugl/driver WindML driver definitions are located in the following sub-directory: h/ugl/driver/keyboard h/ugl/driver/pointer The files in these directories compose the input driver definitions. If you are developing a new WindML input driver, you should place all necessary definitions in a header file in the appropriate directory. Examples of files located in these directories are: uglms.h (Microsoft mouse driver definitions) uglpckbd.h (PC 8042 keyboard driver definitions) uglps2.h (PS/2 mouse driver definitions) uglasbt.h (StrongARM Assabet touchscreen definitions) 3 h/ugl/driver/graphics This directory contains the graphics driver header files. The files are organized by hardware platform in separate sub-directories. Examples of sub-directories located in this directory are: chips (Chips and Technologies graphics driver definitions) vga (VGA mode graphics driver definitions) If you are developing a new WindML graphics driver for a new manufacturer, you should create a new directory, for placement of all driver header files. h/ugl/driver/ext This directory is where the driver header files for any extensions to WindML should be placed. JPEG and video extension definitions are provided. h/ugl/driver/font This directory is where particular font or font engine header files should be placed. A header for the BMF font format is provided. h/ugl/driver/audio This directory is where particular audio driver header files should be placed. Header files for Intel Audio Codec 97 and IGS audio hardware are provided. 37

50 WindML SDK 3.0 Programmer s Guide h/ugl/ext h/ugl/os h/ugl/private This directory contains header files for the WindML extension capability and for particular extensions such as JPEG and video. Any WindML definitions for an OS environment are located in this directory. To port WindML to another OS environment, you must implement the routines documented in h/ugl/uglos.h. Currently, the VxWorks OS portability layer software is provided as reference code which you can easily extend to other environments. For more information, see the OS definitions for the VxWorks RTOS platform located in udvxw.h. It is not necessary to include these header files in your driver. The proper OS header file is automatically mapped in by including h/ugl/ugltypes.h in your WindML driver source code. The routines documented in the private directory are considered internal to WindML. The routines and their parameters described in this directory are subject to change without notice. 38

51 4 Configuration 4.1 Introduction WindML is distributed as a source product; therefore, you must configure and build the WindML library before WindML can be used for the first time. To configure WindML you must specify the hardware, and the hardware operating mode. The following hardware devices require configuring: graphics devices, including both the type of graphics device and the type of output device, such as a CRT monitor or an LCD flat panel keyboards pointers, such as mice, trackballs, or touchscreens audio devices In addition to selecting hardware, you must specify the following: font engine fonts to be used a method for managing memory the window manager, if any, to be used build operations such as building a downloadable object consisting of all WindML capabilities for the specified configuration, building example programs, or simply updating the WindML archive library. This chapter first provides an overview of the WindML configuration process, detailing how you configure the product. 39

52 WindML SDK 3.0 Programmer s Guide Configuring the Operating System To use WindML, configure the operating system to include the following: Establish memory mapping for WindML devices Add device drivers in the kernel Apply any required patches WindML is distributed with reference configurations that can be used with various versions of Tornado, including 2.0.x, 2.1.x, and 2.2. If your BSP or operating system require modifications to take advantage of one of these reference configurations, refer to the text file in installdir/target/src/ugl/bsp for more information. This directory also includes any necessary patches to the operating system that you must apply. If your target hardware is not a reference platform, your BSP may require modifications to include the needed WindML infrastructure. For information about BSP requirements, see 12. Portability The Configuration Process You configure WindML using the graphical configuration tool to perform the following: Select a graphics device and its configuration. You can configure the following characteristics: resolution color depth display type Provide optional components Select a keyboard device and the key mapping for various languages Select a pointing device Select an audio device Select the font engine and fonts to be used Select a window manager A maximum of one of each type of device can be selected for a specified configuration. That is, one graphics device, one keyboard device, one pointer device, and one audio device. 40

53 4 Configuration Configuration Validation The configuration tool operates from a configuration database that asserts rules allowing you to select only valid configurations. The WindML configuration tool validates a configuration as you specify a configuration. When you select a value for a configurable item, other configurable items are changed. This ensures only valid selections are made. For example, if you select the Tvia IGS-5050 graphics card, the resolutions and color depths allowed for selection are restricted to the options that Tvia IGS-5050 supports. You can modify the configuration tool database to suit the changing capabilities of WindML. For example, you can accommodate more features for an already supported driver or add new drivers. The configuration tool places no limit on the number of configurations that can be saved. You can specify multiple WindML configurations and save them to the file system. Although you must use the configuration tool to create a configuration, you do not need it to build WindML, based on the configuration you chose. You can use the command line to build WindML libraries and a downloadable object file. For information on building WindML from the command line, see Using Command Line, p.55. For information on using the configuration tool, see 4.3 Using the Build Dialog and Configuration Tool, p Configuration Files The WindML configuration tool generates a configuration file based on your selection of configurable components. These configuration files are subsequently used by the build process to create the WindML objects and library archives. The WINDML_CONFIG_DIR environment variable controls where these files are stored. The configuration files are stored in installdir/target/h/ugl/config/configtool unless you define the environment variable. NOTE: To change the configuration directory, you must redefine the WINDML_CONFIG_DIR environment variable before launching Tornado. 41

54 WindML SDK 3.0 Programmer s Guide File Naming Conventions WindML provides some of the most commonly used configurations for each of the reference drivers. Although there are no restrictions on names for the configuration files or how many configurations can be created, Wind River adheres to a file naming convention. The filenames encode the target processor board name, device name, frame buffer mode, and resolution, as follows: target processor board_device name_frame buffer mode_resolution.cfg For example, the configuration name for a Tvia, Inc. IGS-5050 configured for 800 x 600 resolution with a frame buffer format of RGB565 for the Malta MIPs processor would be: malta_igs5050_rgb565_800x600.cfg 4.3 Using the Build Dialog and Configuration Tool Use the WindML configuration tool to define a standard configuration, consisting of the following: one graphics device, configured at any supported color depth, resolution, and output device one keyboard device one pointer device a window manager a memory management pool of a specified size You launch the build dialog on Windows, with the menu command, Tornado>Tools>WindML or on UNIX, from the Launcher s tool tray. You launch the configuration dialog from the build dialog. 42

55 4 Configuration Figure 4-1 depicts the build dialog. You can use this dialog to initiate a configuration definition process, build a configuration, or remove object files associated with the configuration. Figure 4-1 WindML Build Dialog 4 The WindML Configuration tool has the following buttons: Configure Click this button to launch the WindML Configuration dialog. This dialog allows you to define, modify, and delete a configuration. Build Click this button to start the compile and link the WindML Configuration as selected from the drop-down list box. Clean Click this button to remove all objects and archived modules for the WindML configuration as selected from the drop-down list box. Quit Click this button to terminate the WindML Configuration tool. 43

56 WindML SDK 3.0 Programmer s Guide WindML Configurations When you click the Configure button on the WindML Build dialog, the WindML Configuration dialog appears. You can use this dialog to define and save a new configuration, modify an existing configuration, or delete a configuration that you no longer need. Figure 4-2 depicts the WindML Configuration dialog with the following tabs: Build This tab defines build characteristics, such as the processor type, the tool chain, whether the build is to include debug information, and the targets to be built such as downloadable objects and example programs. Devices This tab defines the graphics, keyboard, pointer, and audio devices. Advanced This tab defines or alters miscellaneous features such as scalable options. Bitmap Fonts The tab defines the bitmap fonts to be included in build. 44

57 4 Configuration Figure 4-2 WindML Configuration Dialog 4 45

58 WindML SDK 3.0 Programmer s Guide Defining To define a new WindML configuration: 1. Create a new configuration file by selecting File>New. 2. Enter a name for the configuration in the File name field. 3. Select the Build tab on the WindML Configuration dialog shown in Figure 4-2. Use the Build tab to define the following: Processor Once a processor is chosen, only options that apply to that processor are available. If the processor type is changed after setting other options, verify your selections for the other options, such as the type of tool chain. Tool Identify the tool chain to be used to build the WindML libraries and object files. Specify the tool chain by type, such as GNU or Diab. Also specify the required environment, such as little endian, big endian, or floating point technology as software or hardware. Debug Through a checkbox option, specify if you wish to build WindML with debug symbols included in the object file. Additional builds Through a checkbox option, specify if you wish to build a downloadable object file of the WindML configuration, and if you wish to build the WindML example programs. 4. Select the Devices tab as shown in Figure

59 4 Configuration Figure 4-3 Device Definition Display 4 47

60 WindML SDK 3.0 Programmer s Guide Use the Devices tab to define the following: Graphics Driver The name of the graphics device. In Figure 4-3, a Chips & Technology device is selected. Display Type Identify the output device type, such as a generic monitor, an LCD flat panel display, or an EL panel. In Figure 4-3, the selected output type is a generic monitor. Graphics Settings Identify the operating mode of the graphics device. The following attributes define the operating mode: Color Format The number of bits per pixel, followed by the pixel format. For example, in Figure 4-3, 8 Indexed identifies a color format consisting of 8 bits per pixel where the pixel correlates to an index into a CLUT. Resolution The number of pixels horizontally and vertically. In Figure 4-3, the graphics settings are for a display consisting of 1024 pixels horizontally and 768 pixels vertically. Refresh Rate The number of times the display is refreshed per second. Pointer Identify the type and access method for the pointer device. You must specify the following attributes: Type The type of pointing device, such as PS/2, Microsoft serial mouse, or touchscreen. In Figure 4-3, the pointer device is a PS/2 Style Pointer. Name The name of the I/O device to be attached to the pointer device. This must be a valid device name, such as /tyco/0 for a serial device where a serial mouse is attached. In Figure 4-3, the PS/2 mouse is attached to a device named /pointer/0. Each pointer device is assigned a default I/O device name that is the most common device used for a pointer device of the selected type. 48

61 4 Configuration Keyboard Identify the type and access method for the keyboard device. You must specify the following attributes: Type The type of keyboard device, such as PC/AT style. In Figure 4-3, the selected keyboard is a PC/AT Style. 4 Name The name of the I/O device to be attached to the keyboard device. This must be a valid device name, such as /tyco/0 for a serial device where a keyboard is attached. In Figure 4-3, a PC/AT keyboard is attached to a device named /keyboard/0. Each keyboard device is assigned a default I/O device name that is the most common device used for a keyboard device of the selected type. Key Map The fashion whereby the individual keys are to be interpreted, such as a key map for English (US), German, and French. In Figure 4-3, the PC/AT keyboard is used, which has a keyboard map for English (US). Audio Identify the type of audio device and its access method. You must specify the following attributes: Type The type of audio device, such as the Tvia IGS-5050 audio device. There is no audio device selected in Figure 4-3. Name The name of the I/O device to be attached to the audio device. This must be a valid device name, such as /sound. Each audio device is assigned a default I/O device name that is the most common device used for a audio device of the selected type. Channel Number An audio port on the audio device. 49

62 WindML SDK 3.0 Programmer s Guide 5. Select the Advanced tab as shown in Figure 4-4. Figure 4-4 Advanced Definition Information Use the Advanced tab to enable or disable miscellaneous configuring options and to identify the memory pool to be used internally by the WindML library. 50

63 4 Configuration You can reduce the memory footprint by disabling options not used. For example, disable or enable the following attributes: Video Identify whether a video input source is used by your application. JPEG Identify whether the JPEG images will be processed by your application. Please refer to the documentation of the application as to whether WindML must be configured with JPEG image support. Some high-level graphics packages have their own JPEG image handling. 4 Double Buffer Identify whether your application requires double buffering support. This support allows drawing to a graphics frame buffer page while another is actively displayed, and then swaps the pages. This technique is used to reduce flicker when the graphics images are updated at a relatively high rate as would be the case with animation. Overlays Identify whether your application requires the creation of overlay planes such as blending two graphics pages, (background and animated figures), or graphics and video. Software Cursor Specify whether a software cursor is required. If a graphics device supports a hardware cursor, the default selection will always be to use the hardware cursor. A software cursor is necessary when the cursor image must be larger than the hardware capability of the graphics hardware. For capabilities and limitations of a graphics device, including information of cursors, refer to the graphics device release information contained in the installdir/target/h/ugl/driver/graphics/devname/*.txt file. Not all graphics drivers support all features listed in the Advanced tab. When a graphics device does not support a feature, it appears dimmed. In Figure 4-4, the Chips and Technology driver supports the JPEG and double buffering options, but not the video, overlays, and other options. As this driver only supports a software cursor, the software cursor checkbox is checked and appears dimmed. Use the Window Manager selector to select a window manager. If your application does not need a window manager, select None. A basic window manager is included with WindML by default, but other window managers may be available or you can create your own and make it available in the configuration tool. 51

64 WindML SDK 3.0 Programmer s Guide Use the Advanced tab to specify memory options that configure the memory pool used internally by the WindML libraries. You can select between the VxWorks system memory pool or a private WindML memory pool. Using the VxWorks system memory pool means all WindML memory allocations comes from that pool. You can add memory partitioning by selecting the Private Pool radio button, in which case, you must also specify the pool size. 6. Select the font engine from the set of installed font engines. WindML is distributed only with a bitmap font engine which is selected by the Bitmap Fonts tab as shown in Figure 4-5. Additional font engines can be purchased from third parties. If Wind River adds additional font engines, the configuration tool will have additional tabs to configure the font engines. Figure 4-5 Bitmap Font Engine Definition 52

65 4 Configuration If you choose to configure the bitmap font engine distributed with WindML, use the Bitmap Fonts tab to define the following font engine attributes: Unicode Specify whether the application uses multi-byte unicode fonts. Font Glyph Cache Size Specify the number of font glyphs that can be cached. 4 Fonts Specify the individual fonts to be used. Figure 4-5 defines the bitmap font engine as using unicode fonts, having an unlimited font cache size, and using the five fonts in the Included list, which are Courier 8, Courier 12, Courier 14, Courier 18, and Courier Bold 24. If you choose a different font engine, the configuration tool displays a different tab for the font engine. The data items that need to be defined for another font engine may vary from those required of the WindML Bitmap Font engine. To set configuration options, refer to the font engine documentation. Saving After defining your WindML configuration, save it to the file system by selecting File>Save.! WARNING: Although the Save dialog allows files to be created in various directories, you should only place configuration files in the directory where you set the WINDML_CONFIG_DIR environment variable. The WindML Build Tool will only examine that directory to build the selected list of configurations that can be built. Modifying To modify a configuration, select File>Open and select the appropriate configuration file. The configuration tool opens, displaying the settings associated with your configuration. You can modify any of the fields in the tool s various tabs, as described in Defining, p.46. Save the new configuration after you make your changes. 53

66 WindML SDK 3.0 Programmer s Guide Deleting To delete a configuration, open it, and select File>Delete Building WindML Libraries You can build WindML Libraries using the build dialog or command line as follows: Using the Build Dialog Before building WindML, verify the proper targets are identified. Select the Build tab on the WindML Configuration dialog, and make sure the following checkboxes are selected as desired: Build debug version Check this checkbox if you wish to build WindML with debug symbols included in the object file. Build WindML object Check this checkbox if you wish to build a downloadable object file that reflects the specified configuration and builds the WindML library archive. This object allows a WindML application to be downloaded subsequent to the WindML library object file. Since the WindML object file contains the entire 2D API, any WindML application may be downloaded. Build WindML examples Check this checkbox if you wish to build the example programs and link them against the WindML archive. The objects from the example programs are placed in installdir/target/lib/obj$(cpu)$(tool)apps. Objects with a _ugl.o extension are also linked against the WindML archive. After choosing your build options, use the WindML build dialog as shown in Figure 4-6, to select the desired configuration and initiate the build. The WindML build dialog has a drop-down list box so you can select the WindML configuration file for build. In Figure 4-6, a the pentium_chipsandtech_indexed8_1024x768 configuration is selected. 54

67 4 Configuration After you select the desired configuration file, click Build to start the WindML build. Figure 4-6 Building WindML Libraries 4 Using Command Line Although you must use the configuration tool to configure WindML, you may prefer to use the command line to build WindML. To build WindML from the command line: 1. Change your directory to the top-level directory of the WindML source code, as follows: % cd installdir/target/src/ugl 2. Use the appropriate make command to build the WindML libraries and optional objects. The make command must specify the WindML configuration filename. For example, the following make command builds WindML for the Pentium processor with the pentium_igs5050_rgb565_1024x768 configuration file: % make WINDML_CONFIG_NAME=pentium_igs5050_rgb565_1024x768 Alternatively, and if you always use the same WindML configuration, the environment variable WINDML_CONFIG_NAME can be set to pentium_igs5050_rgb565_1024x768. In this case, use the following command to build WindML: % make 55

68 WindML SDK 3.0 Programmer s Guide Removing WindML Object Files You can remove WindML Object Files using the build dialog, or clean WindML objects using command line as follows: Using the Build Dialog The WindML build dialog as shown in Figure 4-6, is used for removing the WindML object files. You select the desired WindML Configuration from the drop-down list box and then click Clean to initiate a clean operation that removes the object files. In Figure 4-6, a pentium_chipsandtech_indexed8_1024x768 WindML Configuration is selected. Using Command Line To clean objects built as part of a configuration, proceed as if you were building WindML from the command line, except you must specify windmlclean as the target of the build. For example: % cd installdir/target/src/ugl installdir/target/src/ugl> make WINDML_CONFIG_NAME=pentium_igs5050_rgb565_1024x768 windmlclean This removes all objects and archives specified in the configuration. 56

69 4 Configuration 4.4 File Locations and Environment Variables The configuration and build process generates files and places them in various locations in the host file system. The locations vary depending on environment variables and Tornado versions. Library object files 4 Tornado 2.0.x and Tornado 2.1.x located in the directory: installdir/target/lib/obj$(cpu)$(tool)ugl Tornado 2.2 located in the directory: installdir/target/lib/$(cpu_family)/$(cpu)/$(tool)/objwndml Library archive files Tornado 2.0.x and Tornado 2.1.x located in the file: installdir/target/lib/lib$(cpu)$(tool)ugl.a Tornado 2.2 located in the file: installdir/target/lib/$(cpu_family)/$(cpu)/$(tool)/libwndml.a Downloadable WindML per configuration Tornado 2.0.x and Tornado 2.1.x located in the file: installdir/target/lib/ugl$(cpu)$(tool).o Tornado 2.2 located in the file: installdir/target/lib/$(cpu_family)/$(cpu)/$(tool)/wndml.o Downloadable WindML example programs for all Tornado versions installdir/target/lib/ugl$(cpu)$(tool)apps Files ending with _ugl.o are linked with the WindML archive. WindML configuration files for all Tornado versions are, by default, placed in the directory installdir/target/h/ugl/config/configtool. You can change this location by setting the environment variable WINDML_CONFIG_DIR to an alternate directory. 57

70 WindML SDK 3.0 Programmer s Guide 4.5 VxWorks BSP Requirements A VxWorks board support package (BSP) may require modifications to enable graphics and input devices. If your operating system is pre-tornado 2.2, your BSP will usually require changes. If you are using Tornado 2.2, many BSPs support WindML without modification. Look in the following directories for specific requirements for configurations with which WindML is tested and for which reference drivers are provided: installdir/target/src/bsp/config/bsp Descriptions of any modifications required for a BSP for each supported Tornado version. To include the mapping of the graphics device, you need to modify the BSP for Tornado versions other than Tornado 2.2 BSP. If the mapping is not added to the BSP, WindML crashes with a page fault/bus error when it attempts to access that graphics device. installdir/target/h/ugl/driver/graphics/devicename/filename.txt A text file for the applicable graphics device that describes BSP limitations and required changes to support that device Graphics Device Memory Mapping A graphics device has two basic components: a frame buffer one or more controllers The frame buffer is a block of memory that stores the image of the data displayed on the display device, such as a monitor or flat panel LCD. Controllers include graphics processors, RAMDACs, and clock chips. Depending on the graphics device, some controllers are not required, or they may be integrated into a single piece of hardware. The frame buffer and each controller must be visible to the processor. Depending on the processor architecture, access to these controllers is through memory mapped I/O, the I/O space, or both. To allow the processor to access a graphics device, you may have to modify your BSP by enabling physical mapping of the device and logical or virtual mapping. The exact changes depend on the type of processor, the type of graphics device, and the bus architecture. 58

71 4 Configuration Physical Mapping Physical mapping involves enabling the address mappers to decode the physical addresses where the graphics device resides. The mapping of the graphics controller depends on its type, the processor architecture, and the VxWorks BSP. WindML does not place restrictions on which bus architecture can be used by the graphics device. It can be the CPU internal bus, an ISA bus, a PCI bus, an AGP bus, and a VME bus. Configuration issues for some of bus architectures are addressed in the following information. 4 PCI Bus VMEbus The PCI specification allows graphics devices to be mapped to the PCI memory space using a standardized method. On system startup, initialization software is responsible for allocating the required amount of PCI memory to each of the PCI devices. This initialization software can be part of a manufacturer s boot code or included in the VxWorks initialization sequence. Some manufacturer s have a BIOS-like capability in firmware that performs this mapping prior to transferring control to the VxWorks boot ROM code. For example, on x86 processors, the BIOS installed on the motherboard typically performs this mapping. This is also true for several PowerPC processors. This capability can be used to map the graphics device into processor memory when the BSP provides support for the automatic configuration of the PCI bus. When a BSP is built with INCLUDE_PCI_AUTOCONFIG selected, PCI devices are automatically assigned a space in the PCI memory. When a PCI device is not mapped to PCI memory space, you must modify the syslib.c file in installdir/target/config/bsp to map the PCI graphics device into available PCI memory. When a safe area is found of sufficient size for the PCI device, the base address (offset 0x10) of the PCI configuration header must be set to reflect this base address. For a VMEbus, a VME mapper must be set so the processor has visibility to the location at which the VME board resides. This step can include setting jumpers on the graphics boards to select the intended address. For details on setting the physical mapping, refer to documentation for the VxWorks BSP and board-specific hardware documentation. 59

72 WindML SDK 3.0 Programmer s Guide Virtual Mapping Virtual mapping enables the processors memory management unit (MMU) to perform the necessary virtual-to-physical mapping and to specify the caching policy appropriately. When the system architecture is PCI-based and the mapping is produced by manufacturer s boot code, the location of the mapped device is needed. This can be accomplished either by executing the routine pciheadershow( ) or the utility uglgraphicsmapshow( ). The following shell session shows the output of a call to uglgraphicsmapshow( ): -> uglgraphicsmapshow Probing PCI bus for graphics devices Device Number 8 Vendor = ATI (1002) Device = MACH64 (4354) Base address = 0xfb Size = 0x Device Number 14 Vendor = IGS Tech (10ea) Device = 5050 (5000) Base address = 0xfe Size = 0x value = 0 = 0x0 In this sequence, the hardware has two PCI graphics devices: ATI MACH64 The device number is the PCI device number which is 8, in this case. The vendor is ATI, which has a PCI vendor code of 1002; the MACH64 has a device ID of This device is mapped to PCI memory at location 0xfb000000, and the required memory space is 0x bytes. IGS5050 The device number is the PCI device number which is 14, in this case. The vendor is Tvia (IGS), which has a PCI vendor code of 10ea; the IGS5050 has a device ID of This device is mapped to PCI memory at location 0xfe000000, and the required memory space is 0x bytes. The mapping is accomplished through modifications to the BSP s syslib.c file. This file usually has a data structure, called sysphysmemdesc[ ] that defines the mapping of memory. This data structure is an array of entries that define blocks of memory. The mapping technique varies among processor types as some processors do not require any virtual mapping. For more information, refer to your processor/bspspecific documentation. 60

73 4 Configuration Each entry has five fields: physical address virtual address size of the memory section memory management enable masks memory management state values 4 The data structure must be modified to include an entry that defines the mapping for the graphics device. Based on the previous example, assuming the Tvia (IGS) IGS5050 device is to be used with the configuration probed by uglgraphicsmapshow( ), the virtual mapping is as follows: Example 4-1 Virtual Mapping /* linear video ram */ { (void *) 0xFE000000, /* The physical mapping */ (void *) 0xFE000000, /* The virtual mapping */ 0x , /* The size of segment */ VM_STATE_MASK_FOR_ALL, VM_STATE_FOR_IO } The size field, which must cover the entire device, varies depending on the size of the frame buffer. The memory management mask and state fields must be set to mark the memory as valid, writable, and non-cacheable.! WARNING: Memory must be marked as cache-inhibited (non-cacheable) if the hardware does not have any cache coherency support. 61

74 WindML SDK 3.0 Programmer s Guide Common BSP API All WindML device drivers follow a common method for accessing VxWorks BSP functionality. The low-level routines that deal directly with the target processor are present in the BSP. These low-level routines, known as the hardware abstraction layer, are described in WindML DDK Programmers Guide: 9.2 Hardware Abstraction Layer, p If your BSP does not include these low-level routines, modify your BSP to provide that support. All BSPs used as a reference platform for WindML, have support for this layer. These routines are present in a file named syswindml.c of the BSP directory. Some BSPs released prior to being retrofitted for WindML require patches. These patches are provided in installdir/target/src/ugl/bsp/config/bspname. 4.6 Project Facility The Tornado project facility allows you to include or exclude WindML functionality into a VxWorks image. For general guidelines on using the Tornado project facility, see the Tornado Getting Started Guide and the Tornado User s Guide: Projects. This guide emphasizes only those project facility features relevant to the setup of WindML. When WindML is installed, a WindML components folder is created in the Tornado project facility component hierarchy, as shown in Figure

75 4 Configuration Figure 4-7 WindML Project Facility Components Folder 4 63

76 WindML SDK 3.0 Programmer s Guide This folder has three sub-folders: 2D graphics, Audio components, and WindML Devices. NOTE: A folder displaying a checkbox icon contains options that are either mutually exclusive or inclusive. To use the project facility to include a WindML component, follow these steps: 1. Select a component. 2. Right-click to view the context menu. 3. Select the Include command. You can exclude components in the same manner, if they have already been included. When you right-click, the context menu displays an Exclude command Linking the 2D Graphics Library The 2D graphics library can by linked with the VxWorks image in two ways: Link the entire 2D layer into the VxWorks image (complete 2D library). This allows the subsequent download of a WindML application after the target is booted. This mode allows any WindML application to be dynamically downloaded since the VxWorks/WindML image contains the entire WindML 2D functionality. Link only the necessary 2D functionality (necessary 2D library). This mode requires that WindML is built into VxWorks, in addition to the WindML application. This results in a smaller VxWorks/WindML image. NOTE: When building a VxWorks image that includes a higher level graphics product, such as Zinc or JWorks, the necessary 2D library should be selected as opposed to the complete 2D library Adding WAV or AU Audio Stream Support Audio library functions to support audio files formatted as WAV or AU files can be included in the VxWorks image. A WindML application subsequently downloaded can play audio files. Select the appropriate component from the component hierarchy, as shown in Figure

77 4 Configuration Defining WindML Device Support Select a device category from the WindML Devices folder: Keyboard Selecting this component adds the WindML keyboard driver to the VxWorks kernel. In Figure 4-7, there are two keyboard selections possible; one is the PC Console Keyboard, and the other is the PS2 Keyboard. 4 Pointer Selecting this component adds the WindML pointer driver to the VxWorks kernel. As shown in Figure 4-7, there are two pointer types, the PS2 mouse and a serial. WindML Graphics Device Selecting this folder presents a list of graphics device types. The types listed vary according to BSP. In Figure 4-7, there is a single type which is a generic PCI type. The generic PCI graphics device covers most instances of graphics devices, and is the selection for the Tvia IGS5050 or a Chips and Technology graphics device. 65

78 WindML SDK 3.0 Programmer s Guide 66

79 5 2D Graphics Library 5.1 Introduction The 2D API includes the following functional areas, which are examined in this chapter: Graphics Contexts (GCs). Graphics contexts are data structures containing information relevant to a current drawing operation such as line width, fill pattern, and clip regions. The 2-D API provides routines to create and destroy graphics contexts, and to set the fields of the graphics context data structure. You must set up a graphics context for an output device before drawing operations can take place. Drawing Primitives. These routines provide basic drawing primitives, including lines, rectangles, ellipses, polygons, and pixels. Batch Drawing. This API allows you to optimize a series of low-level drawing requests to ensure drawing is done efficiently. For example, you can remove affected cursors once from the display instead of performing repeated hide or show requests at the beginning and end of every sequential drawing operation. Text Rendering and Font Management. You can render text using different fonts. You can manage the fonts used by the application, specify fonts, request exact or approximate fonts, and use fonts for text rendering. Bitmap Management. WindML provides an extensive bitmap management API, providing color, monochrome, and transparent bitmaps, as well as DDBs and DIBs. 67

80 WindML SDK 3.0 Programmer s Guide Cursor Management. The cursor management API allows the application to manage and control the behavior of the cursor or mouse. This includes the functionality to maintain and dynamically switch between several bitmaps associated with the cursor. Color Management. The color management API provides routines and macros allowing basic and customized color management to be performed depending on the application requirements. Using color management, an application may create and manipulate color cubes when the target hardware uses indexed color. Region Management. The region management API is used to manage a drawing area or areas used in combination with clipping to define where you can use the 2D graphics API. Double Buffering. The double buffering API allows the application to manage multiple off-screen buffers for flicker-free, off-screen rendering. Double buffering is not supported by all drivers. 5.2 Graphics Contexts The graphics context contains information about drawing characteristics. Most drawing operations can only be done by specifying a valid graphics context to determine the characteristics of how the operation is performed. The drawing characteristics stored in a graphics context include: information for drawing primitives, such as background and foreground colors, line style and width, fill patterns the default bitmap clipping and view port dimensions raster modes the font for text rendering as described in 5.5 Text Rendering and Font Management, p.73. A graphics context is directly associated with a graphics or display device ID. The application can create multiple graphics contexts on each graphics device. To obtain the graphics device ID from the device registry, see 11. Resource Management. 68

81 5 2D Graphics Library Creation Routines Table 5-1 lists the routines to create, copy, and destroy a graphics context. Table 5-1 Graphics Context Routines Routine uglgccreate( ) uglgccopy( ) uglgcdestroy( ) Description Creates a graphics context Copies a graphics context Destroys a graphics context Default Bitmap The destination of a drawing operation is determined by the default bitmap setting in the graphics context. The default bitmap may point to the physical display or an off-screen color bitmap. The physical display is identified by UGL_DISPLAY_ID. A color bitmap is identified by UGL_DDB_ID. Bitmap operations can specify the default bitmap as the source or destination using the UGL_DEFAULT_ID macro. Table 5-2 lists the routines to get and set the default bitmap. Table 5-2 Default Bitmap Routines Routine ugldefaultbitmapset( ) ugldefaultbitmapget( ) Description Sets the default bitmap for a graphics context Gets the default bitmap for a graphics context 5.3 Drawing Primitives You can accomplish basic drawing with simple geometry primitives, including uglellipse( ), uglline( ), and uglpolygon( ). With the WindML API, you can draw lines, rectangles, ellipses, pixels, and polygons. As summarized in Table 5-3, these routines form the basic building blocks of WindML drawing. 69

82 WindML SDK 3.0 Programmer s Guide Table 5-3 Basic Drawing Primitives Routine uglellipse( ) uglline( ) uglpixelset( ) uglpixelget( ) uglpolygon( ) uglrectangle( ) Description Draws a ellipse, arc, or pie slice Draws a line Draws a pixel Gets the color of a pixel Draws a polygon Draws a rectangle All routines use the information in the current graphics context to select foreground and background colors, and line thickness. For more information, see 5.2 Graphics Contexts, p Drawing Primitive Routines Table 5-4 lists the routines to set the display information for graphics primitives, such as foreground and background colors, line width and style, and fill patterns. Table 5-4 Drawing Primitive Related Routines Routine ugllinestyleset( ) ugllinestyleget( ) ugllinewidthset( ) ugllinewidthget( ) uglfillpatternset( ) uglfillpatternget( ) uglbackgroundcolorset( ) uglbackgroundcolorget( ) uglforegroundcolorset( ) uglforegroundcolorget( ) Description Sets the style for any line subsequently drawn Gets the current line style Sets the width for any line subsequently drawn Gets the current line width Sets the fill pattern for any shape subsequently drawn Gets the current fill pattern Sets the background color for the graphics context Gets the current background color Sets the foreground color for the graphics context Gets the current foreground color 70

83 5 2D Graphics Library Basic Drawing Example Example 5-1 describes some basic drawing operations: Example 5-1 Basic Drawing Operations int windmlexamplebasic (void) { UGL_GC_ID gc;... 5 /* * Create a graphics context. Default values are set during * the creation. */ gc = uglgccreate(devid); /* Draw a line */ uglbatchstart(gc); uglforegroundcolorset(gc, colortable[white].uglcolor); uglline(gc, 0, 0, displaywidth - 1, displayheight - 1); uglbatchend(gc); /* Draw a rectangle */ uglbatchstart(gc); uglfillpatternset(gc, patternbitmap); uglforegroundcolorset(gc, colortable[white].uglcolor); uglbackgroundcolorset(gc, colortable[green].uglcolor); ugllinestyleset(gc, UGL_LINE_STYLE_SOLID); ugllinewidthset(gc, 7); uglrectangle(gc, displaywidth / 8, displayheight / 8, displaywidth / 4, displayheight / 4); uglbatchend(gc); /* Draw an ellipse */ uglbatchstart(gc); uglforegroundcolorset(gc, colortable[blue].uglcolor); uglbackgroundcolorset(gc, colortable[red].uglcolor); uglellipse(gc, 400, 80, 600, 160, 0, 0, 0, 0); uglbatchend(gc);... } 71

84 WindML SDK 3.0 Programmer s Guide 5.4 Batch Drawing In addition to the basic drawing methods described in this chapter, WindML supports two routines that add simple batch capabilities to drawing operations: uglbatchstart( ) and uglbatchend( ). Batch drawing provides the following benefits: uses semaphores to ensure integrity of drawing operations minimizes screen flickering uses system resources effectively Whenever you perform a drawing operation, system resources are reserved, cursors are hidden and shown on the display Drawing on Display Example Example 5-2 show you how to draw a line and a rectangle with text on the display: Example 5-2 Drawing a Line and Rectangle on Display DrawScreenItems(UGL_GC_ID gc) { uglbatchstart(gc); uglline(gc, 10, 70, 100, 10); uglrectangle(gc, 50, 50, 149, 79); ugltext(gc, 4, 4, "This is the sample text"); uglbatchend(ugl_gc_id gc); } The calls to uglbatchstart( ) and uglbatchend( ) optimize the drawing of information to the display by maintaining the flicker of the software cursor, and minimizing system resource use. 72

85 5 2D Graphics Library 5.5 Text Rendering and Font Management The 2D text rendering and font management provides the APIs for drawing textual information to the display. Font management allows you to specify font family types such as Helvetica, Courier, and Times Roman, and to combine font attributes, such as bold, italic, and point size to produce the appropriate font for presentation in the target application. The text rendering routines use fonts created by the font management routines to draw text on the display. Table 5-5 lists the 2D font API. 5 Table 5-5 Font Management Routines Routine uglfontcreate( ) uglfontdestroy( ) uglfontmetricsget( ) uglfontfind( ) uglfontfindstring( ) uglfontfindfirst( ) uglfontfindnext( ) uglfontfindclose( ) uglfontdriverinfo( ) uglfontinfo( ) uglfontset( ) uglfontget( ) Description Creates a font Destroys a font Retrieves font metric data for a font Finds a font, using a font descriptor structure Finds a font, specifying the parameters in a string Starts enumerating the fonts available for a font driver Continues enumerating fonts available for a font driver Finishes the font enumeration process Retrieves or send information to a font driver Dynamically sets and gets font attributes Sets the current font set in the graphics context Gets the current font set in the graphics context 73

86 WindML SDK 3.0 Programmer s Guide Table 5-6 lists the text rendering routines. Table 5-6 Text Rendering Routines Routine ugltextdraw( ) ugltextdraww( ) ugltextsizeget( ) ugltextsizegetw( ) uglstyledtextdraw( ) uglstyledtextdraww( ) Description Draws text using the current font, starting at location (x,y) Draws text in double-byte characters using the current font Gets the width and height of a text string Gets the width and height of a text string in double-byte characters Draws styled text, such as rotated text. This function is not supported by all font drivers. Use uglfontdriverinfo( ) to determine if the font driver supports this function Draw styled text in double-byte characters, such as rotated text. This function is not supported by all font drivers. Use uglfontdriverinfo( ) to determine if the font driver supports this function Initializing a Font Driver You must initialize the font driver and font engine before they can be rendered to the screen. A font driver provides the interface between the 2D layer and the proprietary API of a font engine. It also serves as an interface between the graphics driver and the font engine. Embedded systems include a single font driver and corresponding font engine. However, it is possible for a system to contain multiple font engines. Usually the font driver and font engine are initialized or created in uglinitialize( ) and deinitialized or destroyed in ugldeinitialize( ) along with other drivers. Some of the 2D API font routines require the UGL_FONT_DRIVER_ID returned from the font driver creation routine. You can obtain this ID from the registry by the application at any time. For more details on the registry, see 11. Resource Management, specifically uglinitialize( ) and ugldeinitialize( ). After you create the font driver, you may need to configure it before it can be used properly. The uglfontdriverinfo( ) routine performs all run-time configuration of a font driver. 74

87 5 2D Graphics Library Example 5-3 shows how to use uglfontdriverinfo( ) to specify an upper-left text origin, instead of the driver s default baseline positioning. Example 5-3 uglfontdriverinfo( ) textorigin = UGL_FONT_TEXT_UPPER_LEFT; ugldriverfind (UGL_FONT_ENGINE_TYPE, 0, (UGL_UINT32 *)&fontdrvid); uglfontdriverinfo(fontdrvid, UGL_FONT_TEXT_ORIGIN, &textorigin); Run-time configuration options may be font driver-specific. For more information, specifically available compile-time configuration and scalability options, consult the font driver documentation. You can also use ugldriverfontinfo( ) to determine the advanced capabilities of a font driver and set several font attributes, if they are supported. To determine the capabilities of a font driver and engine, see the reference entry for uglfontdriverinfo( ) Creating Fonts You must create a font before it can be used to render text to the screen. To complete this process, perform the following three steps: Step 1: Find an Available Font to Closely Match Desired Font Attributes. A close font match will conserve system memory requirements. Many embedded systems only provide a limited selection of fonts and the set of available fonts might not be known by the application at run-time. This step allows the application to find a font at run-time that most closely matches the particular font attributes. You can do this with uglfontfind( ) or uglfontfindstring( ). You can ignore this step, if you know a particular font is available. Step 2: Create the Font Found from Step 1. Once you know a font exists, create it using uglfontcreate( ). Step 3: Configure Advanced Font Attributes. After you create the font, use uglfontinfo( ) to set advanced font attributes. For example, if you want to draw an anti-aliased font, if anti-aliasing is supported by the driver, the anti-alias mode can be set using uglfontinfo( ). Use uglfontdriverinfo( ) to determine attributes that can be set through uglfontinfo( ). 75

88 WindML SDK 3.0 Programmer s Guide Font Types There are 2 categories of font glyphs - scalable and bitmapped. You can change the size and rotate scalable fonts at run-time. This can be done through the uglfontinfo( ) API used to change the orientation of a scalable font. For API descriptions and the various attributes that may be set using the uglfontinfo( ), see the online HTML or refer to WindML API Reference 3.0. Not all attributes are available with all font engines. To determine available attributes, call uglfontdriverinfo( ) Encoding Fonts WindML provides a set of bitmapped fonts organized according to the ISO standard for 8-bit character representations and according to the UNICODE standard for 16-bit character representations. The UNICODE support is only for fixed width characters consisting of 2 bytes per character. The WindML font API does not perform encoding translation, so you must ensure the construction of textual information is performed according to the underlying font driver capabilities Drawing Text Once you create a font, you must set its font ID (UGL_FONT_ID) in the graphics context before you can use it. Only one font ID can be set in a graphics context at a time. The ugltextdraw( ) routine, and its double-byte equivalent, ugltextdraww( ) is used to draw text on the screen with the current font in the graphics context. NOTE: The routines, ugltextdraw( ) and ugltextdraww( ) do not wrap text on the display or bitmap. Any text extending beyond the bounds of the display or bitmap is clipped. Information on text string dimensions is important for applications that must present and manage text in a consistent manner. You can use ugltextsizeget( ) to determine the string dimensions when drawn on the screen using the current font. WindML deals in pixel sizes for fonts, rather than point sizes. This is because the 2D font API is independent of any particular screen type or size. It is the application s responsibility to translate pixel sizes to point sizes, if necessary. 76

89 5 2D Graphics Library Rendering Font Example Example 5-4 shows how a font can be text rendered to a display using that font: Example 5-4 Rendering Fonts int windmlexampletextio (void) { UGL_FONT_DRIVER_ID fontdrvid; UGL_FONT_DEF fontdef; char *text = "WindML text input and output example.";... 5 /* * This function allows you to find a font from the set of available * fonts. A search parameter string is used to specify the desired font. * Incomplete specifications leave the function to make the * choice. This example specifies Lucida, but not a size, so * the font function chooses one. There are several parameters * used, which are semicolon delimited. */ uglfontfindstring(fontdrvid, "familyname=lucida", &fontdef); /* * After finding a font specified in fontdef, * you can create the font. What is accomplished here depends * on the font engine used. This step could * include conversion of the font data from a platform independent * format to a platform dependent format; similar to a DIB used * to create a DDB. A glyph cache and other * resources are configured for the BMF font engine. */ if ((fontbanner = uglfontcreate(fontdrvid, &fontdef)) == UGL_NULL) { printf("font not found. Exiting.\n"); return(0); } /* Set color combination for the banner. */ uglforegroundcolorset(gc, colortable[yellow].uglcolor); uglbackgroundcolorset(gc, colortable[blue].uglcolor); /* Set the earlier acquired font for the banner. */ uglfontset(gc, fontbanner); /* * Draw the text. The GC contains the bitmap from which to render. * In this case it is the frame buffer. Text is located * at the upper left corner of the screen (0,0). */ ugltextdraw(gc, 0, 0, -1, text);... } 77

90 WindML SDK 3.0 Programmer s Guide 5.6 Bitmap Management The 2D bitmap management API allows you to create and render monochrome, color, and transparent bitmap images to the display. Bitmaps are an important part of a graphical application that can consume a large portion of CPU and bus time. Proper management and planning of bitmap usage is critical during application development. WindML s 2D bitmap API provides flexible bitmap management which allows an application to balance portability and performance. WindML supports three types of bitmaps in the following manner: Standard Color bitmaps that are rectangular and can have many colors. Transparent Bitmaps used to create different non-rectangular images. These bitmaps have a full color component and a transparent component where the background shows through. Monochrome Bitmaps used for fonts. They are bitmaps in the true sense of the word. Each bit corresponds to one pixel with a value of 1 or 0 as follows: '1' indicates the pixel is turned on. This means the color of the pixels is determined by the foreground color setting in the graphics context. '0' indicates the pixel is turned off. This means the color is determined by the background color in the graphics context. 78

91 5 2D Graphics Library Table 5-7 lists the bitmap routines. Table 5-7 Bitmap Routines Routine uglbitmapblt( ) uglbitmapcreate( ) uglbitmapdestroy( ) uglbitmapread( ) uglbitmapstretchblt( ) uglbitmapwrite( ) uglmonobitmapcreate( ) uglmonobitmapdestroy( ) uglmonobitmapread( ) uglmonobitmapwrite( ) ugltransbitmapcreate( ) ugltransbitmapcreatefro mddb( ) ugltransbitmapdestroy( ) ugltransbitmapread( ) ugltransbitmapwrite( ) Description Performs a block image transfer of a bitmap Creates a device-dependent bitmap (DDB) Destroys a bitmap Reads image data from a bitmap Performs a scaled block image transfer of a bitmap Writes image data to a bitmap Creates a monochrome bitmap Destroys a bitmap Reads image data from a monochrome bitmap Write image data to a monochrome bitmap Creates a transparent bitmap Creates a transparent bitmap from a standard bitmap Destroys a transparent bitmap Reads image data from a transparent bitmap Writes image data to a transparent bitmap 5 79

92 WindML SDK 3.0 Programmer s Guide Device Independent Bitmaps WindML defines a portable bitmap representation called a Device Independent Bitmap (DIB), of which there are two versions: Standard color DIB (UGL_DIB) This DIB is used for standard bitmap operations and defines each bitmap pixel with an associated RGB value. This portable color is converted at run-time into a color recognized by the underlying graphics driver. Monochrome DIB (UGL_MDIB) This DIB is used where a single bit type or color operation is required and defines each pixel as on (1) or off (0). Each bitmap pixel is defined as a 1-bit value. This value is used to indicate whether a particular pixel is rendered to the display, or whether the pixel is transparent. Transparent bitmaps are created by combining monochrome and color DIBs, where the monochrome DIB provides transparency information applied to the color DIB. Most bitmap creation routines require the use of monochrome or color DIBs Device Dependent Bitmaps WindML also defines a hardware-specific bitmap representation called a Device Dependent Bitmap (DDB), of which there are three versions: Standard color DDB (UGL_DDB_ID) This DDB defines a color bitmap according to the underlying color system such as RGB565, or ARGB888. Monochrome DDB (UGL_MDDB_ID) This DDB defines a monochrome bitmap according to the most efficient graphics driver representation for transparency. Transparent DDB (UGL_TDDB_ID) This DDB combines a color DDB with a monochrome DDB. NOTE: As with all IDs returned by WindML API calls, never attempt to de-reference UGL_DDB_ID, UGL_MDDB_ID, or UGL_TDDB_ID. These bitmap representations optimize features of the graphics driver to ensure blt operations are performed in an optimal manner. No particular DDB representation can be assured, as graphics vendors define a number of different optimization techniques. All bitmap rendering operations require the creation of a color, monochrome, or transparent DDB. 80

93 5 2D Graphics Library Creating a Bitmap Example Example 5-5 creates two bitmaps, a regular DIB and a transparent DIB, and bitblits them to the display: Example 5-5 Creating Bitmaps UGL_UINT8 transparentdata[] = { #define O WHITE, #define B BLUE, #define Y LIGHTGRAY, #define G GREEN, B B B B B B O O O B B B B B B B B B B B B B O O O B B B B B B B B B B B B B O O O B B B B B B B B B B B B B B O B B B B B B B O B B B B B B B O B B B B B B B B O O O O O O O O O O O O O O O B O O O O O O O Y B O O O O O O O O O O O O O B Y B B B O O O O O O O O O O B B Y B B B B B O O O O O B B B B B Y Y B B B B B O O O B B B B B B Y Y B B B B B B O B B B B B B B Y Y B B B B B B B B B B B B B B Y Y B B B B B B B B B B B B B B Y Y B B B B B B B B B B B B B B Y Y B B B B B B B B B B B B B Y Y Y Y B B B B B B #undef G #undef Y #undef B #undef O }; 5 UGL_UINT8 transparentmask[] = { 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF }; 81

94 WindML SDK 3.0 Programmer s Guide int windmlexamplebitmap (void) { UGL_MDIB transmdib; UGL_DIB transdib; UGL_TDDB_ID transbitmap; UGL_DDB_ID testbitmap;... UGL_COLOR * colordata; colordata = (UGL_COLOR *)UGL_MALLOC(16 * 16 * sizeof(ugl_color)); for (i = 0; i < 16 * 16; i++) colordata[i] = colortable[transparentdata[i]].uglcolor; /* * colordata is a linear array of UGL_COLOR elements * indicated in the DIB header using UGL_DEVICE_COLOR_32. */ (UGL_COLOR *)transdib.pimage = colordata; transdib.colorformat = UGL_DEVICE_COLOR_32; /* * Since you already derived the "direct" representation of the * color from the colortable, you are not using a CLUT in the * DIB. Indicate a direct representation in * the image data using UGL_DIB_DIRECT. */ transdib.clutsize = 0; transdib.pclut = UGL_NULL; transdib.imageformat = UGL_DIB_DIRECT; /* * Set up the dimensions of the color and monochrome bitmaps. * The stride is equal to the width, but for special * cases such as creating bitmaps from sub-sections of a larger DIB, * the stride can be larger. */ transdib.width = transdib.height = transdib.stride = 16; transmdib.width = transmdib.stride = transmdib.height = 16; /* * The monochome DIB is just bits (see transparentmask). There is nothing * more to set. */ transmdib.pimage = transparentmask; /* * When you create the bitmaps, the DIB format is converted to the * hardware frame buffer format. Knowledge of the frame buffer s * format is not required to manipulate, draw to, or blit * bitmaps using the UGL 2-D API. */ transbitmap = ugltransbitmapcreate(devid, &transdib, &transmdib, 82

95 5 2D Graphics Library UGL_DIB_INIT_DATA, 0, UGL_NULL); testbitmap = uglbitmapcreate(devid, &transdib, UGL_DIB_INIT_DATA, 0, UGL_NULL); /* Blit the images to the screen */ uglbatchstart(gc); ClearScreen(gc); /* * UGL provides a function for "writing" a DIB to a bitmap. This * is used in the creation of the bitmap. Writing includes the * conversion of the DIB's format to the bitmap s format. This operation * is slower than blits. Since the frame buffer's format * defines the format of bitmaps, the frame buffer can be considered a * bitmap itself. The frame buffer bitmap is identified using * UGL_DISPLAY_ID. */ 5 uglbitmapwrite(devid, &transdib, 0,0,15,15,UGL_DISPLAY_ID, 100, displayheight - 132); /* * Blitting can only be done between bitmaps. Specify the rectangular * area in the originating bitmap to be blitted, and the destination * position. When the GC is created its "default bitmap" is set to the * screen bitmap, UGL_DISPLAY_ID. Since it is not changed to another * bitmap, blit to the screen by using the UGL_DEFAULT_ID bitmap. */ uglbitmapblt(gc, testbitmap,0,0,15,15, UGL_DEFAULT_ID, displaywidth / 2, displayheight / 2-50); uglbitmapblt(gc, transbitmap,0,0,15,15,ugl_default_id, displaywidth / 2, displayheight / );... } 83

96 WindML SDK 3.0 Programmer s Guide 5.7 Cursor Management A cursor is a special bitmap image created by an application, which is positioned on the screen by a pointing device. The cursor bitmap image supports 254 colors, in addition to transparent and inverted pixels. An application manages a cursor in two different ways: Automatic Cursor Position The application lets WindML process the pointing device input to automatically update the cursor position. This method is easy to implement, as you are not responsible for moving the cursor. Application Positions Cursor Your application is responsible for positioning the cursor based on pointer input events. This provides the application with greater control over cursor and pointing device functions. Table 5-8 lists the available WindML cursor functions for programming applications. Table 5-8 Cursor Handling Routines Routine uglcursorinit( ) uglcursordeinit( ) uglcursorbitmapcreate( ) uglcursorbitmapdestroy( ) uglcursorimageset( ) uglcursorimageget( ) uglcursormove( ) uglcursorpositionget( ) uglcursoron( ) uglcursoroff( ) Description Initializes a cursor Deinitializes a cursor Creates a cursor bitmap Destroys a cursor bitmap Sets the image displayed by the cursor Gets the image currently set for a cursor Moves the position of a cursor Gets the current position of a cursor Turns on a cursor Turns off a cursor 84

97 5 2D Graphics Library Software and Hardware Cursors A hardware cursor is an implementation of cursor technology that puts a graphic cursor on a different drawing plane from other primitive drawing operations. Hardware cursors greatly enhance drawing operations because they do not need to be hidden while performing drawing operations, which is a feature required for software cursors. As most graphics chips do not currently support hardware cursors, consult the driver documentation for any hardware limitations such as image size. Although underlying WindML DDK defines support for both software and hardware cursor interfaces, the SDK cursor API does not distinguish between hardware and software cursors. Unless you are guaranteed the target system implements hardware cursors, use the batch functions uglbatchstart( ) and uglbatchend( ) to minimize the time required to perform cursor management on drawing operations. 5 NOTE: The software cursor does not currently support color inversion Cursor Image and Hot Spots As depicted in Figure 5-1, most images are positioned on a display using their (0,0) origin. This is inappropriate for cursor images because the part of the image that defines the point, or what is perceived as the image that points to or is placed on something on the display, may not be at (0,0) origin. Figure 5-1 Cursor Image and HotSpot Origin (0,0) hot spot 85