summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKeith Whitwell <keith@tungstengraphics.com>2003-04-28 13:21:10 +0000
committerKeith Whitwell <keith@tungstengraphics.com>2003-04-28 13:21:10 +0000
commit687e8a0c089df066d22c5fbdf8bd8d8a9cedc32a (patch)
tree3d46c7d42f6d47334907fc53c79292893c7d2350
parentc205240b389e6d629326c5a68389481e13e6a77d (diff)
Partial documentation of this file.
-rw-r--r--src/miniglx/miniglx_events.c162
1 files changed, 129 insertions, 33 deletions
diff --git a/src/miniglx/miniglx_events.c b/src/miniglx/miniglx_events.c
index b78d2ae966e..7d63c607c25 100644
--- a/src/miniglx/miniglx_events.c
+++ b/src/miniglx/miniglx_events.c
@@ -22,7 +22,7 @@
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
-/* $Id: miniglx_events.c,v 1.1.2.10 2003/04/28 11:30:14 keithw Exp $ */
+/* $Id: miniglx_events.c,v 1.1.2.11 2003/04/28 13:21:10 keithw Exp $ */
/**
@@ -78,7 +78,18 @@ enum msgs {
_RepaintPlease,
};
-
+/**
+ * \brief Allocate an XEvent structure on the event queue.
+ *
+ * \param dpy the display handle.
+ *
+ * \return Pointer to the queued event struct or NULL on failure.
+ *
+ * \internal
+ * If there is space on the XEvent queue, return a pointer
+ * to the next free event and increment the eventqueue tail value.
+ * Otherwise return null.
+ */
static XEvent *queue_event( Display *dpy )
{
int incr = (dpy->eventqueue.tail + 1) & MINIGLX_EVENT_QUEUE_MASK;
@@ -92,6 +103,19 @@ static XEvent *queue_event( Display *dpy )
}
}
+/**
+ * \brief Dequeue an XEvent and copy it into provided storage.
+ *
+ * \param dpy the display handle.
+ * \param event_return pointer to copy the queued event to.
+ *
+ * \return True or False depending on success.
+ *
+ * \internal
+ * If there is a queued XEvent on the queue, copy it to the provided
+ * pointer and increment the eventqueue head value. Otherwise return
+ * null.
+ */
static int dequeue_event( Display *dpy, XEvent *event_return )
{
if (dpy->eventqueue.tail == dpy->eventqueue.head) {
@@ -105,36 +129,59 @@ static int dequeue_event( Display *dpy, XEvent *event_return )
}
}
-
+/**
+ * \brief Shutdown a socket connection.
+ *
+ * \param dpy the display handle.
+ * \param i the index in dpy->fd of the socket connection.
+ *
+ * \internal
+ * Shutdown and close the file descriptor. If this is the special
+ * connection in fd[0], issue an error message and exit - there's been
+ * some sort of failure somewhere. Otherwise, let the application
+ * know about whats happened by issuing a DestroyNotify event.
+ */
static void shut_fd( Display *dpy, int i )
{
- XEvent *er;
-
if (dpy->fd[i].fd < 0)
return;
- if (i == 0) {
- fprintf(stderr, "server connection lost\n");
- exit(1);
- }
-
shutdown (dpy->fd[i].fd, SHUT_RDWR);
close (dpy->fd[i].fd);
dpy->fd[i].fd = -1;
dpy->fd[i].readbuf_count = 0;
dpy->fd[i].writebuf_count = 0;
- /* Pass this to the application as a DestroyNotify event.
- */
- er = queue_event(dpy);
- if (!er) return;
- er->xdestroywindow.type = DestroyNotify;
- er->xdestroywindow.serial = 0;
- er->xdestroywindow.send_event = 0;
- er->xdestroywindow.display = dpy;
- er->xdestroywindow.window = (Window)i;
+ if (i == 0) {
+ fprintf(stderr, "server connection lost\n");
+ exit(1);
+ }
+ else {
+ /* Pass this to the application as a DestroyNotify event.
+ */
+ XEvent *er = queue_event(dpy);
+ if (!er) return;
+ er->xdestroywindow.type = DestroyNotify;
+ er->xdestroywindow.serial = 0;
+ er->xdestroywindow.send_event = 0;
+ er->xdestroywindow.display = dpy;
+ er->xdestroywindow.window = (Window)i;
+ }
}
+/**
+ * \brief Send a message to a socket connection.
+ *
+ * \param dpy the display handle.
+ * \param i the index in dpy->fd of the socket connection.
+ * \param msg the message to send.
+ * \param sz the size of the message
+ *
+ * \internal
+ * Copy the message to the writebuffer for the nominated connection.
+ * This will be actually sent to that file discriptor from
+ * __miniglx_Select().
+ */
static int send_msg( Display *dpy, int i,
const void *msg, size_t sz )
{
@@ -149,11 +196,34 @@ static int send_msg( Display *dpy, int i,
return True;
}
+/**
+ * \brief Send a message to a socket connection.
+ *
+ * \param dpy the display handle.
+ * \param i the index in dpy->fd of the socket connection.
+ * \param msg the message to send.
+ *
+ * \internal
+ * Use send_msg() to send a one-byte message to a socket.
+ */
static int send_char_msg( Display *dpy, int i, char msg )
{
return send_msg( dpy, i, &msg, sizeof(char));
}
+
+/**
+ * \brief Block and recieve a message from a socket connection.
+ *
+ * \param dpy the display handle.
+ * \param connection the index in dpy->fd of the socket connection.
+ * \param msg storage for the recieved message.
+ * \param msg_size the number of bytes to read.
+ *
+ * \internal Block and read from the connection's file descriptor
+ * until msg_size bytes have been received. Only called from
+ * welcome_message_part().
+ */
static int blocking_read( Display *dpy, int connection,
char *msg, size_t msg_size )
{
@@ -210,7 +280,23 @@ static int welcome_message( Display *dpy, int i )
}
-
+/**
+ * \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 int handle_new_client( Display *dpy )
{
struct sockaddr_un client_address;
@@ -715,11 +801,11 @@ XMapWindow( Display *dpy, Window w )
* \param display the display handle as returned by XOpenDisplay().
* \param w the window handle.
*
- * Should clients be allowed to unmap their own windows? Probably, as
- * it is impossible to force them to keep updating their contents & at
- * least this way there is notification that they've stopped.
- *
- * The entrypoint is required for the server in any case.
+ * Called from the client: Lets the server know that the window won't
+ * be updated anymore.
+ *
+ * Called from the server: Tells the specified client that it no longer
+ * holds the focus.
*/
void
XUnmapWindow( Display *dpy, Window w )
@@ -736,6 +822,14 @@ XUnmapWindow( Display *dpy, Window w )
}
+/**
+ * \brief Block and wait for next X event.
+ *
+ * \param display the display handle as returned by XOpenDisplay().
+ * \param event_return a pointer to an XEvent struct for the returned data.
+ *
+ * Wait until there is a new XEvent pending.
+ **/
int XNextEvent(Display *dpy, XEvent *event_return)
{
for (;;) {
@@ -746,6 +840,16 @@ int XNextEvent(Display *dpy, XEvent *event_return)
}
}
+/**
+ * \brief Non-blocking check for next X event.
+ *
+ * \param display the display handle as returned by XOpenDisplay().
+ * \param event_mask IGNORED
+ * \param event_return a pointer to an XEvent struct for the returned data.
+ *
+ * Check if there is a new XEvent pending. Note that event_mask is
+ * ignored and any pending event will be returned.
+ **/
Bool XCheckMaskEvent(Display *dpy, long event_mask, XEvent *event_return)
{
if ( dpy->eventqueue.head != dpy->eventqueue.tail )
@@ -757,14 +861,6 @@ Bool XCheckMaskEvent(Display *dpy, long event_mask, XEvent *event_return)
}
-Bool XCheckWindowEvent(Display *dpy, Window w, long event_mask,
- XEvent *event_return)
-{
- if (!w || w != dpy->TheWindow)
- return False;
-
- return XCheckMaskEvent( dpy, event_mask, event_return );
-}