File: spice_protocol.html

package info (click to toggle)
spice 0.16.0-1
links: PTS, VCS
area: main
in suites: forky, sid
size: 9,460 kB
sloc: ansic: 43,305; cpp: 30,185; sh: 5,342; python: 3,040; makefile: 844
file content (5009 lines) | stat: -rw-r--r-- 181,833 bytes
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 10.2.0" />
<title>Spice Protocol</title>
<style type="text/css">
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */

/* Default font. */
body {
  font-family: Georgia,serif;
}

/* Title font. */
h1, h2, h3, h4, h5, h6,
div.title, caption.title,
thead, p.table.header,
#toctitle,
#author, #revnumber, #revdate, #revremark,
#footer {
  font-family: Arial,Helvetica,sans-serif;
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
  color: navy;
}

strong {
  font-weight: bold;
  color: #083194;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1, h2, h3 {
  border-bottom: 2px solid silver;
}
h2 {
  padding-top: 0.5em;
}
h3 {
  float: left;
}
h3 + * {
  clear: left;
}
h5 {
  font-size: 1.0em;
}

div.sectionbody {
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

ul, ol, li > p {
  margin-top: 0;
}
ul > li     { color: #aaa; }
ul > li > * { color: black; }

.monospaced, code, pre {
  font-family: "Courier New", Courier, monospace;
  font-size: inherit;
  color: navy;
  padding: 0;
  margin: 0;
}
pre {
  white-space: pre-wrap;
}

#author {
  color: #527bbd;
  font-weight: bold;
  font-size: 1.1em;
}
#email {
}
#revnumber, #revdate, #revremark {
}

#footer {
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.0em;
  margin-bottom: 2.0em;
  margin-right: 10%;
  color: #606060;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #527bbd;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid #dddddd;
  border-left: 4px solid #f0f0f0;
  padding: 0.5em;
}

div.listingblock > div.content {
  border: 1px solid #dddddd;
  border-left: 5px solid #f0f0f0;
  background: #f8f8f8;
  padding: 0.5em;
}

div.quoteblock, div.verseblock {
  padding-left: 1.0em;
  margin-left: 1.0em;
  margin-right: 10%;
  border-left: 5px solid #f0f0f0;
  color: #888;
}

div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock > pre.content {
  font-family: inherit;
  font-size: inherit;
}
div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 3px solid #dddddd;
}

div.exampleblock > div.content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; vertical-align: text-bottom; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
ol.arabic {
  list-style-type: decimal;
}
ol.loweralpha {
  list-style-type: lower-alpha;
}
ol.upperalpha {
  list-style-type: upper-alpha;
}
ol.lowerroman {
  list-style-type: lower-roman;
}
ol.upperroman {
  list-style-type: upper-roman;
}

div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
}

tfoot {
  font-weight: bold;
}
td > div.verse {
  white-space: pre;
}

div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hdlist tr {
  padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
}
td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
}
td.hdlist2 {
  vertical-align: top;
}
div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
}

.comment {
  background: yellow;
}

.footnote, .footnoteref {
  font-size: 0.8em;
}

span.footnote, span.footnoteref {
  vertical-align: super;
}

#footnotes {
  margin: 20px 0 20px 0;
  padding: 7px 0 0 0;
}

#footnotes div.footnote {
  margin: 0 0 5px 0;
}

#footnotes hr {
  border: none;
  border-top: 1px solid silver;
  height: 1px;
  text-align: left;
  margin-left: 0;
  width: 20%;
  min-width: 100px;
}

div.colist td {
  padding-right: 0.5em;
  padding-bottom: 0.3em;
  vertical-align: top;
}
div.colist td img {
  margin-top: 0.3em;
}

@media print {
  #footer-badges { display: none; }
}

#toc {
  margin-bottom: 2.5em;
}

#toctitle {
  color: #527bbd;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}

span.aqua { color: aqua; }
span.black { color: black; }
span.blue { color: blue; }
span.fuchsia { color: fuchsia; }
span.gray { color: gray; }
span.green { color: green; }
span.lime { color: lime; }
span.maroon { color: maroon; }
span.navy { color: navy; }
span.olive { color: olive; }
span.purple { color: purple; }
span.red { color: red; }
span.silver { color: silver; }
span.teal { color: teal; }
span.white { color: white; }
span.yellow { color: yellow; }

span.aqua-background { background: aqua; }
span.black-background { background: black; }
span.blue-background { background: blue; }
span.fuchsia-background { background: fuchsia; }
span.gray-background { background: gray; }
span.green-background { background: green; }
span.lime-background { background: lime; }
span.maroon-background { background: maroon; }
span.navy-background { background: navy; }
span.olive-background { background: olive; }
span.purple-background { background: purple; }
span.red-background { background: red; }
span.silver-background { background: silver; }
span.teal-background { background: teal; }
span.white-background { background: white; }
span.yellow-background { background: yellow; }

span.big { font-size: 2em; }
span.small { font-size: 0.6em; }

span.underline { text-decoration: underline; }
span.overline { text-decoration: overline; }
span.line-through { text-decoration: line-through; }

div.unbreakable { page-break-inside: avoid; }


/*
 * xhtml11 specific
 *
 * */

div.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.tableblock > table {
  border: 3px solid #527bbd;
}
thead, p.table.header {
  font-weight: bold;
  color: #527bbd;
}
p.table {
  margin-top: 0;
}
/* Because the table frame attribute is overridden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
  border-style: none;
}
div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
}


/*
 * html5 specific
 *
 * */

table.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
thead, p.tableblock.header {
  font-weight: bold;
  color: #527bbd;
}
p.tableblock {
  margin-top: 0;
}
table.tableblock {
  border-width: 3px;
  border-spacing: 0px;
  border-style: solid;
  border-color: #527bbd;
  border-collapse: collapse;
}
th.tableblock, td.tableblock {
  border-width: 1px;
  padding: 4px;
  border-style: solid;
  border-color: #527bbd;
}

table.tableblock.frame-topbot {
  border-left-style: hidden;
  border-right-style: hidden;
}
table.tableblock.frame-sides {
  border-top-style: hidden;
  border-bottom-style: hidden;
}
table.tableblock.frame-none {
  border-style: hidden;
}

th.tableblock.halign-left, td.tableblock.halign-left {
  text-align: left;
}
th.tableblock.halign-center, td.tableblock.halign-center {
  text-align: center;
}
th.tableblock.halign-right, td.tableblock.halign-right {
  text-align: right;
}

th.tableblock.valign-top, td.tableblock.valign-top {
  vertical-align: top;
}
th.tableblock.valign-middle, td.tableblock.valign-middle {
  vertical-align: middle;
}
th.tableblock.valign-bottom, td.tableblock.valign-bottom {
  vertical-align: bottom;
}


/*
 * manpage specific
 *
 * */

body.manpage h1 {
  padding-top: 0.5em;
  padding-bottom: 0.5em;
  border-top: 2px solid silver;
  border-bottom: 2px solid silver;
}
body.manpage h2 {
  border-style: none;
}
body.manpage div.sectionbody {
  margin-left: 3em;
}

@media print {
  body.manpage div#toc { display: none; }
}


</style>
<script type="text/javascript">
/*<![CDATA[*/
var asciidoc = {  // Namespace.

/////////////////////////////////////////////////////////////////////
// Table Of Contents generator
/////////////////////////////////////////////////////////////////////

/* Author: Mihai Bazon, September 2002
 * http://students.infoiasi.ro/~mishoo
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */
 /* modified by Stuart Rackham, 2006, 2009. License: GPL */

// toclevels = 1..4.
toc: function (toclevels) {

  function getText(el) {
    var text = "";
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
        text += i.data;
      else if (i.firstChild != null)
        text += getText(i);
    }
    return text;
  }

  function TocEntry(el, text, toclevel) {
    this.element = el;
    this.text = text;
    this.toclevel = toclevel;
  }

  function tocEntries(el, toclevels) {
    var result = new Array;
    var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
    // Function that scans the DOM tree for header elements (the DOM2
    // nodeIterator API would be a better technique but not supported by all
    // browsers).
    var iterate = function (el) {
      for (var i = el.firstChild; i != null; i = i.nextSibling) {
        if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
          var mo = re.exec(i.tagName);
          if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
            result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
          }
          iterate(i);
        }
      }
    }
    iterate(el);
    return result;
  }

  var toc = document.getElementById("toc");
  if (!toc) {
    return;
  }

  // Delete existing TOC entries in case we're reloading the TOC.
  var tocEntriesToRemove = [];
  var i;
  for (i = 0; i < toc.childNodes.length; i++) {
    var entry = toc.childNodes[i];
    if (entry.nodeName.toLowerCase() == 'div'
     && entry.getAttribute("class")
     && entry.getAttribute("class").match(/^toclevel/))
      tocEntriesToRemove.push(entry);
  }
  for (i = 0; i < tocEntriesToRemove.length; i++) {
    toc.removeChild(tocEntriesToRemove[i]);
  }

  // Rebuild TOC entries.
  var entries = tocEntries(document.getElementById("content"), toclevels);
  for (var i = 0; i < entries.length; ++i) {
    var entry = entries[i];
    if (entry.element.id == "")
      entry.element.id = "_toc_" + i;
    var a = document.createElement("a");
    a.href = "#" + entry.element.id;
    a.appendChild(document.createTextNode(entry.text));
    var div = document.createElement("div");
    div.appendChild(a);
    div.className = "toclevel" + entry.toclevel;
    toc.appendChild(div);
  }
  if (entries.length == 0)
    toc.parentNode.removeChild(toc);
},


/////////////////////////////////////////////////////////////////////
// Footnotes generator
/////////////////////////////////////////////////////////////////////

/* Based on footnote generation code from:
 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 */

footnotes: function () {
  // Delete existing footnote entries in case we're reloading the footnodes.
  var i;
  var noteholder = document.getElementById("footnotes");
  if (!noteholder) {
    return;
  }
  var entriesToRemove = [];
  for (i = 0; i < noteholder.childNodes.length; i++) {
    var entry = noteholder.childNodes[i];
    if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
      entriesToRemove.push(entry);
  }
  for (i = 0; i < entriesToRemove.length; i++) {
    noteholder.removeChild(entriesToRemove[i]);
  }

  // Rebuild footnote entries.
  var cont = document.getElementById("content");
  var spans = cont.getElementsByTagName("span");
  var refs = {};
  var n = 0;
  for (i=0; i<spans.length; i++) {
    if (spans[i].className == "footnote") {
      n++;
      var note = spans[i].getAttribute("data-note");
      if (!note) {
        // Use [\s\S] in place of . so multi-line matches work.
        // Because JavaScript has no s (dotall) regex flag.
        note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
        spans[i].innerHTML =
          "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
        spans[i].setAttribute("data-note", note);
      }
      noteholder.innerHTML +=
        "<div class='footnote' id='_footnote_" + n + "'>" +
        "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
        n + "</a>. " + note + "</div>";
      var id =spans[i].getAttribute("id");
      if (id != null) refs["#"+id] = n;
    }
  }
  if (n == 0)
    noteholder.parentNode.removeChild(noteholder);
  else {
    // Process footnoterefs.
    for (i=0; i<spans.length; i++) {
      if (spans[i].className == "footnoteref") {
        var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
        href = href.match(/#.*/)[0];  // Because IE return full URL.
        n = refs[href];
        spans[i].innerHTML =
          "[<a href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
      }
    }
  }
},

install: function(toclevels) {
  var timerId;

  function reinstall() {
    asciidoc.footnotes();
    if (toclevels) {
      asciidoc.toc(toclevels);
    }
  }

  function reinstallAndRemoveTimer() {
    clearInterval(timerId);
    reinstall();
  }

  timerId = setInterval(reinstall, 500);
  if (document.addEventListener)
    document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
  else
    window.onload = reinstallAndRemoveTimer;
}

}
asciidoc.install(2);
/*]]>*/
</script>
</head>
<body class="article">
<div id="header">
<h1>Spice Protocol</h1>
<span id="revnumber">version v1.0,</span>
<span id="revdate">01.01.2009</span>
<br /><span id="revremark">Draft 1</span>
<div id="toc">
  <div id="toctitle">Table of Contents</div>
  <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph"><p>Copyright &#169; 2009 Red Hat, Inc.<br />
Licensed under a Creative Commons Attribution-Share Alike 3.0<br />
United States License (see
<a href="http://creativecommons.org/licenses/by-sa/3.0/us/legalcode">http://creativecommons.org/licenses/by-sa/3.0/us/legalcode</a>)<br /></p></div>
</div>
</div>
<div class="sect1">
<h2 id="_introduction">1. Introduction</h2>
<div class="sectionbody">
<div class="paragraph"><p>Spice protocol defines a set of protocol messages for accessing, controlling,
and receiving inputs from remote computing devices (e.g., keyboard, video,
mouse) across networks, and sending output to them. A controlled device can
reside on either side, client and/or server. In addition, the protocol defines
a set of calls for supporting migration of a remote server from one  network
address to another. Encryption of transported data, with one exception, was
kept out of the protocol for maximum flexibility in choosing an encryption
method. Spice uses simple messaging and does not depend on any  RPC standard or
a specific transport layer.</p></div>
<div class="paragraph"><p>Spice communication session is split into multiple communication channels
(e.g., every channel is a remote device) in order to have the ability to
control communication and execution of messages according to the channel type
(e.g. QoS encryption), and to add and remove  communication channels during run
time (which is supported by spice protocol definition). The following
communication channels are defined in the current protocol definition: a). the
main channel serves as the main spice session connection  b). display channel
for receiving remote display updates c). inputs channel for sending mouse and
keyboard events d). cursor channel for receiving pointer shape and position e).
Playback channel for receiving audio stream, and f). Record channel for sending
audio capture. More channel types will be added as the protocol evolves. Spice
also defines a set of protocol definitions for synchronizing channels`
execution on the remote site.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_common_protocol_definition">2. Common Protocol definition</h2>
<div class="sectionbody">
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Endianness
</p>
<div class="paragraph"><p>Unless stated otherwise, all data structures are packed and byte and bit order
is in little endian format.</p></div>
</li>
<li>
<p>
Data types
</p>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
UINT8 – 8 bits unsigned integer
</p>
</li>
<li>
<p>
INT16 – 16 bits signed integer
</p>
</li>
<li>
<p>
UINT16 – 16 bits unsigned  integer
</p>
</li>
<li>
<p>
UINT32 – 32 bits unsigned  integer
</p>
</li>
<li>
<p>
INT32 - 32 bits signed integer
</p>
</li>
<li>
<p>
UINT64 – 64 bits unsigned  integer
</p>
</li>
<li>
<p>
SPICE_ADDRESS - 64 bits unsigned integer, value is the offset of the addressed
data from the beginning of spice protocol message body (i.e., data following
SpiceDataHeader or SpicedSubMessage).
</p>
</li>
<li>
<p>
SPICE_FIXED28_4 – 32 bits fixed point number. 28 high bits are signed integer. Low
4 bits is unsigned integer numerator of a fraction with denominator 16.
</p>
</li>
<li>
<p>
POINT
</p>
<div class="paragraph"><p>INT32 x<br />
INT32 y<br /></p></div>
</li>
<li>
<p>
POINT16
</p>
<div class="paragraph"><p>INT16 x<br />
INT16 y<br /></p></div>
</li>
<li>
<p>
RECT
</p>
<div class="paragraph"><p>INT32 top<br />
INT32 left<br />
INT32 bottom<br />
INT32 right<br /></p></div>
</li>
<li>
<p>
POINTFIX
</p>
<div class="paragraph"><p>SPICE_FIXED28_4 x<br />
SPICE_FIXED28_4 y<br /></p></div>
</li>
</ol></div>
</li>
<li>
<p>
Protocol Magic number UINT8[4]
</p>
<div class="paragraph"><p>SPICE_MAGIC = { 0x52, 0x45, 0x44,  0x51} // "REDQ"</p></div>
</li>
<li>
<p>
Protocol version
</p>
<div class="paragraph"><p>Protocol version defined as  two UINT32 values, major protocol version and
minor protocol version. Server and client having the same major version must
keep compatibility regardless of minor version (i.e., incrementing the major
version brakes compatibility). Major protocol version with "huge" value are
reserved for development purposes and are considered unsupported and
unreliable. "huge" values are defined as having bit 31 set. The minor protocol
version is incremented on every protocol change that does not break
compatibility. It is  set to zero on  major protocol version increment.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
Current Protocol version
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_VERSION_MAJOR <span style="color: #990000">=</span> <span style="color: #993399">2</span>
SPICE_VERSION_MINOR <span style="color: #990000">=</span> <span style="color: #993399">2</span></tt></pre></div></div>
</li>
</ol></div>
</li>
<li>
<p>
Compatibility – UINT32[]
</p>
<div class="paragraph"><p>In order to allow some degree of flexibility in client and server
implementation and in order to improve compatibility, spice protocol supports
bidirectional exchange of channels compatibilities. Compatibilities are
expressed in UINT32 vector that is split into two groups: common
compatibilities and channels compatibilities. Common compatibilities stands for
compatibilities shared by all channels, and  channels compatibilities stands
for channel specific compatibilities. Splitting the vector into two types
allows us to add channel compatibilities independently. Each compatibility is
expressed using one or more bits in the compatibilities vector.
For example capability 0 will be the low bit of the first (index 0) UINT32.</p></div>
</li>
<li>
<p>
Channel types – UINT8
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_CHANNEL_MAIN      <span style="color: #990000">=</span> <span style="color: #993399">1</span>
SPICE_CHANNEL_DISPLAY   <span style="color: #990000">=</span> <span style="color: #993399">2</span>
SPICE_CHANNEL_INPUTS    <span style="color: #990000">=</span> <span style="color: #993399">3</span>
SPICE_CHANNEL_CURSOR    <span style="color: #990000">=</span> <span style="color: #993399">4</span>
SPICE_CHANNEL_PLAYBACK  <span style="color: #990000">=</span> <span style="color: #993399">5</span>
SPICE_CHANNEL_RECORD    <span style="color: #990000">=</span> <span style="color: #993399">6</span>
SPICE_CHANNEL_TUNNEL    <span style="color: #990000">=</span> <span style="color: #993399">7</span> <span style="font-style: italic"><span style="color: #9A1900">// obsolete</span></span>
SPICE_CHANNEL_SMARTCARD <span style="color: #990000">=</span> <span style="color: #993399">8</span>
SPICE_CHANNEL_USBREDIR  <span style="color: #990000">=</span> <span style="color: #993399">9</span>
SPICE_CHANNEL_PORT              <span style="color: #990000">=</span> <span style="color: #993399">10</span>
SPICE_CHANNEL_WEBDAV    <span style="color: #990000">=</span> <span style="color: #993399">11</span></tt></pre></div></div>
</li>
<li>
<p>
Error codes UINT32
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_LINK_ERR_OK                       <span style="color: #990000">=</span> <span style="color: #993399">0</span>
SPICE_LINK_ERR_ERROR                    <span style="color: #990000">=</span> <span style="color: #993399">1</span>
SPICE_LINK_ERR_INVALID_MAGIC            <span style="color: #990000">=</span> <span style="color: #993399">2</span>
SPICE_LINK_ERR_INVALID_DATA             <span style="color: #990000">=</span> <span style="color: #993399">3</span>
SPICE_LINK_ERR_VERSION_MISMATCH         <span style="color: #990000">=</span> <span style="color: #993399">4</span>
SPICE_LINK_ERR_NEED_SECURED             <span style="color: #990000">=</span> <span style="color: #993399">5</span>
SPICE_LINK_ERR_NEED_UNSECURED           <span style="color: #990000">=</span> <span style="color: #993399">6</span>
SPICE_LINK_ERR_PERMISSION_DENIED        <span style="color: #990000">=</span> <span style="color: #993399">7</span>
SPICE_LINK_ERR_BAD_CONNECTION_ID        <span style="color: #990000">=</span> <span style="color: #993399">8</span>
SPICE_LINK_ERR_CHANNEL_NOT_AVAILABLE    <span style="color: #990000">=</span> <span style="color: #993399">9</span></tt></pre></div></div>
</li>
<li>
<p>
Warning codes
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_WARN_GENERAL                              <span style="color: #990000">=</span> <span style="color: #993399">0</span></tt></pre></div></div>
</li>
<li>
<p>
Information codes
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_INFO_GENERAL                              <span style="color: #990000">=</span> <span style="color: #993399">0</span></tt></pre></div></div>
</li>
<li>
<p>
public key buffer size.
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_TICKET_PUBKEY_BYTES <span style="color: #990000">=</span> <span style="color: #993399">162</span> <span style="font-style: italic"><span style="color: #9A1900">/* size needed for holding 1024 bit RSA public</span></span>
<span style="font-style: italic"><span style="color: #9A1900">key in X.509 SubjectPublicKeyInfo format. */</span></span></tt></pre></div></div>
</li>
<li>
<p>
Channel link: establishing a channel connection.
</p>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
Connection process
</p>
<div class="paragraph"><p>The channel connection process is initiated by the client. The client sends
SpiceLinkMess. In response, the server sends SpiceLinkReply. When the client
receives  SpiceLinkReply, it examines the error code and in case there is no
error it encrypts its password with public key received in SpiceLinkReply and
sends it to the server. The server receive the password and sends the link
result to the client. The client examines the link result, and in case the
result equals to SPICE_LINK_ERR_OK, a valid connection is established.</p></div>
<div class="paragraph"><p>Channel connection for channel types other then SPICE_CHANNEL_MAIN is allowed
only after the client has active SPICE_CHANNEL_MAIN channel connection.  Only one
SPICE_CHANNEL_MAIN connection is allowed, and this channel connection establishes
spice session with the remote server.</p></div>
</li>
<li>
<p>
Ticketing
</p>
<div class="paragraph"><p>Ticketing is a mechanism implemented in spice to ensure connections are opened
only from authorized sources. To enable this mechanism a ticket is set in spice
server consisting of a password and time validity. After time validity passes,
the whole ticket is expired. The ticket is encrypted. To encrypt, server
generates a 1024 bit RSA key and send the public part to the client (via
RedLinkInfo). Client uses this key to encrypt the password and send it back to
server (after SpiceLinkMess). Server decrypt the password, compare it to ticket
and ensure it was received within the allowed time-frame.</p></div>
</li>
<li>
<p>
SpiceLinkMess definition.
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 magic</p></td>
<td align="left" valign="top"><p class="table">value of this fields must be equal to SPICE_MAGIC</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 major_version</p></td>
<td align="left" valign="top"><p class="table">value of this fields must be equal to SPICE_VERSION_MAJOR</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 minor_version</p></td>
<td align="left" valign="top"><p class="table">value of this fields must be equal to SPICE_VERSION_MINOR</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 size</p></td>
<td align="left" valign="top"><p class="table">number of bytes following this field to the end of this message.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 connection_id</p></td>
<td align="left" valign="top"><p class="table">In case of a new session (i.e., channel type is SPICE_CHANNEL_MAIN) this field
is set to zero, and in response the server will allocate session id and will
send it via the SpiceLinkReply message. In case of all other channel types, this
field will be equal to the allocated session id.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8 channel_type</p></td>
<td align="left" valign="top"><p class="table">one of SPICE_CHANNEL_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8 channel_id</p></td>
<td align="left" valign="top"><p class="table">channel id to connect to. This enables having multiple channels of the same
type.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 num_common_caps</p></td>
<td align="left" valign="top"><p class="table">number of common client channel capabilities words</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 num_channel_caps</p></td>
<td align="left" valign="top"><p class="table">number of specific client channel capabilities words</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 caps_offset</p></td>
<td align="left" valign="top"><p class="table">location of the start of the capabilities vector given by the bytes offset
from the “ size” member (i.e., from the address of the “connection_id” member).</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SpiceLinkReply  definition
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 magic</p></td>
<td align="left" valign="top"><p class="table">value of this field must be equal to SPICE_MAGIC</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 major_version</p></td>
<td align="left" valign="top"><p class="table">server major protocol version.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 minor_version</p></td>
<td align="left" valign="top"><p class="table">server minor protocol version.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 size</p></td>
<td align="left" valign="top"><p class="table">number of bytes following this field to the end of this message.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32  error</p></td>
<td align="left" valign="top"><p class="table">Error codes (i.e., SPICE_LINK_ERR_?)</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8[SPICE_TICKET_PUBKEY_BYTES]  pub_key</p></td>
<td align="left" valign="top"><p class="table">1024 bit RSA public key in X.509 SubjectPublicKeyInfo format.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 num_common_caps</p></td>
<td align="left" valign="top"><p class="table">number of common server channel capabilities words</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 num_channel_caps</p></td>
<td align="left" valign="top"><p class="table">number of specific server channel capabilities words</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 caps_offset</p></td>
<td align="left" valign="top"><p class="table">location of the start of the capabilities vector given by the bytes offset
from the “ size” member (i.e., from the address of
the “connection_id” member)</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
Encrypted Password
</p>
<div class="paragraph"><p>Client sends RSA encrypted password, with public key received from server (in
SpiceLinkReply). Format is EME-OAEP as described in PKCS#1 v2.0 with SHA-1, MGF1
and an empty encoding parameter.</p></div>
</li>
<li>
<p>
Link Result UINT32
</p>
<div class="paragraph"><p>The server sends link result error code (i.e., SPICE_LINK_ERR_?)</p></div>
</li>
</ol></div>
</li>
<li>
<p>
Protocol message definition
</p>
<div class="paragraph"><p>All messages transmitted after the link stage have a common message layout. It
begins with SpiceDataHeader which describes one main message and an optional sub
messages list.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
SpiceDataHeader
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT64 serial</p></td>
<td align="left" valign="top"><p class="table">serial number of the message within the channel.  Serial numbers start with a
value of 1 and are incremented on every message transmitted.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT16 type</p></td>
<td align="left" valign="top"><p class="table">message type can be one that is  accepted by all channel (e.g., SPICE_MSG_MIGRATE),
or specific to a channel type (e.g., SPICE_MSG_DISPLAY_MODE for display channel).</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 size</p></td>
<td align="left" valign="top"><p class="table">size of the message body in bytes. In case sub_list (see below) is not zero
then the actual main message size is sub_list. The message body follows
SpiceDataHeader</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32  sub_list</p></td>
<td align="left" valign="top"><p class="table">optional sub-messages list. If this field is not zero then sub_list is the
offset in bytes to SpiceSubMessageList from the end of SpiceDataHeader.  All
sub-messages need to be executed before the main message, and in the order they
appear in the sub-messageslist.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SpiceSubMessageList
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT16 size</p></td>
<td align="left" valign="top"><p class="table">number of sub-messages in this list.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32[]  sub_messages</p></td>
<td align="left" valign="top"><p class="table">array of offsets to sub message, offset is number of bytes from the end of
SpiceDataHeader to start of SpicedSubMessage.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SpicedSubMessage
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT16  type</p></td>
<td align="left" valign="top"><p class="table">message type can be one that is  accepted by all channel (e.g., SPICE_MSG_MIGRATE),
or specific to a channel type (e.g., SPICE_MSG_DISPLAY_MODE for display channel).</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 size</p></td>
<td align="left" valign="top"><p class="table">size of the message body in bytes.  The message body follows SpicedSubMessage.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
</ol></div>
</li>
<li>
<p>
Common messages and messaging naming convention
</p>
<div class="paragraph"><p>Messages types and message body structures  are prefixed according to the
source of the message. The prefixes for messages sent from the server to the
client are SPICE_MSG for types and SpiceMsg for structures. For messages sent from the
client the prefixes are SPICE_MSGC and SpiceMsgc.</p></div>
</li>
<li>
<p>
Server messages that are common to all channels
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_MSG_MIGRATE               <span style="color: #990000">=</span> <span style="color: #993399">1</span>
SPICE_MSG_MIGRATE_DATA          <span style="color: #990000">=</span> <span style="color: #993399">2</span>
SPICE_MSG_SET_ACK               <span style="color: #990000">=</span> <span style="color: #993399">3</span>
SPICE_MSG_PING                  <span style="color: #990000">=</span> <span style="color: #993399">4</span>
SPICE_MSG_WAIT_FOR_CHANNELS     <span style="color: #990000">=</span> <span style="color: #993399">5</span>
SPICE_MSG_DISCONNECTING         <span style="color: #990000">=</span> <span style="color: #993399">6</span>
SPICE_MSG_NOTIFY                <span style="color: #990000">=</span> <span style="color: #993399">7</span>

SPICE_MSG_FIRST_AVAIL   <span style="color: #990000">=</span> <span style="color: #993399">101</span></tt></pre></div></div>
<div class="paragraph"><p>Specific channel server messages start from SPICE_MSG_FIRST_AVAIL. All
message types from SPICE_MSG_NOTIFY + 1 to SPICE_MSG_FIRST_AVAIL – 1 are reserved
for further use.</p></div>
</li>
<li>
<p>
Client messages that are common to all channels
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_MSGC_ACK_SYNC                     <span style="color: #990000">=</span> <span style="color: #993399">1</span>
SPICE_MSGC_ACK                          <span style="color: #990000">=</span> <span style="color: #993399">2</span>
SPICE_MSGC_PONG                         <span style="color: #990000">=</span> <span style="color: #993399">3</span>
SPICE_MSGC_MIGRATE_FLUSH_MARK           <span style="color: #990000">=</span> <span style="color: #993399">4</span>
SPICE_MSGC_MIGRATE_DATA                 <span style="color: #990000">=</span> <span style="color: #993399">5</span>
SPICE_MSGC_DISCONNECTING                <span style="color: #990000">=</span> <span style="color: #993399">6</span>

SPICE_MSGC_FIRST_AVAIL          <span style="color: #990000">=</span> <span style="color: #993399">101</span></tt></pre></div></div>
<div class="paragraph"><p>Specific channel client messages start from SPICE_MSGC_FIRST_AVAIL. All
message types from SPICE_MSGC_ACK_SYNC+ 1 to SPICE_MSGC_FIRST_AVAIL – 1 are
reserved for further use.</p></div>
</li>
<li>
<p>
Messages acknowledgment.
</p>
<div class="paragraph"><p>Spice provides a set of messages for requesting an acknowledgment on every one
or more messages that the client consumes. In order to request acknowledgment
messages, the server sends  SPICE_MSG_SET_ACK with the requested acknowledgment
frequency – after how many received messages the client sends acknowledgment. .
In response, the client sends  SPICE_MSGC_ACK_SYNC. From this point, for every
requested number of messages that the client receive, it will send  a SPICE_MSGC_ACK
message.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
SPICE_MSG_SET_ACK, SpiceMsgSetAck
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 generation</p></td>
<td align="left" valign="top"><p class="table">the generation of the acknowledgment sequence. This value will be sent back by
SPICE_MSGC_ACK_SYNC. It is used for acknowledgment accounting synchronization.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 window</p></td>
<td align="left" valign="top"><p class="table">the window size. Spice client will send acknowledgment for every “window”
messages.  Zero window size will disable  messages acknowledgment.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSGC_ACK_SYNC, UINT32
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32</p></td>
<td align="left" valign="top"><p class="table">Spice client sends  SpiceMsgSetAck.generation in response to SPICE_MSG_SET_ACK</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSGC_ACK, VOID
</p>
<div class="paragraph"><p>Spice client sends  SPICE_MSGC_ACK message for every SpiceMsgSetAck.window messages it
consumes.</p></div>
</li>
</ol></div>
</li>
<li>
<p>
Ping
</p>
<div class="paragraph"><p>Spice protocol provides ping messages for debugging purpose. Spice server sends
SPICE_MSG_PING and the client responses with SPICE_MSGC_PONG. The server can measure round
trip time by subtracting current time with the time that is returned in
SPICE_MSGC_PONG message.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
SPICE_MSG_PING, SpiceMsgPing
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 id</p></td>
<td align="left" valign="top"><p class="table">the id of this message</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT64 time</p></td>
<td align="left" valign="top"><p class="table">time stamp of this message</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSGC_PONG, SpiceMsgPing
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 id</p></td>
<td align="left" valign="top"><p class="table">Spice client copies it from SpiceMsgPing.id</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT64 time</p></td>
<td align="left" valign="top"><p class="table">Spice client copies it from SpiceMsgPing.time</p></td>
</tr>
</tbody>
</table>
</div>
</li>
</ol></div>
</li>
<li>
<p>
Channel migration
</p>
<div class="paragraph"><p>Spice supports migration of Spice server. The following common messages
combined with specific main channel messages is used for migrating channels
connections between spice servers. We will refer these servers as source and
destination. Main channel is used for initiating and controlling the migration
process. The following describes the actual channel migration process.</p></div>
<div class="paragraph"><p>Channel migration process starts with sending SPICE_MSG_MIGRATE message from the
server. The client receives the message, examine the attached flags and: if the
server requests messages flush (i.e., SPICE_MIGRATE_NEED_FLUSH flag is on), the
client sends SPICE_MSGC_MIGRATE_FLUSH_MARK message to the server. This procedure can
be used to ensure safe delivery of all mid air messages before performing the
migration action.  if the server requests data transfer (i.e.,
SPICE_MIGRATE_NEED_DATA_TRANSFER flag is on), the client expects to receive one
last message from the server before migrating to destination. This message type
must be SPICE_MSG_MIGRATE_DATA type. The content of the received message will be
transmitted to the destination on connection swap.</p></div>
<div class="paragraph"><p>Afterward, the client swaps communication channels (i.e., starts using the
connection with the destination server). The client can close connection with
the source server only after all other channels also have finished the
migration process. If the server side has requested data transfer, the client
first transmits SPICE_MSGC_MIGRATE_DATA message containing the data received on
SPICE_MSG_MIGRATE_DATA.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
Migration flags
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_MIGRATE_NEED_FLUSH                        <span style="color: #990000">=</span> <span style="color: #993399">1</span>
SPICE_MIGRATE_NEED_DATA_TRANSFER                <span style="color: #990000">=</span> <span style="color: #993399">2</span></tt></pre></div></div>
</li>
<li>
<p>
SPICE_MSG_MIGRATE, SpiceMsgMigrate
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 flags</p></td>
<td align="left" valign="top"><p class="table">combination of SPICE migration flags.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="olist lowerroman"><ol class="lowerroman">
<li>
<p>
SPICE_MSG_MIGRATE_DATA, UINT8[]
</p>
<div class="paragraph"><p>Server migrate data, body of this message is variable length raw data that is
determined by each channel type independently</p></div>
</li>
<li>
<p>
SPICE_MSGC_MIGRATE_FLUSH_MARK, VOID
</p>
<div class="paragraph"><p>This messages mark completion of client communication channel flushing.</p></div>
</li>
</ol></div>
</li>
<li>
<p>
SPICE_MSGC_MIGRATE_DATA, UINT8[]
</p>
<div class="paragraph"><p>Post migration data, sent by client to the destination, containing the data
sent by the source using the SPICE_MSG_MIGRATE_DATA message.</p></div>
</li>
</ol></div>
</li>
<li>
<p>
Channel synchronization
</p>
<div class="paragraph" id="channel_sync"><p>Spice provides mechanism for synchronizing channels message execution on the
client side. The server sends SPICE_MSG_WAIT_FOR_CHANNELS message which contains a
list of channels messages to wait for (i.e., SpiceMsgWaitForChannels). The Spice
client will wait for completion of all the messages that are in that list
before executing any more messages.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
SpiceWaitForChannel
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT8 type</p></td>
<td align="left" valign="top"><p class="table">channel type (e.g., SPICE_CHANNEL_INPUTS)</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8 id</p></td>
<td align="left" valign="top"><p class="table">channel id.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UIN64 serial</p></td>
<td align="left" valign="top"><p class="table">message serial id (i.e, SpiceDataHeader.serial) to wait for</p></td>
</tr>
</tbody>
</table>
</div>
<div class="olist lowerroman"><ol class="lowerroman">
<li>
<p>
SPICE_MSG_WAIT_FOR_CHANNELS, SpiceMsgWaitForChannels
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT8 wait_count</p></td>
<td align="left" valign="top"><p class="table">number of items in wait_list</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">SpiceWaitForChannel[] wait_list</p></td>
<td align="left" valign="top"><p class="table">list of channels to wait for.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
</ol></div>
</li>
</ol></div>
</li>
<li>
<p>
Disconnect reason
</p>
<div class="paragraph"><p>The following messages are used for notification about orderly disconnection
of the server or client.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
SPICE_MSG_DISCONNECTING, SpiceMsgDisconnect
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT64 time_stamp</p></td>
<td align="left" valign="top"><p class="table">time stamp of disconnect action on the server.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 reason</p></td>
<td align="left" valign="top"><p class="table">disconnect reason, SPICE_LINK_ERR_?</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSGC_DISCONNECTING, SpiceMsgDisconnect
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT64 time_stamp</p></td>
<td align="left" valign="top"><p class="table">time stamp of disconnect action on the client.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 reason</p></td>
<td align="left" valign="top"><p class="table">disconnect reason, SPICE_LINK_ERR_?</p></td>
</tr>
</tbody>
</table>
</div>
</li>
</ol></div>
</li>
<li>
<p>
Server notification
</p>
<div class="paragraph"><p>Spice protocol defines message for delivering notifications to the client using
SPICE_MSG_NOTIFY message. Messages are categorized by severity and visibility. The
later can be used as hint for the way the message is displayed to the user. For
example high visibility notifications will trigger message box and low
visibility notifications will be directed to the log.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
SPICE_MSG_NOTIFY, SpiceMsgNotify
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT64 time_stamp</p></td>
<td align="left" valign="top"><p class="table">server side time stamp of this message.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 severity</p></td>
<td align="left" valign="top"><p class="table">one of SPICE_NOTIFY_SEVERITY_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 visibility</p></td>
<td align="left" valign="top"><p class="table">one of  SPICE_NOTIFY_VISIBILITY_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 what</p></td>
<td align="left" valign="top"><p class="table">one of SPICE_LINK_ERR_?, SPICE_WARN_? Or SPICE_INFO_?, depending on severity.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 message_len</p></td>
<td align="left" valign="top"><p class="table">size of message</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8[] message</p></td>
<td align="left" valign="top"><p class="table">message string in UTF8.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8 0</p></td>
<td align="left" valign="top"><p class="table">string zero termination</p></td>
</tr>
</tbody>
</table>
</div>
</li>
</ol></div>
</li>
</ol></div>
</div>
</div>
<div class="sect1">
<h2 id="_main_channel_definition">3. Main Channel definition</h2>
<div class="sectionbody">
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Server messages
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_MSG_MAIN_MIGRATE_BEGIN            <span style="color: #990000">=</span> <span style="color: #993399">101</span>
SPICE_MSG_MAIN_MIGRATE_CANCEL           <span style="color: #990000">=</span> <span style="color: #993399">102</span>
SPICE_MSG_MAIN_INIT                     <span style="color: #990000">=</span> <span style="color: #993399">103</span>
SPICE_MSG_MAIN_CHANNELS_LIST            <span style="color: #990000">=</span> <span style="color: #993399">104</span>
SPICE_MSG_MAIN_MOUSE_MODE               <span style="color: #990000">=</span> <span style="color: #993399">105</span>
SPICE_MSG_MAIN_MULTI_MEDIA_TIME         <span style="color: #990000">=</span> <span style="color: #993399">106</span>

SPICE_MSG_MAIN_AGENT_CONNECTED          <span style="color: #990000">=</span> <span style="color: #993399">107</span>
SPICE_MSG_MAIN_AGENT_DISCONNECTED       <span style="color: #990000">=</span> <span style="color: #993399">108</span>
SPICE_MSG_MAIN_AGENT_DATA               <span style="color: #990000">=</span> <span style="color: #993399">109</span>
SPICE_MSG_MAIN_AGENT_TOKEN              <span style="color: #990000">=</span> <span style="color: #993399">110</span></tt></pre></div></div>
</li>
<li>
<p>
Client messages
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_MSGC_MAIN_CLIENT_INFO             <span style="color: #990000">=</span> <span style="color: #993399">101</span>
SPICE_MSGC_MAIN_MIGRATE_CONNECTED       <span style="color: #990000">=</span> <span style="color: #993399">102</span>
SPICE_MSGC_MAIN_MIGRATE_CONNECT_ERROR   <span style="color: #990000">=</span> <span style="color: #993399">103</span>
SPICE_MSGC_MAIN_ATTACH_CHANNELS         <span style="color: #990000">=</span> <span style="color: #993399">104</span>
SPICE_MSGC_MAIN_MOUSE_MODE_REQUEST      <span style="color: #990000">=</span> <span style="color: #993399">105</span>

SPICE_MSGC_MAIN_AGENT_START             <span style="color: #990000">=</span> <span style="color: #993399">106</span>
SPICE_MSGC_MAIN_AGENT_DATA              <span style="color: #990000">=</span> <span style="color: #993399">107</span>
SPICE_MSGC_MAIN_AGENT_TOKEN             <span style="color: #990000">=</span> <span style="color: #993399">108</span></tt></pre></div></div>
</li>
<li>
<p>
Migration control
</p>
<div class="paragraph"><p>Spice migration control is performed using the main channel messages. Spice
server initiates migration process by sending SPICE_MSG_MAIN_MIGRATE_BEGIN message.
Once the client has completed its pre-migrate procedure it notifies the server
by transmitting SPICE_MSGC_MAIN_MIGRATE_CONNECTED message. In case of pre-migrate
procedure error, the client sends SPICE_MSGC_MAIN_MIGRATE_CONNECT_ERROR. Once the server
receives SPICE_MSGC_MAIN_MIGRATE_CONNECTED he can commence the migration process. The
server can send SPICE_MSG_MAIN_MIGRATE_CANCEL in order to instruct the client to
cancel the migration process.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
SPICE_MSG_MAIN_MIGRATE_BEGIN, SpiceMsgMainMigrationBegin
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT16 port</p></td>
<td align="left" valign="top"><p class="table">port of destination server</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT16 sport</p></td>
<td align="left" valign="top"><p class="table">secure port of destination server</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8[] host_name</p></td>
<td align="left" valign="top"><p class="table">host name of destination server</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_MAIN_MIGRATE_CANCEL, VOID
</p>
<div class="paragraph"><p>Instruct the client to cancel migration process</p></div>
</li>
<li>
<p>
SPICE_MSGC_MAIN_MIGRATE_CONNECTED, VOID
</p>
<div class="paragraph"><p>Notify the server of successful completion of the pre-migrate stage</p></div>
</li>
<li>
<p>
SPICE_MSGC_MAIN_MIGRATE_CONNECT_ERROR, VOID
</p>
<div class="paragraph"><p>Notify the server of pre-migrate stage error</p></div>
</li>
</ol></div>
</li>
<li>
<p>
Mouse modes
</p>
<div class="paragraph" id="mouse_modes"><p>Spice protocol specifies two mouse modes, client mode and server mode. In
client mode, the affective mouse is the client side mouse: the client sends
mouse position within the display and the server sends mouse shape messages. In
server mode, the client sends relative mouse movements and the server sends
position and shape commands. Spice main channel is used for mouse mode control.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
Modes
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_MOUSE_MODE_SERVER <span style="color: #990000">=</span> <span style="color: #993399">1</span>
SPICE_MOUSE_MODE_CLIENT <span style="color: #990000">=</span> <span style="color: #993399">2</span></tt></pre></div></div>
</li>
<li>
<p>
SPICE_MSG_MAIN_MOUSE_MODE, SpiceMsgMainMouseMode
</p>
<div class="paragraph"><p>Spice server sends this message on every mouse mode change</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 supported_modes</p></td>
<td align="left" valign="top"><p class="table">current supported mouse mode, this is any combination of SPICE_MOUSE_MODE_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 current_mode</p></td>
<td align="left" valign="top"><p class="table">the current mouse mode. Can be one of SPICE_MOUSE_MODE_?</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSGC_MAIN_MOUSE_MODE_REQUEST, UINT32
</p>
<div class="paragraph"><p>Spice client sends this message to request specific mouse mode. It is not
guarantied that the server will accept the request. Only on receiving
SPICE_MSG_MAIN_MOUSE_MODE message, the client can know of actual mouse mode change.</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32</p></td>
<td align="left" valign="top"><p class="table">requested mode, one of SPICE_MOUSE_MODE_?</p></td>
</tr>
</tbody>
</table>
</div>
</li>
</ol></div>
</li>
<li>
<p>
Main channel init message
</p>
<div class="paragraph"><p>Spice server must send SpiceMsgMainInit as the first transmitted message t and is
disallowed to send it at any other point.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
SPICE_MSG_MAIN_INIT, SpiceMsgMainInit
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 session_id</p></td>
<td align="left" valign="top"><p class="table">session id is generated by the server. This id will be send on every new
channel connection within this session (i.e., in SpiceLinkMess.connection_id).</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 display_channels_hint</p></td>
<td align="left" valign="top"><p class="table">optional hint of expected number of display channels. Zero is defined as an
invalid value</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 supported_mouse_modes</p></td>
<td align="left" valign="top"><p class="table">supported mouse modes. This is any combination of SPICE_MOUSE_MODE_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 current_mouse_mode</p></td>
<td align="left" valign="top"><p class="table">the current mouse mode, one of SPICE_MOUSE_MODE_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 agent_connected</p></td>
<td align="left" valign="top"><p class="table">current state of Spice agent (see <a href="#spice_agent">This Section</a>), 0 and 1 stand
for disconnected and  connected state respectively.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 agent_tokens</p></td>
<td align="left" valign="top"><p class="table">number of available tokens for sending messages to Spice agent.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 multi_media_time</p></td>
<td align="left" valign="top"><p class="table">current server multimedia time. The multimedia time is used for synchronizing
video (for more information see <a href="#multimedia_time">Multimedia time</a>)</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 ram_hint</p></td>
<td align="left" valign="top"><p class="table">optional hint for help in determining global LZ compression dictionary size
(for more information see section <a href="#spice_image">Spice Image</a> in “Display
Channel”).</p></td>
</tr>
</tbody>
</table>
</div>
</li>
</ol></div>
</li>
<li>
<p>
Server side channels notification
</p>
<div class="paragraph"><p>In order to have the ability to dynamically attach to the server side channels,
Spice protocol includes SPICE_MSG_MAIN_CHANNELS_LIST message. This massage informs
the client of available channels in the server side. In response to this
message the client can decide to link with the new available channel(s). The
server must receive SPICE_MSGC_MAIN_ATTACH_CHANNELS before sending any
SPICE_MSG_MAIN_CHANNELS_LIST message.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
SPICE_MSG_MAIN_CHANNELS_LIST, SpiceMsgChannels
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 num_of_channels</p></td>
<td align="left" valign="top"><p class="table">number of channels in this list</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">SpiceChannelId[] channels</p></td>
<td align="left" valign="top"><p class="table">vector of “num_of_channels” channel ids</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SpiceChannelId
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT8 type</p></td>
<td align="left" valign="top"><p class="table">channel type, one of SPICE_CHANNEL_? channel types, except for SPICE_CHANNEL_MAIN</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8 id</p></td>
<td align="left" valign="top"><p class="table">channel id</p></td>
</tr>
</tbody>
</table>
</div>
</li>
</ol></div>
</li>
<li>
<p>
Multimedia time
</p>
<div class="paragraph" id="multimedia_time"><p>Spice defines messages for setting multimedia time for synchronization of video
and audio streams. Two methods for updating multimedia time are supported. The
first method uses the time stamp of data that arrives on the playback
channel.The second method uses the  main channel SPICE_MSG_MAIN_MULTI_MEDIA_TIME
message. The latter method is used when  no active playback channel exist.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
SPICE_MSG_MAIN_MULTI_MEDIA_TIME, UINT32
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32</p></td>
<td align="left" valign="top"><p class="table">multimedia time</p></td>
</tr>
</tbody>
</table>
</div>
</li>
</ol></div>
</li>
<li>
<p>
Spice agent
</p>
<div class="paragraph" id="spice_agent"><p>Spice protocol defines a set of messages for bidirectional communication
channel between Spice client and spice client agent on the remote server. Spice
provides a communication channel only, the actual transferred data content is
opaque to the protocol. This channel can be used for various purposes, for
example, client-guest clipboard sharing, authentication and display
configuration.</p></div>
<div class="paragraph"><p>Spice client receives notifications of remote site agent connection as part of
the SPICE_MSG_MAIN_INIT message or by a specific server SPICE_MSG_MAIN_AGENT_CONNECTED.
Remote agent disconnection notification is delivered by
SPICE_MSG_MAIN_AGENT_DISCONNECTED message. A bidirectional tokens mechanism is used
in order to prevent blocking of the main channel with agent messages (e.g., in
case the agent stops consuming the data). Each side is not allowed to send more
messages than the tokens allocated to it by the other side. The number of
tokens that are allocated for the client is initialized from SPICE_MSG_MAIN_INIT
message, and farther allocation of tokens is done using SPICE_MSG_MAIN_AGENT_TOKEN.
Server tokens initial count is delivered in SPICE_MSGC_MAIN_AGENT_START message. This
message must be the first agent related message that the client sends to the
server. Farther tokens allocation for the server is done using
SPICE_MSGC_MAIN_AGENT_TOKEN. Actual data packets are delivered using
SPICE_MSG_MAIN_AGENT_DATA and SPICE_MSGC_MAIN_AGENT_DATA.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
Although agent messages are opaque for the protocol, agent data stream is
defined by Spice protocol in order to delineate messages. Still, the
client-server communication is independent from the agent channel, e.g., agent
protocol conflicts don&#8217;t affect the rest of the channels. Agent stream is
defined as a run of messages having the following format:
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 protocol</p></td>
<td align="left" valign="top"><p class="table">unique protocol of this message. The protocol id must be registered in order
to prevent conflicts.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 type</p></td>
<td align="left" valign="top"><p class="table">protocol dependent message type.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT64 opaque</p></td>
<td align="left" valign="top"><p class="table">protocol dependent opaque data.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 size</p></td>
<td align="left" valign="top"><p class="table">size of data  in bytes.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8 data[0]</p></td>
<td align="left" valign="top"><p class="table">data of this message.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>Client and server must continue processing unknown protocols messages or
messages having unknown type (i.e., receive and dump).</p></div>
</li>
<li>
<p>
SPICE_MSG_MAIN_AGENT_CONNECTED, VOID
</p>
</li>
<li>
<p>
SPICE_MSG_MAIN_AGENT_DISCONNECTED, UINT32
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32</p></td>
<td align="left" valign="top"><p class="table">disconnect error code SPICE_LINK_ERR_?</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_AGENT_MAX_DATA_SIZE = 2048
</p>
</li>
<li>
<p>
SPICE_MSG_MAIN_AGENT_DATA, UINT8[]
</p>
<div class="paragraph"><p>Agent packet is the entire message body (i.e. SpiceDataHeader.size). The maximum
packet size is SPICE_AGENT_MAX_DATA_SIZE.</p></div>
</li>
<li>
<p>
SPICE_MSG_MAIN_AGENT_TOKEN, UINT32
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32</p></td>
<td align="left" valign="top"><p class="table">allocated tokens count for the client</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSGC_MAIN_AGENT_START, UINT32
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32</p></td>
<td align="left" valign="top"><p class="table">allocated tokens count for the server</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSGC_MAIN_AGENT_DATA, UINT8[]
</p>
<div class="paragraph"><p>Agent packet is the entire message body (i.e. SpiceDataHeader.size). The maximum
packet size is SPICE_AGENT_MAX_DATA_SIZE.</p></div>
</li>
<li>
<p>
SPICE_MSGC_MAIN_AGENT_TOKEN, UINT32
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32</p></td>
<td align="left" valign="top"><p class="table">allocated tokens count for the server</p></td>
</tr>
</tbody>
</table>
</div>
</li>
</ol></div>
</li>
</ol></div>
</div>
</div>
<div class="sect1">
<h2 id="_inputs_channel_definition">4. Inputs channel definition</h2>
<div class="sectionbody">
<div class="paragraph"><p>Spice Inputs channel controls the server mouse and the keyboard.</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Client messages
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_MSGC_INPUTS_KEY_DOWN              <span style="color: #990000">=</span> <span style="color: #993399">101</span>
SPICE_MSGC_INPUTS_KEY_UP                <span style="color: #990000">=</span> <span style="color: #993399">102</span>
SPICE_MSGC_INPUTS_KEY_MODIFIERS         <span style="color: #990000">=</span> <span style="color: #993399">103</span>

SPICE_MSGC_INPUTS_MOUSE_MOTION          <span style="color: #990000">=</span> <span style="color: #993399">111</span>
SPICE_MSGC_INPUTS_MOUSE_POSITION        <span style="color: #990000">=</span> <span style="color: #993399">112</span>
SPICE_MSGC_INPUTS_MOUSE_PRESS           <span style="color: #990000">=</span> <span style="color: #993399">113</span>
SPICE_MSGC_INPUTS_MOUSE_RELEASE         <span style="color: #990000">=</span> <span style="color: #993399">114</span></tt></pre></div></div>
</li>
<li>
<p>
Server Messages
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_MSG_INPUTS_INIT                   <span style="color: #990000">=</span> <span style="color: #993399">101</span>
SPICE_MSG_INPUTS_KEY_MODIFIERS          <span style="color: #990000">=</span> <span style="color: #993399">102</span>

SPICE_MSG_INPUTS_MOUSE_MOTION_ACK       <span style="color: #990000">=</span> <span style="color: #993399">111</span></tt></pre></div></div>
</li>
<li>
<p>
Keyboard messages
</p>
<div class="paragraph"><p>Spice supports sending keyboard key events and keyboard leds synchronization.
The client sends  key event using SPICE_MSGC_INPUTS_KEY_DOWN and SPICE_MSGC_INPUTS_KEY_UP
messages. Key value is expressed using PC AT scan code (see
<a href="#key_code">KeyCode</a>).   Keyboard leds synchronization is done by sending
SPICE_MSG_INPUTS_KEY_MODIFIERS message by the server or by sending
SPICE_MSGC_INPUTS_KEY_MODIFIERS by the client, these messages contain keyboard leds
state. Keyboard modifiers is also sent by the server using SPICE_MSG_INPUTS_INIT,
this message must be sent as the first server message and the server mustn&#8217;t
send it  at any other point.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
Keyboard led bits
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_SCROLL_LOCK_MODIFIER      <span style="color: #990000">=</span> <span style="color: #993399">1</span>
SPICE_NUM_LOCK_MODIFIER         <span style="color: #990000">=</span> <span style="color: #993399">2</span>
SPICE_CAPS_LOCK_MODIFIER        <span style="color: #990000">=</span> <span style="color: #993399">4</span></tt></pre></div></div>
</li>
<li>
<p>
SPICE_MSG_INPUTS_INIT, UINT32
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32</p></td>
<td align="left" valign="top"><p class="table">any combination of keyboard led bits. If bit is set then the led is on.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_INPUTS_KEY_MODIFIERS, UINT32
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32</p></td>
<td align="left" valign="top"><p class="table">any combination of keyboard led bits. If bit is set then the led is on.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSGC_INPUTS_KEY_MODIFIERS, UINT32
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32</p></td>
<td align="left" valign="top"><p class="table">any combination of keyboard led bits. If bit is set then the led is on.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
KeyCode
</p>
<div class="tableblock" id="key_code">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT8[4]</p></td>
<td align="left" valign="top"><p class="table">the value of key code is a PC AT scan code. The code is composed by up to four
bytes for supporting extended codes. A code is terminated by a zero byte.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSGC_INPUTS_KEY_DOWN, KeyCode
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">KeyCode</p></td>
<td align="left" valign="top"><p class="table">client sends this message to notify of key press event.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSGC_INPUTS_KEY_UP,  KeyCode
</p>
<div class="paragraph"><p>KeyCode – client sends this message to notify of key release event.</p></div>
</li>
</ol></div>
</li>
<li>
<p>
Mouse messages
</p>
<div class="paragraph"><p>spice support two modes of mouse operation: client mouse and server mouse (for
more information see <a href="#mouse_modes">mouse modes</a>). in  server mouse mode the
client sends mouse motion message (i.e., msgc_inputs_mouse_motion), and in
client mouse mode it sends position message (i.e., msgc_inputs_mouse_position).
position message holds the position of the client mouse on the display and the
id of the display channel, which is derived from SpiceLinkMess.channel_id. in
order to prevent flood of mouse motion/position events, the server sends
red_inputs_mouse_motion_ack message on every red_motion_ack_bunch messages it
receive. this mechanism allows the client to keep track on  the server&#8217;s
messages consumption rate  and to change the event pushing policy according to
it. mouse button events are sent to the server using msgc_inputs_mouse_press
and msgc_inputs_mouse_release messages.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
Spice Button ID
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_MOUSE_BUTTON_LEFT         <span style="color: #990000">=</span> <span style="color: #993399">1</span><span style="color: #990000">,</span> left button
SPICE_MOUSE_BUTTON_MIDDLE       <span style="color: #990000">=</span> <span style="color: #993399">2</span><span style="color: #990000">,</span> middle button
SPICE_MOUSE_BUTTON_RIGHT        <span style="color: #990000">=</span> <span style="color: #993399">3</span><span style="color: #990000">,</span> right button
SPICE_MOUSE_BUTTON_UP           <span style="color: #990000">=</span> <span style="color: #993399">4</span><span style="color: #990000">,</span> scroll up button
SPICE_MOUSE_BUTTON_DOWN         <span style="color: #990000">=</span> <span style="color: #993399">5</span><span style="color: #990000">,</span> scroll down button</tt></pre></div></div>
</li>
<li>
<p>
Buttons masks
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_MOUSE_BUTTON_MASK_LEFT            <span style="color: #990000">=</span> <span style="color: #993399">1</span><span style="color: #990000">,</span>  left button mask
SPICE_MOUSE_BUTTON_MASK_MIDDLE          <span style="color: #990000">=</span> <span style="color: #993399">2</span><span style="color: #990000">,</span>  middle button mask
SPICE_MOUSE_BUTTON_MASK_RIGHT           <span style="color: #990000">=</span> <span style="color: #993399">4</span><span style="color: #990000">,</span> right button mask</tt></pre></div></div>
</li>
<li>
<p>
SPICE_INPUT_MOTION_ACK_BUNCH
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_INPUT_MOTION_ACK_BUNCH            <span style="color: #990000">=</span> <span style="color: #993399">4</span></tt></pre></div></div>
</li>
<li>
<p>
SPICE_MSGC_INPUTS_MOUSE_MOTION, SpiceMsgcMouseMotion
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">INT32 dx</p></td>
<td align="left" valign="top"><p class="table">number of pixels the mouse had moved on x axis</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">INT32 dy</p></td>
<td align="left" valign="top"><p class="table">number of pixels the mouse had moved on y axis</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 buttons_state</p></td>
<td align="left" valign="top"><p class="table">any combination of buttons mask. Set bit describe pressed button and clear bit
describe unpressed button.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSGC_INPUTS_MOUSE_POSITION, SpiceMsgcMousePosition
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 x</p></td>
<td align="left" valign="top"><p class="table">position on x axis</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 y</p></td>
<td align="left" valign="top"><p class="table">position on y axis</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32  buttons_state</p></td>
<td align="left" valign="top"><p class="table">any combination of buttons mask. Set bit describe pressed button and clear bit
describe unpressed button.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8 display_id</p></td>
<td align="left" valign="top"><p class="table">id of the display that client mouse is on.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSGC_INPUTS_MOUSE_PRESS, SpiceMsgcMousePress
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 button</p></td>
<td align="left" valign="top"><p class="table">one of SPICE_MOUSE_?BUTTON</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32  buttons_state</p></td>
<td align="left" valign="top"><p class="table">any combination of buttons masks. Set bit describes pressed button, and clear
bit describes unpressed button.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSGC_INPUTS_MOUSE_RELEASE, SpiceMsgcMouseRelease
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 button</p></td>
<td align="left" valign="top"><p class="table">one of SPICE_MOUSE_?BUTTON</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32  buttons_state</p></td>
<td align="left" valign="top"><p class="table">any combination of buttons mask. Set bit describes pressed button and clear
bit describes unpressed button.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
</ol></div>
</li>
</ol></div>
</div>
</div>
<div class="sect1">
<h2 id="_display_channel_definition">5. Display channel definition</h2>
<div class="sectionbody">
<div class="paragraph"><p>Spice protocol defines a set of messages for supporting rendering of the remote
display area on the client display. The protocol supports rendering of graphics
primitives (e.g., lines, images) and video streams. The protocol also supports
caching of images and color palettes on the client side. Spice display channel
supports several images compression methods for reducing network traffic.</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Server messages
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_MSG_DISPLAY_MODE                          <span style="color: #990000">=</span> <span style="color: #993399">101</span>
SPICE_MSG_DISPLAY_MARK                          <span style="color: #990000">=</span> <span style="color: #993399">102</span>
SPICE_MSG_DISPLAY_RESET                         <span style="color: #990000">=</span> <span style="color: #993399">103</span>
SPICE_MSG_DISPLAY_COPY_BITS                     <span style="color: #990000">=</span> <span style="color: #993399">104</span>

SPICE_MSG_DISPLAY_INVAL_LIST                    <span style="color: #990000">=</span> <span style="color: #993399">105</span>
SPICE_MSG_DISPLAY_INVAL_ALL_PIXMAPS             <span style="color: #990000">=</span> <span style="color: #993399">106</span>
SPICE_MSG_DISPLAY_INVAL_PALETTE                 <span style="color: #990000">=</span> <span style="color: #993399">107</span>
SPICE_MSG_DISPLAY_INVAL_ALL_PALETTES            <span style="color: #990000">=</span> <span style="color: #993399">108</span>

SPICE_MSG_DISPLAY_STREAM_CREATE                 <span style="color: #990000">=</span> <span style="color: #993399">122</span>
SPICE_MSG_DISPLAY_STREAM_DATA                   <span style="color: #990000">=</span> <span style="color: #993399">123</span>
SPICE_MSG_DISPLAY_STREAM_CLIP                   <span style="color: #990000">=</span> <span style="color: #993399">124</span>
SPICE_MSG_DISPLAY_STREAM_DESTROY                <span style="color: #990000">=</span> <span style="color: #993399">125</span>
SPICE_MSG_DISPLAY_STREAM_DESTROY_ALL            <span style="color: #990000">=</span> <span style="color: #993399">126</span>

SPICE_MSG_DISPLAY_DRAW_FILL                     <span style="color: #990000">=</span> <span style="color: #993399">302</span>
SPICE_MSG_DISPLAY_DRAW_OPAQUE                   <span style="color: #990000">=</span> <span style="color: #993399">303</span>
SPICE_MSG_DISPLAY_DRAW_COPY                     <span style="color: #990000">=</span> <span style="color: #993399">304</span>
SPICE_MSG_DISPLAY_DRAW_BLEND                    <span style="color: #990000">=</span> <span style="color: #993399">305</span>
SPICE_MSG_DISPLAY_DRAW_BLACKNESS                <span style="color: #990000">=</span> <span style="color: #993399">306</span>
SPICE_MSG_DISPLAY_DRAW_WHITENESS                <span style="color: #990000">=</span> <span style="color: #993399">307</span>
SPICE_MSG_DISPLAY_DRAW_INVERS                   <span style="color: #990000">=</span> <span style="color: #993399">308</span>
SPICE_MSG_DISPLAY_DRAW_ROP3                     <span style="color: #990000">=</span> <span style="color: #993399">309</span>
SPICE_MSG_DISPLAY_DRAW_STROKE                   <span style="color: #990000">=</span> <span style="color: #993399">310</span>
SPICE_MSG_DISPLAY_DRAW_TEXT                     <span style="color: #990000">=</span> <span style="color: #993399">311</span>
SPICE_MSG_DISPLAY_DRAW_TRANSPARENT              <span style="color: #990000">=</span> <span style="color: #993399">312</span>
SPICE_MSG_DISPLAY_DRAW_ALPHA_BLEND              <span style="color: #990000">=</span> <span style="color: #993399">313</span></tt></pre></div></div>
</li>
<li>
<p>
Client messages
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_MSGC_DISPLAY_INIT                         <span style="color: #990000">=</span> <span style="color: #993399">101</span></tt></pre></div></div>
</li>
<li>
<p>
Operation flow
</p>
<div class="paragraph"><p>Spice server sends to the client a mode message using SPICE_MSG_DISPLAY_MODE for
specifying the current draw area size and format. In response the client
creates a draw area for rendering all the followed rendering commands sent by
the server. The client will expose the new remote display area content (i.e.,
after mode command) only after it receives a mark command (i.e.,
SPICE_MSG_DISPLAY_MARK) from the server. The server can send a reset command using
SPICE_MSG_DISPLAY_RESET to instruct the client to drop its draw area and palette
cache.  Sending  mode message is allowed only while no active draw area exists
on the client side. Sending reset message is  allowed only while active draw
area exists on client side. Sending mark message is allowed only once, between
mode and reset messages. Draw commands, copy bits command and stream commands
are allowed only if the client have an active display area (i.e., between
SPICE_MSG_DISPLAY_MODE to SPICE_MSG_DISPLAY_RESET).</p></div>
<div class="paragraph"><p>On channel connection, the client optionally sends an init message, using
SPICE_MSGC_DISPLAY_INIT, in order to enable image caching and global dictionary
compression. The message includes the cache id and its size and the size of the
dictionary compression window. These sizes and id are determined by the client.
It is disallowed to send more then one init message.</p></div>
<div class="paragraph"><p>Color pallets cache are manged by the server.
Items cache insertion commands are sent as part of  the rendering commands.
Cache items removal are sent explicitly using SPICE_MSG_DISPLAY_INVAL_LIST or
SPICE_MSG_DISPLAY_INVAL_LIST server messages. Resetting client caches is done by
sending SPICE_MSG_DISPLAY_INVAL_ALL_PIXMAPS or SPICE_MSG_DISPLAY_INVAL_ALL_PALETTES server
messages.</p></div>
</li>
<li>
<p>
Draw area control
</p>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
SPICE_MSG_DISPLAY_MODE,  SpiceMsgDisplayMode
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 width</p></td>
<td align="left" valign="top"><p class="table">width of the display area</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 height</p></td>
<td align="left" valign="top"><p class="table">height of the display area</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 depth</p></td>
<td align="left" valign="top"><p class="table">color depth of the display area. Valid values are 16bpp  or 32bpp.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_MARK, VOID
</p>
<div class="paragraph"><p>Mark the beginning of the display area visibility</p></div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_RESET, VOID
</p>
<div class="paragraph"><p>Drop current display area of the channel and reset palette cache</p></div>
</li>
</ol></div>
</li>
<li>
<p>
Raster operation descriptor
</p>
<div class="paragraph"><p>The following defines a set of flags for describing raster operations that can
be applied on a source image, source brush, destination and the result during a
rendering operation. Combination of those flags defines the necessary steps
that are needed to be preformed during a rendering operation. In the
following definitions of rendering commands this combination is referred to by
<em>rop_descriptor</em>.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_ROPD_INVERS_SRC           <span style="color: #990000">=</span> <span style="color: #993399">1</span></tt></pre></div></div>
<div class="paragraph"><p>Source Image need to be inverted before rendering</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_ROPD_INVERS_BRUSH         <span style="color: #990000">=</span> <span style="color: #993399">2</span></tt></pre></div></div>
<div class="paragraph"><p>SpiceBrush need to be inverted before rendering</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_ROPD_INVERS_DEST          <span style="color: #990000">=</span> <span style="color: #993399">4</span></tt></pre></div></div>
<div class="paragraph"><p>Destination area need to be inverted before rendering</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_ROPD_OP_PUT               <span style="color: #990000">=</span> <span style="color: #993399">8</span></tt></pre></div></div>
<div class="paragraph"><p>SpiceCopy operation should be used.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_ROPD_OP_OR                <span style="color: #990000">=</span> <span style="color: #993399">16</span></tt></pre></div></div>
<div class="paragraph"><p>OR operation should be used.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_ROPD_OP_AND               <span style="color: #990000">=</span> <span style="color: #993399">32</span></tt></pre></div></div>
<div class="paragraph"><p>AND operation should be used.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_ROPD_OP_XOR               <span style="color: #990000">=</span> <span style="color: #993399">64</span></tt></pre></div></div>
<div class="paragraph"><p>XOR operation should be used.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_ROPD_OP_BLACKNESS         <span style="color: #990000">=</span> <span style="color: #993399">128</span></tt></pre></div></div>
<div class="paragraph"><p>Destination pixel should be replaced by black</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_ROPD_OP_WHITENESS         <span style="color: #990000">=</span> <span style="color: #993399">256</span></tt></pre></div></div>
<div class="paragraph"><p>Destination pixel should be replaced by white</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_ROPD_OP_INVERS            <span style="color: #990000">=</span> <span style="color: #993399">512</span></tt></pre></div></div>
<div class="paragraph"><p>Destination pixel should be inverted</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_ROPD_INVERS_RES           <span style="color: #990000">=</span> <span style="color: #993399">1024</span></tt></pre></div></div>
<div class="paragraph"><p>Result of the operation needs to be inverted</p></div>
<div class="paragraph"><p>OP_PUT, OP_OR, OP_AND, OP_XOR, OP_BLACKNESS, OP_WHITENESS, and OP_INVERS are
mutually exclusive</p></div>
<div class="paragraph"><p>OP_BLACKNESS, OP_WHITENESS, and OP_INVERS are exclusive</p></div>
</li>
<li>
<p>
Raw raster image
</p>
<div class="paragraph"><p>The following section describes Spice raw raster image (Pixmap). Pixmap is one
of several ways to transfer images in Spice protocol (for more information see
<a href="#spice_image">Spice Image</a>).</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
Pixmap format types
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>PIXMAP_FORMAT_1BIT_LE           <span style="color: #990000">=</span> <span style="color: #993399">1</span></tt></pre></div></div>
<div class="paragraph"><p>1 bit per pixel and bits order is little endian. Each pixel value is an index
in a color table. The color table size is 2.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>PIXMAP_FORMAT_1BIT_BE           <span style="color: #990000">=</span> <span style="color: #993399">2</span></tt></pre></div></div>
<div class="paragraph"><p>1 bit per pixel and bits order is big endian. Each pixel value is index in a
color table. The color table size is 2.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>PIXMAP_FORMAT_4BIT_LE           <span style="color: #990000">=</span> <span style="color: #993399">3</span></tt></pre></div></div>
<div class="paragraph"><p>4 bits per pixel and nibble order inside a byte is little endian. Each pixel
value is an index in a color table. The color table size is 16.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>PIXMAP_FORMAT_4BIT_BE           <span style="color: #990000">=</span> <span style="color: #993399">4</span></tt></pre></div></div>
<div class="paragraph"><p>4 bits per pixel and nibble order inside a byte is big endian. Each pixel value
is an index in a color table. The color table size is 16.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>PIXMAP_FORMAT_8BIT              <span style="color: #990000">=</span> <span style="color: #993399">5</span></tt></pre></div></div>
<div class="paragraph"><p>8 bits per pixel. Each pixel value is an index in a color table. The color
table size is 256.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>PIXMAP_FORMAT_16BIT             <span style="color: #990000">=</span> <span style="color: #993399">6</span></tt></pre></div></div>
<div class="paragraph"><p>pixel format is 16 bits RGB555.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>PIXMAP_FORMAT_24BIT             <span style="color: #990000">=</span> <span style="color: #993399">7</span></tt></pre></div></div>
<div class="paragraph"><p>pixel format is 24 bits RGB888.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>PIXMAP_FORMAT_32BIT             <span style="color: #990000">=</span> <span style="color: #993399">8</span></tt></pre></div></div>
<div class="paragraph"><p>pixel format is 32 bits RGB888.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>PIXMAP_FORMAT_RGBA              <span style="color: #990000">=</span> <span style="color: #993399">9</span></tt></pre></div></div>
<div class="paragraph"><p>pixel format is 32 bits ARGB8888.</p></div>
</li>
<li>
<p>
SpicePalette
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT64 id</p></td>
<td align="left" valign="top"><p class="table">unique id of the palette</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT16 table_size</p></td>
<td align="left" valign="top"><p class="table">number of entries in the color table</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32[] color_table</p></td>
<td align="left" valign="top"><p class="table">each entry is RGB555 or RGB888 color depending on the current display area
mode. If  display area mode color depth is 32, the effective format is  RGB888.
If  display area mode color depth is 16 the effective format is  RGB555.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
Pixmap flags
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>PIXMAP_FLAG_PAL_CACHE_ME        <span style="color: #990000">=</span> <span style="color: #993399">1</span></tt></pre></div></div>
<div class="paragraph"><p>Instruct the client to add the palette to cache</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>PIXMAP_FLAG_PAL_FROM_CACHE      <span style="color: #990000">=</span> <span style="color: #993399">2</span></tt></pre></div></div>
<div class="paragraph"><p>Instruct the client to retrieve palette from cache.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>PIXMAP_FLAG_TOP_DOWN            <span style="color: #990000">=</span> <span style="color: #993399">4</span></tt></pre></div></div>
<div class="paragraph"><p>Pixmap lines are ordered from top to bottom (i.e., line 0 is the highest line).</p></div>
</li>
<li>
<p>
Pixmap
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT8 format</p></td>
<td align="left" valign="top"><p class="table">one of PIXMAP_FORMAT_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8 flags</p></td>
<td align="left" valign="top"><p class="table">combination of PIXMAP_FLAG_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 width</p></td>
<td align="left" valign="top"><p class="table">width of the pixmap</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 height</p></td>
<td align="left" valign="top"><p class="table">height of the pixmap</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 stride</p></td>
<td align="left" valign="top"><p class="table">number of bytes to add for moving from the beginning of line n to the
beginning  of line n+1</p></td>
</tr>
<tr>
<td align="left" valign="top"><div><div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">union</span></span> <span style="color: #FF0000">{</span>
        <span style="color: #008080">SPICE_ADDRESS</span> palette<span style="color: #990000">;</span>
        <span style="color: #008080">UINT64</span> palette_id<span style="color: #990000">;</span>
<span style="color: #FF0000">}</span></tt></pre></div></div></div></td>
<td align="left" valign="top"><p class="table">address of the color palette (must be zero if no color table is required for format) <strong>or</strong> id of the palette (valid if FLAG_PAL_FROM_CACHE is set).</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">SPICE_ADDRESS data</p></td>
<td align="left" valign="top"><p class="table">address of line 0 of the pixmap.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
</ol></div>
</li>
<li>
<p>
LZ with palette
</p>
<div class="paragraph"><p>This section describes a data structure that is combination of a color palette
and a compressed pixmap data. The pixmap is compressed using our implementation
of LZSS algorithm (see next section). Each decoded pixel value is an index in
the color palette.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
LZPalette Flags
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>LZPALETTE_FLAG_PAL_CACHE_ME             <span style="color: #990000">=</span> <span style="color: #993399">1</span></tt></pre></div></div>
<div class="paragraph"><p>Instruct the client to add the palette to the cache</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>LZPALETTE_FLAG_PAL_FROM_CACHE           <span style="color: #990000">=</span> <span style="color: #993399">2</span></tt></pre></div></div>
<div class="paragraph"><p>Instruct the client to retrieve palette from the cache.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>LZPALETTE_FLAG_TOP_DOWN                 <span style="color: #990000">=</span> <span style="color: #993399">4</span></tt></pre></div></div>
<div class="paragraph"><p>pixmap lines are ordered from top to bottom (i.e. line 0 is the highest line).</p></div>
</li>
<li>
<p>
LZPalette
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT8 flags</p></td>
<td align="left" valign="top"><p class="table">combination of LZPALETTE_FLAG_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 data_size</p></td>
<td align="left" valign="top"><p class="table">size of compressed data</p></td>
</tr>
<tr>
<td align="left" valign="top"><div><div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">union</span></span> <span style="color: #FF0000">{</span>
        <span style="color: #008080">SPICE_ADDRESS</span> palette<span style="color: #990000">;</span>
        <span style="color: #008080">UINT64</span> palette_id<span style="color: #990000">;</span>
<span style="color: #FF0000">}</span></tt></pre></div></div></div></td>
<td align="left" valign="top"><p class="table">address of the color palette (see SpicePalette section in “Raw raster image”)[zero value
is disallowed] <strong>or</strong> id of the palette (valid if FLAG_PAL_FROM_CACHE).</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8[] data</p></td>
<td align="left" valign="top"><p class="table">compressed pixmap</p></td>
</tr>
</tbody>
</table>
</div>
</li>
</ol></div>
</li>
<li>
<p>
Spice Image
</p>
<div class="paragraph" id="spice_image"><p>The following section describes Spice image. Spice image is used in various
commands and data structures for representing a raster image. Spice image
supports several compression types in addition to the raw mode: Quic, LZ and
GLZ. Quic is a predictive coding algorithm. It is a generalization of SFALIC
from gray-scale to color images withe addition of RLE encoding. By LZ we refer
to the our implementation of the LZSS algorithm, which was adjusted for images
in different formats. By GLZ we refer to an extension of LZ that allows it to
use a dictionary that is based on a set of images and not just on the image
being compressed.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
Image types
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>IMAGE_TYPE_PIXMAP               <span style="color: #990000">=</span> <span style="color: #993399">0</span>
SPICE_IMAGE_TYPE_QUIC           <span style="color: #990000">=</span> <span style="color: #993399">1</span>
SPICE_IMAGE_TYPE_LZ_PLT         <span style="color: #990000">=</span> <span style="color: #993399">100</span>
SPICE_IMAGE_TYPE_LZ_RGB         <span style="color: #990000">=</span> <span style="color: #993399">101</span>
SPICE_IMAGE_TYPE_GLZ_RGB        <span style="color: #990000">=</span> <span style="color: #993399">102</span>
SPICE_IMAGE_TYPE_FROM_CACHE     <span style="color: #990000">=</span> <span style="color: #993399">103</span></tt></pre></div></div>
</li>
<li>
<p>
Image flags
</p>
<div class="paragraph"><p>IMAGE_FLAG_CACHE_ME = 1, this flag instruct the client to add the image to
image cache, cache key is SpiceImageDescriptor.id (see below).</p></div>
</li>
<li>
<p>
SpiceImageDescriptor
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT64 id</p></td>
<td align="left" valign="top"><p class="table">unique id of the image</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8 type</p></td>
<td align="left" valign="top"><p class="table">type of the image. One of IMAGE_TYPE_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8 flags</p></td>
<td align="left" valign="top"><p class="table">any combination of IMAGE_FLAG_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 width</p></td>
<td align="left" valign="top"><p class="table">width of the image</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 height</p></td>
<td align="left" valign="top"><p class="table">height of the image</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
Image data
</p>
<div class="paragraph"><p>Image data follows SpiceImageDescriptor and its content depends on
SpiceImageDescriptor.type:</p></div>
<div class="ulist"><ul>
<li>
<p>
In case of PIXMAP – content is Pixmap.
</p>
</li>
<li>
<p>
In case of QUIC – content is Quic compressed image. Data begins with   the
size of the compressed data, represented by UINT32,  followed by the compressed
data.
</p>
</li>
<li>
<p>
In case of LZ_PLT – content is  LZPalette.
</p>
</li>
<li>
<p>
In case of LZ_RGB – content is LZ_RGB  – LZ encoding of an RGB image. Data
begins with  the size of the compressed data, represented by UINT32, followed
by the compressed data.
</p>
</li>
<li>
<p>
In case of GLZ_RGB – content is GLZ_RGB – GLZ encoding of an RGB image. Data
begins with the size of the compressed data, represented by UINT32, ,  followed
by the compressed data.
</p>
</li>
<li>
<p>
In case of FROM_CACHE –  No image data. The client should use
SpiceImageDescriptor.id to retrieve the relevant image from cache.
</p>
</li>
</ul></div>
</li>
</ol></div>
</li>
<li>
<p>
Glyph SpiceString
</p>
<div class="paragraph"><p>Glyph string defines an array of glyphs for rendering. Glyphs in a string can
be in A1, A4 or A8  format (i.e., 1bpp, 4bpp, or 8bpp alpha mask). Every glyph
contains its rendering position on the destination draw area.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
SpiceRasterGlyph
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">POINT render_pos</p></td>
<td align="left" valign="top"><p class="table">location of the glyph on the draw area</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">POINT glyph_origin</p></td>
<td align="left" valign="top"><p class="table">origin of the glyph. The origin is relative to the upper left corner of the
draw area. Positive value on x axis advances leftward and  positive value on y
axis advances upward.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT16 width</p></td>
<td align="left" valign="top"><p class="table">glyph&#8217;s width</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT16 height</p></td>
<td align="left" valign="top"><p class="table">glyph&#8217;s height</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8[] data</p></td>
<td align="left" valign="top"><p class="table">alpha mask of the glyph. Actual mask data depends on the glyph string&#8217;s flags.
If the format is A1 then the line stride is ALIGN(width, 8) / 8. If the format
is A4,  the line stride is ALIGN(width, 2) / 2. If the format is A8,  the line
stride is width.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
Glyph SpiceString flags
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>GLYPH_STRING_FLAG_RASTER_A1                     <span style="color: #990000">=</span> <span style="color: #993399">1</span></tt></pre></div></div>
<div class="paragraph"><p>Glyphs type is 1bpp alpha value (i.e., 0 is transparent 1 is opaque)</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>GLYPH_STRING_FLAG_RASTER_A4                     <span style="color: #990000">=</span> <span style="color: #993399">2</span></tt></pre></div></div>
<div class="paragraph"><p>Glyphs type is 4bpp alpha value (i.e., 0 is transparent 16 is opaque)</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>GLYPH_STRING_FLAG_RASTER_A8                     <span style="color: #990000">=</span> <span style="color: #993399">4</span></tt></pre></div></div>
<div class="paragraph"><p>Glyphs type is 4bpp alpha value (i.e., 0 is transparent 256 is opaque)</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>GLYPH_STRING_FLAG_RASTER_TOP_DOWN               <span style="color: #990000">=</span> <span style="color: #993399">8</span></tt></pre></div></div>
<div class="paragraph"><p>Line 0 is the top line of the mask</p></div>
</li>
<li>
<p>
GlyphString
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT16 length</p></td>
<td align="left" valign="top"><p class="table">number of glyphs</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT16 flags</p></td>
<td align="left" valign="top"><p class="table">combination of GLYPH_STRING_FLAG_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8[] data</p></td>
<td align="left" valign="top"><p class="table">glyphs</p></td>
</tr>
</tbody>
</table>
</div>
</li>
</ol></div>
</li>
<li>
<p>
Data Types
</p>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
RectList
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 count</p></td>
<td align="left" valign="top"><p class="table">number of RECT items in rects</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">RECT[] rects</p></td>
<td align="left" valign="top"><p class="table">array of &lt;count&gt; RECT</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
Path segment flags
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>PATH_SEGMENT_FLAG_BEGIN         <span style="color: #990000">=</span> <span style="color: #993399">1</span></tt></pre></div></div>
<div class="paragraph"><p>this segment begins a new path</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>PATH_SEGMENT_FLAG_END           <span style="color: #990000">=</span> <span style="color: #993399">2</span></tt></pre></div></div>
<div class="paragraph"><p>this segment ends the current path</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>PATH_SEGMENT_FLAG_CLOSE         <span style="color: #990000">=</span> <span style="color: #993399">8</span></tt></pre></div></div>
<div class="paragraph"><p>this segment closes the path and is invalid if PATH_SEGMENT_FLAG_END is not set</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>PATH_SEGMENT_FLAG_BEZIER        <span style="color: #990000">=</span> <span style="color: #993399">16</span></tt></pre></div></div>
<div class="paragraph"><p>this segment content is a Bezier curve</p></div>
</li>
<li>
<p>
SpicePathSeg
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 flags</p></td>
<td align="left" valign="top"><p class="table">any combination of PATH_SEGMENT_FLAG_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 count</p></td>
<td align="left" valign="top"><p class="table">number of points in the segment</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">POINTFIX[] points</p></td>
<td align="left" valign="top"><p class="table">segment points</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
PathSegList
</p>
<div class="paragraph"><p>List of SpicePathSeg items. End of the list is reached if the sum of all previous
PathSegs' sizes is equal to  list_size. Address of next segment is the address
of SpicePathSeg.points[SpicePathSeg.count]</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 list_size</p></td>
<td align="left" valign="top"><p class="table">total size of in bytes of all PathSegs in the list,</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>SpicePathSeg seg0 – first path segment.</p></div>
</li>
<li>
<p>
SpiceClip types
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_CLIP_TYPE_NONE            <span style="color: #990000">=</span> <span style="color: #993399">0</span></tt></pre></div></div>
<div class="paragraph"><p>no clipping</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_CLIP_TYPE_RECTS           <span style="color: #990000">=</span> <span style="color: #993399">1</span></tt></pre></div></div>
<div class="paragraph"><p>data is RectList and union of all rectangles in RectList is the effective clip</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_CLIP_TYPE_PATH            <span style="color: #990000">=</span> <span style="color: #993399">2</span></tt></pre></div></div>
<div class="paragraph"><p>data is PathSegList and the figure described by PathSegList is the effective
clip</p></div>
</li>
<li>
<p>
SpiceClip
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UIN32 type</p></td>
<td align="left" valign="top"><p class="table">one of CLIP_TYPE_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">SPICE_ADDRESS data</p></td>
<td align="left" valign="top"><p class="table">address of clip data. The content depends on &lt;type&gt;</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
Mask flags
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>MASK_FLAG_INVERS        <span style="color: #990000">=</span> <span style="color: #993399">1</span><span style="color: #990000">,</span> the effective mask is the inverse of the mask</tt></pre></div></div>
</li>
<li>
<p>
Mask
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT8 flags</p></td>
<td align="left" valign="top"><p class="table">flags of the mask, combination of MASK_FLAG_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">POINT position</p></td>
<td align="left" valign="top"><p class="table">origin of the mask in bitmap coordinates</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">SPICE_ADDRESS bitmap</p></td>
<td align="left" valign="top"><p class="table">address of the mask&#8217;s image, the format of the image must be
1bpp. If the bitmap is zero then no masking operation needs to be preformed.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>In all rendering commands, the mask must be big enough to cover the destination
rectangle</p></div>
</li>
<li>
<p>
SpiceBrush types
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_BRUSH_TYPE_NONE           <span style="color: #990000">=</span> <span style="color: #993399">0</span> <span style="font-style: italic"><span style="color: #9A1900">/* the brush is invalid */</span></span>
SPICE_BRUSH_TYPE_SOLID          <span style="color: #990000">=</span> <span style="color: #993399">1</span> <span style="font-style: italic"><span style="color: #9A1900">/* the brush is solid RGB color */</span></span>
SPICE_BRUSH_TYPE_PATTERN        <span style="color: #990000">=</span> <span style="color: #993399">2</span> <span style="font-style: italic"><span style="color: #9A1900">/* the brush is a pattern */</span></span></tt></pre></div></div>
</li>
<li>
<p>
SpicePattern
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">SPICE_ADDRESS image</p></td>
<td align="left" valign="top"><p class="table">address of the pattern&#8217;s Image</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">POINT position</p></td>
<td align="left" valign="top"><p class="table">origin coordinates of the pattern in the image</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SpiceBrush
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 type</p></td>
<td align="left" valign="top"><p class="table">one of BRUSH_TYPE_?</p></td>
</tr>
</tbody>
</table>
</div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Union <span style="color: #FF0000">{</span>
        <span style="color: #008080">UINT32</span> color<span style="color: #990000">;</span> <span style="color: #990000">*/</span> <span style="color: #008080">RGB</span> color<span style="color: #990000">.</span> The format of the color depends on current
draw <span style="color: #008080">area</span> mode<span style="color: #990000">.*/</span>
        <span style="color: #008080">SpicePattern</span> pattern<span style="color: #990000">;</span>
<span style="color: #FF0000">}</span></tt></pre></div></div>
</li>
<li>
<p>
Image scale mode
</p>
<div class="paragraph"><p>The following defines the method for scaling image</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_IMAGE_SCALE_MODE_INTERPOLATE      <span style="color: #990000">=</span> <span style="color: #993399">0</span></tt></pre></div></div>
<div class="paragraph"><p>The client is allowed to INTERPOLATE pixel color.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_IMAGE_SCALE_MODE_NEAREST          <span style="color: #990000">=</span> <span style="color: #993399">1</span></tt></pre></div></div>
<div class="paragraph"><p>The client must use the nearest pixel.</p></div>
</li>
<li>
<p>
LineAtrr flags
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>LINE_ATTR_FLAG_START_WITH_GAP           <span style="color: #990000">=</span> <span style="color: #993399">4</span></tt></pre></div></div>
<div class="paragraph"><p>first style segment if gap (i.e., foreground)</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>LINE_ATTR_FLAG_STYLED                   <span style="color: #990000">=</span> <span style="color: #993399">8</span></tt></pre></div></div>
<div class="paragraph"><p>style member of LineAtrr is valid and contains effective line style for the
rendering operation.</p></div>
</li>
<li>
<p>
LineAtrr join style
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>LINE_ATTR_JOIN_ROUND                    <span style="color: #990000">=</span> <span style="color: #993399">0</span>
LINE_ATTR_JOIN_BEVEL                    <span style="color: #990000">=</span> <span style="color: #993399">1</span>
LINE_ATTR_JOIN_MITER                    <span style="color: #990000">=</span> <span style="color: #993399">2</span></tt></pre></div></div>
</li>
<li>
<p>
LineAtrr cap style
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>LINE_ATTR_CAP_ROUND                     <span style="color: #990000">=</span> <span style="color: #993399">0</span>
LINE_ATTR_CAP_SQUARE                    <span style="color: #990000">=</span> <span style="color: #993399">1</span>
LINE_ATTR_CAP_BUTT                      <span style="color: #990000">=</span> <span style="color: #993399">2</span></tt></pre></div></div>
</li>
<li>
<p>
SpiceLineAttr
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT8 flags</p></td>
<td align="left" valign="top"><p class="table">combination of LINE_ATTR_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8 join_style</p></td>
<td align="left" valign="top"><p class="table">one of LINE_ATTR_JOIN_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8 cap_style</p></td>
<td align="left" valign="top"><p class="table">one of LINE_ATTR_CAP_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8 style_num_segments</p></td>
<td align="left" valign="top"><p class="table">number of style segments in line style</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">SPICE_FIXED28_4 width</p></td>
<td align="left" valign="top"><p class="table">width of the line in pixels</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">SPICE_FIXED28_4 miter_limit</p></td>
<td align="left" valign="top"><p class="table">miter limit in pixels</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">SPICE_ADDRESS style</p></td>
<td align="left" valign="top"><p class="table">address of line style line style is array of SPICE_FIXED28_4. The array defines
segments that each represents length of  foreground or background pixels in the
style. If FLAG_START_WITH_GAP is defined then the first segment in the style is
background, otherwise it is foreground. Renderer uses  this array of segments
repeatedly during rendering operation.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
</ol></div>
</li>
<li>
<p>
Rendering command
</p>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
SpiceMsgDisplayBase
</p>
<div class="paragraph"><p>Common field to all rendering command</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">RECT bounding_box</p></td>
<td align="left" valign="top"><p class="table">the affected area on the display area</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">SpiceClip clip</p></td>
<td align="left" valign="top"><p class="table">the effective clip to set before rendering a command</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_COPY_BITS
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SpiceMsgDisplayBase
<span style="color: #008080">POINT</span> source_position</tt></pre></div></div>
<div class="paragraph"><p>SpiceCopy bits from the draw area to bounding_box on the draw area. Source area left
top corner is source_position and its height and width is equal to bounding_box
height and width. Source and  destination rectangles can overlap.</p></div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_DRAW_FILL
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SpiceMsgDisplayBase
SpiceBrush brush
<span style="color: #008080">UINT16</span> rop_descriptor
Mask mask</tt></pre></div></div>
<div class="paragraph"><p>SpiceFill  bounding_box using brush as the fill pattern and rop_descriptor
instructions. If the mask is valid, it will limit the modified area (i.e., only
pixels on the destination area that their corresponding bits are set will be
affected).</p></div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_DRAW_OPAQUE
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SpiceMsgDisplayBase
<span style="color: #008080">SPICE_ADDRESS</span> source_image
<span style="color: #008080">RECT</span> source_area
SpiceBrush brush
<span style="color: #008080">UINT16</span> rop_descriptor
<span style="color: #008080">UINT8</span> scale_mode
Mask mask</tt></pre></div></div>
<div class="paragraph"><p>Combine pixels from source_area in source_image with the brush&#8217;s pattern using
rop_descriptor instructions. The result image will be rendered into
bounding_box. In case scaling of source image is required it will be performed
according to scale_mode and before the combination with brush pixels. If mask
is valid it will limit the modified area.</p></div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_DRAW_COPY
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SpiceMsgDisplayBase
<span style="color: #008080">SPICE_ADDRESS</span> source_image
<span style="color: #008080">RECT</span> source_area
<span style="color: #008080">UINT16</span> rop_descriptor
<span style="color: #008080">UINT8</span> scale_mode
Mask mask</tt></pre></div></div>
<div class="paragraph"><p>SpiceCopy pixels from source_area in source_image to bounding_box using
rop_descriptor instructions. In case scaling of source image is required it
will be performed according to scale_mode and before the copying to the draw
area. If mask is valid it will limit the modified area.</p></div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_DRAW_BLEND
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SpiceMsgDisplayBase
<span style="color: #008080">SPICE_ADDRESS</span> source_image
<span style="color: #008080">RECT</span> source_area
<span style="color: #008080">UINT16</span> rop_descriptor
<span style="color: #008080">UINT8</span> scale_mode
Mask mask</tt></pre></div></div>
<div class="paragraph"><p>Mixing pixels from source_area in source_image with bounding_box pixels on the
draw area using rop_descriptor instructions. In case scaling of source image is
required it will be performed according to scale_mode and before the mixing
with the draw area. If mask is valid it will limit the modified area.</p></div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_DRAW_BLACKNESS
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SpiceMsgDisplayBase
Mask mask</tt></pre></div></div>
<div class="paragraph"><p>SpiceFill bounding_box with black pixels. If mask is valid it will limit the
modified area.</p></div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_DRAW_WHITENESS
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SpiceMsgDisplayBase
Mask mask</tt></pre></div></div>
<div class="paragraph"><p>SpiceFill bounding_box with white pixels. If mask is valid it will limit the
modified area.</p></div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_DRAW_INVERS
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SpiceMsgDisplayBase
Mask mask</tt></pre></div></div>
<div class="paragraph"><p>Inverse all pixels in bounding_box. If mask is valid it will limit the modified
area.</p></div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_DRAW_ROP3
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SpiceMsgDisplayBase
<span style="color: #008080">SPICE_ADDRESS</span> source_image
<span style="color: #008080">RECT</span> source_area
SpiceBrush brush
UINT8 rop3
<span style="color: #008080">UINT8</span> scale_mode
Mask mask</tt></pre></div></div>
<div class="paragraph"><p>Mix pixels from source_area in source_image, bounding_box pixels in the draw
area, and the brush pattern. The method for mixing three pixels into the
destination area (i.e., bounding_box) is defined by rop3 (i.e., ternary raster
operations). In case scaling of source image is required it will be performed
according to scale_mode and before the mixing. If mask is valid it will limit
the modified area.</p></div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_DRAW_TRANSPARENT
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SpiceMsgDisplayBase
<span style="color: #008080">SPICE_ADDRESS</span> source_image
<span style="color: #008080">RECT</span> source_area
<span style="color: #008080">UINT32</span> transparent_color
<span style="color: #008080">UINT32</span> <span style="color: #008080">transparent</span> _true_color</tt></pre></div></div>
<div class="paragraph"><p>SpiceCopy pixels from source_area on source_image to  bounding_box on the draw area.
In case scaling of source image is required  it will use SPICE_IMAGE_SCALE_MODE_NEAREST.
Pixels with value equal to the transparent color will be masked out.
SpiceTransparent color is provided in two forms: true color (i.e., RGB888) and  the
color in the original format (i.e., before compression) .</p></div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_DRAW_ALPHA_BLEND
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SpiceMsgDisplayBase
UINT8 alpha
<span style="color: #008080">SPICE_ADDRESS</span> source_image
<span style="color: #008080">RECT</span> source_area</tt></pre></div></div>
<div class="paragraph"><p>Alpha blend source_area of source_image on  bounding_box of draw area using
alpha value or alternatively per pixel alpha value.  In case scaling of source
image is required, it will use SPICE_IMAGE_SCALE_MODE_INTERPOLATE mode. Alpha value is
defined as 0 is full transparency and 255 is full opacity. Format of source
image can be pre-multiplied ARGB8888 for per pixel alpha value.</p></div>
<div class="paragraph"><p>New RGB color is defined as:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>color<span style="color: #FF0000">' =   (source_color *  alpha)  /  255</span>
<span style="color: #FF0000">alpha'</span> <span style="color: #990000">=</span>   <span style="color: #990000">(</span>source_alpha <span style="color: #990000">*</span>  alpha<span style="color: #990000">)</span>  <span style="color: #990000">/</span>  <span style="color: #993399">255</span>
new_color <span style="color: #990000">=</span> color<span style="color: #FF0000">' + ((255 - alpha'</span> <span style="color: #990000">)</span> <span style="color: #990000">*</span> destination_color<span style="color: #990000">)</span> <span style="color: #990000">/</span> <span style="color: #993399">255</span></tt></pre></div></div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_DRAW_STROKE
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SpiceMsgDisplayBase
SPICE_ADDRESS path – address of the PathSegList that defines the path to render
SpiceLineAttr attr
Bush brush
<span style="color: #008080">UINT16</span> fore_mode <span style="color: #990000">-</span>  <span style="color: #008080">foreground</span> rop_descriptor
<span style="color: #008080">UINT16</span> back_mode – <span style="color: #008080">background</span> rop_descriptor</tt></pre></div></div>
<div class="paragraph"><p>Render path using brush line attribute and rop descriptors. If the line is
styled (i.e., LINE_ATTR_FLAG_STYLED is set in attr.falgs) then background
(i.e., inverse of the style) is drawn using back_mode and the foreground is
drawn using fore_mode. If the line is not  styled, the entire path is rendered
using fore_mode.</p></div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_DRAW_TEXT
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SpiceMsgDisplayBase
SPICE_ADDRESS string – address of GlyphString
<span style="color: #008080">RECT</span> back_area
<span style="color: #008080">SpiceBrush</span> fore_brush
<span style="color: #008080">SpiceBrush</span> back_brush
<span style="color: #008080">UINT16</span> fore_mode
<span style="color: #008080">UINT16</span> back_mode</tt></pre></div></div>
<div class="paragraph"><p>Render string of glyph on the display area using brush fore_brush and the
rop_descriptor fore_mode. If back_area is not empty the renderer fill back_area
on the display area prior to rendering the glyph string. back_area is  filled
using back_brush and the rop_descriptor back_mode.</p></div>
</li>
</ol></div>
</li>
<li>
<p>
Video streaming commands
</p>
<div class="paragraph"><p>Spice supports the creation of video streams by the server for rendering video
content on the client display area.  Unlike other rendering commands, the
stream data can  be compressed using lossy or video specific compression
algorithms. It is not required to render video frames as they arrive and it is
also allowed to drop video frames. This enables using video frames buffering
for having smoother playback and audio synchronization. Audio  synchronization
is achieved by  using time stamp that is attached to audio and video streams.
By using video streaming the network traffic can be dramatically reduced. When
the stream is created, the server sends create message using
SPICE_MSG_DISPLAY_STREAM_CREATE. After the server creates a stream he can send data
using SPICE_MSG_DISPLAY_STREAM_DATA, or set new stream clipping by sending clip
message using SPICE_MSG_DISPLAY_STREAM_CLIP. Once the server no longer needs the
stream, he can send destroy command using SPICE_MSG_DISPLAY_STREAM_DESTROY. The
server can also destroy all active streams by sending destroy all message using
SPICE_MSG_DISPLAY_STREAM_DESTROY_ALL.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
Stream flags
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>STREAM_FLAG_TOP_DOWN <span style="color: #990000">=</span> <span style="color: #993399">1</span> <span style="font-style: italic"><span style="color: #9A1900">/* stream frame line order is from top to bottom */</span></span></tt></pre></div></div>
</li>
<li>
<p>
Codec types
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>STREAM_CODEC_TYPE_MJPEG <span style="color: #990000">=</span> <span style="color: #993399">1</span> <span style="font-style: italic"><span style="color: #9A1900">/* this stream uses motion JPEG  codec */</span></span></tt></pre></div></div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_STREAM_CREATE,  SpiceMsgDisplayStreamCreate
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 id</p></td>
<td align="left" valign="top"><p class="table">id of the new stream. It is the server&#8217;s responsibility to manage stream ids</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 flags</p></td>
<td align="left" valign="top"><p class="table">flags of the stream, any combination of STREAM_FLAG_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 codec_type</p></td>
<td align="left" valign="top"><p class="table">type of codec used for this stream, one of STREAM_CODEC_TYPE_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT64 reserved</p></td>
<td align="left" valign="top"><p class="table">must be zero</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 stream_width</p></td>
<td align="left" valign="top"><p class="table">width of the source frame.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 stream_height</p></td>
<td align="left" valign="top"><p class="table">height of the source frame</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 source_width</p></td>
<td align="left" valign="top"><p class="table">actual frame width to use, must be less or equal to  stream_width.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 source_height</p></td>
<td align="left" valign="top"><p class="table">actual frame height to use, must be less or equal to  stream_height.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">RECT destination</p></td>
<td align="left" valign="top"><p class="table">area to render into on the client display area</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">SpiceClip clip</p></td>
<td align="left" valign="top"><p class="table">clipping of the stream</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_STREAM_DATA, SpiceMsgDisplayStreamData
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 id</p></td>
<td align="left" valign="top"><p class="table">stream id (i.e., SpiceMsgDisplayStreamCreate.id)</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 multimedia_time</p></td>
<td align="left" valign="top"><p class="table">frame time stamp</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 data_size</p></td>
<td align="left" valign="top"><p class="table">stream data size to consume in bytes</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 pad_size</p></td>
<td align="left" valign="top"><p class="table">additional data padding in bytes</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8[] data</p></td>
<td align="left" valign="top"><p class="table">stream data depending on SpiceMsgDisplayStreamCreate.codec_type. Size of  data is (
data_size +  pad_size)</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_STREAM_CLIP, SpiceMsgDisplayStreamClip
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 id</p></td>
<td align="left" valign="top"><p class="table">stream id (i.e., SpiceMsgDisplayStreamCreate.id)</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>SpiceClip clip – new clipping of the stream</p></div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_STREAM_DESTROY, UINT32
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32</p></td>
<td align="left" valign="top"><p class="table">id of stream to destroy</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_STREAM_DESTROY_ALL, VOID
</p>
<div class="paragraph"><p>Destroy all active streams</p></div>
</li>
</ol></div>
</li>
<li>
<p>
Cache control
</p>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
Resource type
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_RES_TYPE_PIXMAP <span style="color: #990000">=</span> <span style="color: #993399">1</span></tt></pre></div></div>
</li>
<li>
<p>
SpiceResourceID
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT8 type</p></td>
<td align="left" valign="top"><p class="table">type of the resource, one of SPICE_RES_TYPE_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT64 id</p></td>
<td align="left" valign="top"><p class="table">id of the resource</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SpiceResourceList
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT16 count</p></td>
<td align="left" valign="top"><p class="table">number of items in resources</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">SpiceResourceID[] resources</p></td>
<td align="left" valign="top"><p class="table">list of  resources id</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_INVAL_LIST, SpiceResourceList
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">SpiceResourceList</p></td>
<td align="left" valign="top"><p class="table">list of resources to remove from cache</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_INVAL_ALL_PIXMAPS, SpiceMsgWaitForChannels
</p>
<div class="paragraph"><p>Remove all images from the image cache. The client must use SpiceMsgWaitForChannels
(for more info see <a href="#channel_sync">Channel synchronization</a>) to synchronize
with other channels before clearing the cache.</p></div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_INVAL_PALETTE, UINT64
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT64 id of palette</p></td>
<td align="left" valign="top"><p class="table">client needs to remove palette with that id from the cache</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_DISPLAY_INVAL_ALL_PALETTES, VOID
</p>
<div class="paragraph"><p>Remove all palettes from palette cache</p></div>
</li>
</ol></div>
</li>
</ol></div>
</div>
</div>
<div class="sect1">
<h2 id="_cursor_channel_definition">6. Cursor channel definition</h2>
<div class="sectionbody">
<div class="paragraph"><p>Spice protocol defines a set of messages for controlling cursor shape and
position on the remote display area, cursor position messages are irrelevant
for client mouse mode (see <a href="#mouse_modes">Mouse Modes</a>). Spice protocol also
defines a set of messages for managing cursor shape cache on the client site.
Client must strictly obey all such instructions. The server sends
SPICE_MSG_CURSOR_INIT to set current pointer state (i.e., shape, position, visibility
etc.) and to clear shape cache. After the server sends init message it can send
any other cursor command except for SPICE_MSG_CURSOR_INIT. The server can send
SPICE_MSG_CURSOR_RESET message - this will disable the cursor and reset the cursor
cache. After this message the only valid message the server can send is
SPICE_MSG_CURSOR_INIT. The relevant remote display area for a cursor channel is the
one of the display channel that has the same channel id (i.e.,
SpiceLinkMess.channel_id).</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Server messages
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_MSG_CURSOR_INIT           <span style="color: #990000">=</span> <span style="color: #993399">101</span>
SPICE_MSG_CURSOR_RESET          <span style="color: #990000">=</span> <span style="color: #993399">102</span>
SPICE_MSG_CURSOR_SET            <span style="color: #990000">=</span> <span style="color: #993399">103</span>
SPICE_MSG_CURSOR_MOVE           <span style="color: #990000">=</span> <span style="color: #993399">104</span>
SPICE_MSG_CURSOR_HIDE           <span style="color: #990000">=</span> <span style="color: #993399">105</span>
SPICE_MSG_CURSOR_TRAIL          <span style="color: #990000">=</span> <span style="color: #993399">106</span>
SPICE_MSG_CURSOR_INVAL_ONE      <span style="color: #990000">=</span> <span style="color: #993399">107</span>
SPICE_MSG_CURSOR_INVAL_ALL      <span style="color: #990000">=</span> <span style="color: #993399">108</span></tt></pre></div></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
Cursors types
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_CURSOR_TYPE_ALPHA         <span style="color: #990000">=</span> <span style="color: #993399">0</span>
SPICE_CURSOR_TYPE_MONO          <span style="color: #990000">=</span> <span style="color: #993399">1</span>
SPICE_CURSOR_TYPE_COLOR4        <span style="color: #990000">=</span> <span style="color: #993399">2</span>
SPICE_CURSOR_TYPE_COLOR8        <span style="color: #990000">=</span> <span style="color: #993399">3</span>
SPICE_CURSOR_TYPE_COLOR16       <span style="color: #990000">=</span> <span style="color: #993399">4</span>
SPICE_CURSOR_TYPE_COLOR24       <span style="color: #990000">=</span> <span style="color: #993399">5</span>
SPICE_CURSOR_TYPE_COLOR32       <span style="color: #990000">=</span> <span style="color: #993399">6</span></tt></pre></div></div>
</li>
<li>
<p>
SpiceCursorHeader
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT64 unique</p></td>
<td align="left" valign="top"><p class="table">unique identifier of the corresponding cursor shape. It is used for storing
and retrieving cursors from the cursor cache.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT16 type</p></td>
<td align="left" valign="top"><p class="table">type of the shape, one of CURSOR_TYPE_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT16 width</p></td>
<td align="left" valign="top"><p class="table">width of the shape</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT16 height</p></td>
<td align="left" valign="top"><p class="table">height of the shape</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT16 hot_spot_x</p></td>
<td align="left" valign="top"><p class="table">position of hot spot on x axis</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT16 hot_spot_y</p></td>
<td align="left" valign="top"><p class="table">position of hot spot on y axis</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
Cursor flags
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>CURSOR_FLAGS_NONE               <span style="color: #990000">=</span> <span style="color: #993399">1</span></tt></pre></div></div>
<div class="paragraph"><p>set when SpiceCursor (see below) is invalid</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #008080">CURSOR_CURSOR_FLAGS</span> _CACHE_ME   <span style="color: #990000">=</span> <span style="color: #993399">2</span></tt></pre></div></div>
<div class="paragraph"><p>set when the client should add this shape to the shapes cache. The client will
use SpiceCursorHeader.unique as cache key.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>CURSOR_FLAGS_FROM_CACHE         <span style="color: #990000">=</span> <span style="color: #993399">4</span></tt></pre></div></div>
<div class="paragraph"><p>set when the client should retrieve the cursor shape, using SpiceCursorHeader.unique
as key, from the shapes cache. In this case all fields of SpiceCursorHeader except
for <em>unique</em> are invalid.</p></div>
</li>
<li>
<p>
SpiceCursor
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 flags</p></td>
<td align="left" valign="top"><p class="table">any valid combination of  SPICE_CURSOR_FLAGS_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">SpiceCursorHeader header</p></td>
<td align="left" valign="top"><p class="table"></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8[] data</p></td>
<td align="left" valign="top"><p class="table">actual cursor shape data, the size is determine by width, height and type from
SpiceCursorHeader. Next we will describe in detail the  shape data format according
to cursor type:</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">ALPHA, alpha shape</p></td>
<td align="left" valign="top"><p class="table">data contains pre-multiplied ARGB8888 pixmap. Line stride is &lt;width * 4&gt;.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">MONO, monochrome shape</p></td>
<td align="left" valign="top"><p class="table">data contains two bitmaps with size  &lt;width&gt; * &lt;height&gt;. The first bitmap is
AND mask and the second is XOR mask.  Line stride is ALIGN(&lt;width&gt;, 8) / 8.
Bits order within every byte is big endian.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">COLOR4, 4 bits per pixel shape</p></td>
<td align="left" valign="top"><p class="table">First data region is pixmap: the stride of the pixmap is ALIGN(width , 2) / 2;
every nibble is translated to a color usingthe color palette; Nibble order is
big endian. Second data region contain 16 colors palette: each entry is 32 bit
RGB color. Third region is a bitmap mask:  line stride is ALIGN(&lt;width&gt;, 8) /
8; bits order within every byte is big endian.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">COLOR4, 8 bits per pixel shape</p></td>
<td align="left" valign="top"><p class="table">First data region is pixmap: the stride of the pixmap is &lt;width&gt;; every byte
is translated to color using the color palette. Second data region contain 256
colors palette: each entry is 32 bit RGB color. Third region is a bitmap mask:
line stride is ALIGN(&lt;width&gt;, 8) / 8; bits order within every byte is big
endian.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">COLOR16, 16 bits per pixel shape</p></td>
<td align="left" valign="top"><p class="table">First data region is pixmap: the stride of the pixmap is &lt;width * 2&gt;; every
UINT16 is RGB_555. Second region is a bitmap mask: line stride is
ALIGN(&lt;width&gt;, 8) / 8; bits order within every byte is big endian.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">COLOR24, 24 bits per pixel shape</p></td>
<td align="left" valign="top"><p class="table">First data region is pixmap: the stride of the pixmap is &lt;width * 3&gt;; every
UINT8[3] is RGB_888. Second region is a bitmap mask: line stride is
ALIGN(&lt;width&gt;, 8) / 8; bits order within every byte is big endian.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">COLOR32, 32 bits per pixel shape</p></td>
<td align="left" valign="top"><p class="table">First data region is pixmap: the stride of the pixmap is &lt;width * 4&gt;,;every
UINT32 is RGB_888. Second region is a bitmap mask: line stride is
ALIGN(&lt;width&gt;, 8) / 8; bits order within every byte is big endian.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>For more deatails on drawing the cursor shape see <a href="#cursor_shape">this section</a></p></div>
</li>
<li>
<p>
SPICE_MSG_CURSOR_INIT, SpiceMsgCursorInit
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">POINT16 position</p></td>
<td align="left" valign="top"><p class="table">position of mouse pointer on the relevant display area. Not relevant  in
client mode.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT16 trail_length</p></td>
<td align="left" valign="top"><p class="table">number of cursors in the trail excluding main cursor.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT16 trail_frequency</p></td>
<td align="left" valign="top"><p class="table">millisecond interval between trail updates.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UIN8 visible</p></td>
<td align="left" valign="top"><p class="table">if 1, the cursor is visible. If 0, the cursor is invisible.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">SpiceCursor cursor</p></td>
<td align="left" valign="top"><p class="table">current cursor shape</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_CURSOR_RESET, VOID
</p>
</li>
<li>
<p>
SPICE_MSG_CURSOR_SET, SpiceMsgCursorSet
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">POINT16 position</p></td>
<td align="left" valign="top"><p class="table">position of mouse pointer on the relevant display area. not relevant in client
mode.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8 visible</p></td>
<td align="left" valign="top"><p class="table">if 1, the cursor is visible. If 0, the cursor is invisible.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">SpiceCursor cursor</p></td>
<td align="left" valign="top"><p class="table">current cursor shape</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_CURSOR_MOVE, POINT16
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">POINT16</p></td>
<td align="left" valign="top"><p class="table">new mouse position. Not relevant in client mode. This message also implicitly
sets cursor visibility to 1.</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_CURSOR_HIDE, VOID
</p>
<div class="paragraph"><p>Hide pointer on the relevant display area.</p></div>
</li>
<li>
<p>
SPICE_MSG_CURSOR_TRAIL
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT16 length</p></td>
<td align="left" valign="top"><p class="table">number of cursors in the trail excluding main cursor.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT16 frequency</p></td>
<td align="left" valign="top"><p class="table">millisecond interval between trail updates</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_CURSOR_INVAL_ONE, UINT64
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT64</p></td>
<td align="left" valign="top"><p class="table">id of cursor shape to remove from the cursor cache</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_CURSOR_INVAL_ALL, VOLD
</p>
<div class="paragraph"><p>Clear cursor cache</p></div>
</li>
</ol></div>
</li>
<li>
<p>
Drawing the cursor shape according to the cursor type
</p>
<div class="paragraph" id="cursor_shape"><p>This section is relevant only for server mouse mode. Cursor shape positioning
on the display area is done by placing cursor hot spot on the current cursor
position.</p></div>
<div class="olist loweralpha"><ol class="loweralpha">
<li>
<p>
Alpha - no spacial handling, just bland the shape on the display area.
</p>
</li>
<li>
<p>
Monochrome
</p>
<div class="paragraph"><p>For each cleared bit in the AND mask clear the corresponding bits in the
relevant pixel on the display area
For each set bit in the XOR mask reverse the
corresponding bits in the relevant pixel on the display area</p></div>
</li>
<li>
<p>
Color
</p>
<div class="paragraph"><p>If the source color is black and mask bit is set,  NOP.
Else, if the source color is white and the mask bit is set, reverse all bits in
the relevant pixel on the display area.
Else, put source color.</p></div>
</li>
</ol></div>
</li>
</ol></div>
</div>
</div>
<div class="sect1">
<h2 id="_playback_channel_definition">7. Playback channel definition</h2>
<div class="sectionbody">
<div class="paragraph"><p>Spice supports sending audio streams for playback on the client side. An audio
stream is sent by the server in an audio packet using SPICE_MSG_PLAYBACK_DATA
message. The content of the audio packet is controlled by the playback mode
that the server sends using SPICE_MSG_PLAYBACK_MODE message. The server can start and
stop the stream using SPICE_MSG_PLAYBACK_START and SPICE_MSG_PLAYBACK_STOP messages.
Sending audio packet is allowed only between  start and stop messages. Sending
start message is allowed only in stop state and after at least one mode message
was sent. Sending a stop message is allowed only during a start state.</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Server messages
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_MSG_PLAYBACK_DATA                 <span style="color: #990000">=</span> <span style="color: #993399">101</span>
SPICE_MSG_PLAYBACK_MODE                 <span style="color: #990000">=</span> <span style="color: #993399">102</span>
SPICE_MSG_PLAYBACK_START                <span style="color: #990000">=</span> <span style="color: #993399">103</span>
SPICE_MSG_PLAYBACK_STOP                 <span style="color: #990000">=</span> <span style="color: #993399">104</span></tt></pre></div></div>
</li>
<li>
<p>
Audio format
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_AUDIO_FMT_S16                     <span style="color: #990000">=</span> <span style="color: #993399">1</span> <span style="font-style: italic"><span style="color: #9A1900">/* each channel sample is a 16 bit</span></span>
<span style="font-style: italic"><span style="color: #9A1900">signed integer */</span></span></tt></pre></div></div>
</li>
<li>
<p>
Playback data mode
</p>
<div class="paragraph"><p>Two types of data mode are available: (1) raw PCM data, (2) compressed data
in CELT 0_5_1 format (obsolete) and (3) compressed data in OPUS format.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_AUDIO_DATA_MODE_RAW               <span style="color: #990000">=</span> <span style="color: #993399">1</span>
SPICE_AUDIO_DATA_MODE_CELT_0_5_1        <span style="color: #990000">=</span> <span style="color: #993399">2</span>
SPICE_AUDIO_DATA_MODE_OPUS              <span style="color: #990000">=</span> <span style="color: #993399">3</span></tt></pre></div></div>
</li>
<li>
<p>
Playback channel capabilities
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_PLAYBACK_CAP_CELT_0_5_1           <span style="color: #990000">=</span> <span style="color: #993399">0</span>
SPICE_PLAYBACK_CAP_VOLUME               <span style="color: #990000">=</span> <span style="color: #993399">1</span>
SPICE_PLAYBACK_CAP_LATENCY              <span style="color: #990000">=</span> <span style="color: #993399">2</span>
SPICE_PLAYBACK_CAP_OPUS                 <span style="color: #990000">=</span> <span style="color: #993399">3</span></tt></pre></div></div>
<div class="paragraph"><p>Spice client needs to declare support of OPUS in channel capabilities in
order to allow the server to send playback packets in OPUS format.</p></div>
</li>
<li>
<p>
SPICE_MSG_PLAYBACK_MODE, SpiceMsgPlaybackMode
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 time</p></td>
<td align="left" valign="top"><p class="table">server time stamp</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 mode</p></td>
<td align="left" valign="top"><p class="table">one of SPICE_AUDIO_DATA_MODE_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8[] data</p></td>
<td align="left" valign="top"><p class="table">specific data, content depend on mode</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_PLAYBACK_START, SpiceMsgRecordStart
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 channels</p></td>
<td align="left" valign="top"><p class="table">number of audio channels</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 format</p></td>
<td align="left" valign="top"><p class="table">one of SPICE_AUDIO_FMT_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 frequency</p></td>
<td align="left" valign="top"><p class="table">channel samples per second</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_PLAYBACK_DATA, SpiceMsgPlaybackPacket
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 time</p></td>
<td align="left" valign="top"><p class="table">server time stamp</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8[] data</p></td>
<td align="left" valign="top"><p class="table">playback data , content depend on mode</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_PLAYBACK_STOP, VOID
</p>
<div class="paragraph"><p>Stop current audio playback</p></div>
</li>
</ol></div>
</div>
</div>
<div class="sect1">
<h2 id="_record_channel_definition">8. Record Channel definition</h2>
<div class="sectionbody">
<div class="paragraph"><p>Spice supports transmitting of audio captured streams from the client to the
server. Spice server starts audio capturing using SPICE_MSG_RECORD_START message.
This message instructs the client to start transmitting captured audio . In
response, the client sends time stamp of the stream start using
SPICE_MSGC_RECORD_START_MARK. After the client sends start mark it can start
transmitting audio stream data using SPICE_MSGC_RECORD_DATA. One mode message must be
sent by the client before any other message using SPICE_MSGC_RECORD_MODE. This, in
order to inform the server on what type of data will be transferred. Mode
message can also be transmitted at any other time in order to switch the data
type delivered by SPICE_MSGC_RECORD_DATA. The Server can send SPICE_MSG_RECORD_STOP for
stopping captured audio streaming. Sending a start message is allowed only
while the stream is in stop state. Sending a stop message and data messages is
allowed only while the stream is in start state. Sending mark message is
allowed only between start message and the first data message.</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Server messages
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_MSG_RECORD_START                  <span style="color: #990000">=</span> <span style="color: #993399">101</span>
SPICE_MSG_RECORD_STOP                   <span style="color: #990000">=</span> <span style="color: #993399">102</span></tt></pre></div></div>
</li>
<li>
<p>
Client messages
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_MSGC_RECORD_DATA                  <span style="color: #990000">=</span> <span style="color: #993399">101</span>
SPICE_MSGC_RECORD_MODE                  <span style="color: #990000">=</span> <span style="color: #993399">102</span>
SPICE_MSGC_RECORD_START_MARK            <span style="color: #990000">=</span> <span style="color: #993399">103</span></tt></pre></div></div>
</li>
<li>
<p>
Audio format
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_AUDIO_FMT_S16                     <span style="color: #990000">=</span> <span style="color: #993399">1</span> <span style="font-style: italic"><span style="color: #9A1900">/* each channel sample is a 16 bit signed integer */</span></span></tt></pre></div></div>
</li>
<li>
<p>
Record data mode
</p>
<div class="paragraph"><p>Two types of data mode are available: (1) raw PCM data (2) compressed data   in
CELT 0.5.1 format (obsolete) (3) compressed data in OPUS format.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_AUDIO_DATA_MODE_RAW               <span style="color: #990000">=</span> <span style="color: #993399">1</span>
SPICE_AUDIO_DATA_MODE_CELT_0_5_1        <span style="color: #990000">=</span> <span style="color: #993399">2</span>
SPICE_AUDIO_DATA_MODE_OPUS              <span style="color: #990000">=</span> <span style="color: #993399">3</span></tt></pre></div></div>
</li>
<li>
<p>
Record channel capabilities
</p>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>SPICE_RECORD_CAP_CELT_0_5_1             <span style="color: #990000">=</span> <span style="color: #993399">0</span>
SPICE_RECORD_CAP_VOLUME                 <span style="color: #990000">=</span> <span style="color: #993399">1</span>
SPICE_RECORD_CAP_OPUS                   <span style="color: #990000">=</span> <span style="color: #993399">2</span></tt></pre></div></div>
<div class="paragraph"><p>Spice server needs to declare support of OPUS in channel capabilities in
order to allow the client to send recorded packets in OPUS format.</p></div>
</li>
<li>
<p>
SPICE_MSGC_RECORD_MODE, SpiceMsgcRecordMode
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 time</p></td>
<td align="left" valign="top"><p class="table">client time stamp</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 mode</p></td>
<td align="left" valign="top"><p class="table">one of SPICE_AUDIO_DATA_MODE_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8[] data</p></td>
<td align="left" valign="top"><p class="table">specific data, content depend on mode</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_RECORD_START, SpiceMsgRecordStart
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 channel</p></td>
<td align="left" valign="top"><p class="table">number of audio channels</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 format</p></td>
<td align="left" valign="top"><p class="table">one of SPICE_AUDIO_FMT_?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT32 frequency</p></td>
<td align="left" valign="top"><p class="table">channel samples per second</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSGC_RECORD_START_MARK, UINT32
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32</p></td>
<td align="left" valign="top"><p class="table">client time stamp of stream start</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSGC_RECORD_DATA, SpiceMsgcRecordPacket
</p>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">UINT32 time</p></td>
<td align="left" valign="top"><p class="table">client time stamp</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">UINT8[] data</p></td>
<td align="left" valign="top"><p class="table">recorded data , content depend on mode</p></td>
</tr>
</tbody>
</table>
</div>
</li>
<li>
<p>
SPICE_MSG_RECORD_STOP, VOID
</p>
<div class="paragraph"><p>Stop current audio capture</p></div>
</li>
</ol></div>
</div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Version v1.0<br />
Last updated
 2025-05-05 20:35:28 UTC
</div>
</div>
</body>
</html>