|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-DBEAD516-5DD4-5E33-B6DA-657C1AE60C4B" xml:lang="en"><title>Dynamic |
|
13 Behaviour</title><shortdesc>Describes the dynamic behaviour of the Digitizer Driver. The description |
|
14 shows the use of the template port. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <p>The design assumes that interrupts are generated by pen-down events; however, |
|
16 there is no difficulty in adjusting your implementation to deal with interrupts |
|
17 generated by pen-up events. </p> |
|
18 <p>The heart of the design is a DFC that reads digitizer data samples when |
|
19 the pen goes down, and then samples the digitizer at regular intervals until |
|
20 the pen goes up. These samples are accumulated in a buffer in the platform |
|
21 independent layer. When enough samples have been gathered, the platform independent |
|
22 layer averages them, processes them, and issues pen movement events. </p> |
|
23 <table id="GUID-324D657A-DBA8-5862-BC0D-04F02CE2A9D4"> |
|
24 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
25 <tbody> |
|
26 <row> |
|
27 <entry><p>In the template port, the behaviour of the platform specific layer |
|
28 is based on three states: </p> </entry> |
|
29 <entry><p>The template port represents these three states using the enum values |
|
30 of the enum <codeph>TSate,</codeph> defined within the scope of the <codeph>DTemplateDigitiser</codeph> class |
|
31 (derived from <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita"><apiname>DDigitiser</apiname></xref>). The enum values are: </p> </entry> |
|
32 </row> |
|
33 <row> |
|
34 <entry><p>"power up" </p> </entry> |
|
35 <entry><p> <codeph> E_HW_PowerUp</codeph> </p> </entry> |
|
36 </row> |
|
37 <row> |
|
38 <entry><p>"collect sample" </p> </entry> |
|
39 <entry><p> <codeph>E_HW_CollectSample</codeph> </p> </entry> |
|
40 </row> |
|
41 <row> |
|
42 <entry><p>"pen up debounce" </p> </entry> |
|
43 <entry><p> <codeph>E_HW_PenUpDebounce</codeph> </p> </entry> |
|
44 </row> |
|
45 </tbody> |
|
46 </tgroup> |
|
47 </table> |
|
48 <section id="GUID-7860EA0B-CE04-4D32-B813-9D23274999AD"><title>State diagram</title> <p>The flow of control through the digitizer |
|
49 is described by this state diagram. The notes following relate to this state |
|
50 diagram on the left-hand side. </p> <p>The diagram on the right-hand side |
|
51 shows, in a simplified form, the flow of control. The numbers correspond to |
|
52 the state diagram numbers. Calls into the platform independent layer are shown |
|
53 in green boxes; important functions are shown in purple boxes. </p> <table id="GUID-23381681-744E-54DA-AAA2-5F30AD486783"> |
|
54 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
55 <tbody> |
|
56 <row> |
|
57 <entry><fig id="GUID-C7D88A4C-B5A0-5A1B-8710-188DC398B6CB"> |
|
58 <image href="GUID-F127644A-6072-52CA-9B17-E9DDEA784BE0_d0e8997_href.png" placement="inline"/> |
|
59 </fig> </entry> |
|
60 <entry><fig id="GUID-F244E871-48C7-548E-AF69-43D4265F9C48"> |
|
61 <image href="GUID-9173EEBA-CC84-51D9-9C8D-A75F7F494D62_d0e9004_href.png" placement="inline"/> |
|
62 </fig> </entry> |
|
63 </row> |
|
64 </tbody> |
|
65 </tgroup> |
|
66 </table> <ol id="GUID-B0BF0EE6-5059-5C43-BEE7-C500751CEC36"> |
|
67 <li id="GUID-5E21DADA-B4C0-5F90-B7C7-DF44C4FAA0CC"><p>If the pen is down at |
|
68 power on, i.e. when in the <i>power up</i> state, the device keeps sampling |
|
69 the digitiser at regular intervals until the pen is up. In the template port, |
|
70 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> |
|
71 <li id="GUID-DC234930-4914-54BB-B7D1-AF13832EB65F"><p>If the pen is up at |
|
72 power on, i.e. when in the <i>power up</i> state, or when the pen is first |
|
73 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 |
|
74 6 - initialise sampling</xref> </p> </li> |
|
75 <li id="GUID-788762CA-2B94-5E8E-944E-8BC79F5E8E7B"><p>If the pen is down in |
|
76 the <i>collect sample</i> state, then the digitiser coordinates are sampled |
|
77 at regular intervals, and stored in a buffer allocated by the platform independent |
|
78 layer. When a group of samples has been taken, the platform specific layer |
|
79 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 |
|
80 layer to start the processing of the samples. </p> <p>In the template port, |
|
81 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 |
|
82 7 - take sample readings</xref>. </p> </li> |
|
83 <li id="GUID-161E6630-D116-5559-BD19-10BA9A30FDEA"><p>If the pen is lifted |
|
84 while in the <i>collect sample</i> state, then the state changes to the <i>pen |
|
85 up debounce</i> state. This state describes the situation where a pen is lifted |
|
86 from the device and there is uncertainty as to whether this represents a positive |
|
87 move by the user, or whether the pen pressure has just been reduced momentarily. |
|
88 A delay is scheduled to decide to see which is case is true. At the end of |
|
89 the interval the state of the pen is checked again. If the pen is found to |
|
90 be down at the end of this interval, then the state changes back to the <i>collect |
|
91 sample</i> state, and the sample buffer is reset. </p> <p>In the template |
|
92 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> |
|
93 <li id="GUID-FE0F5F20-683E-5860-81E8-940F9FD98794"><p>If the pen is found |
|
94 to be down at the end of this interval, then the state changes back to the <i>collect |
|
95 sample</i> state, and the sample buffer is reset. </p> </li> |
|
96 <li id="GUID-84C0E701-1076-517B-B212-A4A48F2F622B"><p>If the pen is found |
|
97 to be still up at the end of this interval, then the pen is assumed to be |
|
98 intentionally up. The sample buffer is reset in preparation for future readings, |
|
99 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> |
|
100 </ol> </section> |
|
101 <section id="GUID-CD820F5C-01F7-427F-8FFC-675CDE48F1BD"><title>Interaction between the two layers</title> <p>This section |
|
102 shows the main interactions between the two layers: </p> <p><b>1</b> </p> <fig id="GUID-BC82D3E5-C190-57F4-AAC4-38532E2225E9"> |
|
103 <image href="GUID-4FDD1F7B-1A4E-5389-A0A4-22727CD42B5B_d0e9110_href.png" placement="inline"/> |
|
104 </fig> <p>When the device is started, the platform independent layer calls |
|
105 the function <codeph>DoCreate()</codeph>. This is where the power handler |
|
106 should be registered, interrupts bound and any other initialisation should |
|
107 take place. </p> <p>The platform independent layer then calls the function <codeph>WaitForPenDown()</codeph>. |
|
108 This is declared as pure virtual in the <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita"><apiname>DDigitiser</apiname></xref> class |
|
109 and is implemented in the platform specific layer. This function is also called |
|
110 from the <codeph>ProcessPenUp()</codeph> function that runs in a DFC thread |
|
111 scheduled to run when the pen is lifted. This DFC is scheduled in the platform |
|
112 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 |
|
113 4 - implement DDigitiser::WaitForPenDown()</xref>. </p> <p><b>2</b> </p> <fig id="GUID-3C50B57F-46A9-5CF0-94BB-50E63837D2CB"> |
|
114 <image href="GUID-AE53C15E-0C0F-5726-BBA4-E7DCDA7F48B4_d0e9145_href.png" placement="inline"/> |
|
115 </fig> <p>The platform specific layer calls <codeph>RawSampleValid()</codeph> when |
|
116 it has a group of digitizer coordinates ready to be processed by the platform |
|
117 independent layer. This is called in the context of a DFC thread, the DFC |
|
118 being queued when the digitizer interrupt is fired. </p> <p><b>3</b> </p> <fig id="GUID-AAEC4068-6743-5E50-906D-AE05622A0627"> |
|
119 <image href="GUID-DE7BD5C8-9966-5D5E-B81F-D57EA9FBA451_d0e9161_href.png" placement="inline"/> |
|
120 </fig> <p>The platform independent layer calls <codeph>WaitForPenUp()</codeph> to |
|
121 request another sample from the hardware. This is declared as pure virtual |
|
122 in the <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita"><apiname>DDigitiser</apiname></xref> class and is implemented in the platform |
|
123 specific layer. The function is called after the platform independent layer |
|
124 has processed a group of raw samples while the pen is down, and also tells |
|
125 the platform specific layer that the buffers in the platform independent layer |
|
126 can be re-used. </p> <p><b>4</b> </p> <fig id="GUID-5C3344EC-B07F-5D02-A107-7F4BB381EB55"> |
|
127 <image href="GUID-C8450E58-A603-5CF8-993E-053C990DDA19_d0e9181_href.png" placement="inline"/> |
|
128 </fig> <p>The platform independent layer calls <codeph>WaitForPenUpDebounce()</codeph> if |
|
129 a group of collected samples is not good enough. This is declared as pure |
|
130 virtual in the <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita"><apiname>DDigitiser</apiname></xref> class and is implemented in the |
|
131 platform specific layer. The function is called after the platform independent |
|
132 layer has processed a group of raw samples while the pen is down and also |
|
133 tells the platform specific layer that the buffers in the platform independent |
|
134 layer can be re-used. </p> <p><b>5</b> </p> <fig id="GUID-CAF3646F-0078-5F25-94A8-B03A42B132BC"> |
|
135 <image href="GUID-465D1450-B1EF-568B-B518-34ACE8C1697C_d0e9201_href.png" placement="inline"/> |
|
136 </fig> <p>When the pen is lifted, the platform specific layer calls <codeph>PenUp()</codeph> in |
|
137 the platform independent layer, which then changes its internal state, issues |
|
138 a pen up event to the device, and then calls <codeph>WaitForPenDown()</codeph> in |
|
139 the platform specific layer. </p> <p><b>6</b> </p> <fig id="GUID-77BBAF4E-D737-54CF-B67C-292D5ABD5CB3"> |
|
140 <image href="GUID-DB0EDBC2-8204-59F3-9029-EBBCE04A9E3C_d0e9220_href.png" placement="inline"/> |
|
141 </fig> <p>The platform independent layer calls <codeph>DigitiserOn()</codeph> when |
|
142 the device is turned on, or it may be called from the HAL. The function, implemented |
|
143 in the platform specific layer, and turns the hardware on if it is not already |
|
144 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 |
|
145 3 - implement power on behaviour</xref>. </p> <p><b>7</b> </p> <fig id="GUID-481F038C-2C5D-5D95-88A3-62F54EEDA713"> |
|
146 <image href="GUID-2622DE31-AA12-5FAD-86FB-B13259EFC6D9_d0e9239_href.png" placement="inline"/> |
|
147 </fig> <p> <codeph>DigitiserOff()</codeph> turns the digitizer off, and may |
|
148 be called as a result of a power transition, or it may be called from the |
|
149 HAL. If it is called from the Power Manager, the digitizer may already be |
|
150 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 |
|
151 convert digitizer coordinates to and from screen coordinates. Both are declared |
|
152 as pure virtual in the <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita"><apiname>DDigitiser</apiname></xref> class and need to be |
|
153 implemented in the platform specific layer. </p> <p><b>9</b> </p> <fig id="GUID-500D1D6B-85AE-5C1C-8F34-95036A6B9D82"> |
|
154 <image href="GUID-3F0053A7-6EE2-5B59-81C2-27EC3CC7820A_d0e9276_href.png" placement="inline"/> |
|
155 </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>. |
|
156 It delegates the handling of 5 of the individual behaviours, as represented |
|
157 by the <xref href="GUID-86A737D5-0602-3DB3-9CFF-764C80A8D468.dita"><apiname>TDigitiserHalFunction</apiname></xref> function-ids, to the following |
|
158 functions, declared as pure virtual in the <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita"><apiname>DDigitiser</apiname></xref> class, |
|
159 and implemented by the platform specific layer: </p> <ul> |
|
160 <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> |
|
161 <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> |
|
162 <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> |
|
163 <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> |
|
164 <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> |
|
165 </ul> </section> |
|
166 </conbody></concept> |