wrlib/wraster.h.in

   1 /*
   2  * Raster graphics library
   3  *
   4  * Copyright (c) 1997-2003 Alfredo K. Kojima
   5  *
   6  *  This library is free software; you can redistribute it and/or
   7  *  modify it under the terms of the GNU Library General Public
   8  *  License as published by the Free Software Foundation; either
   9  *  version 2 of the License, or (at your option) any later version.
  10  *
  11  *  This library is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  *  Library General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU Library General Public
  17  *  License along with this library; if not, write to the Free
  18  *  Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
  19  *  MA 02110-1301, USA.
  20  */
  21
  22 /*
  23  * Environment variables:
  24  *
  25  * WRASTER_GAMMA <rgamma>/<ggamma>/<bgamma>
  26  * gamma correction value. Must be  greater than 0
  27  * Only for PseudoColor visuals.
  28  *
  29  * Default:
  30  * WRASTER_GAMMA 1/1/1
  31  *
  32  *
  33  * If you want a specific value for a screen, append the screen number
  34  * preceded by a hash to the variable name as in
  35  * WRASTER_GAMMA#1
  36  * for screen number 1
  37  */
  38
  39 #ifndef RLRASTER_H_
  40 #define RLRASTER_H_
  41
  42
  43 /* version of the header for the library */
  44 #define WRASTER_HEADER_VERSION  25
  45
  46
  47 #include <X11/Xlib.h>
  48 #include <X11/Xutil.h>
  49 @USE_XSHM@#include <X11/extensions/XShm.h>
  50
  51
  52 /*
  53  * Define some macro to provide attributes for the compiler
  54  *
  55  * These attributes help producing better code and/or detecting bugs, however not all compiler support them
  56  * as they are not standard.
  57  * Because we're a public API header, we can't count on autoconf to detect them for us, so we use that #if
  58  * mechanism and define an internal macro appropriately. Please note that the macro are not considered being
  59  * part of the public API.
  60  */
  61 #if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5)
  62 #define __wrlib_deprecated(msg)  __attribute__ ((deprecated(msg)))
  63 #elif __GNUC__ >= 3
  64 #define __wrlib_deprecated(msg)  __attribute__ ((deprecated))
  65 #else
  66 #define __wrlib_deprecated(msg)
  67 #endif
  68
  69 #if __GNUC__ >= 3
  70 /* Apparently introduced in GCC 3.0.x */
  71 /* Function returns newly allocated memory that does not alias any existing variable */
  72 #define __wrlib_nonalias         __attribute__ ((malloc))
  73 #else
  74 #define __wrlib_nonalias
  75 #endif
  76
  77 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3)
  78 /* Apparently introduced in GCC 3.3.x */
  79 /* The argument at index #i must not be NULL */
  80 #define __wrlib_nonnull(...)     __attribute__ ((nonnull(__VA_ARGS__)))
  81 #else
  82 #define __wrlib_nonnull(argidx)
  83 #endif
  84
  85 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)
  86 /* Apparently introduced in GCC 3.4.x */
  87 /* The return value of this function *must* be checked/used */
  88 #define __wrlib_useresult        __attribute__ ((warn_unused_result))
  89 #else
  90 #define __wrlib_useresult
  91 #endif
  92
  93
  94 #ifdef __cplusplus
  95 extern "C" {
  96 #endif /* __cplusplus */
  97
  98 /* RBestMatchRendering or RDitheredRendering */
  99 #define RC_RenderMode           (1<<0)
 100
 101 /* number of colors per channel for colormap in PseudoColor mode */
 102 #define RC_ColorsPerChannel     (1<<1)
 103
 104 /* do gamma correction */
 105 #define RC_GammaCorrection      (1<<2)
 106
 107 /* visual id to use */
 108 #define RC_VisualID             (1<<3)
 109
 110 /* shared memory usage */
 111 #define RC_UseSharedMemory      (1<<4)
 112
 113 /* use default instead of best visual */
 114 #define RC_DefaultVisual        (1<<5)
 115
 116 /* filter type for smoothed scaling */
 117 #define RC_ScalingFilter        (1<<6)
 118
 119 /* standard colormap usage */
 120 #define RC_StandardColormap     (1<<7)
 121
 122
 123
 124 /* image display modes */
 125 typedef enum {
 126         RDitheredRendering = 0,
 127         RBestMatchRendering = 1
 128 } RRenderingMode;
 129
 130
 131 /* std colormap usage/creation modes */
 132 typedef enum {
 133         RUseStdColormap,        /* default: fallbacks to RIgnore if there is none defined */
 134         RCreateStdColormap,
 135         RIgnoreStdColormap
 136 } RStdColormapMode;
 137
 138
 139 /* smoothed scaling filter types */
 140 typedef enum {
 141         RBoxFilter,
 142         RTriangleFilter,
 143         RBellFilter,
 144         RBSplineFilter,
 145         RLanczos3Filter,
 146         RMitchellFilter
 147 } RScalingFilter;
 148
 149
 150 typedef struct RContextAttributes {
 151     int flags;
 152     RRenderingMode render_mode;
 153     int colors_per_channel;            /* for PseudoColor */
 154     float rgamma;                      /* gamma correction for red, */
 155     float ggamma;                      /* green, */
 156     float bgamma;                      /* and blue */
 157     VisualID visualid;         /* visual ID to use */
 158     int use_shared_memory;             /* True of False */
 159     RScalingFilter scaling_filter;
 160     RStdColormapMode standard_colormap_mode;    /* what to do with std cma */
 161 } RContextAttributes;
 162
 163
 164 /*
 165  * describes a screen in terms of depth, visual, number of colors
 166  * we can use, if we should do dithering, and what colors to use for
 167  * dithering.
 168  */
 169 typedef struct RContext {
 170     Display *dpy;
 171     int screen_number;
 172     Colormap cmap;
 173
 174     RContextAttributes *attribs;
 175
 176     GC copy_gc;
 177
 178     Visual *visual;
 179     int depth;
 180     Window drawable;               /* window to pass for XCreatePixmap().*/
 181     /* generally = root */
 182     int vclass;
 183
 184     unsigned long black;
 185     unsigned long white;
 186
 187     int red_offset;                    /* only used in 24bpp */
 188     int green_offset;
 189     int blue_offset;
 190
 191     /* only used for pseudocolor and grayscale */
 192
 193     XStandardColormap *std_rgb_map;    /* standard RGB colormap */
 194     XStandardColormap *std_gray_map;   /* standard grayscale colormap */
 195
 196     int ncolors;                       /* total number of colors we can use */
 197     XColor *colors;                    /* internal colormap */
 198     unsigned long *pixels;             /* RContext->colors[].pixel */
 199
 200     struct {
 201         unsigned int use_shared_pixmap:1;
 202         unsigned int optimize_for_speed:1
 203             __wrlib_deprecated("Flag optimize_for_speed in RContext is not used anymore "
 204                                "and will be removed in future version, please do not use");
 205     } flags;
 206 } RContext;
 207
 208
 209 typedef struct RColor {
 210     unsigned char red;
 211     unsigned char green;
 212     unsigned char blue;
 213     unsigned char alpha;
 214 } RColor;
 215
 216
 217 typedef struct RHSVColor {
 218     unsigned short hue;        /* 0-359 */
 219     unsigned char saturation;      /* 0-255 */
 220     unsigned char value;               /* 0-255 */
 221 } RHSVColor;
 222
 223
 224
 225 typedef struct RPoint {
 226     int x, y;
 227 } RPoint;
 228
 229
 230 typedef struct RSegment {
 231     int x1, y1, x2, y2;
 232 } RSegment;
 233
 234
 235
 236 /* image formats */
 237 enum RImageFormat {
 238     RRGBFormat,
 239     RRGBAFormat
 240 };
 241
 242
 243 /*
 244  * internal 24bit+alpha image representation
 245  */
 246 typedef struct RImage {
 247     unsigned char *data;       /* image data RGBA or RGB */
 248     int width, height;     /* size of the image */
 249     enum RImageFormat format;
 250     RColor background;     /* background color */
 251     int refCount;
 252 } RImage;
 253
 254
 255 /*
 256  * internal wrapper for XImage. Used for shm abstraction
 257  */
 258 typedef struct RXImage {
 259     XImage *image;
 260
 261 @USE_XSHM@    /* Private data. Do not access */
 262 @USE_XSHM@    XShmSegmentInfo info;
 263 @USE_XSHM@    char is_shared;
 264 } RXImage;
 265
 266
 267 /* note that not all operations are supported in all functions */
 268 typedef enum {
 269     RClearOperation,           /* clear with 0 */
 270     RCopyOperation,
 271     RNormalOperation,          /* same as combine */
 272     RAddOperation,
 273     RSubtractOperation
 274 } RPixelOperation;
 275
 276
 277 typedef enum {
 278     RAbsoluteCoordinates = 0,
 279     RRelativeCoordinates = 1
 280 } RCoordinatesMode;
 281
 282
 283 enum {
 284     RSunkenBevel        = -1,
 285     RNoBevel    = 0,
 286     RRaisedBevel        = 1
 287 };
 288 /* bw compat */
 289 #define RBEV_SUNKEN     RSunkenBevel
 290 /* 1 pixel wide */
 291 #define RBEV_RAISED     RRaisedBevel
 292 /* 1 pixel wide on top/left 2 on bottom/right */
 293 #define RBEV_RAISED2    2
 294 /* 2 pixel width */
 295 #define RBEV_RAISED3    3
 296
 297 typedef enum {
 298     RHorizontalGradient = 2,
 299     RVerticalGradient = 3,
 300     RDiagonalGradient = 4
 301 } RGradientStyle;
 302 /* for backwards compatibility */
 303 #define RGRD_HORIZONTAL  RHorizontalGradient
 304 #define RGRD_VERTICAL   RVerticalGradient
 305 #define RGRD_DIAGONAL   RDiagonalGradient
 306
 307
 308 /*
 309  * How an image can be flipped, for RFlipImage
 310  *
 311  * Values are actually bit-mask which can be OR'd
 312  */
 313 #define RHorizontalFlip 0x0001
 314 #define RVerticalFlip   0x0002
 315
 316
 317 /* error codes */
 318 #define RERR_NONE               0
 319 #define RERR_OPEN               1      /* cant open file */
 320 #define RERR_READ               2      /* error reading from file */
 321 #define RERR_WRITE              3      /* error writing to file */
 322 #define RERR_NOMEMORY           4      /* out of memory */
 323 #define RERR_NOCOLOR            5      /* out of color cells */
 324 #define RERR_BADIMAGEFILE       6      /* image file is corrupted or invalid */
 325 #define RERR_BADFORMAT          7      /* image file format is unknown */
 326 #define RERR_BADINDEX           8      /* no such image index in file */
 327
 328 #define RERR_BADVISUALID        16     /* invalid visual ID requested for context */
 329 #define RERR_STDCMAPFAIL        17     /* failed to created std colormap */
 330
 331 #define RERR_XERROR             127    /* internal X error */
 332 #define RERR_INTERNAL           128    /* should not happen */
 333
 334
 335 /*
 336  * Cleaning before application exit
 337  */
 338 void RShutdown(void);
 339
 340 /*
 341  * Returns a NULL terminated array of strings containing the
 342  * supported formats, such as: TIFF, XPM, PNG, JPEG, PPM, GIF
 343  * Do not free the returned data.
 344  */
 345 char **RSupportedFileFormats(void)
 346         __wrlib_useresult;
 347
 348
 349 char *RGetImageFileFormat(const char *file)
 350         __wrlib_useresult __wrlib_nonnull(1);
 351
 352 /*
 353  * Xlib contexts
 354  */
 355 RContext *RCreateContext(Display *dpy, int screen_number,
 356                          const RContextAttributes *attribs)
 357         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1);
 358
 359 void RDestroyContext(RContext *context);
 360
 361 Bool RGetClosestXColor(RContext *context, const RColor *color, XColor *retColor)
 362         __wrlib_nonnull(1, 2, 3);
 363
 364 /*
 365  * RImage creation
 366  */
 367 RImage *RCreateImage(unsigned width, unsigned height, int alpha)
 368         __wrlib_useresult __wrlib_nonalias;
 369
 370 RImage *RCreateImageFromXImage(RContext *context, XImage *image, XImage *mask)
 371         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1, 2);
 372
 373 RImage *RCreateImageFromDrawable(RContext *context, Drawable drawable,
 374                                  Pixmap mask)
 375         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1);
 376
 377 RImage *RLoadImage(RContext *context, const char *file, int index)
 378         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1, 2);
 379
 380 RImage* RRetainImage(RImage *image);
 381
 382 void RReleaseImage(RImage *image)
 383         __wrlib_nonnull(1);
 384
 385 RImage *RGetImageFromXPMData(RContext *context, char **xpmData)
 386         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1, 2);
 387
 388 /*
 389  * RImage storing
 390  */
 391 Bool RSaveImage(RImage *image, const char *filename, const char *format)
 392         __wrlib_nonnull(1, 2, 3);
 393
 394 Bool RSaveTitledImage(RImage *image, const char *filename, const char *format, char *title)
 395         __wrlib_nonnull(1, 2, 3);
 396
 397 /*
 398  * Area manipulation
 399  */
 400 RImage *RCloneImage(RImage *image)
 401         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1);
 402
 403 RImage *RGetSubImage(RImage *image, int x, int y, unsigned width,
 404                      unsigned height)
 405         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1);
 406
 407 void RCombineImageWithColor(RImage *image, const RColor *color)
 408         __wrlib_nonnull(1, 2);
 409
 410 void RCombineImages(RImage *image, RImage *src)
 411         __wrlib_nonnull(1, 2);
 412
 413 void RCombineArea(RImage *image, RImage *src, int sx, int sy, unsigned width,
 414                   unsigned height, int dx, int dy)
 415         __wrlib_nonnull(1, 2);
 416
 417 void RCopyArea(RImage *image, RImage *src, int sx, int sy, unsigned width,
 418                unsigned height, int dx, int dy)
 419         __wrlib_nonnull(1, 2);
 420
 421 void RCombineImagesWithOpaqueness(RImage *image, RImage *src, int opaqueness)
 422         __wrlib_nonnull(1, 2);
 423
 424 void RCombineAreaWithOpaqueness(RImage *image, RImage *src, int sx, int sy,
 425                                 unsigned width, unsigned height, int dx, int dy,
 426                                 int opaqueness)
 427         __wrlib_nonnull(1, 2);
 428
 429 void RCombineAlpha(unsigned char *d, unsigned char *s, int s_has_alpha,
 430                    int width, int height, int dwi, int swi, int opacity)
 431         __wrlib_nonnull(1, 2);
 432
 433 RImage *RScaleImage(RImage *image, unsigned new_width, unsigned new_height)
 434         __wrlib_useresult __wrlib_nonalias;
 435
 436 RImage *RSmoothScaleImage(RImage *src, unsigned new_width,
 437                           unsigned new_height)
 438         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1);
 439
 440 RImage *RRotateImage(RImage *image, float angle)
 441         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1);
 442
 443 RImage *RFlipImage(RImage *image, int mode)
 444         __wrlib_useresult __wrlib_nonalias;
 445
 446 RImage *RMakeTiledImage(RImage *tile, unsigned width, unsigned height)
 447         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1);
 448
 449 RImage* RMakeCenteredImage(RImage *image, unsigned width, unsigned height,
 450                            const RColor *color)
 451         __wrlib_useresult __wrlib_nonalias __wrlib_nonnull(1, 4);
 452
 453 /*
 454  * Drawing
 455  */
 456 Bool RGetPixel(RImage *image, int x, int y, RColor *color)
 457         __wrlib_nonnull(1, 4);
 458
 459 void RPutPixel(RImage *image, int x, int y, const RColor *color)
 460         __wrlib_nonnull(1, 4);
 461
 462 void ROperatePixel(RImage *image, RPixelOperation operation, int x, int y, const RColor *color)
 463         __wrlib_nonnull(1, 5);
 464
 465 void RPutPixels(RImage *image, const RPoint *points, int npoints, RCoordinatesMode mode,
 466                 const RColor *color)
 467         __wrlib_nonnull(1, 2, 5);
 468
 469 void ROperatePixels(RImage *image, RPixelOperation operation, const RPoint *points,
 470                     int npoints, RCoordinatesMode mode, const RColor *color)
 471         __wrlib_nonnull(1, 3, 6);
 472
 473 int RDrawLine(RImage *image, int x0, int y0, int x1, int y1, const RColor *color)
 474         __wrlib_nonnull(1, 6);
 475
 476 int ROperateLine(RImage *image, RPixelOperation operation, int x0, int y0, int x1, int y1,
 477                  const RColor *color)
 478         __wrlib_nonnull(1, 7);
 479
 480 void RDrawLines(RImage *image, const RPoint *points, int npoints, RCoordinatesMode mode,
 481                 const RColor *color)
 482         __wrlib_nonnull(1, 2, 5);
 483
 484 void ROperateLines(RImage *image, RPixelOperation operation, const RPoint *points, int npoints,
 485                    RCoordinatesMode mode, const RColor *color)
 486         __wrlib_nonnull(1, 3, 6);
 487
 488 void ROperateRectangle(RImage *image, RPixelOperation operation, int x0, int y0, int x1, int y1, const RColor *color)
 489         __wrlib_nonnull(1, 7);
 490
 491 void RDrawSegments(RImage *image, const RSegment *segs, int nsegs, const RColor *color)
 492         __wrlib_nonnull(1, 2, 4);
 493
 494 void ROperateSegments(RImage *image, RPixelOperation operation, const RSegment *segs, int nsegs,
 495                       const RColor *color)
 496         __wrlib_nonnull(1, 3, 5);
 497
 498 /*
 499  * Color convertion
 500  */
 501 void RRGBtoHSV(const RColor *color, RHSVColor *hsv)
 502         __wrlib_nonnull(1, 2);
 503
 504 void RHSVtoRGB(const RHSVColor *hsv, RColor *rgb)
 505         __wrlib_nonnull(1, 2);
 506
 507 /*
 508  * Painting
 509  */
 510 void RClearImage(RImage *image, const RColor *color)
 511         __wrlib_nonnull(1, 2);
 512
 513 void RLightImage(RImage *image, const RColor *color)
 514         __wrlib_nonnull(1, 2);
 515
 516 void RFillImage(RImage *image, const RColor *color)
 517         __wrlib_nonnull(1, 2);
 518
 519 void RBevelImage(RImage *image, int bevel_type)
 520         __wrlib_nonnull(1);
 521
 522 RImage *RRenderGradient(unsigned width, unsigned height, const RColor *from,
 523                         const RColor *to, RGradientStyle style)
 524         __wrlib_nonalias __wrlib_useresult __wrlib_nonnull(3, 4);
 525
 526
 527 RImage *RRenderMultiGradient(unsigned width, unsigned height, RColor **colors,
 528                              RGradientStyle style)
 529         __wrlib_nonalias __wrlib_useresult __wrlib_nonnull(3);
 530
 531
 532 RImage *RRenderInterwovenGradient(unsigned width, unsigned height,
 533                                   RColor colors1[2], int thickness1,
 534                                   RColor colors2[2], int thickness2)
 535         __wrlib_nonalias __wrlib_useresult;
 536
 537
 538 /*
 539  * Convertion into X Pixmaps
 540  */
 541 int RConvertImage(RContext *context, RImage *image, Pixmap *pixmap)
 542         __wrlib_nonnull(1, 2, 3);
 543
 544 int RConvertImageMask(RContext *context, RImage *image, Pixmap *pixmap,
 545                       Pixmap *mask, int threshold)
 546         __wrlib_nonnull(1, 2, 3, 4);
 547
 548
 549 /*
 550  * misc. utilities
 551  */
 552 RXImage *RCreateXImage(RContext *context, int depth,
 553                        unsigned width, unsigned height)
 554         __wrlib_nonalias __wrlib_useresult __wrlib_nonnull(1);
 555
 556 RXImage *RGetXImage(RContext *context, Drawable d, int x, int y,
 557                     unsigned width, unsigned height)
 558         __wrlib_nonalias __wrlib_useresult __wrlib_nonnull(1);
 559
 560 void RDestroyXImage(RContext *context, RXImage *ximage)
 561         __wrlib_nonnull(1, 2);
 562
 563 void RPutXImage(RContext *context, Drawable d, GC gc, RXImage *ximage,
 564                 int src_x, int src_y, int dest_x, int dest_y,
 565                 unsigned width, unsigned height)
 566         __wrlib_nonnull(1, 3);
 567
 568 /* do not free the returned string! */
 569 const char *RMessageForError(int errorCode)
 570         __wrlib_useresult;
 571
 572 int RBlurImage(RImage *image)
 573         __wrlib_nonnull(1);
 574
 575 /****** Global Variables *******/
 576
 577 extern int RErrorCode;
 578
 579 #ifdef __cplusplus
 580 }
 581 #endif /* __cplusplus */
 582
 583 /*
 584  * The definitions below are done for internal use only
 585  * We undef them so users of the library may not misuse them
 586  */
 587 #undef __wrlib_deprecated
 588 #undef __wrlib_nonalias
 589 #undef __wrlib_nonnull
 590 #undef __wrlib_useresult
 591
 592 #endif