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:
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.
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:
Event_Resize — This function will be called only if your window was opened as a resizable window. In this case your application will almost certainly want to process this event. The function's w and h parameters will indicate the new size of your window, in pixels. You can then use this information to change the dimensions of your memory surface, redraw the pixels and refresh the window.
Event_KeyDown — This function will be called when a user presses a key on the keyboard while interacting with your window. The function's key parameter will provide a platform independent code of the key that was pressed. If necessary, your application can then act accordingly.
Event_KeyUp — This function will be called when a user releases a key on the keyboard while interacting with your window. The function's key parameter will provide a platform independent code of the key that was released. If necessary, your application can then act accordingly.
Event_MouseButtonDown — This function will be called when a user presses a mouse button while the mouse pointer is inside your window. The function's button parameter will provide a platform independent code of the mouse button that was pressed, while the x and y parameters will provide the (x, y) coordinates of the mouse pointer at that moment. The (x, y) coordinates will be in pixels and relative to the origin of your window. If necessary, your application can then act accordingly.
Event_MouseMove — This function will be called when a user moves the mouse pointer inside your window. The function's x and y parameters will provide the (x, y) coordinates of the position to which the mouse pointer was moved. The (x, y) coordinates will be in pixels and relative to the origin of your window. If necessary, your application can then act accordingly.
Event_MouseButtonUp — This function will be called when a user releases a mouse button while the mouse pointer is inside your window. The function's button parameter will provide a platform independent code of the mouse button that was released, while the x and y parameters will provide the (x, y) coordinates of the mouse pointer at that moment. The (x, y) coordinates will be in pixels and relative to the origin of your window. If necessary, your application can then act accordingly.
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.