Index

D-Type Helper Library For Platform Independent Window Display

Overview

D-Type's helper library for platform independent window display (also known as dtwindow) makes is it easy to write portable windowed applications capable of displaying D-Type's memory (off-screen) 32-bpp RGB surfaces. These applications are written using a single source code base and, when compiled, run virtually identically on Windows, Linux and Macintosh. In the future support for additional platforms and memory surface formats might be added.

The dtwindow library is written in C++ and features a C++ based public API (Application Programming Interface). There are currently three implementations: the Windows implementation (intended for use on Microsoft Windows), the Unix implementation (intended for use on Linux and Mac OS X under X11) and the native macOS implementation (Cocoa). All three implementations have the same public interface. This is what makes it possible to write portable windowed applications using a single source code base.

The library consists of two classes: CDTDisplay and CDTWindow. Both are declared in dtwindow.h. Their public interface looks as follows:

CDTDisplay

class CDTDisplay
{
public: // Constructors and destructors  

    CDTDisplay(DT_ULONG flags);
    virtual ~CDTDisplay();

public: // Public methods  

    void EventLoop();
};

CDTWindow

class CDTWindow
{
public: // Constructors and destructors  

    CDTWindow(CDTDisplay* display);
    CDTWindow(CDTDisplay* display, const DT_CHAR* title, DT_SLONG w, DT_SLONG h, DT_ULONG flags);
    virtual ~CDTWindow();

public: // Public methods  

    DT_SWORD Open(const DT_CHAR* title, DT_SLONG w, DT_SLONG h, DT_ULONG flags);
    void Close();

    DT_SLONG GetW();
    DT_SLONG GetH();
    DT_SLONG GetStatus();

    DT_SWORD SetPixels(void* pixels, DT_ULONG flags);
    DT_SWORD Refresh(DT_SLONG x, DT_SLONG y, DT_SLONG w, DT_SLONG h, DT_ULONG flags);
    DT_SWORD Modify(DT_ULONG flags);

protected: // Event-driven callbacks  

    virtual void Event_Resize(DT_SLONG w, DT_SLONG h) {}
    virtual void Event_KeyDown(DT_SLONG key) {}
    virtual void Event_KeyUp(DT_SLONG key) {}
    virtual void Event_MouseButtonDown(DT_SLONG button, DT_SLONG x, DT_SLONG y) {}
    virtual void Event_MouseMove(DT_SLONG x, DT_SLONG y) {}
    virtual void Event_MouseButtonUp(DT_SLONG button, DT_SLONG x, DT_SLONG y) {}
};

The CDTDisplay class represents a display (i.e. a monitor or similar output device) on which your window(s) will be displayed. Your application only needs to instantiate this class and call its EventLoop method when it is ready to process window messages.

The CDTWindow class represents a window and is more complex. After instantiating this class, you typically do the following:

  1. Call its Open method to open the window. Note that CDTWindow's default constructor does not automatically open your window. You must do this explicitly by calling its Open method (or, alternatively, you can instantiate CDTWindow using its alternative constructor which opens the window). Regardless of the method you choose to open your window, you must specify its title, initial width and height (in pixels) and, optionally, some extra flags (e.g. to indicate if your window should be resizable). Your window's width and height will match your 32-bpp RGB surface's dimensions.

  2. Call its SetPixels method to attach to your window a memory buffer that stores your surface's pixels. As soon as this is done, your window will refresh and display your surface's pixels.

    The pixels must be stored in D-Type's 32 RGB format. This format uses four bytes per pixel: the first three bytes represent the B, G and R color components, while the last byte is unused. Pixels in this surface format can be generated, for example, by calling the dtOutputSetAsMDC function and setting its format parameter to 32 and subformat parameter to 0.

Once the above two steps are completed, you have a window on the screen that shows your 32-bpp RGB surface. Now your application is ready to process window messages that may be generated by or sent to your window. As mentioned earlier, this is done by calling the EventLoop method of your CDTDisplay class. Any captured window messages are then processed by your application using the available event-driven callbacks. There are currently 6 such callbacks: Event_Resize, Event_KeyDown, Event_KeyUp, Event_MouseButtonDown, Event_MouseMove and Event_MouseButtonUp. These are simply standard C++ virtual functions that your application can override in your own class in order to process an event. Their intended use is as follows:

In a typical application, you will have only one CDTDisplay object and one or more CDTWindow objects. All the CDTWindow objects will be associated with the same CDTDisplay object.

 

Index