<?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-DBEAD516-5DD4-5E33-B6DA-657C1AE60C4B" xml:lang="en"><title>Dynamic

Behaviour</title><shortdesc>Describes the dynamic behaviour of the Digitizer Driver. The description

shows the use of the template port. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The design assumes that interrupts are generated by pen-down events; however,

there is no difficulty in adjusting your implementation to deal with interrupts

generated by pen-up events. </p>

<p>The heart of the design is a DFC that reads digitizer data samples when

the pen goes down, and then samples the digitizer at regular intervals until

the pen goes up. These samples are accumulated in a buffer in the platform

independent layer. When enough samples have been gathered, the platform independent

layer averages them, processes them, and issues pen movement events. </p>

<table id="GUID-324D657A-DBA8-5862-BC0D-04F02CE2A9D4">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p>In the template port, the behaviour of the platform specific layer

is based on three states: </p> </entry>

<entry><p>The template port represents these three states using the enum values

of the enum <codeph>TSate,</codeph> defined within the scope of the <codeph>DTemplateDigitiser</codeph> class

(derived from <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita"><apiname>DDigitiser</apiname></xref>). The enum values are: </p> </entry>

</row>

<row>

<entry><p>"power up" </p> </entry>

<entry><p> <codeph> E_HW_PowerUp</codeph>  </p> </entry>

</row>

<row>

<entry><p>"collect sample" </p> </entry>

<entry><p> <codeph>E_HW_CollectSample</codeph>  </p> </entry>

</row>

<row>

<entry><p>"pen up debounce" </p> </entry>

<entry><p> <codeph>E_HW_PenUpDebounce</codeph>  </p> </entry>

</row>

</tbody>

</tgroup>

</table>

<section id="GUID-7860EA0B-CE04-4D32-B813-9D23274999AD"><title>State diagram</title> <p>The flow of control through the digitizer

is described by this state diagram. The notes following relate to this state

diagram on the left-hand side. </p> <p>The diagram on the right-hand side

shows, in a simplified form, the flow of control. The numbers correspond to

the state diagram numbers. Calls into the platform independent layer are shown

in green boxes; important functions are shown in purple boxes. </p> <table id="GUID-23381681-744E-54DA-AAA2-5F30AD486783">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><fig id="GUID-C7D88A4C-B5A0-5A1B-8710-188DC398B6CB">

<image href="GUID-F127644A-6072-52CA-9B17-E9DDEA784BE0_d0e8997_href.png" placement="inline"/>

</fig> </entry>

<entry><fig id="GUID-F244E871-48C7-548E-AF69-43D4265F9C48">

<image href="GUID-9173EEBA-CC84-51D9-9C8D-A75F7F494D62_d0e9004_href.png" placement="inline"/>

</fig> </entry>

</row>

</tbody>

</tgroup>

</table> <ol id="GUID-B0BF0EE6-5059-5C43-BEE7-C500751CEC36">

<li id="GUID-5E21DADA-B4C0-5F90-B7C7-DF44C4FAA0CC"><p>If the pen is down at

power on, i.e. when in the <i>power up</i> state, the device keeps sampling

the digitiser at regular intervals until the pen is up. In the template port,

the interval is defined by the constant <xref href="GUID-3574BE12-9DA9-573D-8545-3B073005A139.dita#GUID-3574BE12-9DA9-573D-8545-3B073005A139/GUID-EDA72AF2-460E-52F0-9EC7-634B7AC14D46">KPenUpPollTime</xref> </p> </li>

<li id="GUID-DC234930-4914-54BB-B7D1-AF13832EB65F"><p>If the pen is up at

power on, i.e. when in the <i>power up</i> state, or when the pen is first

lifted, the sampling is initialised; see <xref href="GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07.dita#GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07/GUID-4B0737BA-74E2-5FF2-BCE3-4BC822C14470">Step

6 - initialise sampling</xref>  </p> </li>

<li id="GUID-788762CA-2B94-5E8E-944E-8BC79F5E8E7B"><p>If the pen is down in

the <i>collect sample</i> state, then the digitiser coordinates are sampled

at regular intervals, and stored in a buffer allocated by the platform independent

layer. When a group of samples has been taken, the platform specific layer

calls <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita#GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9/GUID-35568A81-14C1-39A2-A8AC-A1D1ED1C0E93"><apiname>DDigitiser::RawSampleValid()</apiname></xref> in the platform independent

layer to start the processing of the samples. </p> <p>In the template port,

the interval is defined by the constant <xref href="GUID-3574BE12-9DA9-573D-8545-3B073005A139.dita#GUID-3574BE12-9DA9-573D-8545-3B073005A139/GUID-C8EC7A1D-7597-57BB-ADE4-0EDFFEB323D0">KInterSampleTime</xref>; see <xref href="GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07.dita#GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07/GUID-4E84D583-7745-531B-AB62-65D012B4BCB2">Step

7 - take sample readings</xref>. </p> </li>

<li id="GUID-161E6630-D116-5559-BD19-10BA9A30FDEA"><p>If the pen is lifted

while in the <i>collect sample</i> state, then the state changes to the <i>pen

up debounce</i> state. This state describes the situation where a pen is lifted

from the device and there is uncertainty as to whether this represents a positive

move by the user, or whether the pen pressure has just been reduced momentarily.

A delay is scheduled to decide to see which is case is true. At the end of

the interval the state of the pen is checked again. If the pen is found to

be down at the end of this interval, then the state changes back to the <i>collect

sample</i> state, and the sample buffer is reset. </p> <p>In the template

port, the delay interval is defined by the constant <xref href="GUID-3574BE12-9DA9-573D-8545-3B073005A139.dita#GUID-3574BE12-9DA9-573D-8545-3B073005A139/GUID-9BFC5FDA-FC84-5B54-93AA-BED4035F2A59">KPenUpDebounceTime</xref>. </p> </li>

<li id="GUID-FE0F5F20-683E-5860-81E8-940F9FD98794"><p>If the pen is found

to be down at the end of this interval, then the state changes back to the <i>collect

sample</i> state, and the sample buffer is reset. </p> </li>

<li id="GUID-84C0E701-1076-517B-B212-A4A48F2F622B"><p>If the pen is found

to be still up at the end of this interval, then the pen is assumed to be

intentionally up. The sample buffer is reset in preparation for future readings,

and the platform independent layer is notified that the pen is now up by calling <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita#GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9/GUID-58094BAE-A932-366A-A2B0-977E3539540C"><apiname>DDigitiser::PenUp()</apiname></xref>. </p> </li>

</ol> </section>

<section id="GUID-CD820F5C-01F7-427F-8FFC-675CDE48F1BD"><title>Interaction between the two layers</title> <p>This section

shows the main interactions between the two layers: </p> <p><b>1</b> </p> <fig id="GUID-BC82D3E5-C190-57F4-AAC4-38532E2225E9">

<image href="GUID-4FDD1F7B-1A4E-5389-A0A4-22727CD42B5B_d0e9110_href.png" placement="inline"/>

</fig> <p>When the device is started, the platform independent layer calls

the function <codeph>DoCreate()</codeph>. This is where the power handler

should be registered, interrupts bound and any other initialisation should

take place. </p> <p>The platform independent layer then calls the function <codeph>WaitForPenDown()</codeph>.

This is declared as pure virtual in the <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita"><apiname>DDigitiser</apiname></xref> class

and is implemented in the platform specific layer. This function is also called

from the <codeph>ProcessPenUp()</codeph> function that runs in a DFC thread

scheduled to run when the pen is lifted. This DFC is scheduled in the platform

specific layer. </p> <p>See also <xref href="GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07.dita#GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07/GUID-1A1194A0-DF74-59E7-B3AD-FD87D501F00F">Step

4 - implement DDigitiser::WaitForPenDown()</xref>. </p> <p><b>2</b> </p> <fig id="GUID-3C50B57F-46A9-5CF0-94BB-50E63837D2CB">

<image href="GUID-AE53C15E-0C0F-5726-BBA4-E7DCDA7F48B4_d0e9145_href.png" placement="inline"/>

</fig> <p>The platform specific layer calls <codeph>RawSampleValid()</codeph> when

it has a group of digitizer coordinates ready to be processed by the platform

independent layer. This is called in the context of a DFC thread, the DFC

being queued when the digitizer interrupt is fired. </p> <p><b>3</b> </p> <fig id="GUID-AAEC4068-6743-5E50-906D-AE05622A0627">

<image href="GUID-DE7BD5C8-9966-5D5E-B81F-D57EA9FBA451_d0e9161_href.png" placement="inline"/>

</fig> <p>The platform independent layer calls <codeph>WaitForPenUp()</codeph> to

request another sample from the hardware. This is declared as pure virtual

in the <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita"><apiname>DDigitiser</apiname></xref> class and is implemented in the platform

specific layer. The function is called after the platform independent layer

has processed a group of raw samples while the pen is down, and also tells

the platform specific layer that the buffers in the platform independent layer

can be re-used. </p> <p><b>4</b> </p> <fig id="GUID-5C3344EC-B07F-5D02-A107-7F4BB381EB55">

<image href="GUID-C8450E58-A603-5CF8-993E-053C990DDA19_d0e9181_href.png" placement="inline"/>

</fig> <p>The platform independent layer calls <codeph>WaitForPenUpDebounce()</codeph> if

a group of collected samples is not good enough. This is declared as pure

virtual in the <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita"><apiname>DDigitiser</apiname></xref> class and is implemented in the

platform specific layer. The function is called after the platform independent

layer has processed a group of raw samples while the pen is down and also

tells the platform specific layer that the buffers in the platform independent

layer can be re-used. </p> <p><b>5</b> </p> <fig id="GUID-CAF3646F-0078-5F25-94A8-B03A42B132BC">

<image href="GUID-465D1450-B1EF-568B-B518-34ACE8C1697C_d0e9201_href.png" placement="inline"/>

</fig> <p>When the pen is lifted, the platform specific layer calls <codeph>PenUp()</codeph> in

the platform independent layer, which then changes its internal state, issues

a pen up event to the device, and then calls <codeph>WaitForPenDown()</codeph> in

the platform specific layer. </p> <p><b>6</b> </p> <fig id="GUID-77BBAF4E-D737-54CF-B67C-292D5ABD5CB3">

<image href="GUID-DB0EDBC2-8204-59F3-9029-EBBCE04A9E3C_d0e9220_href.png" placement="inline"/>

</fig> <p>The platform independent layer calls <codeph>DigitiserOn()</codeph> when

the device is turned on, or it may be called from the HAL. The function, implemented

in the platform specific layer, and turns the hardware on if it is not already

on. See also <xref href="GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07.dita#GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07/GUID-A4B43E01-9638-5967-8EFA-0AABA33189EA">Step

3 - implement power on behaviour</xref>. </p> <p><b>7</b> </p> <fig id="GUID-481F038C-2C5D-5D95-88A3-62F54EEDA713">

<image href="GUID-2622DE31-AA12-5FAD-86FB-B13259EFC6D9_d0e9239_href.png" placement="inline"/>

</fig> <p> <codeph>DigitiserOff()</codeph> turns the digitizer off, and may

be called as a result of a power transition, or it may be called from the

HAL. If it is called from the Power Manager, the digitizer may already be

off if the platform is in silent running mode. See also <xref href="GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07.dita#GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07/GUID-6DC8A3DB-452F-5738-9D60-7E34BF8A3596">Step 10 - implement DDigitiser::DigitiserOff()</xref>. </p> <p><b>8</b> </p> <p>There are two functions: <codeph>DigitiserToScreen()</codeph> and <codeph>ScreenToDigitiser()</codeph> that

convert digitizer coordinates to and from screen coordinates. Both are declared

as pure virtual in the <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita"><apiname>DDigitiser</apiname></xref> class and need to be

implemented in the platform specific layer. </p> <p><b>9</b> </p> <fig id="GUID-500D1D6B-85AE-5C1C-8F34-95036A6B9D82">

<image href="GUID-3F0053A7-6EE2-5B59-81C2-27EC3CC7820A_d0e9276_href.png" placement="inline"/>

</fig> <p>The platform independent layer provides the <xref href="GUID-9AE254D4-AA60-579E-8D9D-F2797106A413.dita#GUID-9AE254D4-AA60-579E-8D9D-F2797106A413/GUID-1B59A40C-D023-5555-8E5E-DF18D653D321">HAL handler</xref> for the <xref href="GUID-E22F7F41-C578-36B4-A7AB-AE0AEF520A69.dita"><apiname>EHalGroupDigitiser</apiname></xref>  <xref href="GUID-9AE254D4-AA60-579E-8D9D-F2797106A413.dita#GUID-9AE254D4-AA60-579E-8D9D-F2797106A413/GUID-366CC4B8-C6BD-5DCC-B55D-6D87CD5C8E64">HAL groups and function-ids</xref>. This is <codeph>DDigitiser::HalFunction()</codeph>.

It delegates the handling of 5 of the individual behaviours, as represented

by the <xref href="GUID-86A737D5-0602-3DB3-9CFF-764C80A8D468.dita"><apiname>TDigitiserHalFunction</apiname></xref> function-ids, to the following

functions, declared as pure virtual in the <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita"><apiname>DDigitiser</apiname></xref> class,

and implemented by the platform specific layer: </p> <ul>

<li id="GUID-A1F40F14-B2AB-5784-B5E9-35411C722CD0"><p> <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita#GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9/GUID-1B0F51F0-C3F4-333A-AC7E-CE332248355E"><apiname>DDigitiser::SetXYInputCalibration()</apiname></xref>  </p> </li>

<li id="GUID-2EC061EB-FBC4-5462-98E2-AA79B6BFD981"><p> <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita#GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9/GUID-856B4F1A-ACE4-338B-B618-3DB3830CE0B9"><apiname>DDigitiser::CalibrationPoints()</apiname></xref>  </p> </li>

<li id="GUID-4DBA15F8-34D3-5586-BF0C-89B648005EEE"><p> <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita#GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9/GUID-90861298-19B7-3D1F-80CD-E49D4C500D49"><apiname>DDigitiser::SaveXYInputCalibration()</apiname></xref>  </p> </li>

<li id="GUID-B6CCEBBA-93CD-5C2A-9343-9F22E7E1DD2D"><p> <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita#GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9/GUID-4184805F-CF27-30AA-A551-684B595E4228"><apiname>DDigitiser::RestoreXYInputCalibration()</apiname></xref>  </p> </li>

<li id="GUID-4626F772-B9E9-5313-80F3-AF7859F58ADD"><p> <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita#GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9/GUID-B2B3E681-018C-34A9-9686-580B60FE0D40"><apiname>DDigitiser::DigitiserInfo()</apiname></xref>  </p> </li>

</ul> </section>

</conbody></concept>