<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-C1B080D9-9C6C-520B-B73E-4EB344B1FC5E" xml:lang="en"><title>GDI

Collection Overview</title><shortdesc>The Graphics Device Interface (GDI) collection is an important

collection within the Graphics subsystem. It provides a suite of abstract

base classes, interfaces and data structures. The suite represents and interacts

with physical graphics hardware such as display screens, off-screen memory

and printers. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Architectural Relationship</title> <p>The GDI collection provides

base classes and utility functions. Every graphics component ends up using

it. The components in this collection are closely linked and provide important

functionality. The GDI component is a low-level component in this collection,

BitGDI is based on this and DirectGDI is a potentially faster alternative

to BitGDI. The Colour Palette provides coloring indexing operations. </p> </section>

<section><title>Description</title> <p>GDI consists of a large number of diverse

APIs that cover many different aspects of graphics including graphics device

abstraction, color value handling, linear digital differential analysis, font

description and information, printer devices abstraction, line breaking, text

rendering, handling of bidirectional text, text wrapper and linked font creation. </p> <p>Graphics

Device Interface collection includes the following components: </p> <ul>

<li id="GUID-BA77A047-4A77-5527-9EE8-AE4302E759C9"><p><xref href="GUID-C1B080D9-9C6C-520B-B73E-4EB344B1FC5E.dita#GUID-C1B080D9-9C6C-520B-B73E-4EB344B1FC5E/GUID-25C920A3-EF7C-5E8E-B94E-531B56E36DB9">GDI</xref>  </p> </li>

<li id="GUID-08EB75C6-0E70-5F16-9CF1-BF43AFDB3CC7"><p><xref href="GUID-C1B080D9-9C6C-520B-B73E-4EB344B1FC5E.dita#GUID-C1B080D9-9C6C-520B-B73E-4EB344B1FC5E/GUID-4CDF56F2-E278-5488-AD9D-D42EFC145A40">BitGDI</xref>  </p> </li>

<li id="GUID-13396341-EBF4-54F4-BC5A-5223F269114C"><p><xref href="GUID-C1B080D9-9C6C-520B-B73E-4EB344B1FC5E.dita#GUID-C1B080D9-9C6C-520B-B73E-4EB344B1FC5E/GUID-81F903E9-F9BD-5141-8402-483D6E26F1F0">DirectGDI</xref>  </p> </li>

<li id="GUID-61FA0D95-AE43-50AB-B0BF-0BE9BF9D3C95"><p><xref href="GUID-C1B080D9-9C6C-520B-B73E-4EB344B1FC5E.dita#GUID-C1B080D9-9C6C-520B-B73E-4EB344B1FC5E/GUID-059D5B88-E69F-5898-8D87-161B349B7C0C">Colour Palette</xref>  </p> </li>

</ul> </section>

<section id="GUID-25C920A3-EF7C-5E8E-B94E-531B56E36DB9"><title>GDI</title> <p>GDI

is a low level component. Two key concepts related to GDI are Device (<xref href="GUID-500FC564-35E9-3B66-A0C2-1269371A2EA0.dita"><apiname>CGraphicsDevice</apiname></xref>)

and Context (<xref href="GUID-DAD09DCF-3123-38B4-99E9-91FB24B92138.dita"><apiname>CGraphicsContext</apiname></xref>). Throughout the Graphics

sub-system a graphics device provides a graphics context through which the

device may be drawn to. The context maintains 'settings', such as the pen

and brush colors and styles in use, and provides a rich API of drawing commands

for creating graphical and textual output. </p> <p>Most display devices use

bitmap graphics and the GDI provides specializations of both <xref href="GUID-500FC564-35E9-3B66-A0C2-1269371A2EA0.dita"><apiname>CGraphicsDevice</apiname></xref> and <xref href="GUID-DAD09DCF-3123-38B4-99E9-91FB24B92138.dita"><apiname>CGraphicsContext</apiname></xref> to

act as base classes for bitmap devices: namely <xref href="GUID-2DEFEC47-F36E-3133-A08D-55F7C2534CC0.dita"><apiname>CBitmapDevice</apiname></xref> and <xref href="GUID-FC746873-0570-3900-AD89-42B205FDC0D3.dita"><apiname>CBitmapContext</apiname></xref>.

These add, amongst other attributes, pixel awareness, blitting, scanlines

and fading. </p> <p>The GDI defines abstract base classes for storing and

manipulating fonts (<xref href="GUID-2A12FE3B-47F2-3016-8161-A971CA506491.dita"><apiname>CFont</apiname></xref>, <xref href="GUID-0CA79D2D-827F-3A20-A10C-1CC9C576E803.dita"><apiname>CTypefaceStore</apiname></xref>, <xref href="GUID-B68B7BC8-CFBA-32F4-A0BE-8378F0C105DA.dita"><apiname>CFontCache</apiname></xref>)

and additional supporting classes and structures. </p> <p>The GDI defines

the interface for mapping between device-specific pixels and real-world twips.

A twip is a twentieth of a point and a point is 1/72 of an inch. That makes

a twip 1/1440 of an inch, 1/567 of a centimeter or about 0.018mm. </p> <p>The

GDI defines a base class for representing embedded pictures, <xref href="GUID-829D57CD-9659-347B-AAE9-5F0A0ECD555C.dita"><apiname>CPicture</apiname></xref>,

and supporting classes. It also provides base classes, interfaces and structures

for printing. </p> </section>

<section id="GUID-4CDF56F2-E278-5488-AD9D-D42EFC145A40"><title> BitGDI</title> <p>The <xref href="GUID-EAAD1719-C02C-5705-A5C3-993E36441BE6.dita">BitGDI Component</xref> is

used by legacy applications and the Window Server in the <xref href="GUID-F64E6551-670E-5E12-8103-DE504D3EC94F.dita">non-ScreenPlay

variant</xref>. The BitGDI component provides the <xref href="GUID-B229156F-2344-3F46-8542-AC65882D80DE.dita"><apiname>CFbsScreenDevice</apiname></xref> and <xref href="GUID-4A501086-7EFF-376D-8901-6D9B2EB4EFF2.dita"><apiname>CFbsBitGc</apiname></xref> APIs,

which are concrete implementations of <xref href="GUID-500FC564-35E9-3B66-A0C2-1269371A2EA0.dita"><apiname>CGraphicsDevice</apiname></xref> and <xref href="GUID-DAD09DCF-3123-38B4-99E9-91FB24B92138.dita"><apiname>CGraphicsContext</apiname></xref> for

bitmap-based devices. This component enables: </p> <ul>

<li id="GUID-989D5F4A-3DB5-55DA-91FE-5E70D3DFF57E"><p>hardware-independent

access to screen attributes </p> </li>

<li id="GUID-7E420A37-E7A9-5583-8FE0-393677696319"><p>bitmapped drawing which

holds settings and supports drawing to bitmapped devices and screens independent

of the display. </p> </li>

</ul> <fig id="GUID-C75462F4-7DB3-57BF-ABDE-C500669F45C5">

</fig> </section>

<section id="GUID-059D5B88-E69F-5898-8D87-161B349B7C0C"><title>Colour

Palette</title> <p>The <xref href="GUID-E82FABA9-9CCC-548F-99DB-EF2B9036B405.dita">Colour

Palette component</xref> provides coloring functionality. A user can specify

the use of a particular color, as described by a <xref href="GUID-F84C7F40-6DEB-39D1-B172-CB0CC3918E27.dita"><apiname>TRgb</apiname></xref>,

and have that color rendered on a machine’s display device as closely as possible

to the color specified. A related functionality allows arrays of colors to

be stored as bitmaps, and displayed at a later date in the same manner. </p> <p>Color

palettes also provide user-definable palette support to the GDI. A palette

is a user-defined set of colors, which is a subset of the full range of 24-bit

colors. This allows users the advantages of having a low bpp color mode whilst

being able to specify the colors available in that mode. Only a palette of

16 colors enables changing the palette. Palettes are also used to allow 24-bit

bitmaps to be stored in a more compressed form by finding the actual number

of different colors used in the bitmap. This creates a palette that allows

mapping of colors to a smaller index space. The pixels of the bitmaps are

encoded using indexes to this new index space. A palette has a size which

is set at its creation and cannot alter the number of entries in the palette.

Each entry in a palette is a mapping between that entry's index and a <codeph>TRgb</codeph> value.

Palette entries can be got and set at any time between the palette's creation

and destruction. The GDI's palette support also provides functions to find

the nearest palette color to a requested <codeph>TRgb</codeph> color. </p> </section>

</conbody><related-links>

<link href="GUID-E89F034F-C807-5FF9-B06B-F7CCD2441041.dita"><linktext>Graphics

Device Interface (GDI) Collection</linktext></link>

</related-links></concept>