From 50bb4abe86635c8bb26ad643d4402f109e03a7d0 Mon Sep 17 00:00:00 2001 From: Sam Lau Date: Tue, 24 Oct 2006 17:14:02 -0700 Subject: Sun bug 4985712: man pages needed for MIT-SHM extension functions --- man/XShm.man | 202 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 man/XShm.man (limited to 'man') diff --git a/man/XShm.man b/man/XShm.man new file mode 100644 index 0000000..079ced5 --- /dev/null +++ b/man/XShm.man @@ -0,0 +1,202 @@ +.\" Copyright (c) 1991 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining a +.\" copy of this software and associated documentation files (the "Software"), +.\" to deal in the Software without restriction, including without limitation +.\" the rights to use, copy, modify, merge, publish, distribute, sublicense, +.\" and/or sell copies of the Software, and to permit persons to whom the +.\" Software furnished to do so, subject to the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included in +.\" all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +.\" THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +.\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF +.\" OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +.\" SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall not +.\" be used in advertising or otherwise to promote the sale, use or other +.\" dealing in this Software without prior written authorization from the +.\" X Consortium. +.\" +.\" Copyright 2006 Sun Microsystems, Inc. All Rights Reserved +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining a +.\" copy of this software and associated documentation files (the "Software"), +.\" to deal in the Software without restriction, including without limitation +.\" the rights to use, copy, modify, merge, publish, distribute, +.\" sublicense, and/or sell copies of the Software, and to permit persons +.\" to whom the Software is furnished to do so, subject to the following +.\" conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the names of the copyright holders +.\" shall not be used in advertising or otherwise to promote the sale, use +.\" or other dealings in this Software without prior written authorization +.\" from said copyright holders. +.\" +.\" X Window System is a trademark of The Open Group. +.\" +.de ZN +.ie t \fB\^\\$1\^\fR\\$2 +.el \fI\^\\$1\^\fP\\$2 +.. +.TH XShm __libmansuffix__ __xorgversion__ "X FUNCTIONS" +.SH NAME +XShmQueryExtension, XShmQueryVersion, XShmPixmapFormat, XShmAttach, XShmDetach +XShmCreateImage, XShmPutImage, XShmGetImage, XShmCreatePixmap, XShmGetEventBase - X Shared Memory extension functions +.SH SYNTAX +.nf +.LP +\&#include +\&#include +\&#include +\&#include +.LP +Bool XShmQueryExtension( + Display *display); +.LP +Bool XShmQueryVersion( + Display *display; + int *major, *minor; + Bool *pixmaps); +.LP +Status XShmPixmapFormat( + Display *display); +.LP +Status XShmAttach( + Display *display; + XShmSegmentInfo *shminfo); +.LP +Status XShmDetach( + Display *display; + XShmSegmentInfo *shminfo); + +.LP +XImage *XShmCreateImage ( + Display *display; + Visual *visual; + unsigned int depth, width, height; + int format; + char *data; + XShmSegmentInfo *shminfo); +.LP +Status XShmPutImage( + Display *display; + Drawable d; + GC gc; + XImage *image; + int src_x, src_y, dest_x, dest_y; + unsigned int width, height; + bool send_event); +.LP +Status XShmGetImage ( + Display *display; + Drawable d; + XImage *image; + int x, y; + unsigned long plane_mask); +.LP +Pixmap XShmCreatePixmap( + Display *display; + Drawable d; + char *data; + XShmSegmentInfo *shminfo; + unsigned int width, height, depth); +.LP +Status XShmGetEventBase( + Display *display); +.LP + +.fi +.SH STRUCTURES +.nf +.ta 3i +\fIEvents:\fP +typedef struct { + int type; /\\(* of event */ + unsigned long serial; /\\(* # of last request processed by server*/ + Bool send_event; /\\(* true if this came frome a SendEvent request*/ + Display *display; /\\(* Display the event was read from */ + Drawable drawable; /\\(* drawable of request */ + int major_code; /\\(* ShmReqCode */ + int minor_code; /\\(* X_ShmPutImage */ + ShmSeg shmseg; /\\(* the ShmSeg used in the request*/ + unsigned long offset; /\\(* the offset into ShmSeg used in the request*/ +} XShmCompletionEvent; +.LP +\fIa structure of type XShmSegmentInfo :\fP + +typedef struct { + ShmSeg shmseg; /\\(* resource id */ + int shmid; /\\(* kernel id */ + char *shmaddr; /\\(* address in client */ + Bool readOnly; /\\(* how the server should attach it */ +} XShmSegmentInfo; + +.SH DESCRIPTION +.PP +.PP +.ZN XShmQueryExtension +checks to see if the shared memory extensions are available for the +specified display. +.PP +.ZN XShmQueryVersion +returns the version numbers of the extension implementation. Shared +memory pixmaps are supported if the pixmaps argument returns true. +.PP +.ZN XShmAttach +tells the server to attach to your shared memory segment. If all goes +well, you will get a non-zero status, back and your XImage is ready +for use. +.PP +.ZN XShmDetach +tells the server to detach from your shared memory segment. +.PP +.ZN XShmPutImage +combines an image in memory with a shape of the specified drawable. If +XYBitmap format is used, the depth must be one, or a ``BadMatch'' +error results. The foreground pixel in the GC defines the source for +the one bits in the image, and the background pixel defines the source +for the zero bits. For XYPixmap and ZPixmap, the depth must match the +depth of the drawable, or a ``BadMatch'' error results. +.PP +.ZN XShmGetImage +reads image data into a shared memory XImage where display is the +display of interest, drawable is the source drawable, image is the +destination XImage, x and y are offsets within the drawable, and +plane_mask defines which planes are to be read. +.PP +.ZN XShmCreateImage +allocates the memory needed for an XImage structure for the specified +display but does not allocate space for the image itself. +.PP +.ZN XShmPixmapFormat +gets the format for the server. If your application can deal with the +server pixmap data format, a shared memory segment and shminfo +structure are created. +.PP +.ZN XShmCreatePixmap +points to a pixmap which you can manipulate in all of the usual ways, +with the added bonus of being able to edit its contents directly +through the shared memory segment. +.PP +.ZN XShmGetEventBase +gets the completion event value. +.PP +.SH SEE ALSO +\fIMIT-SHM - The MIT Shared Memory Extension \fP -- cgit v1.2.1