                          =========================
                          = ptc mode list example =
                          =========================


Overview
--------

This example creates an uninitialized PTC object "PTC ptc;" then queries
this object for a list of all available modes. The List<T> template is used
to return a list of MODE structures (see "iface.h" for the declaration of the
MODE struct, and see "list.h" the List and List::Iterator template classes).



Accessing mode lists
--------------------

There is one quirk to the PTC::GetModeList function - if you request a
mode list from an uninitialized PTC object (as we do here). You get a list of
ALL modes available with all available interfaces (i.e. IVga, IVesa, IDirectX
and so on...). If however, you call PTC::GetModeList _after_ you have
initialized the ptc object, you will get a mode list only for the current
interface.


For example, this code retrieves the mode list for all interfaces:

    PTC ptc;                       // uninitialized ptc object
    List<MODE> modelist;
    ptc.GetModeList(modelist);


and this code retrieves the list of modes for the current interface:

    PTC ptc(320,200,ARGB8888);     // interface is created here
    List<MODE> modelist;
    ptc.GetModeList(modelist);




PTC::Init vs. PTC::SetMode
--------------------------

A second similar quirk is the difference between PTC::Init and PTC::SetMode.
PTC::Init is basically a mirror of the PTC constructor functionality to allow
you do Close and Re-Init the object at will. Please note, that a PTC::Init
does not need to be preceded by a PTC::Close.

PTC::Init operates by trying ALL interfaces to set a specific mode, it only
gives up when there all interfaces have failed to set a mode. Init has the
side effect of TOTALLY nuking the interface also. All bound surfaces are lost
because the current interface is deleted before the new mode is set.

PTC::SetMode is a much nicer however - it operates on the current interface
and uses that to set a mode. It does not nuke the interface like Init does.
It is however limited in that the current interface cannot set a mode that
it doesn't support itself. For example, if you were currently in a VESA mode
(IVESA interface) Then any requests to set a fakemode would fail because
fakemodes are only available with the VGA interface (IVGA).


In summary, use PTC::SetMode to change modes *after* your initial PTC setup
where possible as they are faster and cause less trauma in general to your
surfaces :)

Use a PTC::Init only when you have to.




Mode lists in windowed displays
-------------------------------

Under platforms like win32, windowed output will be available. This is
indicated in the modelist with a single entry with xres,xres equal to the 
width of the display in pixels and output mode WINDOWED. This means that any
mode of output type "WINDOWED" should not be interpreted as a mode of exactly
"xres x yres" only (as with FULLSCREEN modes). In reality you can create any 
window size you like. The xres, yres information in the modelist is just a 
guide "this is the size of the display". Note that the xres,yres parms you 
pass to PTC ptc(xres,yres) describe the width and height of the window to be 
created.
