[qemu.git] / ui / vnc-enc-tight.h

/*
 * QEMU VNC display driver: tight encoding
 *
 * From libvncserver/rfb/rfbproto.h
 * Copyright (C) 2005 Rohit Kumar, Johannes E. Schindelin
 * Copyright (C) 2000-2002 Constantin Kaplinsky.  All Rights Reserved.
 * Copyright (C) 2000 Tridia Corporation.  All Rights Reserved.
 * Copyright (C) 1999 AT&T Laboratories Cambridge.  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 AUTHORS OR 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.
 */

#ifndef VNC_ENCODING_TIGHT_H
#define VNC_ENCODING_TIGHT_H

/*- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 * Tight Encoding.
 *
 *-- The first byte of each Tight-encoded rectangle is a "compression control
 *   byte". Its format is as follows (bit 0 is the least significant one):
 *
 *   bit 0:    if 1, then compression stream 0 should be reset;
 *   bit 1:    if 1, then compression stream 1 should be reset;
 *   bit 2:    if 1, then compression stream 2 should be reset;
 *   bit 3:    if 1, then compression stream 3 should be reset;
 *   bits 7-4: if 1000 (0x08), then the compression type is "fill",
 *             if 1001 (0x09), then the compression type is "jpeg",
 *             if 1010 (0x0A), then the compression type is "png",
 *             if 0xxx, then the compression type is "basic",
 *             values greater than 1010 are not valid.
 *
 * If the compression type is "basic", then bits 6..4 of the
 * compression control byte (those xxx in 0xxx) specify the following:
 *
 *   bits 5-4:  decimal representation is the index of a particular zlib
 *              stream which should be used for decompressing the data;
 *   bit 6:     if 1, then a "filter id" byte is following this byte.
 *
 *-- The data that follows after the compression control byte described
 * above depends on the compression type ("fill", "jpeg", "png" or "basic").
 *
 *-- If the compression type is "fill", then the only pixel value follows, in
 * client pixel format (see NOTE 1). This value applies to all pixels of the
 * rectangle.
 *
 *-- If the compression type is "jpeg" or "png", the following data stream
 * looks like this:
 *
 *   1..3 bytes:  data size (N) in compact representation;
 *   N bytes:     JPEG or PNG image.
 *
 * Data size is compactly represented in one, two or three bytes, according
 * to the following scheme:
 *
 *  0xxxxxxx                    (for values 0..127)
 *  1xxxxxxx 0yyyyyyy           (for values 128..16383)
 *  1xxxxxxx 1yyyyyyy zzzzzzzz  (for values 16384..4194303)
 *
 * Here each character denotes one bit, xxxxxxx are the least significant 7
 * bits of the value (bits 0-6), yyyyyyy are bits 7-13, and zzzzzzzz are the
 * most significant 8 bits (bits 14-21). For example, decimal value 10000
 * should be represented as two bytes: binary 10010000 01001110, or
 * hexadecimal 90 4E.
 *
 *-- If the compression type is "basic" and bit 6 of the compression control
 * byte was set to 1, then the next (second) byte specifies "filter id" which
 * tells the decoder what filter type was used by the encoder to pre-process
 * pixel data before the compression. The "filter id" byte can be one of the
 * following:
 *
 *   0:  no filter ("copy" filter);
 *   1:  "palette" filter;
 *   2:  "gradient" filter.
 *
 *-- If bit 6 of the compression control byte is set to 0 (no "filter id"
 * byte), or if the filter id is 0, then raw pixel values in the client
 * format (see NOTE 1) will be compressed. See below details on the
 * compression.
 *
 *-- The "gradient" filter pre-processes pixel data with a simple algorithm
 * which converts each color component to a difference between a "predicted"
 * intensity and the actual intensity. Such a technique does not affect
 * uncompressed data size, but helps to compress photo-like images better.
 * Pseudo-code for converting intensities to differences is the following:
 *
 *   P[i,j] := V[i-1,j] + V[i,j-1] - V[i-1,j-1];
 *   if (P[i,j] < 0) then P[i,j] := 0;
 *   if (P[i,j] > MAX) then P[i,j] := MAX;
 *   D[i,j] := V[i,j] - P[i,j];
 *
 * Here V[i,j] is the intensity of a color component for a pixel at
 * coordinates (i,j). MAX is the maximum value of intensity for a color
 * component.
 *
 *-- The "palette" filter converts true-color pixel data to indexed colors
 * and a palette which can consist of 2..256 colors. If the number of colors
 * is 2, then each pixel is encoded in 1 bit, otherwise 8 bits is used to
 * encode one pixel. 1-bit encoding is performed such way that the most
 * significant bits correspond to the leftmost pixels, and each raw of pixels
 * is aligned to the byte boundary. When "palette" filter is used, the
 * palette is sent before the pixel data. The palette begins with an unsigned
 * byte which value is the number of colors in the palette minus 1 (i.e. 1
 * means 2 colors, 255 means 256 colors in the palette). Then follows the
 * palette itself which consist of pixel values in client pixel format (see
 * NOTE 1).
 *
 *-- The pixel data is compressed using the zlib library. But if the data
 * size after applying the filter but before the compression is less then 12,
 * then the data is sent as is, uncompressed. Four separate zlib streams
 * (0..3) can be used and the decoder should read the actual stream id from
 * the compression control byte (see NOTE 2).
 *
 * If the compression is not used, then the pixel data is sent as is,
 * otherwise the data stream looks like this:
 *
 *   1..3 bytes:  data size (N) in compact representation;
 *   N bytes:     zlib-compressed data.
 *
 * Data size is compactly represented in one, two or three bytes, just like
 * in the "jpeg" compression method (see above).
 *
 *-- NOTE 1. If the color depth is 24, and all three color components are
 * 8-bit wide, then one pixel in Tight encoding is always represented by
 * three bytes, where the first byte is red component, the second byte is
 * green component, and the third byte is blue component of the pixel color
 * value. This applies to colors in palettes as well.
 *
 *-- NOTE 2. The decoder must reset compression streams' states before
 * decoding the rectangle, if some of bits 0,1,2,3 in the compression control
 * byte are set to 1. Note that the decoder must reset zlib streams even if
 * the compression type is "fill", "jpeg" or "png".
 *
 *-- NOTE 3. The "gradient" filter and "jpeg" compression may be used only
 * when bits-per-pixel value is either 16 or 32, not 8.
 *
 *-- NOTE 4. The width of any Tight-encoded rectangle cannot exceed 2048
 * pixels. If a rectangle is wider, it must be split into several rectangles
 * and each one should be encoded separately.
 *
 */

#define VNC_TIGHT_EXPLICIT_FILTER       0x04
#define VNC_TIGHT_FILL                  0x08
#define VNC_TIGHT_JPEG                  0x09
#define VNC_TIGHT_PNG                   0x0A
#define VNC_TIGHT_MAX_SUBENCODING       0x0A

/* Filters to improve compression efficiency */
#define VNC_TIGHT_FILTER_COPY             0x00
#define VNC_TIGHT_FILTER_PALETTE          0x01
#define VNC_TIGHT_FILTER_GRADIENT         0x02

/* Note: The following constant should not be changed. */
#define VNC_TIGHT_MIN_TO_COMPRESS 12

/* The parameters below may be adjusted. */
#define VNC_TIGHT_MIN_SPLIT_RECT_SIZE     4096
#define VNC_TIGHT_MIN_SOLID_SUBRECT_SIZE  2048
#define VNC_TIGHT_MAX_SPLIT_TILE_SIZE       16

#define VNC_TIGHT_JPEG_MIN_RECT_SIZE      4096
#define VNC_TIGHT_DETECT_SUBROW_WIDTH        7
#define VNC_TIGHT_DETECT_MIN_WIDTH           8
#define VNC_TIGHT_DETECT_MIN_HEIGHT          8

#endif /* VNC_ENCODING_TIGHT_H */
Commit	Line	Data
380282b0 CC	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",
efe556ad	45	* if 1010 (0x0A), then the compression type is "png",
380282b0	46	* if 0xxx, then the compression type is "basic",
efe556ad	47	* values greater than 1010 are not valid.
380282b0 CC	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
efe556ad	57	* above depends on the compression type ("fill", "jpeg", "png" or "basic").
380282b0 CC	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	*
efe556ad CC	63	*-- If the compression type is "jpeg" or "png", the following data stream
efe556ad CC	64	* looks like this:
380282b0 CC	65	*
380282b0 CC	66	* 1..3 bytes: data size (N) in compact representation;
efe556ad	67	* N bytes: JPEG or PNG image.
380282b0 CC	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
efe556ad	148	* the compression type is "fill", "jpeg" or "png".
380282b0 CC	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
efe556ad CC	162	#define VNC_TIGHT_PNG 0x0A
efe556ad CC	163	#define VNC_TIGHT_MAX_SUBENCODING 0x0A
380282b0 CC	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
2f6f5c7a CC	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
380282b0	183	#endif /* VNC_ENCODING_TIGHT_H */