|
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-3F0FCBB5-98D2-4355-96E3-2DA938DE1C16" xml:lang="en"><title>DSA Migration Guide</title><shortdesc>This migration guide explains the guidelines that applications |
|
13 that use direct screen access (DSA) must follow in order to run on |
|
14 ScreenPlay (NGA) devices.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <p>Introduced in an earlier version of the Symbian platform, DSA enables |
|
16 applications that require high frame rates (such as video and games) |
|
17 to bypass the Window Server and write to the screen directly. On |
|
18 ScreenPlay, Symbian recommends the use of EGL window surfaces in preference |
|
19 to DSA.</p> |
|
20 <p>Support for DSA is maintained for backward compatibility reasons. |
|
21 However, whereas on some earlier devices, applications might work |
|
22 without fully conforming to the rules of DSA, these rules are now |
|
23 necessarily enforced. Applications that follow the following guidelines |
|
24 should run correctly on a ScreenPlay device.</p> |
|
25 <section id="GUID-3725C49E-4804-4AF3-9797-1D052685893F"><title>Always |
|
26 use a DSA session when using DSA</title> <p>The main classes |
|
27 of the DSA framework are <xref href="GUID-24C7AE25-B44A-3B6F-AA05-EA90A8D36129.dita"><apiname>CDirectScreenAccess</apiname></xref>, <xref href="GUID-E2092CF9-98E8-3206-91B2-36011AA6FB77.dita"><apiname>RDirectScreenAccess</apiname></xref> and <xref href="GUID-5A289A8A-1485-3AB9-94CF-177B83D4F450.dita"><apiname>MDirectScreenAccess</apiname></xref>. Before drawing to the screen, the DSA application must create a |
|
28 DSA session; for example, by instantiating <codeph>CDirectScreenAccess</codeph> and calling <codeph>CDirectScreenAccess::StartL()</codeph>. This |
|
29 rule applies regardless of whether the application accesses the DSA |
|
30 framebuffer using <xref href="GUID-4A501086-7EFF-376D-8901-6D9B2EB4EFF2.dita"><apiname>CFbsBitGc</apiname></xref>, <xref href="GUID-B229156F-2344-3F46-8542-AC65882D80DE.dita"><apiname>CFbsScreenDevice</apiname></xref> or gains a pointer directly through HAL.</p><p>Applications that |
|
31 fail to create a DSA session will not work. Applications that draw |
|
32 outside of an active period of DSA will not work. This is because |
|
33 all DSA rendering is directed into a virtual framebuffer and the Operating |
|
34 System uses the DSA session to determine when that framebuffer should |
|
35 be made visible.</p><p>The following example demonstrates requesting |
|
36 direct screen access:</p><codeblock xml:space="preserve">voidCMyDSAEngine::StartDrawingL() |
|
37 { |
|
38 // Initialize DSA. |
|
39 TRAPD(dsaError,iDSA->StartL()); |
|
40 if (dsaError==KErrNone) |
|
41 { |
|
42 // Get the graphics context for drawing. |
|
43 iGc=iDSA->Gc(); |
|
44 |
|
45 // Get the region to draw to. |
|
46 iRegion=iDSA->DrawingRegion(); |
|
47 |
|
48 // Set the clipping region to this region. |
|
49 iGc->SetClippingRegion(iRegion); |
|
50 |
|
51 // Start generating timer events (the drawing is done in a timer callback). |
|
52 iPeriodicTimer=CPeriodic::NewL(CActive::EPriorityStandard); |
|
53 iPeriodicTimer->Start(0,KInterval,TCallBack(DrawNextFrame, this)); |
|
54 iDrawing=ETrue; |
|
55 } |
|
56 } |
|
57 </codeblock></section> |
|
58 <section id="GUID-ED2BEF42-7E4D-484F-8142-011271D7A584"><title>Inform |
|
59 the Operating System after updating the DSA buffer</title><p>Applications |
|
60 can access the screen by writing to the video hardware framebuffer |
|
61 or by using <xref href="GUID-B229156F-2344-3F46-8542-AC65882D80DE.dita"><apiname>CFbsScreenDevice</apiname></xref>. Regardless which |
|
62 of these methods you use, the application must inform the OS that |
|
63 the framebuffer has been updated in order for the DSA drawing to be |
|
64 pushed to the display.</p><p>Applications that fail to declare modifications |
|
65 to the framebuffer will not see their content correctly appear on-screen. |
|
66 This is because the OS uses event-driven updating to copy the contents |
|
67 of the DSA framebuffer into the display.</p><p>When writing to the |
|
68 video hardware frame buffer, force a screen update by creating a redraw |
|
69 event like this:</p><codeblock xml:space="preserve">TRawEventredraw; |
|
70 redraw.Set(TRawEvent::ERedraw); |
|
71 UserSvr::AddEvent(redraw);</codeblock><p>When using <xref href="GUID-B229156F-2344-3F46-8542-AC65882D80DE.dita"><apiname>CFbsScreenDevice</apiname></xref>, force a screen update by calling one of the following:</p><codeblock xml:space="preserve">void CFbsScreenDevice::Update(); |
|
72 void CFbsScreenDevice::Update(constTRegion &aRegion); |
|
73 </codeblock> </section> |
|
74 <section id="GUID-862F9788-B580-4D93-84B4-677D4B964BB9"><title>Do |
|
75 not mix DSA and non-DSA rendering</title><p>The application must not |
|
76 issue <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref> rendering to a window when DSA |
|
77 is active on that window. If both types of rendering are required, |
|
78 the application must ensure that they only happen in distinct periods |
|
79 demarcated by the DSA session.</p><p>Applications that interleave |
|
80 periods of DSA rendering with periods of standard indirect (<xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref>) rendering, expecting to see each painted on |
|
81 top of the previous, will not work. This is because the OS now uses |
|
82 two separate framebuffers; one for DSA rendering and one for indirect |
|
83 rendering. Previous versions of the OS use a single |
|
84 framebuffer for both types of rendering.</p><p>Applications must be |
|
85 written to render the entire contents of their window using either |
|
86 DSA or indirect rendering at any one point of time.</p></section> |
|
87 </conbody><related-links> |
|
88 <link href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita"><linktext>The |
|
89 ScreenPlay Graphics Architecture</linktext></link> |
|
90 <link href="GUID-484B51EC-2209-5492-8E9C-9D792AB0DF35.dita"><linktext>Graphics |
|
91 and Drawing</linktext></link> |
|
92 </related-links></concept> |