BDirectWindow

Constructor and Destructor

BDirectWindow()

BDirectWindow::BDirectWindow(BRect frame, const char *title, window_type type, uint32 flags, uint32 workspace = B_CURRENT_WORKSPACE)
BDirectWindow::BDirectWindow(BRect frame, const char *title, window_look look, window_feel feel, uint32 flags, uint32 workspace = B_CURRENT_WORKSPACE)

Creates and returns a new BDirectWindow object. This is functionally equivalent to the BWindow constructor, except the resulting BDirectWindow supports direct window operations.

You will probably want to set up a flag to keep track of whether or not the direct window’s connection to the screen is viable. In the constructor, you should set this flag (let’s call it fConnectionDisabled ) to false, which indicates to both DirectConnected() and your drawing thread that the window is not in the process of being deconstructed. The destructor would then set this flag to true before terminating the connection to avoid the unlikely possibility of the connection trying to restart while the BDirectWindow is being dismantled.

You’ll also need other flags or semaphores (or benaphores) to manage the interaction between the BDirectWindow and your drawing thread.

See the sample code in “Using a Direct Window” for an example.

~BDirectWindow()

BDirectWindow::~BDirectWindow()

Frees all memory the BDirectWindow object allocated for itself. You should never delete a BDirectWindow object; call its Quit() function instead (inherited from BWindow).

Your BDirectWindow destructor should begin by setting the fConnectionDisabled flag to true, to prevent DirectConnected() from attempting to reconnect to the direct window while it’s being deconstructed.

Then you should call Hide() and Sync() to force the direct window to disconnect direct access (both inherited from BWindow):

MyDirectWindow::~BDirectWindow
{
   fConnectionDisabled = true;
   Hide();
   Sync();
   /* complete usual destruction here */
}

Hook Functions

DirectConnected()

virtual void BDirectWindow::DirectConnected(direct_buffer_info *info)

This hook function is the core of BDirectWindow. Your application should override this function to learn about the state of the graphics display onto which you’re drawing, as well as to be informed of any changes that occur.

This function is also called to suspend and resume your direct access privileges.

Your code in this function should be as short as possible, because what your DirectConnected() function does can affect the performance of the entire system. DirectConnected() should only handle the immediate task of dealing with changes in the direct drawing context, and shouldn’t normally do any actual drawing—that’s what your drawing thread is for.

If you have drawing that absolutely has to be done before you can safely return control to the application server (see the note below), you may do so, but your code should do the absolute minimum drawing necessary and leave everything else to the drawing thread.

Note

DirectConnected() should only return when it can guarantee to the application server that the request specified by info will be strictly obeyed.

The structure pointed to by info goes away after DirectConnected() returns, so you should cache the information that interests you.

Warning

If your DirectConnected() implementation doesn’t handle a request within three seconds, the Application Server will intentionally crash your application under the assumption that it’s deadlocked. Be sure to handle requests as quickly as possible.

See “Getting Connected (and Staying That Way)” for more information about the direct_buffer_info structure.

Member Functions

GetClippingRegion()

status_t BDirectWindow::GetClippingRegion(BRegion *region, BPoint *origin = NULL) const

Sets the specified region to match the current clipping region of the direct window. If origin is specified, each point in the region is offset by the origin, resulting in a BRegion that’s localized to your application’s vision of where in space the origin is (relative to the origin of the screen’s frame buffer).

Although the direct_buffer_info structure contains the clipping region of a direct window, it’s not in standard BRegion form. This function is provided so you can obtain a standard BRegion if you need one.

Warning

The GetClippingRegion() function can only be called from the DirectConnected() function; calling it from outside DirectConnected() will return invalid results.

If you need to cache the clipping region of your window and need a BRegion for clipping purposes, you could use the following code inside your DirectConnected() function:

BRegion rgn;
GetClippingRegion(&rgn);

This serves a double purpose: it obtains the clipping region in BRegion form, and it returns a copy of the region that you can maintain locally. However, it may be more efficient to copy the clipping region by hand, since the clipping rectangle list used by BDirectWindow uses integer numbers, while BRegion uses floating-point.

Return Code	Description
B_OK.	The clipping region was successfully returned.
B_ERROR.	An error occurred while trying to obtain the clipping region.

IsFullScreen(), SetFullScreen()

bool BDirectWindow::IsFullScreen() const

status_t BDirectWindow::SetFullScreen(bool enable)

IsFullScreen() returns true if the direct window is in full-screen exclusive mode, or false if it’s in window mode.

The value returned by IsFullScreen() is indeterminate if a call to SetFullScreen() is in progress—if this is the case, you shouldn’t rely on the resulting value. Instead, it would be safer to maintain a state setting of your own and use that value.

SetFullScreen() enables full-screen exclusive mode if the enable flag is true. To switch to window mode, pass false. The SupportsWindowMode() function can be used to determine whether or not the video card is capable of supporting window mode. See “Window Mode vs. Full Screen Mode” for a detailed explanation of the differences between these modes.

When your window is in full screen mode, it will always have the focus, and no other window can come in front of it.

SetFullScreen() can return any of the following result codes.

Return Code	Description
B_OK.	The mode was successfully changed.
B_ERROR.	An error occurred while trying to switch between full screen and window modes (for example, another window may already be in full-screen exclusive mode in the same workspace).

SupportsWindowMode()

static bool BDirectWindow::SupportsWindowMode(screen_id id = B_MAIN_SCREEN_ID)

Returns true if the specified screen supports window mode; if you require the ability to directly access the frame buffer of a window (rather than occupying the whole screen), you should call this function to be sure that the graphics hardware in the computer running your application supports it. Because this is a static function, you don’t have to construct a BDirectWindow object to call it:

if (BDirectWindow::SupportsWindowMode()) {
   /* do stuff here */
}

In particular, window mode requires a graphics card with DMA support and a hardware cursor; older video cards may not be capable of supporting window mode.

If window mode isn’t supported, but you still select window mode, DirectConnected() will never be called (so you’ll never be authorized for direct frame buffer access).

Even if window mode isn’t supported, you can still use BDirectWindow objects for full-screen direct access to the frame buffer, but it’s recommended that you avoid direct video DMA or the use of parallel drawing threads that use both direct frame buffer access and BView calls (because it’s likely that such a graphics card won’t handle the parallel access and freeze the PCI bus—and that would be bad).