98 intentionally up. The sample buffer is reset in preparation for future readings, |
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> |
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> |
100 </ol> </section> |
101 <section id="GUID-CD820F5C-01F7-427F-8FFC-675CDE48F1BD"><title>Interaction between the two layers</title> <p>This 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"> |
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_d0e379956_href.png" placement="inline"/> |
103 <image href="GUID-4FDD1F7B-1A4E-5389-A0A4-22727CD42B5B_d0e385809_href.png" placement="inline"/> |
104 </fig> <p>When the device is started, the platform independent layer calls |
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 |
105 the function <codeph>DoCreate()</codeph>. This is where the power handler |
106 should be registered, interrupts bound and any other initialisation should |
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>. |
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 |
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 |
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 |
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 |
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 |
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"> |
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_d0e379991_href.png" placement="inline"/> |
114 <image href="GUID-AE53C15E-0C0F-5726-BBA4-E7DCDA7F48B4_d0e385844_href.png" placement="inline"/> |
115 </fig> <p>The platform specific layer calls <codeph>RawSampleValid()</codeph> when |
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 |
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 |
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"> |
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_d0e380007_href.png" placement="inline"/> |
119 <image href="GUID-DE7BD5C8-9966-5D5E-B81F-D57EA9FBA451_d0e385860_href.png" placement="inline"/> |
120 </fig> <p>The platform independent layer calls <codeph>WaitForPenUp()</codeph> to |
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 |
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 |
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 |
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 |
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 |
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"> |
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_d0e380027_href.png" placement="inline"/> |
127 <image href="GUID-C8450E58-A603-5CF8-993E-053C990DDA19_d0e385880_href.png" placement="inline"/> |
128 </fig> <p>The platform independent layer calls <codeph>WaitForPenUpDebounce()</codeph> if |
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 |
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 |
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 |
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 |
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 |
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"> |
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_d0e380047_href.png" placement="inline"/> |
135 <image href="GUID-465D1450-B1EF-568B-B518-34ACE8C1697C_d0e385900_href.png" placement="inline"/> |
136 </fig> <p>When the pen is lifted, the platform specific layer calls <codeph>PenUp()</codeph> in |
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 |
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 |
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"> |
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_d0e380066_href.png" placement="inline"/> |
140 <image href="GUID-DB0EDBC2-8204-59F3-9029-EBBCE04A9E3C_d0e385919_href.png" placement="inline"/> |
141 </fig> <p>The platform independent layer calls <codeph>DigitiserOn()</codeph> when |
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 |
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 |
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 |
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"> |
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_d0e380085_href.png" placement="inline"/> |
146 <image href="GUID-2622DE31-AA12-5FAD-86FB-B13259EFC6D9_d0e385938_href.png" placement="inline"/> |
147 </fig> <p> <codeph>DigitiserOff()</codeph> turns the digitizer off, and may |
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 |
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 |
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 |
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 |
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 |
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"> |
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_d0e380122_href.png" placement="inline"/> |
154 <image href="GUID-3F0053A7-6EE2-5B59-81C2-27EC3CC7820A_d0e385975_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>. |
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 |
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 |
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, |
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> |
159 and implemented by the platform specific layer: </p> <ul> |