DSA Migration Guide

Always use a DSA session when using DSA

The main classes of the DSA framework are CDirectScreenAccess, RDirectScreenAccess and MDirectScreenAccess. Before drawing to the screen, the DSA application must create a DSA session; for example, by instantiating CDirectScreenAccess and calling CDirectScreenAccess::StartL(). This rule applies regardless of whether the application accesses the DSA framebuffer using CFbsBitGc, CFbsScreenDevice or gains a pointer directly through HAL.

Applications that fail to create a DSA session will not work. Applications that draw outside of an active period of DSA will not work. This is because all DSA rendering is directed into a virtual framebuffer and the Operating System uses the DSA session to determine when that framebuffer should be made visible.

The following example demonstrates requesting direct screen access:

voidCMyDSAEngine::StartDrawingL()
    {
    // Initialize DSA.
    TRAPD(dsaError,iDSA->StartL());
    if (dsaError==KErrNone)
        {
        // Get the graphics context for drawing.
        iGc=iDSA->Gc();

        // Get the region to draw to.
        iRegion=iDSA->DrawingRegion();

        // Set the clipping region to this region.
        iGc->SetClippingRegion(iRegion); 

        // Start generating timer events (the drawing is done in a timer callback).
        iPeriodicTimer=CPeriodic::NewL(CActive::EPriorityStandard);
        iPeriodicTimer->Start(0,KInterval,TCallBack(DrawNextFrame, this));
        iDrawing=ETrue;
        }
    }

Inform the Operating System after updating the DSA buffer

Applications can access the screen by writing to the video hardware framebuffer or by using CFbsScreenDevice. Regardless which of these methods you use, the application must inform the OS that the framebuffer has been updated in order for the DSA drawing to be pushed to the display.

Applications that fail to declare modifications to the framebuffer will not see their content correctly appear on-screen. This is because the OS uses event-driven updating to copy the contents of the DSA framebuffer into the display.

When writing to the video hardware frame buffer, force a screen update by creating a redraw event like this:

TRawEventredraw;
redraw.Set(TRawEvent::ERedraw);
UserSvr::AddEvent(redraw);

When using CFbsScreenDevice, force a screen update by calling one of the following:

void CFbsScreenDevice::Update();
void CFbsScreenDevice::Update(constTRegion &aRegion);

Do not mix DSA and non-DSA rendering

The application must not issue CWindowGc rendering to a window when DSA is active on that window. If both types of rendering are required, the application must ensure that they only happen in distinct periods demarcated by the DSA session.

Applications that interleave periods of DSA rendering with periods of standard indirect (CWindowGc) rendering, expecting to see each painted on top of the previous, will not work. This is because the OS now uses two separate framebuffers; one for DSA rendering and one for indirect rendering. Previous versions of the OS use a single framebuffer for both types of rendering.

Applications must be written to render the entire contents of their window using either DSA or indirect rendering at any one point of time.