ui/vnc-enc-tight.h

   1 /*
   2  * QEMU VNC display driver: tight encoding
   3  *
   4  * From libvncserver/rfb/rfbproto.h
   5  * Copyright (C) 2005 Rohit Kumar, Johannes E. Schindelin
   6  * Copyright (C) 2000-2002 Constantin Kaplinsky.  All Rights Reserved.
   7  * Copyright (C) 2000 Tridia Corporation.  All Rights Reserved.
   8  * Copyright (C) 1999 AT&T Laboratories Cambridge.  All Rights Reserved.
   9  *
  10  *
  11  * Permission is hereby granted, free of charge, to any person obtaining a copy
  12  * of this software and associated documentation files (the "Software"), to deal
  13  * in the Software without restriction, including without limitation the rights
  14  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  15  * copies of the Software, and to permit persons to whom the Software is
  16  * furnished to do so, subject to the following conditions:
  17  *
  18  * The above copyright notice and this permission notice shall be included in
  19  * all copies or substantial portions of the Software.
  20  *
  21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  22  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  23  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  24  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  25  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  26  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  27  * THE SOFTWARE.
  28  */
  29
  30 #ifndef VNC_ENCODING_TIGHT_H
  31 #define VNC_ENCODING_TIGHT_H
  32
  33 /*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  34  * Tight Encoding.
  35  *
  36  *-- The first byte of each Tight-encoded rectangle is a "compression control
  37  *   byte". Its format is as follows (bit 0 is the least significant one):
  38  *
  39  *   bit 0:    if 1, then compression stream 0 should be reset;
  40  *   bit 1:    if 1, then compression stream 1 should be reset;
  41  *   bit 2:    if 1, then compression stream 2 should be reset;
  42  *   bit 3:    if 1, then compression stream 3 should be reset;
  43  *   bits 7-4: if 1000 (0x08), then the compression type is "fill",
  44  *             if 1001 (0x09), then the compression type is "jpeg",
  45  *             if 1010 (0x0A), then the compression type is "png",
  46  *             if 0xxx, then the compression type is "basic",
  47  *             values greater than 1010 are not valid.
  48  *
  49  * If the compression type is "basic", then bits 6..4 of the
  50  * compression control byte (those xxx in 0xxx) specify the following:
  51  *
  52  *   bits 5-4:  decimal representation is the index of a particular zlib
  53  *              stream which should be used for decompressing the data;
  54  *   bit 6:     if 1, then a "filter id" byte is following this byte.
  55  *
  56  *-- The data that follows after the compression control byte described
  57  * above depends on the compression type ("fill", "jpeg", "png" or "basic").
  58  *
  59  *-- If the compression type is "fill", then the only pixel value follows, in
  60  * client pixel format (see NOTE 1). This value applies to all pixels of the
  61  * rectangle.
  62  *
  63  *-- If the compression type is "jpeg" or "png", the following data stream
  64  * looks like this:
  65  *
  66  *   1..3 bytes:  data size (N) in compact representation;
  67  *   N bytes:     JPEG or PNG image.
  68  *
  69  * Data size is compactly represented in one, two or three bytes, according
  70  * to the following scheme:
  71  *
  72  *  0xxxxxxx                    (for values 0..127)
  73  *  1xxxxxxx 0yyyyyyy           (for values 128..16383)
  74  *  1xxxxxxx 1yyyyyyy zzzzzzzz  (for values 16384..4194303)
  75  *
  76  * Here each character denotes one bit, xxxxxxx are the least significant 7
  77  * bits of the value (bits 0-6), yyyyyyy are bits 7-13, and zzzzzzzz are the
  78  * most significant 8 bits (bits 14-21). For example, decimal value 10000
  79  * should be represented as two bytes: binary 10010000 01001110, or
  80  * hexadecimal 90 4E.
  81  *
  82  *-- If the compression type is "basic" and bit 6 of the compression control
  83  * byte was set to 1, then the next (second) byte specifies "filter id" which
  84  * tells the decoder what filter type was used by the encoder to pre-process
  85  * pixel data before the compression. The "filter id" byte can be one of the
  86  * following:
  87  *
  88  *   0:  no filter ("copy" filter);
  89  *   1:  "palette" filter;
  90  *   2:  "gradient" filter.
  91  *
  92  *-- If bit 6 of the compression control byte is set to 0 (no "filter id"
  93  * byte), or if the filter id is 0, then raw pixel values in the client
  94  * format (see NOTE 1) will be compressed. See below details on the
  95  * compression.
  96  *
  97  *-- The "gradient" filter pre-processes pixel data with a simple algorithm
  98  * which converts each color component to a difference between a "predicted"
  99  * intensity and the actual intensity. Such a technique does not affect
 100  * uncompressed data size, but helps to compress photo-like images better.
 101  * Pseudo-code for converting intensities to differences is the following:
 102  *
 103  *   P[i,j] := V[i-1,j] + V[i,j-1] - V[i-1,j-1];
 104  *   if (P[i,j] < 0) then P[i,j] := 0;
 105  *   if (P[i,j] > MAX) then P[i,j] := MAX;
 106  *   D[i,j] := V[i,j] - P[i,j];
 107  *
 108  * Here V[i,j] is the intensity of a color component for a pixel at
 109  * coordinates (i,j). MAX is the maximum value of intensity for a color
 110  * component.
 111  *
 112  *-- The "palette" filter converts true-color pixel data to indexed colors
 113  * and a palette which can consist of 2..256 colors. If the number of colors
 114  * is 2, then each pixel is encoded in 1 bit, otherwise 8 bits is used to
 115  * encode one pixel. 1-bit encoding is performed such way that the most
 116  * significant bits correspond to the leftmost pixels, and each raw of pixels
 117  * is aligned to the byte boundary. When "palette" filter is used, the
 118  * palette is sent before the pixel data. The palette begins with an unsigned
 119  * byte which value is the number of colors in the palette minus 1 (i.e. 1
 120  * means 2 colors, 255 means 256 colors in the palette). Then follows the
 121  * palette itself which consist of pixel values in client pixel format (see
 122  * NOTE 1).
 123  *
 124  *-- The pixel data is compressed using the zlib library. But if the data
 125  * size after applying the filter but before the compression is less then 12,
 126  * then the data is sent as is, uncompressed. Four separate zlib streams
 127  * (0..3) can be used and the decoder should read the actual stream id from
 128  * the compression control byte (see NOTE 2).
 129  *
 130  * If the compression is not used, then the pixel data is sent as is,
 131  * otherwise the data stream looks like this:
 132  *
 133  *   1..3 bytes:  data size (N) in compact representation;
 134  *   N bytes:     zlib-compressed data.
 135  *
 136  * Data size is compactly represented in one, two or three bytes, just like
 137  * in the "jpeg" compression method (see above).
 138  *
 139  *-- NOTE 1. If the color depth is 24, and all three color components are
 140  * 8-bit wide, then one pixel in Tight encoding is always represented by
 141  * three bytes, where the first byte is red component, the second byte is
 142  * green component, and the third byte is blue component of the pixel color
 143  * value. This applies to colors in palettes as well.
 144  *
 145  *-- NOTE 2. The decoder must reset compression streams' states before
 146  * decoding the rectangle, if some of bits 0,1,2,3 in the compression control
 147  * byte are set to 1. Note that the decoder must reset zlib streams even if
 148  * the compression type is "fill", "jpeg" or "png".
 149  *
 150  *-- NOTE 3. The "gradient" filter and "jpeg" compression may be used only
 151  * when bits-per-pixel value is either 16 or 32, not 8.
 152  *
 153  *-- NOTE 4. The width of any Tight-encoded rectangle cannot exceed 2048
 154  * pixels. If a rectangle is wider, it must be split into several rectangles
 155  * and each one should be encoded separately.
 156  *
 157  */
 158
 159 #define VNC_TIGHT_EXPLICIT_FILTER       0x04
 160 #define VNC_TIGHT_FILL                  0x08
 161 #define VNC_TIGHT_JPEG                  0x09
 162 #define VNC_TIGHT_PNG                   0x0A
 163 #define VNC_TIGHT_MAX_SUBENCODING       0x0A
 164
 165 /* Filters to improve compression efficiency */
 166 #define VNC_TIGHT_FILTER_COPY             0x00
 167 #define VNC_TIGHT_FILTER_PALETTE          0x01
 168 #define VNC_TIGHT_FILTER_GRADIENT         0x02
 169
 170 /* Note: The following constant should not be changed. */
 171 #define VNC_TIGHT_MIN_TO_COMPRESS 12
 172
 173 /* The parameters below may be adjusted. */
 174 #define VNC_TIGHT_MIN_SPLIT_RECT_SIZE     4096
 175 #define VNC_TIGHT_MIN_SOLID_SUBRECT_SIZE  2048
 176 #define VNC_TIGHT_MAX_SPLIT_TILE_SIZE       16
 177
 178 #define VNC_TIGHT_JPEG_MIN_RECT_SIZE      4096
 179 #define VNC_TIGHT_DETECT_SUBROW_WIDTH        7
 180 #define VNC_TIGHT_DETECT_MIN_WIDTH           8
 181 #define VNC_TIGHT_DETECT_MIN_HEIGHT          8
 182
 183 #endif /* VNC_ENCODING_TIGHT_H */