22 to a window and then add a red diagonal line below it (A in following |
22 to a window and then add a red diagonal line below it (A in following |
23 diagram). When this is performed as redraw drawing, the application |
23 diagram). When this is performed as redraw drawing, the application |
24 calculates the bounding rectangles of the "Hello!" text and the red |
24 calculates the bounding rectangles of the "Hello!" text and the red |
25 line (B). For each one, the application passes the rectangle to <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-F5E85A7B-0DAE-32C1-AF71-8FC2F5F01509"><apiname>RWindow::BeginRedraw(const TRect &)</apiname></xref>, then calls the |
25 line (B). For each one, the application passes the rectangle to <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-F5E85A7B-0DAE-32C1-AF71-8FC2F5F01509"><apiname>RWindow::BeginRedraw(const TRect &)</apiname></xref>, then calls the |
26 draw commands and afterwards calls <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-3DE16607-AD3B-3946-BEB3-88512EAAB9CE"><apiname>RWindow::EndRedraw()</apiname></xref>. </p> <fig id="GUID-53B962F7-D425-5D72-8148-F822A3462243"> |
26 draw commands and afterwards calls <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-3DE16607-AD3B-3946-BEB3-88512EAAB9CE"><apiname>RWindow::EndRedraw()</apiname></xref>. </p> <fig id="GUID-53B962F7-D425-5D72-8148-F822A3462243"> |
27 <image href="GUID-1DDFFB60-BBA8-500E-A9B1-F048EE5BFBD0_d0e242754_href.png" placement="inline"/> |
27 <image href="GUID-1DDFFB60-BBA8-500E-A9B1-F048EE5BFBD0_d0e240588_href.png" placement="inline"/> |
28 </fig> <p>This has the advantage that the Window Server knows that |
28 </fig> <p>This has the advantage that the Window Server knows that |
29 the area of the window that has the "Hello!" text is not affected |
29 the area of the window that has the "Hello!" text is not affected |
30 by the drawing of the red line. There are also advantages when some |
30 by the drawing of the red line. There are also advantages when some |
31 or all of the window needs to be repainted. For example, suppose another |
31 or all of the window needs to be repainted. For example, suppose another |
32 window (such as an OK dialog box) appears above the window (as shown |
32 window (such as an OK dialog box) appears above the window (as shown |
39 line without bracketing it within <codeph>BeginRedraw()</codeph> and <codeph>EndRedraw()</codeph> calls. This is called <b>non-redraw drawing</b>. In ScreenPlay, each non-redraw drawing operation triggers the Window |
39 line without bracketing it within <codeph>BeginRedraw()</codeph> and <codeph>EndRedraw()</codeph> calls. This is called <b>non-redraw drawing</b>. In ScreenPlay, each non-redraw drawing operation triggers the Window |
40 Server to invalidate the entire window. This means that the client |
40 Server to invalidate the entire window. This means that the client |
41 application must then perform a full window redraw, as shown in the |
41 application must then perform a full window redraw, as shown in the |
42 next diagram. </p> <fig id="GUID-A36DF80C-6B53-5D9D-878B-0854BB36E44A"> |
42 next diagram. </p> <fig id="GUID-A36DF80C-6B53-5D9D-878B-0854BB36E44A"> |
43 <title> Non-redraw drawing sequence </title> |
43 <title> Non-redraw drawing sequence </title> |
44 <image href="GUID-7C51BC7A-CB97-5A7E-A5EF-BB3623DFFFED_d0e242777_href.png" placement="inline"/> |
44 <image href="GUID-7C51BC7A-CB97-5A7E-A5EF-BB3623DFFFED_d0e240611_href.png" placement="inline"/> |
45 </fig> <p>This is less efficient than the Window Server replaying |
45 </fig> <p>This is less efficient than the Window Server replaying |
46 the draw operations for the affected area. </p> <p>Symbian recommends |
46 the draw operations for the affected area. </p> <p>Symbian recommends |
47 that all drawing is now performed as redraw drawing. Typically this |
47 that all drawing is now performed as redraw drawing. Typically this |
48 involves dividing the window up into rectangular areas that represent |
48 involves dividing the window up into rectangular areas that represent |
49 different aspects of the user interface—for example, as shown in the |
49 different aspects of the user interface—for example, as shown in the |
50 following diagram. If anything spoils the screen, the Window Server |
50 following diagram. If anything spoils the screen, the Window Server |
51 then only needs to redraw the corresponding portions of the user interface. </p> <fig id="GUID-BAD0C762-0EBD-51E2-BC64-DF38749CA7D8"> |
51 then only needs to redraw the corresponding portions of the user interface. </p> <fig id="GUID-BAD0C762-0EBD-51E2-BC64-DF38749CA7D8"> |
52 <image href="GUID-F2E8CB4B-C1BB-577D-B018-7FF231B70D8C_d0e242788_href.png" placement="inline"/> |
52 <image href="GUID-F2E8CB4B-C1BB-577D-B018-7FF231B70D8C_d0e240622_href.png" placement="inline"/> |
53 </fig> <p>In earlier versions of Symbian, before the introduction |
53 </fig> <p>In earlier versions of Symbian, before the introduction |
54 of the <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-250ED45A-76F3-3623-BA4B-22D31613A2EF"><apiname>CCoeControl::DrawNow(const TRect &)const</apiname></xref> overload, developers sometimes used non-redraw drawing to update |
54 of the <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-250ED45A-76F3-3623-BA4B-22D31613A2EF"><apiname>CCoeControl::DrawNow(const TRect &)const</apiname></xref> overload, developers sometimes used non-redraw drawing to update |
55 a small part of a control. This technique has often been used for |
55 a small part of a control. This technique has often been used for |
56 virtual keyboards and calendar controls. This type of use case is |
56 virtual keyboards and calendar controls. This type of use case is |
57 now particularly unsuited to non-redraw drawing because in ScreenPlay |
57 now particularly unsuited to non-redraw drawing because in ScreenPlay |
81 the smallest possible bounding rectangle to the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-9337538E-7A53-3153-A330-968B5E4F2FF2"><apiname>RWindow::BeginRedraw()</apiname></xref> and <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-D5458F8C-E199-37DD-B821-050B749122C6"><apiname>CCoeControl::DrawNow()</apiname></xref> methods. If this still |
81 the smallest possible bounding rectangle to the <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-9337538E-7A53-3153-A330-968B5E4F2FF2"><apiname>RWindow::BeginRedraw()</apiname></xref> and <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-D5458F8C-E199-37DD-B821-050B749122C6"><apiname>CCoeControl::DrawNow()</apiname></xref> methods. If this still |
82 results in poor performance, because, for example, there is a large |
82 results in poor performance, because, for example, there is a large |
83 amount of incremental screen updating, the recommended solution in |
83 amount of incremental screen updating, the recommended solution in |
84 ScreenPlay is to render to a surface. </p><p><b>High frequency rendering</b> </p><p>It is possible for a client to provide batches of redraw |
84 ScreenPlay is to render to a surface. </p><p><b>High frequency rendering</b> </p><p>It is possible for a client to provide batches of redraw |
85 drawing (that is, drawing bracketed in <codeph>BeginRedraw()</codeph> and <codeph>EndRedraw()</codeph> calls) for the same region of a |
85 drawing (that is, drawing bracketed in <codeph>BeginRedraw()</codeph> and <codeph>EndRedraw()</codeph> calls) for the same region of a |
86 window faster than they can be displayed on the screen. |
86 window faster than they can be displayed on the screen. When this |
87 When this happens, the Window Server may discard the drawing commands |
87 happens, the Window Server may discard the drawing commands in one |
88 in one or more of the earlier batches of redraw drawing and simply |
88 or more of the earlier batches of redraw drawing and simply draw the |
89 draw the pixels defined in a later redraw batch to the screen. This |
89 pixels defined in a later redraw batch to the screen. This can result |
90 can result in missing frames, but is only likely to be noticeable |
90 in missing frames, but is only likely to be noticeable in an application |
91 in an application like a game that performs high-frequency rendering.</p><p>The solution is to call <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-B431DC60-D11F-3239-8F52-4257B9B0E0C9"><apiname>RWsSession::Finish()</apiname></xref> after each <codeph>EndRedraw()</codeph> call. This slows the client |
91 like a game that performs high-frequency rendering.</p><p>The solution |
92 so that it does not generate pixel content faster than the Window |
92 is to call <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-B431DC60-D11F-3239-8F52-4257B9B0E0C9"><apiname>RWsSession::Finish()</apiname></xref> after each <codeph>EndRedraw()</codeph> call. This slows the client so that it does |
93 Server can display it on the screen. </p><p>To summarize: When you |
93 not generate pixel content faster than the Window Server can display |
94 want to ensure that every single frame is shown on the screen, call <codeph>Finish()</codeph> after each <codeph>EndRedraw()</codeph> call.</p> <p><b>Delay of execution </b> </p> <p>After you migrate non-redraw |
94 it on the screen. </p><p>To summarize: When you want to ensure that |
95 drawing to redraw drawing, the execution of the drawing operations |
95 every single frame is shown on the screen, call <codeph>Finish()</codeph> after each <codeph>EndRedraw()</codeph> call.</p> <p><b>Delay of |
96 is deferred compared to previously. This means that if the arguments |
96 execution </b> </p> <p>After you migrate non-redraw drawing to redraw |
97 of the drawing operations result in a panic, the panic also appears |
97 drawing, the execution of the drawing operations is deferred compared |
98 later than before. </p> <p><b>CRemoteGc usage </b> </p> <p>Device |
98 to previously. This means that if the arguments of the drawing operations |
99 creators can use <xref href="GUID-9965F9F1-ACEE-398C-BDAB-B3D5D61D4EBE.dita"><apiname>CRemoteGc</apiname></xref> to create a data buffer |
99 result in a panic, the panic also appears later than before. </p> <p><b>CRemoteGc usage </b> </p> <p>Device creators can use <xref href="GUID-9965F9F1-ACEE-398C-BDAB-B3D5D61D4EBE.dita"><apiname>CRemoteGc</apiname></xref> to create a data buffer containing a series of |
100 containing a series of drawing operations. These can then be executed |
100 drawing operations. These can then be executed to display the drawing |
101 to display the drawing on the screen by using <xref href="GUID-B25363C2-8757-36D4-93D2-769CDA1BDF86.dita#GUID-B25363C2-8757-36D4-93D2-769CDA1BDF86/GUID-35C68602-7684-3A1C-ADA2-9C8822E18DE0"><apiname>CCommandBuffer::Play()</apiname></xref>. </p> <p>For example, consider a weather program that has one sub-system |
101 on the screen by using <xref href="GUID-B25363C2-8757-36D4-93D2-769CDA1BDF86.dita#GUID-B25363C2-8757-36D4-93D2-769CDA1BDF86/GUID-35C68602-7684-3A1C-ADA2-9C8822E18DE0"><apiname>CCommandBuffer::Play()</apiname></xref>. </p> <p>For example, consider a weather program that has one sub-system |
102 responsible for deciding the drawing operations that comprise a weather |
102 responsible for deciding the drawing operations that comprise a weather |
103 symbol and another sub-system that places weather symbols at different |
103 symbol and another sub-system that places weather symbols at different |
104 locations on the screen. Here we potentially have a Cloud symbol buffer |
104 locations on the screen. Here we potentially have a Cloud symbol buffer |
105 created once and played many times. </p> <p>The points to note are: </p> <ul> |
105 created once and played many times. </p> <p>The points to note are: </p> <ul> |
106 <li id="GUID-A8DCB4C4-9D80-5F0F-A894-512A432A9E11"><p>Any <codeph>BeginRedraw()</codeph> and <codeph>EndRedraw()</codeph> commands |
106 <li id="GUID-A8DCB4C4-9D80-5F0F-A894-512A432A9E11"><p>Any <codeph>BeginRedraw()</codeph> and <codeph>EndRedraw()</codeph> commands |