diff --git a/docs/user/Doxyfile b/docs/user/Doxyfile index b9f030f2610..49b772454dd 100644 --- a/docs/user/Doxyfile +++ b/docs/user/Doxyfile @@ -614,6 +614,7 @@ INPUT = . \ ../../headers/os/drivers/fs_interface.h \ ../../headers/os/drivers/USB3.h \ ../../headers/os/drivers/USB_spec.h \ + ../../headers/os/game \ ../../headers/os/interface \ ../../headers/os/locale \ ../../headers/os/media \ diff --git a/docs/user/game/DirectWindow.dox b/docs/user/game/DirectWindow.dox new file mode 100644 index 00000000000..7e08b435e87 --- /dev/null +++ b/docs/user/game/DirectWindow.dox @@ -0,0 +1,276 @@ +/* + * Copyright 2012 Haiku, Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * John Scipione, jscipione@gmail.com + * + * Corresponds to: + * src/kits/game/DirectWindow.cpp hrev45044 + * src/kits/game/DirectWindow.h hrev45044 + */ + + +/*! + \file DirectWindow.h + \brief Provides the DirectWindow class. +*/ + + +/*! + \enum direct_buffer_state + \brief Direct buffer state constants +*/ + + +/*! + \enum direct_driver_state + \brief Direct driver state constants +*/ + + +/*! + \struct direct_buffer_info + \brief Direct butter info struct +*/ + + +/*! + \var direct_buffer_info::buffer_state + State of the direct buffer access privileges. + It can have one of the following values: + - \c B_DIRECT_MODE_MASK + - \c B_DIRECT_START + - \c B_DIRECT_MODIFY + - \c B_DIRECT_STOP + - \c B_BUFFER_MOVED + - \c B_BUFFER_RESET + - \c B_BUFFER_RESIZED + - \c B_CLIPPING_MODIFIED +*/ + + +/*! + \var direct_buffer_info::driver_state + State of the graphics card on which your direct window is displayed. + There are two possible values: + - \c B_MODE_CHANGED The resolution or color depth has changed. + - \c B_DRIVER_CHANGED The window was moved onto another monitor. +*/ + + +/*! + \var direct_buffer_info::bits + Pointer to the frame buffer in your team's memory space. +*/ + + +/*! + \var direct_buffer_info::pci_bits + Pointer to the frame buffer in the PCI memory space. This value is + typically needed to control DMA. +*/ + +/*! + \var direct_buffer_info::bytes_per_row + Number of bytes used to represent a single row of pixels in the frame buffer. +*/ + + +/*! + \var direct_buffer_info::bits_per_pixel + number of bits actually used to store a single pixel, including reserved, + unused, or alpha channel bits. This value is usually a multiple of eight. +*/ + + +/*! + \var direct_buffer_info::pixel_format + The format used to encode a pixel as defined by the \c color_space type. +*/ + +/*! + \var direct_buffer_info::layout + Reserved for future use. +*/ + +/*! + \var direct_buffer_info::orientation + Reserved for future use. +*/ + +/*! + \var direct_buffer_info::_reserved[9] + Reserved for future use. +*/ + +/*! + \var direct_buffer_info::_dd_type_ + Reserved for future use. +*/ + +/*! + \var direct_buffer_info::_dd_token_ + Reserved for future use. +*/ + +/*! + \var direct_buffer_info::clip_list_count + Number of rectangles in \c clip_list. +*/ + +/*! + \var direct_buffer_info::window_bounds + Rectangle that defines the full content area of the window in screen + coordinates. +*/ + +/*! + \var direct_buffer_info::clip_bounds + Bounding rectangle of the visible part of the content area of the window + in screen coordinates. +*/ + + +/*! + \var direct_buffer_info::clip_list + List of rectangles that together define the visible region of the content + area of the window in screen coordinates. +*/ + + +/*! + \class DirectWindow + \ingroup game + \ingroup libbe + \brief Provides direct access to the video card graphics frame buffer. +*/ + + +/*! + \fn BDirectWindow::BDirectWindow(BRect frame, const char *title, + window_type type, uint32 flags, uint32 workspace) + \brief Creates and initializes a BDirectWindow. + + \param frame The initial frame coordinates of the window. + \param title Window title + \param type Window type (see BWindow) + \param flags Window flags (see BWindow) + \param workspace Workspace (see BWindow) +*/ + + +/*! + \fn BDirectWindow::BDirectWindow(BRect frame, const char *title, + window_look look, window_feel feel, uint32 flags, uint32 workspace) + \brief Creates and initializes a BDirectWindow. + + \param frame The initial frame coordinates of the window. + \param title Window title + \param look window look (see BWindow) + \param feel window feel (see BWindow) + \param flags window flags (see BWindow) + \param workspace workspace (see BWindow) +*/ + + +/*! + \fn BDirectWindow::~BDirectWindow() + \brief Destroys the BDirectWindow and frees all memory used by it. + + Do not delete a BDirectWindow object directly, call Quit() instead. + + Set the fConnectionDisabled flag to \c true to prevent DirectConnected() + from attempting to reconnect while it's being destroyed. + + next call Hide() and finally Sync() to force the direct window to + disconnect from direct access. +*/ + + +/*! + \fn BArchivable* BDirectWindow::Instantiate(BMessage *data) + \brief Instantiate window from message \a data. Not implemented. +*/ + + +/*! + \fn status_t BDirectWindow::Archive(BMessage *data, bool deep) const + \brief Archive window into message \a data. Not implemented. +*/ + + +/*! + \fn void BDirectWindow::DirectConnected(direct_buffer_info *info) + \brief hook function called when your application learns about the state + of the graphics display and changes occur. + + This is the heart of BDirectWindow. + + \param info The \c direct_buffer_info struct +*/ + + +/*! + \fn status_t BDirectWindow::GetClippingRegion(BRegion *region, + BPoint *origin) const + \brief Sets \a region to the current clipping region of the direct window. + + If \a origin is not \c NULL, the \a region is offset by \a origin. + + \warning GetClippingRegion() should only be called from within the + DirectConnected() method. If called outside GetClippingRegion() will + return \c B_ERROR. + + \param region The clipping region to fill out. + \param origin An origin to offset the region by. + + \returns A status code. + \retval B_OK Everything went as expected. + \retval B_BAD_VALUE \a region was NULL. + \retval B_ERROR Window not locked or not in DirectConnected() method. + \retval B_NO_MEMORY Not enough memory to fill \a region +*/ + + +/*! + \fn status_t BDirectWindow::SetFullScreen(bool enable) + \brief Enables or disables full-screen mode. + + The SupportsWindowMode() method determines whether or not the video card + is capable of supporting windowed mode. + + When the window is in full screen mode it will always have the focus and + no other window can be in front of it. + + \param enable \c true to enable fullscreen mode, \c false for windowed mode. + + \returns A status code. + \retval B_OK Everything went as expected. + \retval B_ERROR An error occurred while trying to switch between full screen + and windowed mode. + + \sa BDirectWindow::SupportsWindowMode() +*/ + + +/*! + \fn bool BDirectWindow::IsFullScreen() const + \brief Returns whether the window is in full-screen or windowed mode. + + \returns \c true if in full-screen mode, \c false if in windowed mode. +*/ + + +/*! + \fn static bool BDirectWindow::SupportsWindowMode(screen_id id) + \brief Returns whether or not the specified screen supports windowed mode. + + Because this is a static function you don't have to construct a + BDirectWindow object to call it. + + \param id The id of the screen you want to check, \c B_MAIN_SCREEN_ID by + default. + + \returns \c true if the screen support windowed mode, \c false otherwise. +*/