mirror of
https://gitlab.freedesktop.org/mesa/mesa.git
synced 2026-02-02 02:20:25 +01:00
Add the missing detailed documentation bits on miniglx.c and xf86drm.c.
Several updates and fixes to the documentation.
This commit is contained in:
Jose Fonseca
parent
cf119744c3
commit
4fb1eb7be2
3 changed files with 152 additions and 41 deletions
|
|
@ -22,7 +22,7 @@
|
|||
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
*/
|
||||
|
||||
/* $Id: miniglx.c,v 1.1.4.38 2003/01/18 12:25:57 keithw Exp $ */
|
||||
/* $Id: miniglx.c,v 1.1.4.39 2003/01/19 12:18:08 jrfonseca Exp $ */
|
||||
|
||||
|
||||
/**
|
||||
|
|
@ -132,14 +132,26 @@ static void SwitchDisplay(int i_signal)
|
|||
}
|
||||
|
||||
/**********************************************************************/
|
||||
/** \name FBdev functions */
|
||||
/** \name Framebuffer device functions */
|
||||
/**********************************************************************/
|
||||
/*@{*/
|
||||
|
||||
/**
|
||||
* \brief Do first part of setting up fbdev.
|
||||
* \brief Do the first part of setting up the framebuffer device.
|
||||
*
|
||||
* \param dpy the display handle.
|
||||
*
|
||||
* \return GL_TRUE on success, or GL_FALSE on failure.
|
||||
*
|
||||
* \sa This is called during XOpenDisplay().
|
||||
*
|
||||
* \internal
|
||||
* Gets the VT number, opens the respective console TTY device. Saves its state
|
||||
* to restore when exiting and goes into graphics mode.
|
||||
*
|
||||
* Opens the framebuffer device and make a copy of the original variable screen
|
||||
* information and gets the fixed screen information. Maps the framebuffer and
|
||||
* MMIO region into the process address space.
|
||||
*/
|
||||
static GLboolean
|
||||
OpenFBDev( Display *dpy )
|
||||
|
|
@ -154,7 +166,7 @@ OpenFBDev( Display *dpy )
|
|||
return GL_FALSE;
|
||||
}
|
||||
|
||||
/* open /dev/tty0 and get the vt number */
|
||||
/* open /dev/tty0 and get the VT number */
|
||||
if ((fd = open("/dev/tty0", O_WRONLY, 0)) < 0) {
|
||||
fprintf(stderr, "error opening /dev/tty0\n");
|
||||
return GL_FALSE;
|
||||
|
|
@ -305,9 +317,24 @@ OpenFBDev( Display *dpy )
|
|||
|
||||
|
||||
/**
|
||||
* \brief Setup up our desired fbdev framebuffer mode.
|
||||
* \brief Setup up the desired framebuffer device mode.
|
||||
*
|
||||
* \param dpy the display handle.
|
||||
* \param win the window handle, from which the screen size is taken.
|
||||
*
|
||||
* \return GL_TRUE on success, or GL_FALSE on failure.
|
||||
*
|
||||
* \sa This is called during XCreateWindow().
|
||||
*
|
||||
* \internal
|
||||
* Bumps the size of the window the the next supported mode. Sets the variable
|
||||
* screen information according to the desired mode and asks the driver to
|
||||
* validate the mode. Certifies that a TrueColor visual is used from the
|
||||
* updated fixed screen information.
|
||||
*
|
||||
* Attempts to draws a bitmap with a gradient.
|
||||
*
|
||||
* \todo Timings are hardcoded in the code for a set of supported modes.
|
||||
*/
|
||||
static GLboolean
|
||||
SetupFBDev( Display *dpy, Window win )
|
||||
|
|
@ -505,10 +532,18 @@ SetupFBDev( Display *dpy, Window win )
|
|||
|
||||
|
||||
/**
|
||||
* \brief Restore framebuffer to state it was in before we started
|
||||
* (undoes work done in SetupFBDev).
|
||||
* \brief Restore the framebuffer device to state it was in before we started
|
||||
*
|
||||
* Undoes the work done by SetupFBDev().
|
||||
*
|
||||
* \param dpy the display handle.
|
||||
*
|
||||
* \return GL_TRUE on success, or GL_FALSE on failure.
|
||||
*
|
||||
* \sa Called from XDestroyWindow().
|
||||
*
|
||||
* \internal
|
||||
* Restores the original variable screen info.
|
||||
*/
|
||||
static GLboolean
|
||||
RestoreFBDev( Display *dpy )
|
||||
|
|
@ -526,9 +561,15 @@ RestoreFBDev( Display *dpy )
|
|||
|
||||
|
||||
/**
|
||||
* \brief Close FBDev.
|
||||
* \brief Close the framebuffer device.
|
||||
*
|
||||
* \param dpy the display handle.
|
||||
*
|
||||
* \sa Called from XCloseDisplay().
|
||||
*
|
||||
* \internal
|
||||
* Unmaps the framebuffer and MMIO region. Restores the text mode and the
|
||||
* original virtual terminal. Closes the console and framebuffer devices.
|
||||
*/
|
||||
static void
|
||||
CloseFBDev( Display *dpy )
|
||||
|
|
@ -565,6 +606,17 @@ CloseFBDev( Display *dpy )
|
|||
/**********************************************************************/
|
||||
/*@{*/
|
||||
|
||||
/**
|
||||
* \brief Find the DRI screen dependent methods associated with the display.
|
||||
*
|
||||
* \param dpy a display handle, as returned by XOpenDisplay().
|
||||
* \param scrn the screen number. Not referenced.
|
||||
*
|
||||
* \returns a pointer to a __DRIscreenRec structure.
|
||||
*
|
||||
* \internal
|
||||
* Returns the MiniGLXDisplayRec::driScreen attribute.
|
||||
*/
|
||||
__DRIscreen *
|
||||
__glXFindDRIScreen(Display *dpy, int scrn)
|
||||
{
|
||||
|
|
@ -572,6 +624,16 @@ __glXFindDRIScreen(Display *dpy, int scrn)
|
|||
return &(dpy->driScreen);
|
||||
}
|
||||
|
||||
/**
|
||||
* \brief Validate a drawable.
|
||||
*
|
||||
* \param dpy a display handle, as returned by XOpenDisplay().
|
||||
* \param draw drawable to validate.
|
||||
*
|
||||
* \internal
|
||||
* Since Mini GLX only supports one window, compares the specified drawable with
|
||||
* the MiniGLXDisplayRec::TheWindow attribute.
|
||||
*/
|
||||
Bool
|
||||
__glXWindowExists(Display *dpy, GLXDrawable draw)
|
||||
{
|
||||
|
|
@ -581,6 +643,14 @@ __glXWindowExists(Display *dpy, GLXDrawable draw)
|
|||
return False;
|
||||
}
|
||||
|
||||
/**
|
||||
* \brief Get current thread ID.
|
||||
*
|
||||
* \return thread ID.
|
||||
*
|
||||
* \internal
|
||||
* Always returns 0.
|
||||
*/
|
||||
unsigned long
|
||||
_glthread_GetID(void)
|
||||
{
|
||||
|
|
@ -638,9 +708,19 @@ static int get_chipset_from_busid( Display *dpy )
|
|||
/**
|
||||
* \brief Read settings from a configuration file.
|
||||
*
|
||||
* \return non-zeros on success, zero otherwise.
|
||||
* The configuration file is usually "/etc/minigilx.conf", but can be overriden
|
||||
* with the MINIGLX_CONF environment variable.
|
||||
*
|
||||
* The format consists in \code option = value \endcode lines. The option names
|
||||
* corresponds to the fields in MiniGLXDisplayRec.
|
||||
*
|
||||
* \param dpy the display handle as.
|
||||
*
|
||||
* \return non-zero on success, zero otherwise.
|
||||
*
|
||||
* \internal
|
||||
* Sets some defaults. Opens and parses the the Mini GLX configuration file and
|
||||
* fills in the MiniGLXDisplayRec field that corresponds for each option.
|
||||
*/
|
||||
static int __read_config_file( Display *dpy )
|
||||
{
|
||||
|
|
@ -749,8 +829,18 @@ static int __read_config_file( Display *dpy )
|
|||
* the graphics system, NULL otherwise.
|
||||
*
|
||||
* \internal
|
||||
* Allocates a MiniGLXDisplayRec structure and fills in with information from a
|
||||
* configuration file.
|
||||
*
|
||||
* \attention This function not stable.
|
||||
* Opens and initializes the fbdev device.
|
||||
*
|
||||
* Loads the DRI driver and pulls in MiniGLX-specific hooks into a
|
||||
* MiniGLXDriverRec structure, and the standard DRI \e __driCreateScreen hook.
|
||||
* Asks the driver for a list of supported visuals. Performs the client-side
|
||||
* initialization - has to be done this here as it depends on the chosen
|
||||
* display resolution, which in this window system depends on the size of the
|
||||
* \e window created. Also setups the callbacks in the screen private
|
||||
* information.
|
||||
*/
|
||||
Display *
|
||||
XOpenDisplay( const char *display_name )
|
||||
|
|
@ -834,7 +924,7 @@ XOpenDisplay( const char *display_name )
|
|||
* Clearly there is a limit of one on the number of windows in
|
||||
* existence at any time.
|
||||
*
|
||||
* Need to shut down drm and free dri data in XDestroyWindow, too.
|
||||
* Need to shut down DRM and free DRI data in XDestroyWindow(), too.
|
||||
*/
|
||||
dpy->driScreen.private = (*dpy->createScreen)(dpy, 0,
|
||||
&(dpy->driScreen),
|
||||
|
|
@ -867,9 +957,12 @@ XOpenDisplay( const char *display_name )
|
|||
*
|
||||
* \internal
|
||||
* This function frees the \p display structure, after calling the
|
||||
* __DRIscreenRec::destroyScreen method pointed by MiniGLXDisplayRec::driScreen
|
||||
* attribute of \p display, closing the dynamic library handle
|
||||
* MiniGLXDisplayRec::dlHandle and calling CleanupFBDev() to close the fbdev.
|
||||
* __DRIscreenRec::destroyScreen method pointed by
|
||||
* MiniGLXDisplayRec::driScreen attribute of \p display, closing the dynamic
|
||||
* library handle MiniGLXDisplayRec::dlHandle and calling CloseFBDev() to
|
||||
* close the fbdev.
|
||||
*
|
||||
* Also destroy the window and halt the framebuffer device.
|
||||
*/
|
||||
void
|
||||
XCloseDisplay( Display *display )
|
||||
|
|
@ -901,7 +994,7 @@ XCloseDisplay( Display *display )
|
|||
/**
|
||||
* \brief Window creation.
|
||||
*
|
||||
* \param display a #Display pointer, as returned by XOpenDisplay().
|
||||
* \param display a display handle, as returned by XOpenDisplay().
|
||||
* \param parent the parent window for the new window. For Mini GLX this should
|
||||
* be
|
||||
* \code RootWindow(display, 0) \endcode
|
||||
|
|
@ -911,8 +1004,8 @@ XCloseDisplay( Display *display )
|
|||
* screen width such as 1024 or 1280.
|
||||
* \param height the window height. For Mini GLX, this specifies the desired
|
||||
* screen height such as 768 or 1024.
|
||||
* \param border_width This parameter should be zero.
|
||||
* \param depth the window pixel depth. For Mini GLX this should be the depth
|
||||
* \param border_width the border sith. For Mini GLX, it should be zero.
|
||||
* \param depth the window pixel depth. For Mini GLX, this should be the depth
|
||||
* found in the #XVisualInfo object returned by glXChooseVisual()
|
||||
* \param class the window class. For Mini GLX this value should be
|
||||
* #InputOutput.
|
||||
|
|
@ -1103,8 +1196,8 @@ XMapWindow( Display *display, Window w )
|
|||
* \return the color map.
|
||||
*
|
||||
* \internal
|
||||
* This function is only provided to ease porting. Practically a no-op.
|
||||
* Returns a pointer to an one-byte chunk of memory allocated with #MALLOC.
|
||||
* This function is only provided to ease porting. Practically a no-op -
|
||||
* returns a pointer to a dinamically allocated chunk of memory (one byte).
|
||||
*/
|
||||
Colormap
|
||||
XCreateColormap( Display *dpy, Window w, Visual *visual, int alloc )
|
||||
|
|
@ -1436,7 +1529,8 @@ glXChooseVisual( Display *dpy, int screen, int *attribList )
|
|||
* invalid.
|
||||
*
|
||||
* \internal
|
||||
* Returns the appropriate attribute of ::__GLXvisualConfig pointed by MiniGLXVisualRec::glxConfig of XVisualInfo::visual.
|
||||
* Returns the appropriate attribute of ::__GLXvisualConfig pointed by
|
||||
* MiniGLXVisualRec::glxConfig of XVisualInfo::visual.
|
||||
*
|
||||
* \sa datatypes.
|
||||
*/
|
||||
|
|
@ -1588,7 +1682,7 @@ glXDestroyContext( Display *dpy, GLXContext ctx )
|
|||
* __DRIcontextRec::unbindContext and binds the new one via
|
||||
* __DRIcontextRec::bindContext.
|
||||
*
|
||||
* If /p drawable is zero it unbinds the GLX context by calling
|
||||
* If \p drawable is zero it unbinds the GLX context by calling
|
||||
* __DRIcontextRec::bindContext with zeros.
|
||||
*/
|
||||
Bool
|
||||
|
|
|
|||
|
|
@ -52,9 +52,9 @@ typedef struct __GLXvisualConfigRec {
|
|||
} __GLXvisualConfig;
|
||||
|
||||
|
||||
typedef struct __DRIscreenRec __DRIscreen;
|
||||
typedef struct __DRIcontextRec __DRIcontext;
|
||||
typedef struct __DRIdrawableRec __DRIdrawable;
|
||||
typedef struct __DRIscreenRec __DRIscreen; /**< \copydoc __DRIscreenRec */
|
||||
typedef struct __DRIcontextRec __DRIcontext; /**< \copydoc __DRIcontextRec */
|
||||
typedef struct __DRIdrawableRec __DRIdrawable; /**< \copydoc __DRIdrawableRec */
|
||||
|
||||
|
||||
typedef void *(*CreateScreenFunc)(Display *dpy, int scrn, __DRIscreen *psc,
|
||||
|
|
@ -65,7 +65,6 @@ typedef void *(*CreateScreenFunc)(Display *dpy, int scrn, __DRIscreen *psc,
|
|||
/**
|
||||
* \brief Screen dependent methods.
|
||||
*
|
||||
* \internal
|
||||
* This structure is initialized during the MiniGLXDisplayRec::createScreen
|
||||
* call.
|
||||
*/
|
||||
|
|
@ -113,7 +112,6 @@ struct __DRIscreenRec {
|
|||
/**
|
||||
* \brief Context dependent methods.
|
||||
*
|
||||
* \internal
|
||||
* This structure is initialized during the __DRIscreenRec::createContext call.
|
||||
*/
|
||||
struct __DRIcontextRec {
|
||||
|
|
@ -149,7 +147,6 @@ struct __DRIcontextRec {
|
|||
/**
|
||||
* \brief Drawable dependent methods.
|
||||
*
|
||||
* \internal
|
||||
* This structure is initialized during the __DRIscreenRec::createDrawable call.
|
||||
*
|
||||
* __DRIscreenRec::createDrawable is not called by libGL at this time. It's
|
||||
|
|
@ -178,17 +175,31 @@ struct __DRIdrawableRec {
|
|||
/**
|
||||
* \brief Interface to driver.
|
||||
*
|
||||
* \internal
|
||||
* This structure is retrieved from the loadable driver by dlsym
|
||||
* "__driMiniGLXDriver" to access the miniglx-specific hardware
|
||||
* This structure is retrieved from the loadable driver by the \e
|
||||
* __driMiniGLXDriver symbol to access the MiniGLX-specific hardware
|
||||
* initalization and takedown routines.
|
||||
*/
|
||||
struct MiniGLXDriverRec {
|
||||
/**
|
||||
* \brief Get the list of supported configs.
|
||||
*/
|
||||
int (*initScreenConfigs)( struct MiniGLXDisplayRec *dpy,
|
||||
int *numConfigs, __GLXvisualConfig **configs );
|
||||
/**
|
||||
* \brief Validate the framebuffer device mode
|
||||
*/
|
||||
int (*validateMode)( struct MiniGLXDisplayRec *dpy );
|
||||
|
||||
int (*postValidateMode)( struct MiniGLXDisplayRec *dpy );
|
||||
|
||||
/**
|
||||
* \brief Initialize the framebuffer device.
|
||||
*/
|
||||
int (*initFBDev)( struct MiniGLXDisplayRec *dpy );
|
||||
|
||||
/**
|
||||
* \brief Halt the framebuffer device.
|
||||
*/
|
||||
void (*haltFBDev)( struct MiniGLXDisplayRec *dpy );
|
||||
};
|
||||
|
||||
|
|
@ -196,14 +207,13 @@ struct MiniGLXDriverRec {
|
|||
|
||||
/**
|
||||
* \brief Supported pixel formats.
|
||||
* \enum pixelFormat
|
||||
*/
|
||||
enum PixelFormat {
|
||||
PF_B8G8R8, /**< 24-bit BGR */
|
||||
PF_B8G8R8A8, /**< 32-bit BGRA */
|
||||
PF_B5G6R5, /**< 16-bit BGR */
|
||||
PF_B5G5R5, /**< 15-bit BGR */
|
||||
PF_CI8 /**< 8-bit color index */
|
||||
PF_B8G8R8, /**< \brief 24-bit BGR */
|
||||
PF_B8G8R8A8, /**< \brief 32-bit BGRA */
|
||||
PF_B5G6R5, /**< \brief 16-bit BGR */
|
||||
PF_B5G5R5, /**< \brief 15-bit BGR */
|
||||
PF_CI8 /**< \brief 8-bit color index */
|
||||
};
|
||||
|
||||
|
||||
|
|
@ -288,8 +298,8 @@ struct MiniGLXDisplayRec {
|
|||
* \name From __GLXdisplayPrivate
|
||||
*/
|
||||
/*@{*/
|
||||
CreateScreenFunc createScreen;
|
||||
__DRIscreen driScreen;
|
||||
CreateScreenFunc createScreen; /**< \brief \e __driCreateScreen hook */
|
||||
__DRIscreen driScreen; /**< \brief Screen dependent methods */
|
||||
void *dlHandle; /**<
|
||||
* \brief handle to the client dynamic
|
||||
* library
|
||||
|
|
@ -306,8 +316,7 @@ struct MiniGLXDisplayRec {
|
|||
/**
|
||||
* \name Configuration details
|
||||
*
|
||||
* \todo Will come from a file, hardcoded for now
|
||||
* \todo Can we get chipset from fbdev? -- kindof, see fbdevhw.c
|
||||
* They are read from a configuration file by __read_config_file().
|
||||
*/
|
||||
/*@{*/
|
||||
const char *fbdevDevice;
|
||||
|
|
|
|||
|
|
@ -1441,6 +1441,8 @@ int drmGetInterruptFromBusID(int fd, int busnum, int devnum, int funcnum)
|
|||
* \return zero on sucess, or a negative value on failure.
|
||||
*
|
||||
* \internal
|
||||
* Issues a ioctl given by
|
||||
* \code DRM_COMMAND_BASE + drmCommandIndex \endcode.
|
||||
*/
|
||||
int drmCommandNone(int fd, unsigned long drmCommandIndex)
|
||||
{
|
||||
|
|
@ -1465,8 +1467,10 @@ int drmCommandNone(int fd, unsigned long drmCommandIndex)
|
|||
* \param size size of the data to be read.
|
||||
*
|
||||
* \return zero on sucess, or a negative value on failure.
|
||||
*
|
||||
*
|
||||
* \internal
|
||||
* Issues a read ioctl given by
|
||||
* \code DRM_COMMAND_BASE + drmCommandIndex \endcode.
|
||||
*/
|
||||
int drmCommandRead(int fd, unsigned long drmCommandIndex,
|
||||
void *data, unsigned long size )
|
||||
|
|
@ -1494,6 +1498,8 @@ int drmCommandRead(int fd, unsigned long drmCommandIndex,
|
|||
* \return zero on sucess, or a negative value on failure.
|
||||
*
|
||||
* \internal
|
||||
* Issues a write ioctl given by
|
||||
* \code DRM_COMMAND_BASE + drmCommandIndex \endcode.
|
||||
*/
|
||||
int drmCommandWrite(int fd, unsigned long drmCommandIndex,
|
||||
void *data, unsigned long size )
|
||||
|
|
@ -1521,6 +1527,8 @@ int drmCommandWrite(int fd, unsigned long drmCommandIndex,
|
|||
* \return zero on sucess, or a negative value on failure.
|
||||
*
|
||||
* \internal
|
||||
* Issues a read-write ioctl given by
|
||||
* \code DRM_COMMAND_BASE + drmCommandIndex \endcode.
|
||||
*/
|
||||
int drmCommandWriteRead(int fd, unsigned long drmCommandIndex,
|
||||
void *data, unsigned long size )
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue