                         ===========================
                         = primary surface example =
                         ===========================


Overview
--------

This example explicitly sets up a 32bit ARGB8888 video mode, then accesses
the primary surface and writes directly to it. The primary surface is the
video surface that is currently being displayed on screen - by writing to the
primary surface you write directly to the screen. The only drawback is that
the nice virtual 32bit mode advantage is lost. This example will only work
when an ARGB8888 video mode is available.




Accessing the primary surface
-----------------------------

>    // get primary surface (display surface)
>    Surface *primary=ptc.GetPrimary();
>    if (!primary || !primary->ok())
>    {
>        ptc.Close();
>        cout << "could not access primary surface\n";
>        return 0;
>    }

The code above attempts to get a pointer to the primary surface. It is very
careful to check that the primary surface is a) non-NULL b) valid. The reason
for this is that not all interfaces are capable of direct screen access (for
example the Win32 GDI interface).  

Take care of the primary surface pointer you retrieve from the PTC object.
Don't assume that it will remain valid forever - it will be deleted when the
interface changes modes (on a PTC::Init, PTC::SetMode and PTC::Close). In all
other situations PTC guarantees that the primary surface will remain valid
for you - this is why primary.cpp can grab the primary surface once and then
use it for the rest of the program safely.

Delete or Surface::Free the primary surface pointer at your own risk. *BOOM*
