<?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>