1/*
2 * Copyright © 2002 Keith Packard
3 *
4 * Permission to use, copy, modify, distribute, and sell this software and its
5 * documentation for any purpose is hereby granted without fee, provided that
6 * the above copyright notice appear in all copies and that both that
7 * copyright notice and this permission notice appear in supporting
8 * documentation, and that the name of Keith Packard not be used in
9 * advertising or publicity pertaining to distribution of the software without
10 * specific, written prior permission.  Keith Packard makes no
11 * representations about the suitability of this software for any purpose.  It
12 * is provided "as is" without express or implied warranty.
13 *
14 * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
15 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
16 * EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
17 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
18 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
19 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
20 * PERFORMANCE OF THIS SOFTWARE.
21 */
22
23#ifndef _XCURSOR_H_
24#define _XCURSOR_H_
25#include <stdio.h>
26#include <X11/Xfuncproto.h>
27#include <X11/Xlib.h>
28
29typedef int		XcursorBool;
30typedef unsigned int	XcursorUInt;
31
32typedef XcursorUInt	XcursorDim;
33typedef XcursorUInt	XcursorPixel;
34
35#define XcursorTrue	1
36#define XcursorFalse	0
37
38/*
39 * Cursor files start with a header.  The header
40 * contains a magic number, a version number and a
41 * table of contents which has type and offset information
42 * for the remaining tables in the file.
43 *
44 * File minor versions increment for compatible changes
45 * File major versions increment for incompatible changes (never, we hope)
46 *
47 * Chunks of the same type are always upward compatible.  Incompatible
48 * changes are made with new chunk types; the old data can remain under
49 * the old type.  Upward compatible changes can add header data as the
50 * header lengths are specified in the file.
51 *
52 *  File:
53 *	FileHeader
54 *	LISTofChunk
55 *
56 *  FileHeader:
57 *	CARD32		magic	    magic number
58 *	CARD32		header	    bytes in file header
59 *	CARD32		version	    file version
60 *	CARD32		ntoc	    number of toc entries
61 *	LISTofFileToc   toc	    table of contents
62 *
63 *  FileToc:
64 *	CARD32		type	    entry type
65 *	CARD32		subtype	    entry subtype (size for images)
66 *	CARD32		position    absolute file position
67 */
68
69#define XCURSOR_MAGIC	0x72756358  /* "Xcur" LSBFirst */
70
71/*
72 * Current Xcursor version number.  Will be substituted by configure
73 * from the version in the libXcursor configure.ac file.
74 */
75
76#undef XCURSOR_LIB_MAJOR
77#undef XCURSOR_LIB_MINOR
78#undef XCURSOR_LIB_REVISION
79#define XCURSOR_LIB_VERSION	((XCURSOR_LIB_MAJOR * 10000) + \
80				 (XCURSOR_LIB_MINOR * 100) + \
81				 (XCURSOR_LIB_REVISION))
82
83/*
84 * This version number is stored in cursor files; changes to the
85 * file format require updating this version number
86 */
87#define XCURSOR_FILE_MAJOR	1
88#define XCURSOR_FILE_MINOR	0
89#define XCURSOR_FILE_VERSION	((XCURSOR_FILE_MAJOR << 16) | (XCURSOR_FILE_MINOR))
90#define XCURSOR_FILE_HEADER_LEN	(4 * 4)
91#define XCURSOR_FILE_TOC_LEN	(3 * 4)
92
93typedef struct _XcursorFileToc {
94    XcursorUInt	    type;	/* chunk type */
95    XcursorUInt	    subtype;	/* subtype (size for images) */
96    XcursorUInt	    position;	/* absolute position in file */
97} XcursorFileToc;
98
99typedef struct _XcursorFileHeader {
100    XcursorUInt	    magic;	/* magic number */
101    XcursorUInt	    header;	/* byte length of header */
102    XcursorUInt	    version;	/* file version number */
103    XcursorUInt	    ntoc;	/* number of toc entries */
104    XcursorFileToc  *tocs;	/* table of contents */
105} XcursorFileHeader;
106
107/*
108 * The rest of the file is a list of chunks, each tagged by type
109 * and version.
110 *
111 *  Chunk:
112 *	ChunkHeader
113 *	<extra type-specific header fields>
114 *	<type-specific data>
115 *
116 *  ChunkHeader:
117 *	CARD32	    header	bytes in chunk header + type header
118 *	CARD32	    type	chunk type
119 *	CARD32	    subtype	chunk subtype
120 *	CARD32	    version	chunk type version
121 */
122
123#define XCURSOR_CHUNK_HEADER_LEN    (4 * 4)
124
125typedef struct _XcursorChunkHeader {
126    XcursorUInt	    header;	/* bytes in chunk header */
127    XcursorUInt	    type;	/* chunk type */
128    XcursorUInt	    subtype;	/* chunk subtype (size for images) */
129    XcursorUInt	    version;	/* version of this type */
130} XcursorChunkHeader;
131
132/*
133 * Here's a list of the known chunk types
134 */
135
136/*
137 * Comments consist of a 4-byte length field followed by
138 * UTF-8 encoded text
139 *
140 *  Comment:
141 *	ChunkHeader header	chunk header
142 *	CARD32	    length	bytes in text
143 *	LISTofCARD8 text	UTF-8 encoded text
144 */
145
146#define XCURSOR_COMMENT_TYPE	    0xfffe0001
147#define XCURSOR_COMMENT_VERSION	    1
148#define XCURSOR_COMMENT_HEADER_LEN  (XCURSOR_CHUNK_HEADER_LEN + (1 *4))
149#define XCURSOR_COMMENT_COPYRIGHT   1
150#define XCURSOR_COMMENT_LICENSE	    2
151#define XCURSOR_COMMENT_OTHER	    3
152#define XCURSOR_COMMENT_MAX_LEN	    0x100000
153
154typedef struct _XcursorComment {
155    XcursorUInt	    version;
156    XcursorUInt	    comment_type;
157    char	    *comment;
158} XcursorComment;
159
160/*
161 * Each cursor image occupies a separate image chunk.
162 * The length of the image header follows the chunk header
163 * so that future versions can extend the header without
164 * breaking older applications
165 *
166 *  Image:
167 *	ChunkHeader	header	chunk header
168 *	CARD32		width	actual width
169 *	CARD32		height	actual height
170 *	CARD32		xhot	hot spot x
171 *	CARD32		yhot	hot spot y
172 *	CARD32		delay	animation delay
173 *	LISTofCARD32	pixels	ARGB pixels
174 */
175
176#define XCURSOR_IMAGE_TYPE    	    0xfffd0002
177#define XCURSOR_IMAGE_VERSION	    1
178#define XCURSOR_IMAGE_HEADER_LEN    (XCURSOR_CHUNK_HEADER_LEN + (5*4))
179#define XCURSOR_IMAGE_MAX_SIZE	    0x7fff	/* 32767x32767 max cursor size */
180
181typedef struct _XcursorImage {
182    XcursorUInt	    version;	/* version of the image data */
183    XcursorDim	    size;	/* nominal size for matching */
184    XcursorDim	    width;	/* actual width */
185    XcursorDim	    height;	/* actual height */
186    XcursorDim	    xhot;	/* hot spot x (must be inside image) */
187    XcursorDim	    yhot;	/* hot spot y (must be inside image) */
188    XcursorUInt	    delay;	/* animation delay to next frame (ms) */
189    XcursorPixel    *pixels;	/* pointer to pixels */
190} XcursorImage;
191
192/*
193 * Other data structures exposed by the library API
194 */
195typedef struct _XcursorImages {
196    int		    nimage;	/* number of images */
197    XcursorImage    **images;	/* array of XcursorImage pointers */
198    char	    *name;	/* name used to load images */
199} XcursorImages;
200
201typedef struct _XcursorCursors {
202    Display	    *dpy;	/* Display holding cursors */
203    int		    ref;	/* reference count */
204    int		    ncursor;	/* number of cursors */
205    Cursor	    *cursors;	/* array of cursors */
206} XcursorCursors;
207
208typedef struct _XcursorAnimate {
209    XcursorCursors   *cursors;	/* list of cursors to use */
210    int		    sequence;	/* which cursor is next */
211} XcursorAnimate;
212
213typedef struct _XcursorFile XcursorFile;
214
215struct _XcursorFile {
216    void    *closure;
217    int	    (*read)  (XcursorFile *file, unsigned char *buf, int len);
218    int	    (*write) (XcursorFile *file, unsigned char *buf, int len);
219    int	    (*seek)  (XcursorFile *file, long offset, int whence);
220};
221
222typedef struct _XcursorComments {
223    int		    ncomment;	/* number of comments */
224    XcursorComment  **comments;	/* array of XcursorComment pointers */
225} XcursorComments;
226
227#define XCURSOR_CORE_THEME  "core"
228
229_XFUNCPROTOBEGIN
230
231/*
232 * Manage Image objects
233 */
234XcursorImage *
235XcursorImageCreate (int width, int height);
236
237void
238XcursorImageDestroy (XcursorImage *image);
239
240/*
241 * Manage Images objects
242 */
243XcursorImages *
244XcursorImagesCreate (int size);
245
246void
247XcursorImagesDestroy (XcursorImages *images);
248
249void
250XcursorImagesSetName (XcursorImages *images, const char *name);
251
252/*
253 * Manage Cursor objects
254 */
255XcursorCursors *
256XcursorCursorsCreate (Display *dpy, int size);
257
258void
259XcursorCursorsDestroy (XcursorCursors *cursors);
260
261/*
262 * Manage Animate objects
263 */
264XcursorAnimate *
265XcursorAnimateCreate (XcursorCursors *cursors);
266
267void
268XcursorAnimateDestroy (XcursorAnimate *animate);
269
270Cursor
271XcursorAnimateNext (XcursorAnimate *animate);
272
273/*
274 * Manage Comment objects
275 */
276XcursorComment *
277XcursorCommentCreate (XcursorUInt comment_type, int length);
278
279void
280XcursorCommentDestroy (XcursorComment *comment);
281
282XcursorComments *
283XcursorCommentsCreate (int size);
284
285void
286XcursorCommentsDestroy (XcursorComments *comments);
287
288/*
289 * XcursorFile/Image APIs
290 */
291XcursorImage *
292XcursorXcFileLoadImage (XcursorFile *file, int size);
293
294XcursorImages *
295XcursorXcFileLoadImages (XcursorFile *file, int size);
296
297XcursorImages *
298XcursorXcFileLoadAllImages (XcursorFile *file);
299
300XcursorBool
301XcursorXcFileLoad (XcursorFile	    *file,
302		   XcursorComments  **commentsp,
303		   XcursorImages    **imagesp);
304
305XcursorBool
306XcursorXcFileSave (XcursorFile		    *file,
307		   const XcursorComments    *comments,
308		   const XcursorImages	    *images);
309
310/*
311 * FILE/Image APIs
312 */
313XcursorImage *
314XcursorFileLoadImage (FILE *file, int size);
315
316XcursorImages *
317XcursorFileLoadImages (FILE *file, int size);
318
319XcursorImages *
320XcursorFileLoadAllImages (FILE *file);
321
322XcursorBool
323XcursorFileLoad (FILE		    *file,
324		 XcursorComments    **commentsp,
325		 XcursorImages	    **imagesp);
326
327XcursorBool
328XcursorFileSaveImages (FILE *file, const XcursorImages *images);
329
330XcursorBool
331XcursorFileSave (FILE *			file,
332		 const XcursorComments	*comments,
333		 const XcursorImages	*images);
334
335/*
336 * Filename/Image APIs
337 */
338XcursorImage *
339XcursorFilenameLoadImage (const char *filename, int size);
340
341XcursorImages *
342XcursorFilenameLoadImages (const char *filename, int size);
343
344XcursorImages *
345XcursorFilenameLoadAllImages (const char *filename);
346
347XcursorBool
348XcursorFilenameLoad (const char		*file,
349		     XcursorComments	**commentsp,
350		     XcursorImages	**imagesp);
351
352XcursorBool
353XcursorFilenameSaveImages (const char *filename, const XcursorImages *images);
354
355XcursorBool
356XcursorFilenameSave (const char		    *file,
357		     const XcursorComments  *comments,
358		     const XcursorImages    *images);
359
360/*
361 * Library/Image APIs
362 */
363XcursorImage *
364XcursorLibraryLoadImage (const char *library, const char *theme, int size);
365
366XcursorImages *
367XcursorLibraryLoadImages (const char *library, const char *theme, int size);
368
369/*
370 * Library/shape API
371 */
372
373const char *
374XcursorLibraryPath (void);
375
376int
377XcursorLibraryShape (const char *library);
378
379/*
380 * Image/Cursor APIs
381 */
382
383Cursor
384XcursorImageLoadCursor (Display *dpy, const XcursorImage *image);
385
386XcursorCursors *
387XcursorImagesLoadCursors (Display *dpy, const XcursorImages *images);
388
389Cursor
390XcursorImagesLoadCursor (Display *dpy, const XcursorImages *images);
391
392/*
393 * Filename/Cursor APIs
394 */
395Cursor
396XcursorFilenameLoadCursor (Display *dpy, const char *file);
397
398XcursorCursors *
399XcursorFilenameLoadCursors (Display *dpy, const char *file);
400
401/*
402 * Library/Cursor APIs
403 */
404Cursor
405XcursorLibraryLoadCursor (Display *dpy, const char *file);
406
407XcursorCursors *
408XcursorLibraryLoadCursors (Display *dpy, const char *file);
409
410/*
411 * Shape/Image APIs
412 */
413
414XcursorImage *
415XcursorShapeLoadImage (unsigned int shape, const char *theme, int size);
416
417XcursorImages *
418XcursorShapeLoadImages (unsigned int shape, const char *theme, int size);
419
420/*
421 * Shape/Cursor APIs
422 */
423Cursor
424XcursorShapeLoadCursor (Display *dpy, unsigned int shape);
425
426XcursorCursors *
427XcursorShapeLoadCursors (Display *dpy, unsigned int shape);
428
429/*
430 * This is the function called by Xlib when attempting to
431 * load cursors from XCreateGlyphCursor.  The interface must
432 * not change as Xlib loads 'libXcursor.so' instead of
433 * a specific major version
434 */
435Cursor
436XcursorTryShapeCursor (Display	    *dpy,
437		       Font	    source_font,
438		       Font	    mask_font,
439		       unsigned int source_char,
440		       unsigned int mask_char,
441		       XColor _Xconst *foreground,
442		       XColor _Xconst *background);
443
444void
445XcursorNoticeCreateBitmap (Display	*dpy,
446			   Pixmap	pid,
447			   unsigned int width,
448			   unsigned int height);
449
450void
451XcursorNoticePutBitmap (Display	    *dpy,
452			Drawable    draw,
453			XImage	    *image);
454
455Cursor
456XcursorTryShapeBitmapCursor (Display		*dpy,
457			     Pixmap		source,
458			     Pixmap		mask,
459			     XColor		*foreground,
460			     XColor		*background,
461			     unsigned int	x,
462			     unsigned int	y);
463
464#define XCURSOR_BITMAP_HASH_SIZE    16
465
466void
467XcursorImageHash (XImage	*image,
468		  unsigned char	hash[XCURSOR_BITMAP_HASH_SIZE]);
469
470/*
471 * Display information APIs
472 */
473XcursorBool
474XcursorSupportsARGB (Display *dpy);
475
476XcursorBool
477XcursorSupportsAnim (Display *dpy);
478
479XcursorBool
480XcursorSetDefaultSize (Display *dpy, int size);
481
482int
483XcursorGetDefaultSize (Display *dpy);
484
485XcursorBool
486XcursorSetTheme (Display *dpy, const char *theme);
487
488char *
489XcursorGetTheme (Display *dpy);
490
491XcursorBool
492XcursorGetThemeCore (Display *dpy);
493
494XcursorBool
495XcursorSetThemeCore (Display *dpy, XcursorBool theme_core);
496
497_XFUNCPROTOEND
498
499#endif
500