diff options
Diffstat (limited to 'bltsville/bltsville/index.html')
| -rw-r--r-- | bltsville/bltsville/index.html | 4362 |
1 files changed, 4362 insertions, 0 deletions
diff --git a/bltsville/bltsville/index.html b/bltsville/bltsville/index.html new file mode 100644 index 0000000..4b3a96c --- /dev/null +++ b/bltsville/bltsville/index.html @@ -0,0 +1,4362 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
+
+<head>
+<meta http-equiv="Content-Language" content="en-us" />
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Welcome to BLTsville</title>
+<style type="text/css">
+.cmd_line {
+ background: #000;
+ color: #fff;
+ padding: 10px;
+}
+.inline_code {
+ font-family: "Courier New", Courier, monospace;
+ font-size: small;
+}
+.code_block {
+ margin-left: 40px;
+ font-family: "Courier New", Courier, monospace;
+ font-size: small;
+}
+.small_code_block_in_table {
+ font-family: "Courier New", Courier, monospace;
+ font-size: x-small;
+}
+.small_code_block {
+ font-family: "Courier New", Courier, monospace;
+ font-size: x-small;
+ margin-left: 40px;
+}
+.underline_code {
+ font-family: "Courier New", Courier, monospace;
+ font-size: small;
+ text-decoration: underline;
+}
+.Code_Header {
+ font-size: xx-large;
+ font-weight: bold;
+ text-align: left;
+ font-family: "Courier New", Courier, monospace;
+}
+.Code_Header_2 {
+ font-size: x-large;
+ font-weight: bold;
+ text-align: left;
+ font-family: "Courier New", Courier, monospace;
+}
+.Code_Header_3 {
+ font-size: large;
+ font-weight: bold;
+ text-align: left;
+ font-family: "Courier New", Courier, monospace;
+}
+.imponly {
+ border: thin solid #666666;
+ margin-left: 40px;
+ background-color: #E5E5E5;
+ font-family: Arial, Helvetica, sans-serif;
+ color: #333333;
+}
+.Header1 {
+ margin: 0px 0 0 0;
+ font-size: xx-large;
+ font-weight: bold;
+ text-align: left;
+ line-height: normal;
+ background-color: #E0E0E0;
+}
+.Header2 {
+ font-size: xx-large;
+ font-weight: bold;
+ margin: 0px;
+ line-height: 100%;
+}
+.Header3 {
+ font-size: x-large;
+ font-weight: bold;
+ margin: 0px;
+ line-height: 100%;
+}
+.Header4 {
+ font-size: large;
+ font-weight: bold;
+ margin: 0px;
+ line-height: 100%;
+}
+.strong_emphasis {
+ text-decoration: underline;
+ font-weight: bold;
+}
+.filename {
+ font-family: Arial, Helvetica, sans-serif;
+ font-size: small;
+}
+.underline {
+ text-decoration: underline;
+}
+.grn_left {
+ text-align: left;
+ color: #009900;
+}
+.left_topbord {
+ text-align: left;
+ border-top-style: solid;
+ border-top-width: 1px;
+}
+.center_topbord {
+ text-align: center;
+ border-top-style: solid;
+ border-top-width: 1px;
+}
+.blue_left_botbord {
+ text-align: left;
+ border-bottom-style: solid;
+ border-bottom-width: 1px;
+ color: #0000FF;
+}
+.blue_center_botbord {
+ text-align: center;
+ border-bottom-style: solid;
+ border-bottom-width: 1px;
+ color: #0000FF;
+}
+.red_center {
+ text-align: center;
+ color: #FF0000;
+}
+.red_left {
+ text-align: left;
+ color: #FF0000;
+}
+.grn_center {
+ text-align: center;
+ color: #009900;
+}
+.red_center_topbord {
+ text-align: center;
+ border-top-style: solid;
+ border-top-width: 1px;
+ color: #FF0000;
+}
+.blu_center_topbord {
+ text-align: center;
+ border-top-style: solid;
+ border-top-width: 1px;
+ color: #0000FF;
+}
+.indent_thick_bord {
+ border-color: #000000;
+ border-style: solid;
+ margin-left: 40px;
+}
+.thin_bord {
+ border-style: solid;
+ border-width: 1px;
+}
+.thin_bord_dbl_botbord {
+ border-left-style: solid;
+ border-left-width: 1px;
+ border-right-style: solid;
+ border-right-width: 1px;
+ border-top-style: solid;
+ border-top-width: 1px;
+ border-bottom-style: double;
+ border-bottom-width: 3px;
+}
+.dl_link {
+ float: right;
+}
+.note {
+ font-family: Arial, Helvetica, sans-serif;
+ font-weight: bold;
+ margin-left: 40px;
+}
+.small_note {
+ font-size: xx-small;
+ line-height: 100%;
+}
+.ctr {
+ text-align: center;
+}
+.glyph_cache {
+ font-family: "Courier New", Courier, monospace;
+ font-size: medium;
+ font-weight: normal;
+ font-style: normal;
+ margin-left: 40px;
+ background-color: #000000;
+ color: #FFFFFF;
+}
+.example {
+ border-style: solid;
+ border-width: 1px;
+ margin-left: 40px;
+ margin-right: 40px;
+}
+.rt_thick_bord {
+ border-right-style: solid;
+ border-right-color: #000000;
+}
+.indent {
+ margin-left: 40px;
+}
+.ctr_thin_bord {
+ border-style: solid;
+ border-width: 1px;
+ text-align: center;
+}
+.indent_thin_bord {
+ border-style: solid;
+ border-width: 1px;
+ margin-left: 40px;
+}
+.bold_sans {
+ font-family: Arial, Helvetica, sans-serif;
+ font-weight: bold;
+}
+.nowrap {
+ border-style: solid;
+ border-width: 1px;
+ white-space: nowrap;
+ font-size: small;
+}
+</style>
+</head>
+
+<body>
+
+<table style="width: 100%; line-height: 100%;">
+ <tr>
+ <td style="width: 484px">
+ <table>
+ <tr>
+ <td>
+ <div style="background-position: center; background-image: url('bvlogo.png'); width: 484px; height: 400px; background-repeat: no-repeat;">
+ <div style="position: relative; left: 0; top: 0;">
+ <a href="http://graphics.github.com/ocd">
+ <img src="ocdtab.png" alt="Now With OCD" style="border-width: 0; position: absolute; top: 0; right: 0;" /></a>
+ </div>
+ </div>
+ </td>
+ </tr>
+ <tr>
+ <td class="ctr"><span class="Header2">Version 2.2</span></td>
+ </tr>
+ </table>
+ </td>
+ <td>
+ <p>BLTsville is the open 2-D API designed to provide an abstract interface for both hardware and software 2-D implementations.</p>
+ <p>BLTs (BLock Transfers) involve the moving around of blocks (rectangles) of pixels. BLTsville is the place
+ to go for BLTs.</p>
+ <hr />
+ <table style="width: 100%">
+ <tr>
+ <td>
+ <div class="dl_link">
+ <img alt="CC BY-ND" longdesc="Creative Commons Attribution-NoDerivs 3.0 Unported License" src="http://i.creativecommons.org/l/by-nd/3.0/88x31.png" width="88" height="31" /></div>
+ <p class="Header2">License</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <div>
+ <p class="small_note">The API is designed and maintained by Texas Instruments, Inc., but anyone is free
+ to use it with no cost or obligation.</p>
+ <p>This project is licensed under the <a href="http://creativecommons.org/licenses/by-nd/3.0/">Creative
+ Commons Attribution-NoDerivs 3.0 Unported License</a> (user mode), and the
+ <a href="http://www.gnu.org/licenses/gpl-2.0.html">GNU General Public License version 2</a> (kernel
+ mode).</p>
+ </div>
+ </td>
+ </tr>
+ </table>
+ <hr />
+ <table style="width: 100%">
+ <tr>
+ <td>
+ <p class="Header2">Dependencies</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>This project is dependent on the <a href="http://graphics.github.com/ocd">Open Color format Defintions
+ (OCD) project</a>.</p>
+ </td>
+ </tr>
+ </table>
+ <hr />
+ <table style="width: 100%">
+ <tr>
+ <td>
+ <p class="Header2">Source</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <div class="dl_link">
+ <a href="http://github.com/graphics/bltsville/zipball/master">
+ <img width="90" alt="download zip" src="http://github.com/images/modules/download/zip.png" /></a>
+ <a href="http://github.com/graphics/bltsville/tarball/master">
+ <img width="90" alt="download tar" src="http://github.com/images/modules/download/tar.png" /></a>
+ </div>
+ <div>
+ Get the source code (headers) from GitHub at <a href="http://github.com/graphics/bltsville">github.com/graphics/bltsville</a>,
+ or download the project in <a href="http://github.com/graphics/bltsville/zipball/master">zip</a> or
+ <a href="http://github.com/graphics/bltsville/tarball/master">tar</a> format.</div>
+ <p>You can also clone the project with <a href="http://git-scm.com">Git</a> by running:</p>
+ <pre><a class="cmd_line">$ git clone git://github.com/graphics/bltsville</a></pre>
+ </td>
+ </tr>
+ <tr>
+ <td><hr />
+ <table style="width: 100%">
+ <tr>
+ <td class="Header2">Wiki</td>
+ </tr>
+ <tr>
+ <td><a href="https://github.com/graphics/bltsville/wiki">https://github.com/graphics/bltsville/wiki</a></td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+</table>
+<hr />
+<p class="Header1">Points of Interest in BLTsville</p>
+<table style="width: 100%">
+ <tr>
+ <td style="width: 50%" valign="top">
+ <ul>
+ <li>Solid fills</li>
+ <li>Pattern fills</li>
+ <li>Copies</li>
+ <li>Color format conversion<ul>
+ <li>Extensive color format support<ul>
+ <li>RGB, BGR</li>
+ <li>RGBA, ARGB, etc.</li>
+ <li>YCbCr (YUV)<ul>
+ <li>subsampling</li>
+ <li>packed</li>
+ <li>planar</li>
+ </ul>
+ </li>
+ <li>Monochrome</li>
+ <li>Alpha-only</li>
+ <li>Look-Up Table (LUT)</li>
+ </ul>
+ </li>
+ <li>Extensible color format</li>
+ </ul>
+ </li>
+ <li>ROP4<ul>
+ <li>Three inputs</li>
+ </ul>
+ </li>
+ <li>Blends<ul>
+ <li>Pre-defined Porter-Duff blends</li>
+ <li>Pre-defined DirectFB support</li>
+ <li>Extensible blends</li>
+ </ul>
+ </li>
+ <li>Multiple </li>
+ <li>Filters<ul>
+ <li>Extensible filters</li>
+ </ul>
+ </li>
+ <li>Independent horizontal and vertical <strong>flipping</strong></li>
+ <li>Independent <strong>scaling</strong> of all three inputs</li>
+ <li>Clipping</li>
+ <li>Independent <strong>rotation</strong> of all three inputs (multiples of 90 degrees)</li>
+ </ul>
+ </td>
+ <td style="width: 50%" valign="top">
+ <ul>
+ <li>Choice of <strong>scaling</strong> type<ul>
+ <li>Quality based choice</li>
+ <li>Speed based choice</li>
+ <li>Image type based choice</li>
+ <li>Specific scale type choice</li>
+ <li>Extensible scale type</li>
+ </ul>
+ </li>
+ <li>Synchronous operations</li>
+ <li>Asynchronous operations<ul>
+ <li>Client notification of BLT completion</li>
+ </ul>
+ </li>
+ <li>Batching<ul>
+ <li>Combine multiple BLTs into group that can be handled more efficiently by implementations<ul>
+ <li>Character BLTs</li>
+ <li>Multi-layer blending</li>
+ <li>ROP/Blend combination with specified ordering</li>
+ <li>etc.</li>
+ </ul>
+ </li>
+ <li>Delta BLTs</li>
+ </ul>
+ </li>
+ <li>Dithering<ul>
+ <li>Quality based choice</li>
+ <li>Speed based choice</li>
+ <li>Image type based choice</li>
+ <li>Specific dither type choice</li>
+ <li>Extensible dither type</li>
+ </ul>
+ </li>
+ <li>Any implementation support<ul>
+ <li>CPU</li>
+ <li>2-D Accelerator</li>
+ </ul>
+ </li>
+ </ul>
+ </td>
+ </tr>
+</table>
+<hr />
+<ul>
+ <li>BLTsville does not dictate capabilities of the implementations<ul>
+ <li>Operations specified either work or return an error indicating that the operation is not supported</li>
+ </ul>
+ </li>
+</ul>
+<hr />
+<p class="Header1">How to Get to BLTsville</p>
+<p>BLTsville's API is defined in the BLTsville header files. A client must include <span class="inline_code">bltsville.h</span>
+to access the implementations. This header includes the remaining headers (including <span class="inline_code">ocd.h</span>).</p>
+<p class="note">NOTE: The <span class="underline_code">bvinternal.h</span><span class="underline"> header is for implementations
+only</span> and should not be used by clients.</p>
+<p>BLTsville has both user mode and a kernel mode interaces. The kernel mode interface is quite similar to (and compatible
+with) the user mode, but due to the minor differences and license issues, there are two different sets of header files.</p>
+<hr />
+<p class="Header1">History of BLTsville</p>
+<br />
+<p class="Header4">Versions 1.x</p>
+<p>BLTsville was based on a previous closed interface, which had a few implementations and shipped on a few devices.
+That interface represented the 1.x versions. A lot was learned from that work, and these lessons were used in the
+founding of BLTsville.</p>
+<p class="Header4">Version 2.0</p>
+<p>This was the initial release of the user mode interface. This version is not compatible with the 1.x versions.
+Several minor updates were posted, but the API itself did not change, so no changes to the client or implementation were
+required.</p>
+<p class="Header4">Version 2.1</p>
+<p>This is a minor update to the API, and it adds the kernel mode interface. Some additions to the API have been made.
+Details of the changes are below with their compatibility matrices.</p>
+<ul>
+ <li><span class="inline_code"><a href="#bv_cache">bv_cache()</a></span> was added to allow manipulation of the CPU cache.
+ This is an optional interface meant for hardware implementations.</li>
+</ul>
+<table class="indent_thin_bord">
+ <tr>
+ <td class="thin_bord"> </td>
+ <td class="ctr_thin_bord"><strong>2.0 Client</strong></td>
+ <td class="ctr_thin_bord"><strong>2.0 Client</strong><br />
+ (w/2.1 Headers)</td>
+ <td class="ctr_thin_bord"><strong>2.1 Client</strong></td>
+ </tr>
+ <tr>
+ <td class="thin_bord"><strong>2.0 Implementation</strong></td>
+ <td class="ctr_thin_bord">compatible</td>
+ <td class="ctr_thin_bord">New function and structure definitions have no effect.</td>
+ <td class="ctr_thin_bord">Client must deal with lack of <span class="inline_code"><a href="#bv_cache">bv_cache()</a></span>.</td>
+ </tr>
+ <tr>
+ <td class="thin_bord"><strong>2.0 Implementation</strong><br />
+ (w/2.1 Headers)</td>
+ <td class="ctr_thin_bord">New function and structure definitions have no effect.</td>
+ <td class="ctr_thin_bord">New function and structure definitions have no effect.</td>
+ <td class="ctr_thin_bord">Client must deal with lack of <span class="inline_code"><a href="#bv_cache">bv_cache()</a></span>.</td>
+ </tr>
+ <tr>
+ <td class="thin_bord"><strong>2.1 Implementation</strong></td>
+ <td class="ctr_thin_bord">New function and structures have no effect.</td>
+ <td class="ctr_thin_bord">New function and structures have no effect.</td>
+ <td class="ctr_thin_bord">compatible</td>
+ </tr>
+</table>
+<ul>
+ <li><span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> was extended with the
+ <span class="inline_code"><a href="#bvbuffdesc.auxtype">auxtype</a></span> and <span class="inline_code">
+ <a href="#bvbuffdesc.auxptr">auxptr</a></span> members to allow buffer descriptions beyond a virtual address.
+ Note that only the kernel mode interface currently includes a standard <span class="inline_code">auxtype</span>, but
+ user mode interface <span class="inline_code">auxtype</span>s may be added later. Both interfaces provide a mechanism
+ for individual vendors to add their own <span class="inline_code">auxtype</span>, using the same vendor ID mechanism
+ as the rest of BLTsville.</li>
+</ul>
+<table class="indent_thin_bord">
+ <tr>
+ <td class="thin_bord"> </td>
+ <td class="ctr_thin_bord"><strong>2.0 Client</strong></td>
+ <td class="ctr_thin_bord"><strong>2.0 Client</strong><br />
+ (w/2.1 Headers)</td>
+ <td class="ctr_thin_bord"><strong>2.1 Client</strong></td>
+ </tr>
+ <tr>
+ <td class="thin_bord"><strong>2.0 Implementation</strong></td>
+ <td class="ctr_thin_bord">compatible</td>
+ <td class="ctr_thin_bord">Client must clear <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span>
+ using <span class="inline_code"><span style="white-space: nowrap">sizeof(<a href="#bvbuffdesc">bvbuffdesc</a>)</span></span>.</td>
+ <td class="ctr_thin_bord">Implementation must handle <span class="inline_code">
+ <a href="#bvbuffdesc.structsize">bvbuffdesc.structsize</a> > <span style="white-space: nowrap">sizeof(<a href="#bvbuffdesc">bvbuffdesc</a>)</span></span>.</td>
+ </tr>
+ <tr>
+ <td class="thin_bord"><strong>2.0 Implementation</strong><br />
+ (w/2.1 Headers)</td>
+ <td class="ctr_thin_bord">Implementation must handle <span class="inline_code">
+ <a href="#bvbuffdesc.structsize">bvbuffdesc.structsize</a> < <span style="white-space: nowrap">sizeof(<a href="#bvbuffdesc">bvbuffdesc</a>)</span></span>.</td>
+ <td class="ctr_thin_bord">Client must clear <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span>
+ using <span class="inline_code"><span style="white-space: nowrap">sizeof(<a href="#bvbuffdesc">bvbuffdesc</a>)</span></span>.</td>
+ <td class="ctr_thin_bord">Client must deal with implementation that uses <span class="inline_code">
+ <a href="#bvbuffdesc.virtaddr">bvbuffdesc.virtaddr</a></span> or returns error if <span class="inline_code">
+ <a href="#bvbuffdesc.virtaddr">bvbuffdesc.virtaddr</a></span> is 0.</td>
+ </tr>
+ <tr>
+ <td class="thin_bord"><strong>2.1 Implementation</strong></td>
+ <td class="ctr_thin_bord">Implementation must handle <span class="inline_code">
+ <a href="#bvbuffdesc.structsize">bvbuffdesc.structsize</a> < <span style="white-space: nowrap">sizeof(<a href="#bvbuffdesc">bvbuffdesc</a>)</span></span>.</td>
+ <td class="ctr_thin_bord">Client must clear <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span>
+ using <span class="inline_code"><span style="white-space: nowrap">sizeof(<a href="#bvbuffdesc">bvbuffdesc</a>)</span></span>.</td>
+ <td class="ctr_thin_bord">compatible</td>
+ </tr>
+</table>
+<ul>
+ <li>Added documentation of <a href="#NOP">NOP BLT</a> used as synchronization mechanism for <a href="#BVFLAG_ASYNC">
+ asynchronous BLTs</a>.<ul>
+ <li>Clients that do not use <a href="#BVFLAG_ASYNC">asynchronous BLTs</a> or the <a href="#NOP">NOP BLT</a> will
+ not be affected.</li>
+ <li>Implementations that do not support the NOP BLT will return an error. This will not cause a problem
+ for clients when using implementations which are actually synchronous. For clients using asynchronous
+ implementations, an alternate supported but innocuous BLT will be necessary (e.g. copying a pixel to itself).</li>
+ </ul>
+ </li>
+</ul>
+<p class="Header4">Version 2.2</p>
+<p>This is a minor update which includes the following:</p>
+<ul>
+ <li>Addition of the <span class="inline_code"><a href="#src2auxdstrect">src2auxdstrect</a></span> and
+ <span class="inline_code"><a href="#maskauxdstrect">maskauxdstrect</a></span> members to <span class="inline_code">
+ <a href="#bvbltparams">bvbltparams</a></span> with example.</li>
+ <li>Addition of <span class="inline_code"><a href="#BVFLAG_SRC2_AUXDSTRECT">BVFLAG_SRC2_AUXDSTRECT</a></span> and <span class="inline_code">
+ <a href="#BVFLAG_MASK_AUXDSTRECT">BVFLAG_MASK_AUXDSTRECT</a></span> flags.</li>
+ <li>Added <span class="inline_code"><a href="#BVAT_PHYSADDR">BVAT_PHYSADDR</a></span> to the kernel mode
+ <span class="inline_code"><a href="#bvbuffdesc.auxtype">bvbuffdesc.auxtype</a></span> enumerations.</li>
+ <li>Added clarification to the <span class="inline_code"><a href="#bvphysdesc">bvphysdesc</a></span> documentation.</li>
+</ul>
+<p>Compatibility</p>
+<ul>
+ <li>Clients that do not use the <span class="inline_code"><a href="#BVFLAG_SRC1_AUXDSTRECT">BVFLAG_*_AUXDSTRECT</a></span>
+ flags will not be affected.</li>
+ <li>Clients using the new (long) <span class="inline_code"><a href="#bvbltparams">bvbltparams</a></span> will work with
+ older implementations. If the clients set the <span class="inline_code"><a href="#BVFLAG_SRC2_AUXDSTRECT">
+ BVFLAG_*_AUXDSTRECT</a></span> flags, the implementations will return <span class="inline_code">BVERR_FLAGS</span>,
+ indicating the lack of support for this feature.</li>
+ <li>Implementations supporting the new <span class="inline_code"><a href="#bvbltparams">bvbltparams</a></span> will
+ accept the older (smaller) version, distinguished by the <span class="inline_code">
+ <a href="#bvbltparams.structsize">structsize</a></span> member. Clients using the older versions will not set
+ the <span class="inline_code"><a href="#BVFLAG_SRC2_AUXDSTRECT">BVFLAG_*_AUXDSTRECT</a></span> flags, so the new
+ members will not be utilized.</li>
+ <li>Clients using <span class="inline_code"><a href="#BVAT_PHYSADDR">BVAT_PHYSADDR</a></span> will get an error from
+ implementations that do not support this enumeration. The <span class="inline_code"><a href="#BVAT_PHYSDESC">
+ BVAT_PHYSDESC</a></span> may be used if supported by the implementation, but care must be taken to ensure the buffer
+ is defined properly. See <span class="inline_code"><a href="#bvphysdesc">bvphysdesc</a></span> for details.</li>
+</ul>
+<hr />
+<p class="Header1">BLTsville Neighborhoods</p>
+<p>Implementations may be software (CPU) or 2-D hardware, and many may coexist. Each implementation will have an individual
+entry point, so it can be directly addressed. But there will also be a more general interface for each of these two
+types of implementations so that system integrators can choose the most appropriate implementation. In other words,
+the system integrator will choose one software and one 2-D hardware implementation to be the "default" used when a client
+does not need to choose a specific implementation.</p>
+<p class="Header2">User Mode Interface</p>
+<p>Clients use the standard names below to access the default implementations. The client then imports the pointers
+to the functions. (The specific name decoration and import method will be dictated by the host Operating System (O/S).)
+Some examples:</p>
+<ul>
+ <li>CPU: <span class="filename">bltsville_cpu</span><ul>
+ <li>Linux/Android: <span class="filename">libbltsville_cpu.so</span></li>
+ <li>Windows: <span class="filename">bltsville_cpu.dll</span></li>
+ <li>etc.</li>
+ </ul>
+ </li>
+ <li>2-D hardware: <span class="filename">bltsville_hw2d</span><ul>
+ <li>Linux/Android: <span class="filename">libbltsville_hw2d.so</span></li>
+ <li>Windows: <span class="filename">bltsville_hw2d.dll</span></li>
+ <li>etc.</li>
+ </ul>
+ </li>
+</ul>
+<p>Usually these entry points will be symbolic links (either explicit in systems like Linux which support them, or implicit
+using a thin wrapper) to the specific implementation. This allows system integrators to connect the client with the
+most capable implementation available in the system. For example, <span class="filename">bltsville_hw2d</span> might
+be a symbolic link to <span class="filename">bltsville_gc2d</span>.</p>
+<p>In addition, there may be more implementations co-existing in a given system. These will have additional unique
+names as determined by the vendors. For example:</p>
+<ul>
+ <li>Reference CPU software implementation: <span class="filename">bltsville_refcpu</span></li>
+ <li>System DMA 2-D hardware implementation: <span class="filename">bltsville_mydma</span></li>
+</ul>
+<p class="Header3">Initialization</p>
+<p>In general, each O/S has the ability to manually load a library. This in turn causes a function in the library
+to be called so the library can perform initialization. Unfortunately, not all O/Ss allow this initialization
+function to return an error if the initialization fails. Equally unfortunately, it may be necessary for the
+initialization to be performed in that function. To accommodate this, BLTsville defers the specific initialization
+to the O/S environment.</p>
+<p class="Header4">Linux/Android</p>
+<p>The client will call <span class="inline_code">dlopen()</span> to open the library. It will then import the
+<span class="inline_code">bv_*()</span> functions, and call them as desired. Initialization will occur in
+association with one or more of these activities. If the initialization fails, the bv_*() functions will return
+the <span class="inline_code">BVERR_RSRC</span> error, indicating that a required resource was not obtained.</p>
+<p class="imponly"><strong>Implementations Only<br />
+</strong><br />
+If the library has designated a function with the <span class="inline_code">__attribute__ ((constructor))</span>, that
+function will be called. Linux implementations may use this function to perform initialization (including opening
+an interface to an associated kernel module). However, since this function cannot return an error, and thus cannot
+fail, if the initialization fails, this must be recorded. Then, when the client calls any of the
+<span class="inline_code">bv_*()</span> functions, these should immediately return the <span class="inline_code">
+BVERR_RSRC</span> error, indicating that the library was unable to initialize (obtain a necessary resource).<br />
+<br />
+Linux implementations may also choose to initialize on the first call to a <span class="inline_code">bv_*()</span>
+function. Failure is likewise indicated by returning the <span class="inline_code">BVERR_RSRC</span> error.<br />
+<br />
+<strong>NOTE: Be careful not to repeatedly attempt initialization when a failure is encountered. Some
+initializations, and especially initialization failures, can take a long time. This means clients trying to call
+</strong><span class="inline_code"><strong>bv_*()</strong></span><strong> functions (presumably before falling back to
+alternatives) will be repeatedly penalized if the library can't initialize. Instead, attempt initialization
+once, and from them on return <span class="inline_code">BVERR_RSRC</span>.</strong></p>
+<p class="Header2">Kernel Mode Interface</p>
+<p>For most kernel space BLTsville clients, only a 2-D hardware implementation will be used. However, both types of
+implementations are supported. Clients use the standard names below to access the default implementations and obtain
+pointers to the functions. (The specific method of obtaining the interface will be dictated by the host Operating
+System (O/S).) Some examples:</p>
+<ul>
+ <li>CPU<ul>
+ <li>Linux/Android <span class="inline_code">bvcpu_entry()</span></li>
+ <li>etc.</li>
+ </ul>
+ </li>
+ <li>2-D hardware<ul>
+ <li>Linux/Android <span class="inline_code">bv2d_entry()</span></li>
+ <li>etc.</li>
+ </ul>
+ </li>
+</ul>
+<p>These entry points may represent the implementations themselves, but more likely they will link the client to the implementations
+using more specific names. For example, <span class="inline_code">bv2d_entry()</span> may link the client to
+<span class="inline_code">gcbv_entry()</span>.</p>
+<p>In addition, there may be more implementations co-existing in the kernel. These will require additional unique
+names as determined by the vendors. For example:</p>
+<ul>
+ <li>Reference CPU software implementation: <span class="inline_code">cpurefbv_entry()</span></li>
+ <li>Vivante GC320 2-D hardware implementation: <span class="inline_code">gcbv_entry()</span></li>
+</ul>
+<hr />
+<p class="Header1">Things To Do In BLTsville</p>
+<p>BLTsville's interface consists of three or four functions per implementation, which must be imported by the
+client at run time:</p>
+<ul>
+ <li><span class="inline_code"><a href="#bv_map">bv_map()</a></span></li>
+ <li><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></li>
+ <li><span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span></li>
+ <li><span class="inline_code"><a href="#bv_cache">bv_cache()</a></span> (optional)</li>
+</ul>
+<p class="note">NOTE: If the library failed to initialize, these functions will return <span class="inline_code">
+BVERR_RSRC</span>, indicating that a required resource was not obtained.</p>
+<a name="bv_map" class="Code_Header">bv_map()</a>
+<p class="code_block">enum bverror bv_map(<a href="#bvbuffdesc">struct bvbuffdesc* buffdesc</a>);</p>
+<p><span class="strong_emphasis">BLTsville does not allocate buffers.</span> Clients must describe a buffer
+in BLTsville using the <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> structure so a given implementation
+can access the buffer.</p>
+<p><span class="inline_code">bv_map()</span> is used to provide the implementation an opportunity to associate hardware
+resources with the specified buffer. Most hardware requires this type of mapping, and there is usually appreciable
+overhead associated with it. By providing a separate call for this operation, BLTsville allows the client to move
+this overhead to the most appropriate time in its execution.</p>
+<p>For a given buffer, the client can call the <span class="inline_code">bv_map()</span> function imported from each implementation
+to establish the mapping immediately. But this is not required.</p>
+<p>As a special bonus, BLTsville clients can call to any implementation's <span class="inline_code">bv_map()</span>.
+This is sufficient to indicate that the client can be trusted to make the corresponding call to
+<span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span> upon destruction of the buffer. Then when a client
+calls an implementation's <span class="inline_code"><a href="#bv_blt">bv_blt()</a></span>, if the mapping needs to be done,
+it's done at that time. But the mapping is maintained, so that the overhead is avoided on subsequent
+<span class="inline_code"><a href="#bv_blt">bv_blt()</a></span> calls. This lets implementations use <em>lazy mapping</em>
+only as necessary. If an implementation is not called, the mapping is not done.</p>
+<p><em>Normally, the lowest overhead </em><span class="inline_code"><em>bv_map()</em></span><em> call will be in the CPU-based
+implementation. So most clients will want to make a single, low overhead </em><span class="inline_code"><em>bv_map()</em></span><em>
+call to the bltsville_cpu implementation to avoid the mapping/unmapping overhead on each </em><span class="inline_code">
+<a href="#bv_blt"><em>bv_blt()</em></a></span><em> call, while avoiding the mapping overhead when possible.</em></p>
+<p><em><strong>Calling </strong></em><span class="inline_code"><em><strong>bv_map()</strong></em></span><em><strong> is
+actually optional prior to calling </strong></em><span class="inline_code"><a href="#bv_blt"><em><strong>bv_blt()</strong></em></a></span><em><strong>.
+However, if it is not called at least once for a given buffer, it must be assumed that </strong></em>
+<span class="inline_code"><a href="#bv_unmap"><strong><em>bv_unmap()</em></strong></a></span><em><strong> will not be called.
+So the mapping must be done when </strong></em><span class="inline_code"><a href="#bv_blt"><em><strong>bv_blt()</strong></em></a></span><em><strong>
+is called, and unmapping done when it is complete. This means the overhead will be incurred for every </strong>
+</em><a href="#bv_blt" class="inline_code"><em><strong>bv_blt()</strong></em></a><em><strong> call which uses that buffer.</strong></em></p>
+<p class="note">NOTE: Obviously any API cannot add capabilities beyond an implementation's capabilities. So, for example,
+if an implementation requires memory to be allocated from a special pool of memory, that responsibility falls upon the client.
+The <span class="inline_code">bv_map()</span> function for that implementation will need to check the characteristics of
+the memory and return an error if it does not meet the necessary criteria.</p>
+<p class="Header4"><a name="bv_map_Function_Sequences">Function Sequences</a></p>
+<p>To clarify, here are some function sequences and the operations associated with them:</p>
+<table class="indent">
+ <tr>
+ <td class="ctr_thin_bord"><strong>Implementation</strong></td>
+ <td class="ctr_thin_bord"><strong>Function</strong></td>
+ <td class="ctr_thin_bord"><strong>Operation</strong></td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">A</td>
+ <td class="thin_bord"><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></td>
+ <td class="thin_bord">map A<br />
+ BLT A<br />
+ unmap A</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">A</td>
+ <td class="thin_bord"><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></td>
+ <td class="thin_bord">map A<br />
+ BLT A<br />
+ unmap A</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">B</td>
+ <td class="thin_bord"><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></td>
+ <td class="thin_bord">map B<br />
+ BLT B<br />
+ unmap B</td>
+ </tr>
+</table>
+<br />
+<table class="indent">
+ <tr>
+ <td class="ctr_thin_bord"><strong>Implementation</strong></td>
+ <td class="ctr_thin_bord"><strong>Function</strong></td>
+ <td class="ctr_thin_bord"><strong>Operation</strong></td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">A</td>
+ <td class="thin_bord"><span class="inline_code"><a href="#bv_map">bv_map()</a></span></td>
+ <td class="thin_bord">map A</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">A</td>
+ <td class="thin_bord"><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></td>
+ <td class="thin_bord">BLT A</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">A</td>
+ <td class="thin_bord"><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></td>
+ <td class="thin_bord">BLT A</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">A</td>
+ <td class="thin_bord"><span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span></td>
+ <td class="thin_bord">unmap A</td>
+ </tr>
+</table>
+<br />
+<table class="indent">
+ <tr>
+ <td class="ctr_thin_bord"><strong>Implementation</strong></td>
+ <td class="ctr_thin_bord"><strong>Function</strong></td>
+ <td class="ctr_thin_bord"><strong>Operation</strong></td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">A</td>
+ <td class="thin_bord"><span class="inline_code"><a href="#bv_map">bv_map()</a></span></td>
+ <td class="thin_bord">map A</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">B</td>
+ <td class="thin_bord"><span class="inline_code"><a href="#bv_map">bv_map()</a></span></td>
+ <td class="thin_bord">map B</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">A</td>
+ <td class="thin_bord"><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></td>
+ <td class="thin_bord">BLT A</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">B</td>
+ <td class="thin_bord"><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></td>
+ <td class="thin_bord">BLT B</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">A</td>
+ <td class="thin_bord"><span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span></td>
+ <td class="thin_bord">unmap A</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">B</td>
+ <td class="thin_bord"><span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span></td>
+ <td class="thin_bord">unmap B</td>
+ </tr>
+</table>
+<br />
+<table class="indent">
+ <tr>
+ <td class="ctr_thin_bord"><strong>Implementation</strong></td>
+ <td class="ctr_thin_bord"><strong>Function</strong></td>
+ <td class="ctr_thin_bord"><strong>Operation</strong></td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">A</td>
+ <td class="thin_bord"><span class="inline_code"><a href="#bv_map">bv_map()</a></span></td>
+ <td class="thin_bord">map A</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">B</td>
+ <td class="thin_bord"><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></td>
+ <td class="thin_bord">map B<br />
+ BLT B</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">B</td>
+ <td class="thin_bord"><span class="inline_code"><a href="#bv_blt">bv_blt()</a></span></td>
+ <td class="thin_bord">BLT B</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">A</td>
+ <td class="thin_bord"><span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span></td>
+ <td class="thin_bord">unmap A<br />
+ unmap B</td>
+ </tr>
+</table>
+<br />
+<div class="note">
+ NOTE: Calling <span class="inline_code">bv_map()</span> and <span class="inline_code"><a href="#bv_unmap">
+ bv_unmap()</a></span> with the same <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> from
+ different, unsynchronized threads, even (especially) from different implementations, will result in undefined
+ behavior. This is similar to calling <span class="inline_code">malloc()</span> and <span class="inline_code">
+ free()</span> using the same buffer pointer in different, unsynchronized threads. While this may work
+ sometimes and for some implementations and combinations of implementations, BLTsville does not provide any
+ synchronization mechanism to make this safe. Clients must ensure that these calls are synchronized in cases
+ where such behavior appears to be necessary.</div>
+<br />
+<a name="bv_blt" class="Code_Header">bv_blt()</a>
+<p class="code_block">enum bverror bv_blt(<a href="#bvbltparams">struct bvbltparams* bltparams</a>);</p>
+<p>The main function of BLTsville is <span class="inline_code">bv_blt()</span>. A <span class="inline_code">
+<a href="#bvbltparams">bvbltparams</a></span> structure is passed into <span class="inline_code">bv_blt()</span> to trigger
+the desired 2-D operation.</p>
+<a name="bv_unmap" class="Code_Header">bv_unmap()</a>
+<p class="code_block">enum bverror bv_unmap(<a href="#bvbuffdesc">struct bvbuffdesc* buffdesc</a>);</p>
+<p><span class="inline_code">bv_unmap()</span> is used to free implementation resources associated with a buffer.
+Normally, if <span class="inline_code"><a href="#bv_map">bv_map()</a></span> was called for a given buffer,
+<span class="inline_code">bv_unmap()</span> should be called as well.</p>
+<p>For convenience, only one <span class="inline_code">bv_unmap()</span> needs to be called for each buffer, regardless
+of how many implementations were used, including multiple calls to <span class="inline_code"><a href="#bv_map">bv_map()</a></span>.</p>
+<p>Also for convenience, <span class="inline_code">bv_unmap()</span> may be called multiple times on the same buffer.
+Note that only the first call will actually free (all) the associated resources. See the
+<a href="#bv_map_Function_Sequences">Function Sequences</a> under <span class="inline_code"><a href="#bv_map">bv_map()</a></span>
+for more details.</p>
+<p class="imponly"><strong>Implementations Only</strong><br />
+<br />
+Implementations must ensure that unmapping of buffers which are in use by asynchronous BLTs are appropriately delayed to
+avoid improper access.</p>
+<a name="bv_cache" class="Code_Header">bv_cache()</a>
+<p class="code_block">enum bverror bv_cache(<a href="#bvcopprams">struct bvcopparams *copparams</a>);</p>
+<p><span class="inline_code">bv_cache()</span> provides manual CPU cache control to maintain cache coherence of surfaces
+between the CPU and other hardware. The <a href="#bvbuffdesc">bvcopparams</a> structure provides the information needed
+to properly manipulate the CPU cache.</p>
+<p>This function is <em>optional</em>. If this function fails to import, it means the implementation does not provide
+it, but <span class="inline_code"><a href="#bv_map">bv_map()</a></span>, <span class="inline_code">
+<a href="#bv_blt">bv_blt()</a></span>, and <span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span> may still
+be used.</p>
+<p><em>In general, this function will be provided with BLTsville implementations which utilize 2-D hardware, even though
+it manipulates the CPU cache. This is because most systems require a kernel module to manipulate the cache, and this
+is not always practical to include with a user-mode CPU implementation.</em></p>
+<p><strong>BEWARE: Manipulation of the CPU cache is tricky. Moreover, different CPUs behave differently, so
+cache manipulation that works on one device may fail on another. Also, mismanaged operation of the cache can have
+significant impact on overall system performance. And incorrect manipulation of the cache can cause instability or
+crashes. Please read and understand all of the discussions below before using this function.</strong></p>
+<ol>
+ <li>To avoid system instability, do not perform cache operations on buffers which would not be accessed by BLTsville.</li>
+ <li>For maximum performance, combine adjacent rectangles into one <span class="inline_code">bv_cache()</span> call.
+ For example, when BLTing a line of characters, do not issue a <span class="inline_code">bv_cache()</span> call for each
+ character. Instead, make one call to bv_cache() which includes all the characters.</li>
+ <li>When using a hardware BLTsville implementation to read data written into a cached surface by the CPU, use the
+ <span class="inline_code"><a href="#CPU_TO_DEVICE">BVCACHE_CPU_TO_DEVICE</a></span> operation after the CPU has completed
+ its operation and before the hardware BLTsville operation is initiated.</li>
+ <li>When using a hardware BLTsville implementation to write data into a cached surface that will be read by the CPU,
+ use the <span class="inline_code"><a href="#CPU_FROM_DEVICE">BVCACHE_CPU_FROM_DEVICE</a></span> operation after the
+ hardware BLTsville operation has completed (note this means after the callback if the BLT is asynchronous) and before
+ the CPU accesses the surface.</li>
+ <li>When using a hardware BLTsville implementation to write data into a cached surface that has been written by the
+ CPU, using the <span class="inline_code"><a href="#CPU_TO_DEVICE">BVCACHE_CPU_TO_DEVICE</a></span> operation after the
+ CPU has completed its operation and before the hardware BLTsville operation is initiated.<ul>
+ <li class="bold_sans">NOTE: This cache operation may not be necessary on all hardware, but it is good practice to perform it
+ anyway. This operation will be necessary for a CPU with a write allocation policy on the cache, but may not
+ be necessary for CPUs without such a configuration.</li>
+ <li class="bold_sans"><strong>NOTE WELL: CPU access to a destination buffer is not always initiated by the client. Buffers
+ recently allocated may be cleared by the CPU on behalf of the client via the allocation call. Failure to perform
+ this operation may result in image corruption even if no further CPU accesses are performed on the surface!</strong></li>
+ </ul>
+ </li>
+</ol>
+<table class="example">
+ <tr>
+ <td>
+ <p><strong>Example</strong>: On one particular device, a surface was allocated using the standard user mode
+ <span class="inline_code">malloc()</span>. An image was copied into a portion of this surface using a hardware
+ implementation of BLTsville. The result was then read by the CPU.</p>
+ <p>Logically, <span class="inline_code">bv_cache()</span> was used to perform a <span class="inline_code">
+ <a href="#CPU_FROM_DEVICE">BVCACHE_CPU_FROM_DEVICE</a></span> operation after the hardware-based BLTsville operation
+ completed, but before the CPU read was performed. However, corruption appeared both inside the image copied,
+ as well as outside the image!</p>
+ <p>Both corruptions were caused by not realizing that there was a CPU operation (clear) performed on behalf of the
+ <span class="inline_code">malloc()</span>, for which the proper cache manipulation was not performed.</p>
+ <p>The corruption outside the image was due to data in the cache being invalidated before it reached the memory.
+ As mentioned above, buffers allocated are normally cleared by the system. In this case, since the buffer used
+ for the surface was configured with a write allocated cache, this meant that not all writes to clear the buffer
+ were in memory when the <span class="inline_code"><a href="#CPU_FROM_DEVICE">BVCACHE_CPU_FROM_DEVICE</a></span>
+ operation was performed. As a result, the uncommitted data in the cache was invalidated and lost, and the
+ previous contents of the memory remained for the CPU to read.</p>
+ <p>The corruption inside the image was caused by data in the cache being committed to memory after the hardware
+ BLT completed, but before the <span class="inline_code"><a href="#CPU_FROM_DEVICE">BVCACHE_CPU_FROM_DEVICE</a></span>
+ operation was executed.</p>
+ <p>Both corruptions were corrected by performing a <span class="inline_code"><a href="#CPU_TO_DEVICE">BVCACHE_CPU_TO_DEVICE</a></span>
+ operation on the <span class="underline">destination</span> surface <strong>before</strong> performing the BLT (item
+ 5 above), in addition to the <span class="inline_code"><a href="#CPU_FROM_DEVICE">BVCACHE_CPU_FROM_DEVICE</a></span>
+ operation performed <strong>after</strong> the BLT (item 3 above).</p>
+ </td>
+ </tr>
+</table>
+<br />
+<hr /><a name="bvbltparams" class="Code_Header">bvbltparams</a>
+<p><span class="inline_code">bvbltparams</span> is the central structure in BLTsville. This structure holds the details
+of the BLT being requested by the client.</p>
+<p class="small_code_block">union bvop {<br />
+ unsigned short <a href="#rop">rop</a>;<br />
+ enum bvblend <a href="#blend">blend</a>;<br />
+ struct bvfilter *<a href="#filter">filter</a>;<br />
+};<br />
+<br />
+struct bvinbuff {<br />
+ <a href="#bvbuffdesc">struct bvbuffdesc</a> *<a href="#src1.desc">desc</a>;<br />
+ <a href="#bvtileparams">struct bvtileparams</a> *<a href="#src1.tileparams">tileparams</a>;<br />
+};<br />
+<br />
+struct bvbltparams {<br />
+ unsigned int <a href="#bvbltparams.structsize">structsize</a>;<br />
+<br />
+ char *<a href="#errdesc">errdesc</a>;<br />
+<br />
+ unsigned long <a href="#implementation">implementation</a>;<br />
+ unsigned long <a href="#flags">flags</a>;<br />
+ union bvop <a href="#op">op</a>;<br />
+<br />
+ void *<a href="#colorkey">colorkey</a>;<br />
+ union bvalpha <a href="#globalalpha">globalalpha</a>;<br />
+<br />
+ enum bvscalemode <a href="#scalemode">scalemode</a>;<br />
+ enum bvdithermode <a href="#dithermode">dithermode</a>;<br />
+<br />
+ <a href="#bvbuffdesc">struct bvbuffdesc</a> *<a href="#dstdesc">dstdesc</a>;<br />
+ <a href="#bvsurfgeom">struct bvsurfgeom</a> *<a href="#dstgeom">dstgeom</a>;<br />
+ <a href="#bvrect">struct bvrect</a> <a href="#dstrect">dstrect</a>;<br />
+<br />
+ union bvinbuff <a href="#src1">src1</a>;<br />
+ <a href="#bvsurfgeom">struct bvsurfgeom</a> *<a href="#src1geom">src1geom</a>;<br />
+ <a href="#bvrect">struct bvrect</a> <a href="#src1rect">src1rect</a>;<br />
+<br />
+ union bvinbuff <a href="#src2">src2</a>;<br />
+ <a href="#bvsurfgeom">struct bvsurfgeom</a> *<a href="#src2geom">src2geom</a>;<br />
+ <a href="#bvrect">struct bvrect</a> <a href="#src2rect">src2rect</a>;<br />
+<br />
+ union bvinbuff <a href="#mask">mask</a>;<br />
+ <a href="#bvsurfgeom">struct bvsurfgeom</a> *<a href="#maskgeom">maskgeom</a>;<br />
+ <a href="#bvrect">struct bvrect</a> <a href="#maskrect">maskrect</a>;<br />
+<br />
+ <a href="#bvrect">struct bvrect</a> <a href="#cliprect">cliprect</a>;<br />
+<br />
+ unsigned long <a href="#batchflags">batchflags</a>;<br />
+ struct bvbatch *<a href="#batch">batch</a>;<br />
+<br />
+ void (*<a href="#callbackfn">callbackfn</a>)(<a href="#bvcallbackerror">struct
+bvcallbackerror</a> *err,<br />
+
+unsigned long callbackdata);<br />
+ unsigned long <a href="#callbackdata">callbackdata</a>;<br />
+<br />
+ <a href="#bvrect">struct bvrect</a> <a href="#src2auxdstrect">src2auxdstrect</a>;<br />
+ <a href="#bvrect">struct bvrect</a> <a href="#maskauxdstrect">maskauxdstrect</a>;<br />
+};</p>
+<a name="bvbltparams.structsize" class="Code_Header_2">bvbltparams.structsize</a>
+<p><span class="code_block">unsigned long structsize; /* input */</span></p>
+<p>This member is used to allow backwards and forwards compatibility between versions of BLTsville. It should be set
+to the <span class="inline_code">sizeof()</span> the structure by the client or implementation, whichever allocated the
+structure.</p>
+<p>BLTsville is designed to be forwards and backwards compatible between client and library versions. But this compatibility
+would be eliminated if clients chose to check for a specific version of the BLTsville implementations and fail if the specific
+version requested was not in place. So, instead of exporting a version number, BLTsville structures use the
+<span class="inline_code">structsize</span> member to indicate the number of bytes in the structure. This is used
+to communicate between the client and implementation which portions of the structure exist. This effectively bypasses
+the concept of a version and focuses on the specifics of what changes need to be considered to maintain compatibility.</p>
+<ol>
+ <li>When an old client calls into a new implementation, that implementation will realize if the client only provides
+ a subset of an updated structure. The implementation will handle this and utilize only that information which
+ has been provided. New features will be disabled, but functionality will be maintained.</li>
+ <li>When a new client calls into an old implementation, that implementation will ignore the extra members of the structure
+ and operate in ignorance of them. If these members are necessary for some new functionality, this will be evident
+ from other fields in the structure, so that the implementation can gracefully fail.</li>
+</ol>
+<p>If <span class="inline_code">structsize</span> is set to a value that is too small for an implementation, it may return
+a <span class="inline_code"><a href="#BVERR_BLTPARAMS_VERS">BVERR_BLTPARAMS_VERS</a></span> error.</p>
+<p class="Code_Header_2"><a name="bvbltparams.errdesc">bvbltparams.errdesc</a></p>
+<p><span class="code_block">char* errdesc; /* output */</span></p>
+<p><span class="inline_code">errdesc</span> is optionally used by implementations to pass a 0-terminated string with additional
+debugging information back to clients for debugging purposes. <span class="inline_code">errdesc</span> is not localized
+or otherwise meant to provide information that is displayed to users.</p>
+<p class="Code_Header_2"><a name="implementation">bvbltparams.implementation</a></p>
+<p class="code_block">unsigned long implementation; /* input */</p>
+<p>Multiple implementations of BLTsville can be combined under managers which can distribute the BLT requests to the implementations
+based on whatever criteria the manager chooses. This might include availability of the operation, performance, loading,
+or power state. In such a scenario, the client may need to override or augment the choice made by the manager.
+This field allows that control.</p>
+<p><strong><em>Note that this feature is extremely complicated, and more detailed documentation needs to be created to allow
+creation of managers and smooth integration by a client. There are serious issues that must be understood before any
+manager can be put into place, such as CPU cache coherence and multiple implementation operation interdependence.
+For now, this field should be set to 0 by clients.</em></strong></p>
+<p>If the implementation cannot respond to the <span class="inline_code">implementation</span> flags set, it may return
+a <span class="inline_code"><a href="#BVERR_IMPLEMENTATION">BVERR_IMPLEMENTATION</a></span> error.</p>
+<p class="Code_Header_2"><a name="flags">bvbltparams.flags</a></p>
+<p class="code_block">unsigned long flags; /* input */</p>
+<p>The <span class="inline_code">flags</span> member provides the baseline of information to <span class="inline_code">
+<a href="#bv_blt">bv_blt()</a></span> about the type of BLT being requested.</p>
+<p>To maintain compatibility, unused bits in the flags member should be set to 0.</p>
+<p>If the flags set are not supported by the implementation, it may return <span class="inline_code">
+<a href="#BVERR_FLAGS">BVERR_FLAGS</a></span>, or a more specific <a href="#bverror">error code</a>.</p>
+<p class="Code_Header_3"><a name="BVFLAG_OP_">bvbltparams.flags - BVFLAG_OP_*</a></p>
+<p>The <span class="inline_code">op</span> field of the flags member specifies the type of BLT operation to perform.
+Currently there are three types of BLT operations defined:</p>
+<table class="indent">
+ <tr>
+ <td valign="top">1.</td>
+ <td><span class="inline_code"><strong><a name="BVFLAG_ROP">BVFLAG_ROP</a></strong></span><br />
+ <p>This flag indicates the operation being performed is a raster operation, and the <span class="inline_code">
+ <a href="#op">bvbltparams.op</a></span> union is treated as <span class="inline_code"><a href="#rop">rop</a></span>.
+ Raster OPerations are binary operations performed on the bits of the inputs. See <span class="inline_code">
+ <a href="#rop">bvbltparams.op.rop</a></span> for details.<br />
+ <br />
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td valign="top">2.</td>
+ <td>
+ <p><span class="inline_code"><strong><a name="BVFLAG_BLEND">BVFLAG_BLEND</a></strong></span><br />
+ </p>
+ <p>This flag indicates the operation being performed is a blend, and the <span class="inline_code">
+ <a href="#op">bvbltparams.op</a></span> union is treated as <span class="inline_code"><a href="#blend">blend</a></span>.
+ Blending involves mixing multiple layers of pixels using the specified equations. Surrounding pixels are not
+ involved in blend operations. See <span class="inline_code"><a href="#blend">bvbltparams.op.blend</a></span>
+ for details.<br />
+ <br />
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td valign="top">3.</td>
+ <td><span class="inline_code"><strong><a name="BVFLAG_FILTER">BVFLAG_FILTER</a></strong></span><br />
+ <br />
+ This flag indicates the operation being performed is a filter, and the <span class="inline_code"><a href="#op">bvbltparams.op</a></span>
+ union is treated as <span class="inline_code"><a href="#filter">filter</a></span>. Filtering involves mixing
+ multiple layers of pixels. Surrounding pixels are involved in filter operations. See
+ <span class="inline_code"><a href="#filter">bvbltparams.op.filter</a></span> for details.<br />
+ </td>
+ </tr>
+</table>
+<p class="Code_Header_3"><a name="BVFLAG_KEY_SRC">bvbltparams.flags - BVFLAG_KEY_SRC</a>/<a name="BVFLAG_KEY_DST">DST</a></p>
+<p>The <span class="inline_code">BVFLAG_KEY_SRC</span> and <span class="inline_code">BVFLAG_KEY_DST</span> enable source
+and destination color keying, respectively. When either flag is set, the <span class="inline_code">
+<a href="#colorkey">colorkey</a></span> member of <span class="inline_code"><a href="#bvbltparams">bvbltparams</a></span>
+is used.</p>
+<p><span class="inline_code">BVFLAG_KEY_SRC</span> and <span class="inline_code">BVFLAG_KEY_DST</span> are mutually exclusive.</p>
+<p>See <span class="inline_code"><a href="#colorkey">bvbltparams.colorkey</a></span> for details.</p>
+<p class="Code_Header_3"><a name="BVFLAG_CLIP">bvbltparams.flags - BVFLAG_CLIP</a></p>
+<p>When <span class="inline_code">BVFLAG_CLIP</span> is set, the <span class="inline_code"><a href="#cliprect">cliprect</a></span>
+member of <span class="inline_code"><a href="#bvbltparams">bvbltparams</a></span> is used by the implementation as a limiting
+rectangle on data written to the destination. See <span class="inline_code"><a href="#cliprect">cliprect</a></span>
+for details.</p>
+<p class="Code_Header_3"><a name="BVFLAG_SRCMASK">bvbltparams.flags - BVFLAG_SRCMASK</a></p>
+<p>Normally, the mask is applied at the destination, after all scaling has been completed (including scaling the mask if
+necessary). But some environments require that the mask be applied at the sources, before scaling occurs. The
+<span class="inline_code">BVFLAG_SRCMASK</span> flag requests that the implementation use this method if supported.</p>
+<p class="Code_Header_3">bvbltparams.flags - BVFLAG_TILE_*</p>
+<p>Normally, when a source's size does not match the destination, the source is scaled to fill the destination. But
+when the corresponding <span class="inline_code">BVFLAG_TILE_*</span> flag is set, this behavior is modified.</p>
+<p>First, the source's size specifies a tile (or pattern, or brush) to be used to fill the destination. This tile
+is replicated instead of scaled.</p>
+<p>The origin of the source's rectangle is used to locate the tile within a larger surface. </p>
+<p>Second, a <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> object is no longer supplied by the client
+in the bvbltparams structure. In its place is a <span class="inline_code"><a href="#bvtileparams">bvtileparams</a></span>
+object.</p>
+<p>Refer to the <span class="inline_code"><a href="#bvtileparams">bvtileparams</a></span> structure definition for details.</p>
+<p class="Code_Header_3">bvbltparams.flags - <a name="BVFLAG_HORZ_FLIP">BVFLAG_HORZ</a>/<a name="BVFLAG_VERT_FLIP">VERT_FLIP_*</a></p>
+<p>These flags indicate that the corresponding image is flipped horizontally or vertically as it is used by the operation.</p>
+<p class="Code_Header_3">bvbltparams.flags - BVFLAG_SCALE/DITHER_RETURN</p>
+<p>The scale and dither types can be specified with an implicit type. The implementation will then convert that internally
+to an explicit scale or dither type. These flags request that the implementation return the explicit type chosen to
+the client in the corresponding <span class="inline_code"><a href="#scalemode">bvbltparams.scalemode</a></span> and
+<span class="inline_code"><a href="#dithermode">bvbltparams.dithermode</a></span> members.</p>
+<p class="Code_Header_3">bvbltparams.flags - BVFLAG_ASYNC</p>
+<p>This flag allows the client to inform the implementation that it can queue the requested BLT and return from
+<span class="inline_code"><a href="#bv_blt">bv_blt()</a></span> before it has completed. If this bit is not set, when
+the <span class="inline_code"><a href="#bv_blt">bv_blt()</a></span> returns, the operation is complete.</p>
+<p>Normally, a client will also utilize the <span class="inline_code"><a href="#callbackfn">bvbltparams.callbackfn</a></span>
+and <span class="inline_code"><a href="#callbackdata">bvbltparams.callbackdata</a></span> members to receive a notification
+when the BLT has completed.</p>
+<p class="note">NOTE: Asynchronous BLTs are performed in the order in which they are submitted within an implementation.
+This was done to provide a simple dependency mechanism.
+However, synchronization between implementations must be handled by the client, using the callback mechanism.</p>
+<p class="note">NOTE: Since asynchronous BLTs are performed in the order in which they are submitted, it follows
+that a synchronized BLT after a set of asynchronous BLTs may be used as synchronization as well.</p>
+<p class="note"><a name="NOP">NOTE</a>: Certain situations may require manual synchronization without an associated BLT.
+Rather than introduce an additional BLTsville function call, the method of handling this will be via a NOP BLT. To
+accomplish a NOP BLT, the client should issue a BLT using the <span class="inline_code"><a href="#rop">
+bvbltparams.op.rop</a></span> code of <span class="inline_code">0xAAAA</span> (copy destination to destination), and
+with the <span class="inline_code">BVFLAG_ASYNC</span> flag <span class="underline">not</span> set. Alternatively, the NOP BLT may set the
+<span class="inline_code">BVFLAG_ASYNC</span> and provide a <span class="inline_code"><a href="#callbackfn">
+bvbltparams.callbackfn</a></span>. <em>To facilitate implementations, a valid destination surface should be
+specified.</em></p>
+<p class="imponly"><strong>Implementations Only<br />
+<br />
+</strong>In general, this BLTsville specification has avoided placing any requirement on implementations for specific
+operations. However, in support of this special case, support for these NOP BLTs will need to be an implementation
+<span class="underline"><strong>requirement</strong></span>. </p>
+<p class="Code_Header_3">bvbltparams.flags - BVFLAG_BATCH_BEGIN/CONTINUE/END</p>
+<p>These flags are used to control batching of BLTs for two main reasons:</p>
+<ol>
+ <li>To group small, similar BLTs to consolidate overhead. For example, the BLTs associated with rendering each
+ character in a word.</li>
+ <li>To group related BLTs, which may allow an implementation to perform a more efficient, but equivalent set of operations.</li>
+</ol>
+<p>See <a href="#batching">Batching</a> for details.</p>
+<p class="Code_Header_3">bvbltparams.flags - <a name="BVFLAG_SRC2_AUXDSTRECT">BVFLAG_SRC2</a>/<a name="BVFLAG_MASK_AUXDSTRECT">MASK_AUXDSTRECT</a></p>
+<p>These flags are used to indicate that the bvbltparams.src2auxdstrect and bvbltparams.maskauxdstrect are to be used.
+See these entries below for details. These flags are likely to be ignored except for the special case explained below,
+so they should be used only when necessary.</p>
+<p class="Code_Header_2"><a name="rop">bvbltparams.op.rop</a></p>
+<p class="code_block">unsigned short op; /* input */ </p>
+<p>When <span class="inline_code"><a href="#BVFLAG_ROP">BVFLAG_ROP</a></span> is set in the <span class="inline_code">
+<a href="#flags">bvbltparams.flags</a></span> member, the <span class="inline_code"><a href="#op">bvbltparams.op</a></span>
+union is treated as <span class="inline_code">rop</span>. Raster OPerations are binary operations performed on the
+bits of the inputs:</p>
+<ul>
+ <li>ROP1s have one source: the destination. Two bits are sufficient to specify the four possible (2<sup>2</sup>)
+ ROP1 operations.</li>
+ <li>ROP2s have two sources: the destination and a source. Four bits are used to specify the sixteen (2<sup>2+2</sup>)
+ ROP2 operations.</li>
+ <li>ROP3s have three sources: the destination, a source (source 1), and a pattern (a.k.a. brush), which we call
+ source 2 in BLTsville. Eight bits are used to specify the 256 (2<sup>2+2+2</sup>) ROP3 operations.</li>
+ <li>ROP4s have four sources: the destination, two sources, and a mask. Sixteen bits are used to specify
+ the 65,536 (2<sup>2+2+2+2</sup>) ROP4 operations.</li>
+</ul>
+<p>BLTsville's <span class="inline_code">rop</span> element is used to specify a ROP4, but anything from ROP1 up to ROP4
+can be defined using this member:</p>
+<ul>
+ <li>To specify an 8-bit ROP3 as a 16-bit ROP4, replicate the 8 bits twice: 0x2323.</li>
+ <li>To specify a 4-bit ROP2 as a 16-bit ROP4, replicate the 4 bits four times: 0x2222.</li>
+ <li>To specify a 2-bit ROP1 as a 16-bit ROP4, replicate the 2 bits eight times: 0x5555.</li>
+</ul>
+<p class="note">NOTE:
+By far the most common ROP used will be 0xCCCC, which indicates a simple copy from source 1 to the destination.</p>
+<p>The table below is the magic decoder ring: </p>
+<table class="indent">
+ <tr>
+ <td>Mask</td>
+ <td class="ctr"> 1 </td>
+ <td class="ctr"> 1 </td>
+ <td class="ctr"> 1 </td>
+ <td class="ctr"> 1 </td>
+ <td class="ctr"> 1 </td>
+ <td class="ctr"> 1 </td>
+ <td class="ctr"> 1 </td>
+ <td class="ctr"> 1 </td>
+ <td class="ctr"> 0 </td>
+ <td class="ctr"> 0 </td>
+ <td class="ctr"> 0 </td>
+ <td class="ctr"> 0 </td>
+ <td class="ctr"> 0 </td>
+ <td class="ctr"> 0 </td>
+ <td class="ctr"> 0 </td>
+ <td class="ctr"> 0 </td>
+ </tr>
+ <tr>
+ <td class="red_left">Source 2 </td>
+ <td class="red_center"> 1 </td>
+ <td class="red_center"> 1 </td>
+ <td class="red_center"> 1 </td>
+ <td class="red_center"> 1 </td>
+ <td class="red_center"> 0 </td>
+ <td class="red_center"> 0 </td>
+ <td class="red_center"> 0 </td>
+ <td class="red_center"> 0 </td>
+ <td class="red_center"> 1 </td>
+ <td class="red_center"> 1 </td>
+ <td class="red_center"> 1 </td>
+ <td class="red_center"> 1 </td>
+ <td class="red_center"> 0 </td>
+ <td class="red_center"> 0 </td>
+ <td class="red_center"> 0 </td>
+ <td class="red_center"> 0 </td>
+ </tr>
+ <tr>
+ <td class="grn_left">Source 1 </td>
+ <td class="grn_center"> 1 </td>
+ <td class="grn_center"> 1 </td>
+ <td class="grn_center"> 0 </td>
+ <td class="grn_center"> 0 </td>
+ <td class="grn_center"> 1 </td>
+ <td class="grn_center"> 1 </td>
+ <td class="grn_center"> 0 </td>
+ <td class="grn_center"> 0 </td>
+ <td class="grn_center"> 1 </td>
+ <td class="grn_center"> 1 </td>
+ <td class="grn_center"> 0 </td>
+ <td class="grn_center"> 0 </td>
+ <td class="grn_center"> 1 </td>
+ <td class="grn_center"> 1 </td>
+ <td class="grn_center"> 0 </td>
+ <td class="grn_center"> 0 </td>
+ </tr>
+ <tr>
+ <td class="blue_left_botbord">Destination </td>
+ <td class="blue_center_botbord"> 1 </td>
+ <td class="blue_center_botbord"> 0 </td>
+ <td class="blue_center_botbord"> 1 </td>
+ <td class="blue_center_botbord"> 0 </td>
+ <td class="blue_center_botbord"> 1 </td>
+ <td class="blue_center_botbord"> 0 </td>
+ <td class="blue_center_botbord"> 1 </td>
+ <td class="blue_center_botbord"> 0 </td>
+ <td class="blue_center_botbord"> 1 </td>
+ <td class="blue_center_botbord"> 0 </td>
+ <td class="blue_center_botbord"> 1 </td>
+ <td class="blue_center_botbord"> 0 </td>
+ <td class="blue_center_botbord"> 1 </td>
+ <td class="blue_center_botbord"> 0 </td>
+ <td class="blue_center_botbord"> 1 </td>
+ <td class="blue_center_botbord"> 0 </td>
+ </tr>
+ <tr>
+ <td class="left_topbord">Raster Operation </td>
+ <td class="center_topbord"> 15 </td>
+ <td class="center_topbord"> 14 </td>
+ <td class="center_topbord"> 13 </td>
+ <td class="center_topbord"> 12 </td>
+ <td class="center_topbord"> 11 </td>
+ <td class="center_topbord"> 10 </td>
+ <td class="center_topbord"> 9 </td>
+ <td class="center_topbord"> 8 </td>
+ <td class="center_topbord"> 7 </td>
+ <td class="center_topbord"> 6 </td>
+ <td class="center_topbord"> 5 </td>
+ <td class="center_topbord"> 4 </td>
+ <td class="center_topbord"> 3 </td>
+ <td class="center_topbord"> 2 </td>
+ <td class="center_topbord"> 1 </td>
+ <td class="center_topbord"> 0 </td>
+ </tr>
+</table>
+<br />
+For example, to specify an operation that uses the mask to choose between source 1 and destination (source 1 when mask is
+1, destination when mask is 0), a client would calculate the bottom line by parsing each column:<br />
+<br />
+When mask is 1 (the first eight columns), the <span class="inline_code">rop</span> matches the source 1 row. When
+mask is 0 (the last eight columns), the <span class="inline_code">rop</span> matches the destination row.<br />
+<br />
+<table class="indent">
+ <tr>
+ <td class="left_topbord">Raster Operation </td>
+ <td class="red_center_topbord"> 1 </td>
+ <td class="red_center_topbord"> 1 </td>
+ <td class="red_center_topbord"> 1 </td>
+ <td class="red_center_topbord"> 1 </td>
+ <td class="red_center_topbord"> 0 </td>
+ <td class="red_center_topbord"> 0 </td>
+ <td class="red_center_topbord"> 0 </td>
+ <td class="red_center_topbord"> 0 </td>
+ <td class="blu_center_topbord"> 1 </td>
+ <td class="blu_center_topbord"> 0 </td>
+ <td class="blu_center_topbord"> 1 </td>
+ <td class="blu_center_topbord"> 0 </td>
+ <td class="blu_center_topbord"> 1 </td>
+ <td class="blu_center_topbord"> 0 </td>
+ <td class="blu_center_topbord"> 1 </td>
+ <td class="blu_center_topbord"> 0 </td>
+ </tr>
+</table>
+<br />
+So the <span class="inline_code">rop</span> for this operation would be 0xF0AA.<br />
+<br />
+Here is a list of some commonly used raster operations that have been given names:<br />
+<br />
+<table class="indent_thick_bord">
+ <tr>
+ <td class="thin_bord_dbl_botbord"><strong>ROP </strong></td>
+ <td class="thin_bord_dbl_botbord"><strong>Constant</strong></td>
+ <td class="thin_bord_dbl_botbord"><strong>Description</strong></td>
+ </tr>
+ <tr>
+ <td class="thin_bord">BLACKNESS</td>
+ <td class="thin_bord">0x0000</td>
+ <td class="thin_bord">Set all destination bits to black (0). Dest = 0</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">NOTSRCERASE</td>
+ <td class="thin_bord">0x1111</td>
+ <td class="thin_bord">Dest = ~Src1 & ~Dest = ~(Src1 | Dest)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">NOTSRCCOPY</td>
+ <td class="thin_bord">0x3333</td>
+ <td class="thin_bord">Dest = ~Src1</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">SRCERASE</td>
+ <td class="thin_bord">0x4444</td>
+ <td class="thin_bord">Dest = Src1 & ~Dest</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">DSTINVERT</td>
+ <td class="thin_bord">0x5555</td>
+ <td class="thin_bord">Invert (NOT) the destination bits. Dest = ~Dest</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">PATINVERT</td>
+ <td class="thin_bord">0x5A5A</td>
+ <td class="thin_bord">XOR with Src2. Dest = Src2 ^ Dest</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">SRCINVERT</td>
+ <td class="thin_bord">0x6666</td>
+ <td class="thin_bord">XOR with Src1. Dest = Src1 ^ Dest</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">SRCAND</td>
+ <td class="thin_bord">0x8888</td>
+ <td class="thin_bord">Dest = Src1 & Dest</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">NOP</td>
+ <td class="thin_bord">0xAAAA</td>
+ <td class="thin_bord">Dest = Dest</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">MERGEPAINT</td>
+ <td class="thin_bord">0xBBBB</td>
+ <td class="thin_bord">Dest = ~Src1 | Dest</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">MERGECOPY</td>
+ <td class="thin_bord">0xC0C0</td>
+ <td class="thin_bord">Dest = Src1 & Src2</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">SRCCOPY</td>
+ <td class="thin_bord">0xCCCC</td>
+ <td class="thin_bord">Dest = Src1</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">SRCPAINT</td>
+ <td class="thin_bord">0xEEEE</td>
+ <td class="thin_bord">OR with Src1. Dest = Src1 | Dest</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">PATCOPY</td>
+ <td class="thin_bord">0xF0F0</td>
+ <td class="thin_bord">Copy source 2 to destination. Dest = Src2</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">PATPAINT</td>
+ <td class="thin_bord">0xFBFB</td>
+ <td class="thin_bord">Dest = ~Src1 | Src2 | Dest</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">WHITENESS</td>
+ <td class="thin_bord">0xFFFF</td>
+ <td class="thin_bord">Set all destination bits to white (1). Dest = 1</td>
+ </tr>
+</table>
+<br />
+<span class="Code_Header_2"><a name="blend">bvbltparams.op.blend</a></span>
+<p class="code_block">enum bvblend blend; /* input */</p>
+<p>When <span class="inline_code"><a href="#BVFLAG_BLEND">BVFLAG_BLEND</a></span> is set in the
+<span class="inline_code"><a href="#flags">bvbltparams.flags</a></span> member, the <span class="inline_code">
+<a href="#op">bvbltparams.op</a></span> union is treated as a <span class="inline_code">blend</span>.</p>
+<p>To specify the blend, the client fills in <span class="inline_code">blend</span> with one of the
+<span class="inline_code"><a href="#bvblend">bvblend</a></span> values.</p>
+<p><span class="inline_code"><a href="#bvblend">bvblend</a></span> is an enumeration assembled from sets of fields.
+The values specified may be extended beyond those that are explicitly defined using the definitions in the
+<span class="filename">bvblend.h</span> header file.</p>
+<p>The first 4 bits are the format. Currently two format groups are defined, but others can be added. The remainder
+of the bits are used as defined by the individual format:</p>
+<table class="indent">
+ <tr>
+ <td valign="top">1.</td>
+ <td><span class="Code_Header_3">BVBLENDDEF_FORMAT_CLASSIC</span><br />
+ <br />
+ The <span class="inline_code">BVBLENDDEF_FORMAT_CLASSIC</span> is meant to handle the classic Porter-Duff equations.
+ It can also handle the DirectFB blending.<br />
+ <br />
+ <span class="inline_code">BVBLENDDEF_FORMAT_CLASSIC</span> is based on the following equations:<br />
+ <div>
+ <p class="indent">C<sub>d</sub> = K<sub>1</sub>C<sub>1</sub> + K<sub>2</sub>C<sub>2</sub><br />
+ A<sub>d</sub> = K<sub>3</sub>A<sub>1</sub> + K<sub>4</sub>A<sub>2</sub></p>
+ </div>
+ where:<br />
+ <div>
+ <p class="indent">C<sub>d</sub>: destination color<br />
+ C<sub>1</sub>: source 1 color<br />
+ C<sub>2</sub>: source 2 color<br />
+ A<sub>d</sub>: destination alpha<br />
+ A<sub>1</sub>: source 1 alpha<br />
+ A<sub>2</sub>: source 2 alpha<br />
+ K<sub>#</sub>: one of the constants defined using the bitfields below</p>
+ </div>
+ The 28 bits for <span class="inline_code">BVBLENDDEF_FORMAT_CLASSIC</span> are divided into 5 sections.<br />
+ <br />
+ The most significant 4 bits are modifiers, used to include additional alpha values from global or remote sources.<br />
+ <br />
+ [27] The most significant bit indicates that a remote alpha is to be included in the blend. The format of this is
+ defined by <span class="inline_code"><a href="#maskgeom">bvbltparams.maskgeom.format</a></span>.<br />
+ <br />
+ [26] The next bit is reserved.<br />
+ <br />
+ [25:24] The next 2 bits are used to indicate that a global alpha is to be included, and what its format is:<br />
+ <div>
+ <p class="indent">00: no global included<br />
+ 01: global included; bvbltparams.globalalpha.size8 is used (0 -> 255)<br />
+ 10: this value is reserved<br />
+ 11: global included; bvbltparams.flogalalpha.fp is used (0.0 -> 1.0) </p>
+ </div>
+ The remaining bits are divided into 4 sections, one to define each of the constants:<br />
+ <br />
+ [23:18] - K1<br />
+ [17:12] - K2<br />
+ [11:6] - K3<br />
+ [5:0] - K4<br />
+ <br />
+ The format is the same for all 4 constant fields:<br />
+ <br />
+ [5:4] The first 2 bits of each field indicates the way in which the other 2 fields are interpreted:<br />
+ <div>
+ <p class="indent">00: only As: the other two fields contain only As; there should be only one valid A value
+ between the two fields<br />
+ 01: minimum: the value of the constant is the minimum of the two fields<br />
+ 10: maximum: the value of the constant is the maximum of the two fields<br />
+ 11: only Cs: the other two fields contain only Cs; there should be only one valid C value between the two fields</p>
+ </div>
+ [3:2] The middle 2 bits of each field contain the inverse field:<br />
+ <div>
+ <p class="indent">00: 1-C1 ("don't care" for "only As")<br />
+ 01: 1-A1 ("don't care" for "only Cs")<br />
+ 10: 1-C2 ("don't care" for "only As")<br />
+ 11: 1-A2 ("don't care" for "only Cs")</p>
+ </div>
+ [1:0] The last 2 bits if each field contain the normal field:<br />
+ <div>
+ <p class="indent">00: C1 ("don't care" for "only As")<br />
+ 01: A1 ("don't care" for "only Cs")<br />
+ 10: C2 ("don't care" for "only As")<br />
+ 11: A2 ("don't care" for "only Cs")</p>
+ </div>
+ EXCEPTIONS:<br />
+ <br />
+ 00 00 00 - The value 00 00 00, which normally would indicate "only As" with two "don't care" fields, is interpreted
+ as a constant of 0.<br />
+ <br />
+ 11 11 11 - The value 11 11 11, which normally would indicate "only Cs" with two "don't care" fields, is interpreted
+ as a constant of 1.<br />
+ <br />
+ <span class="Header4">Constants</span><br />
+ <br />
+ Put together, these can define portions of the blend equations that can be put together in a variety of ways:<br />
+ <br />
+ <table class="indent_thick_bord">
+ <tr>
+ <td class="rt_thick_bord">
+ <table>
+ <tr>
+ <td class="thin_bord">00 00 00</td>
+ <td class="thin_bord">undefined -> zero</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">00 00 01</td>
+ <td class="thin_bord">A1 (preferred)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">00 00 10</td>
+ <td class="thin_bord">undefined</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">00 00 11</td>
+ <td class="thin_bord">A2 (preferred)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">00 01 00</td>
+ <td class="thin_bord">1-A1 (preferred)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">00 01 01</td>
+ <td class="thin_bord">undefined</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">00 01 10</td>
+ <td class="thin_bord">1-A1 (use 00 01 00)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">00 01 11</td>
+ <td class="thin_bord">undefined</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">00 10 00</td>
+ <td class="thin_bord">undefined</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">00 10 01</td>
+ <td class="thin_bord">A1 (use 00 00 01)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">00 10 10</td>
+ <td class="thin_bord">undefined</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">00 10 11</td>
+ <td class="thin_bord">A2 (use 00 00 11)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">00 11 00</td>
+ <td class="thin_bord">1-A2 (preferred)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">00 11 01</td>
+ <td class="thin_bord">undefined</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">00 11 10</td>
+ <td class="thin_bord">1-A2 (use 00 11 00)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">00 11 11</td>
+ <td class="thin_bord">undefined</td>
+ </tr>
+ </table>
+ </td>
+ <td class="rt_thick_bord">
+ <table>
+ <tr>
+ <td class="thin_bord">01 00 00</td>
+ <td class="thin_bord">min(C1,1-C1)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">01 00 01</td>
+ <td class="thin_bord">min(A1,1-C1)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">01 00 10</td>
+ <td class="thin_bord">min(C2,1-C1)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">01 00 11</td>
+ <td class="thin_bord">min(A2,1-C1)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">01 01 00</td>
+ <td class="thin_bord">min(C1,1-A1)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">01 01 01</td>
+ <td class="thin_bord">min(A1,1-A1)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">01 01 10</td>
+ <td class="thin_bord">min(C2,1-A1)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">01 01 11</td>
+ <td class="thin_bord">min(A2,1-A1)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">01 10 00</td>
+ <td class="thin_bord">min(C1,1-C2)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">01 10 01</td>
+ <td class="thin_bord">min(A1,1-C2)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">01 10 10</td>
+ <td class="thin_bord">min(C2,1-C2)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">01 10 11</td>
+ <td class="thin_bord">min(A2,1-C2)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">01 11 00</td>
+ <td class="thin_bord">min(C1,1-A2)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">01 11 01</td>
+ <td class="thin_bord">min(A1,1-A2)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">01 11 10</td>
+ <td class="thin_bord">min(C2,1-A2)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">01 11 11</td>
+ <td class="thin_bord">min(A2,1-A2)</td>
+ </tr>
+ </table>
+ </td>
+ <td class="rt_thick_bord">
+ <table>
+ <tr>
+ <td class="thin_bord">10 00 00</td>
+ <td class="thin_bord">max(C1,1-C1)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">10 00 01</td>
+ <td class="thin_bord">max(A1,1-C1)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">10 00 10</td>
+ <td class="thin_bord">max(C2,1-C1)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">10 00 11</td>
+ <td class="thin_bord">max(A2,1-C1)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">10 01 00</td>
+ <td class="thin_bord">max(C1,1-A1)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">10 01 01</td>
+ <td class="thin_bord">max(A1,1-A1)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">10 01 10</td>
+ <td class="thin_bord">max(C2,1-A1)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">10 01 11</td>
+ <td class="thin_bord">max(A2,1-A1)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">10 10 00</td>
+ <td class="thin_bord">max(C1,1-C2)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">10 10 01</td>
+ <td class="thin_bord">max(A1,1-C2)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">10 10 10</td>
+ <td class="thin_bord">max(C2,1-C2)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">10 10 11</td>
+ <td class="thin_bord">max(A2,1-C2)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">10 11 00</td>
+ <td class="thin_bord">max(C1,1-A2)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">10 11 01</td>
+ <td class="thin_bord">max(A1,1-A2)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">10 11 10</td>
+ <td class="thin_bord">max(C2,1-A2)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">10 11 11</td>
+ <td class="thin_bord">max(A2,1-A2)</td>
+ </tr>
+ </table>
+ </td>
+ <td>
+ <table>
+ <tr>
+ <td class="thin_bord">11 00 00</td>
+ <td class="thin_bord">undefined</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">11 00 01</td>
+ <td class="thin_bord">1-C1 (use 11 00 11)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">11 00 10</td>
+ <td class="thin_bord">undefined</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">11 00 11</td>
+ <td class="thin_bord">1-C1 (preferred)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">11 01 00</td>
+ <td class="thin_bord">C1 (use 11 11 00)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">11 01 01</td>
+ <td class="thin_bord">undefined</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">11 01 10</td>
+ <td class="thin_bord">C2 (use 11 11 10)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">11 01 11</td>
+ <td class="thin_bord">undefined</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">11 10 00</td>
+ <td class="thin_bord">undefined</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">11 10 01</td>
+ <td class="thin_bord">1-C2 (use 11 10 11)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">11 10 10</td>
+ <td class="thin_bord">undefined</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">11 10 11</td>
+ <td class="thin_bord">1-C2 (preferred)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">11 11 00</td>
+ <td class="thin_bord">C1 (preferred)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">11 11 01</td>
+ <td class="thin_bord">undefined</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">11 11 10</td>
+ <td class="thin_bord">C2 (preferred)</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">11 11 11</td>
+ <td class="thin_bord">undefined -> one</td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ </table>
+ <span class="Header4"><br />
+ DirectFB Example</span><br />
+ <br />
+ Putting these together into the proper constants, the blending equations can be built for different APIs.
+ Here is how DirectFB would be mapped:<br />
+ <br />
+ For DirectFB, the
+ <a href="http://directfb.org/docs/DirectFB_Reference_1_2/IDirectFBSurface_SetSrcBlendFunction.html" class="inline_code">
+ SetSrcBlendFunction()</a> and
+ <a href="http://directfb.org/docs/DirectFB_Reference_1_2/IDirectFBSurface_SetDstBlendFunction.html" class="inline_code">
+ SetDstBlendFunction()</a> can specify 121 combinations of blends (11 x 11). It's impractical to specify these combinations
+ individually. Instead, the settings indicated by each call should be bitwise OR'd to make the proper single value
+ used in BLTsville.<br />
+ <br />
+ <table class="code_block">
+ <tr>
+ <td class="ctr"> </td>
+ <td colspan="5" class="ctr"><strong>32-bit Binary Value</strong></td>
+ </tr>
+ <tr>
+ <td><strong>
+ <a href="http://directfb.org/docs/DirectFB_Reference_1_2/IDirectFBSurface_SetSrcBlendFunction.html">SetSrcBlendFunction()</a></strong></td>
+ <td class="ctr"><strong>[VendorID]</strong></td>
+ <td class="ctr"><strong> [--K1--] </strong></td>
+ <td class="ctr"><strong> [--K2--] </strong></td>
+ <td class="ctr"><strong> [--K3--] </strong></td>
+ <td class="ctr"><strong> [--K4--] </strong></td>
+ </tr>
+ <tr>
+ <td>DSBF_ZERO</td>
+ <td class="ctr">0000 0000</td>
+ <td class="ctr">00 00 00</td>
+ <td class="ctr">xx xx xx</td>
+ <td class="ctr">00 00 00</td>
+ <td class="ctr">xx xx xx</td>
+ </tr>
+ <tr>
+ <td>DSBF_ONE</td>
+ <td class="ctr">0000 0000</td>
+ <td class="ctr">11 11 11</td>
+ <td class="ctr">xx xx xx</td>
+ <td class="ctr">11 11 11</td>
+ <td class="ctr">xx xx xx</td>
+ </tr>
+ <tr>
+ <td>DSBF_SRCCOLOR</td>
+ <td class="ctr">0000 0000</td>
+ <td class="ctr">11 11 00</td>
+ <td class="ctr">xx xx xx</td>
+ <td class="ctr">00 00 01</td>
+ <td class="ctr">xx xx xx</td>
+ </tr>
+ <tr>
+ <td>DSBF_INVSRCCOLOR</td>
+ <td class="ctr">0000 0000</td>
+ <td class="ctr">11 00 11</td>
+ <td class="ctr">xx xx xx</td>
+ <td class="ctr">00 01 00</td>
+ <td class="ctr">xx xx xx</td>
+ </tr>
+ <tr>
+ <td>DSBF_SRCALPHA</td>
+ <td class="ctr">0000 0000</td>
+ <td class="ctr">00 00 01</td>
+ <td class="ctr">xx xx xx</td>
+ <td class="ctr">00 00 01</td>
+ <td class="ctr">xx xx xx</td>
+ </tr>
+ <tr>
+ <td>DSBF_INVSRCALPHA</td>
+ <td class="ctr">0000 0000</td>
+ <td class="ctr">00 01 00</td>
+ <td class="ctr">xx xx xx</td>
+ <td class="ctr">00 01 00</td>
+ <td class="ctr">xx xx xx</td>
+ </tr>
+ <tr>
+ <td>DSBF_DESTCOLOR</td>
+ <td class="ctr">0000 0000</td>
+ <td class="ctr">11 11 10</td>
+ <td class="ctr">xx xx xx</td>
+ <td class="ctr">00 00 11</td>
+ <td class="ctr">xx xx xx</td>
+ </tr>
+ <tr>
+ <td>DSBF_INVDESTCOLOR</td>
+ <td class="ctr">0000 0000</td>
+ <td class="ctr">11 10 11</td>
+ <td class="ctr">xx xx xx</td>
+ <td class="ctr">00 11 00</td>
+ <td class="ctr">xx xx xx</td>
+ </tr>
+ <tr>
+ <td>DSBF_DESTALPHA</td>
+ <td class="ctr">0000 0000</td>
+ <td class="ctr">00 00 11</td>
+ <td class="ctr">xx xx xx</td>
+ <td class="ctr">00 00 11</td>
+ <td class="ctr">xx xx xx</td>
+ </tr>
+ <tr>
+ <td>DSBF_INVDESTALPHA</td>
+ <td class="ctr">0000 0000</td>
+ <td class="ctr">00 11 00</td>
+ <td class="ctr">xx xx xx</td>
+ <td class="ctr">00 11 00</td>
+ <td class="ctr">xx xx xx</td>
+ </tr>
+ <tr>
+ <td>DSBF_SRCALPHASAT</td>
+ <td class="ctr">0000 0000</td>
+ <td class="ctr">01 11 01</td>
+ <td class="ctr">xx xx xx</td>
+ <td class="ctr">11 11 11</td>
+ <td class="ctr">xx xx xx</td>
+ </tr>
+ </table>
+ <br />
+ <table class="code_block">
+ <tr>
+ <td class="ctr"> </td>
+ <td colspan="5" class="ctr"><strong>32-bit Binary Value</strong></td>
+ </tr>
+ <tr>
+ <td><strong>
+ <a href="http://directfb.org/docs/DirectFB_Reference_1_2/IDirectFBSurface_SetDstBlendFunction.html">SetDstBlendFunction()</a></strong></td>
+ <td class="ctr"><strong>[VendorID]</strong></td>
+ <td class="ctr"><strong> [--K1--] </strong></td>
+ <td class="ctr"><strong> [--K2--] </strong></td>
+ <td class="ctr"><strong> [--K3--] </strong></td>
+ <td class="ctr"><strong> [--K4--] </strong></td>
+ </tr>
+ <tr>
+ <td>DSBF_ZERO</td>
+ <td class="ctr">0000 0000</td>
+ <td class="ctr">xx xx xx</td>
+ <td class="ctr">00 00 00</td>
+ <td class="ctr">xx xx xx</td>
+ <td class="ctr">00 00 00</td>
+ </tr>
+ <tr>
+ <td>DSBF_ONE</td>
+ <td class="ctr">0000 0000</td>
+ <td class="ctr">xx xx xx</td>
+ <td class="ctr">11 11 11</td>
+ <td class="ctr">xx xx xx</td>
+ <td class="ctr">11 11 11</td>
+ </tr>
+ <tr>
+ <td>DSBF_SRCCOLOR</td>
+ <td class="ctr">0000 0000</td>
+ <td class="ctr">xx xx xx</td>
+ <td class="ctr">11 11 00</td>
+ <td class="ctr">xx xx xx</td>
+ <td class="ctr">00 00 01</td>
+ </tr>
+ <tr>
+ <td>etc.</td>
+ <td class="ctr"> </td>
+ <td class="ctr"> </td>
+ <td class="ctr"> </td>
+ <td class="ctr"> </td>
+ <td> </td>
+ </tr>
+ </table>
+ <br />
+ <span class="Header4">Porter-Duff</span><br />
+ <br />
+ For Porter-Duff blends, the equations can be more specifically defined. For convenience, these are enumerated in
+ the <span class="inline_code">bvblend.h</span> header. These enumerations utilize only the local alpha in the equations
+ as indicated. To use global or remote alpha, these enumerations need to be modified. For example, to include the
+ global alpha in the Porter-Duff <span class="inline_code">BVBLEND_SRC1OVER</span> blend, the blend could be defined
+ like this:<br />
+ <br />
+ <div>
+ <table class="indent">
+ <tr>
+ <td valign="top"><span class="inline_code">params.op.blend =</span></td>
+ <td><span class="inline_code">BVBLEND_SRC1OVER +<br />
+ BVBLENDDEF_GLOBAL_UCHAR;</span></td>
+ </tr>
+ </table>
+ </div>
+ <br />
+ To include the remote alpha, the blend could be defined like this:<br />
+ <br />
+ <div>
+ <table class="indent">
+ <tr>
+ <td valign="top"><span class="inline_code">params.op.blend =</span></td>
+ <td><span class="inline_code">BVBLEND_SRC1OVER +<br />
+ BVBLENDDEF_REMOTE;</span></td>
+ </tr>
+ </table>
+ </div>
+ <br />
+ And to include both:<br />
+ <br />
+ <div>
+ <table class="indent">
+ <tr>
+ <td valign="top"><span class="inline_code">params.op.blend =</span></td>
+ <td><span class="inline_code">BVBLEND_SRC1OVER +<br />
+ BVBLENDDEF_GLOBAL_UCHAR +<br />
+ BVBLENDDEF_REMOTE;</span></td>
+ </tr>
+ </table>
+ </div>
+ <br />
+ Note that if the source color formats include local alphas, the local alphas, global alpha, and remote alpha will
+ be used together.<br />
+ <br />
+ Note also that the equations assume the surfaces are premultiplied. So if the surface formats indicate that they
+ are not premultiplied, the alpha multiplication of each color is done prior to using the surface values in the equations.<br />
+ <br />
+ For example, <span class="inline_code">BVBLEND_SRC1OVER</span> specifies the equations:<br />
+ <table class="indent">
+ <tr>
+ <td>C<sub>d</sub> = C<sub>1</sub> + (1 - A<sub>1</sub>)C<sub>2</sub><br />
+ A<sub>d</sub> = A<sub>1</sub> + (1 - A<sub>1</sub>)A<sub>2</sub> </td>
+ </tr>
+ </table>
+ <br />
+ If the format of surface 1 is non-premultiplied, the equations are modified to include the multiplication explicitly:<br />
+ <br />
+ <table class="indent">
+ <tr>
+ <td>C<sub>d</sub> = A<sub>1</sub>C<sub>1</sub> + (1 - A<sub>1</sub>)C<sub>2</sub><br />
+ A<sub>d</sub> = A<sub>1</sub> + (1 - A<sub>1</sub>)A<sub>2</sub> </td>
+ </tr>
+ </table>
+ <br />
+ Likewise, if the format of surface 2 is non-premultiplied, the equations are modified for this:<br />
+ <br />
+ <table class="indent">
+ <tr>
+ <td>
+ <div>
+ C<sub>d</sub> = C<sub>1</sub> + (1 - A<sub>1</sub>)A<sub>2</sub>C<sub>2</sub><br />
+ A<sub>d</sub> = A<sub>1</sub> + (1 - A<sub>1</sub>)A<sub>2</sub> </div>
+ </td>
+ </tr>
+ </table>
+ <br />
+ When including global or remote alphas, these values are used to modify the source 1 value values before being used
+ in the blend equation:<br />
+ <br />
+ <table class="indent">
+ <tr>
+ <td class="ctr">C<sub>1</sub> = A<sub>g</sub>C<sub>1</sub><br />
+ A<sub>1</sub> = A<sub>g</sub>A<sub>1</sub></td>
+ <td style="width: 20%" class="ctr">-or-</td>
+ <td class="ctr">C<sub>1</sub> = A<sub>r</sub>C<sub>1</sub><br />
+ A<sub>1</sub> = A<sub>r</sub>A<sub>1</sub></td>
+ <td class="ctr">-or-</td>
+ <td class="ctr">C<sub>1</sub> = A<sub>r</sub>A<sub>g</sub>C<sub>1</sub><br />
+ A<sub>1</sub> = A<sub>r</sub>A<sub>g</sub>A<sub>1</sub></td>
+ </tr>
+ </table>
+ <br />
+ </td>
+ </tr>
+ <tr>
+ <td valign="top">2.</td>
+ <td><span class="Code_Header_3"><strong><a name="BVBLENDDEF_FORMAT_ESSENTIAL0">BVBLENDDEF_FORMAT_ESSENTIAL</a></strong></span><br />
+ <br />
+ The essential blending equations are based on the blending equations in common image manipulation programs.<pre class="indent"><code>BVBLEND_LIGHTEN max(src1, src2)
+BVBLEND_DARKEN min(src1, src2)
+BVBLEND_MULTIPLY (src1 * src2) / 255
+BVBLEND_AVERAGE (src1 + src2) / 2
+BVBLEND_ADD src1 + src2 (saturated)
+BVBLEND_SUBTRACT src1 + src2 - 255 (saturated)
+BVBLEND_DIFFERENCE abs(src - src2)
+BVBLEND_NEGATION 255 - abs(255 - src1 - src2)
+BVBLEND_SCREEN 255 - (((255 - src1) * (255 - src2)) / 256)
+BVBLEND_EXCLUSION src1 + src2 - ((2 * src1 * src2) / 255)
+BVBLEND_OVERLAY (src2 < 128) ? (2 * src1 * src2 / 255) : (255 - 2 * (255 - src1) * (255 - src2) / 255)
+BVBLEND_SOFT_LIGHT (src2 < 128) ? (2 * ((src1 >> 1) + 64)) * ((float)src2 / 255) : (255 - (2 * (255 - ((src1 >> 1) + 64)) * (float)(255 - src2) / 255))
+BVBLEND_HARD_LIGHT (src1 < 128) ? (2 * src2 * src1 / 255) : (255 - 2 * (255 - src2) * (255 - src1) / 255)
+BVBLEND_COLOR_DODGE (src2 == 255) ? src2 : min(255, ((src1 << 8) / (255 - src2))
+BVBLEND_COLOR_BURN (src2 == 0) ? src2 : max(0, (255 - ((255 - src1) << 8 ) / src2))))
+BVBLEND_LINEAR_DODGE same as BVBLEND_ADD
+BVBLEND_LINEAR_BURN same as BVBLEND_SUBTRACT
+BVBLEND_LINEAR_LIGHT (src2 < 128) ? LINEAR_BURN(src1,(2 * src2)) : LINEAR_DODGE(src1,(2 * (src2 - 128)))
+BVBLEND_VIVID_LIGHT (src2 < 128) ? COLOR_BURN(src1,(2 * src2)) : COLOR_DODGE(src1,(2 * (src2 - 128))))
+BVBLEND_PIN_LIGHT (src2 < 128) ? DARKEN(src1,(2 * src2)) : LIGHTEN(src1,(2 * (src2 - 128)))
+BVBLEND_HARD_MIX (VIVID_LIGHT(src1, src2) < 128) ? 0 : 255
+BVBLEND_REFLECT (src2 == 255) ? src2 : min(255, (src1 * src1 / (255 - src2)))
+BVBLEND_GLOW (src1 == 255) ? src1 : min(255, (src2 * src2 / (255 - src1)))
+BVBLEND_PHOENIX min(src1, src2) - max(src1, src2) + 255)
+BVBLEND_ALPHA alf * src1 + (1 - alf) * src2)</code></pre>
+ </td>
+ </tr>
+</table>
+<a name="filter" class="Code_Header_2">bvbltparams.op.filter</a>
+<p class="code_block">struct bvfilter *filter; /* input */</p>
+<p>When <span class="inline_code"><a href="#BVFLAG_FILTER">BVFLAG_FILTER</a></span> is set in the
+<span class="inline_code"><a href="#flags">bvbltparams.flags</a></span> member, the <span class="inline_code">
+<a href="#op">bvbltparams.op</a></span> union is treated as a <span class="inline_code">filter</span>.</p>
+<p>To specify the filter, the client fills in <span class="inline_code">filter</span> with one of the
+<span class="inline_code">bvfilter</span> values.</p>
+<p>These values will be extended as general filter types are requested.</p>
+<a name="colorkey" class="Code_Header_2">bvbltparams.colorkey</a>
+<p class="code_block">void *colorkey; /* input */</p>
+<p>When either <span class="inline_code"><a href="#BVFLAG_KEY_SRC">BVFLAG_KEY_SRC</a></span> or
+<span class="inline_code"><a href="#BVFLAG_KEY_DST">BVFLAG_KEY_DST</a></span> is set in the <span class="inline_code">
+<a href="#flags">bvbltparams.flags</a></span> member, <span class="inline_code">colorkey</span> points to a single pixel
+used as the color key.</p>
+<p>The format of this pixel matches the surface being keyed. i.e. <span class="inline_code"><a href="#bvsurfgeom">
+src1geom.format</a></span> is the format of the color key if <span class="inline_code">BVFLAG_KEY_SRC</span> is set, or
+<span class="inline_code"><a href="#bvsurfgeom">dst.format</a></span> is the format of the color key if
+<span class="inline_code">BVFLAG_KEY_DST</span> is set.</p>
+<p><em>Subsampled formats do not currently support color keying.</em></p>
+<p class="Code_Header_2"><a name="globalalpha">bvbltparams.globalalpha</a></p>
+<p class="code_block">union bvalpha globalalpha; /* input */</p>
+<p>When <span class="inline_code"><a href="#BVFLAG_BLEND">BVFLAG_BLEND</a></span> is set in the
+<span class="inline_code"><a href="#flags">bvbltparams.flags</a></span>, and when the <span class="inline_code">
+<a href="#blend">blend</a></span> chosen requires it, <span class="inline_code">globalalpha</span> is used to provide an
+alpha blending value for the entire operation. The type is also dependent on the <span class="inline_code">
+<a href="#blend">blend</a></span> chosen.</p>
+<p>For the <span class="inline_code">BVBLENDDEF_FORMAT_CLASSIC</span> blend types, if the <span class="inline_code">BVBLENDDEF_GLOBAL_MASK</span>
+field is not 0, this field is used. Currently <span class="inline_code">BVBLENDDEF_FORMAT_CLASSIC</span> provides
+for an 8-bit (unsigned character / byte) format designated by <span class="inline_code">BVBLENDDEF_GLOBAL_UCHAR</span> as
+well as a 32-bit floating point format designated by <span class="inline_code">BVBLENDDEF_GLOBAL_FLOAT</span>.</p>
+<p class="Code_Header_2"><a name="scalemode">bvbltparams.scalemode</a></p>
+<p class="code_block">enum bvscalemode scalemode; /* input/output */</p>
+<p>This member allows the client to specify the type of scaling to be used. The enumeration begins with 8 bits indicating
+the vendor. The remaining bits are defined by the vendor. <span class="inline_code">BVSCALEDEF_VENDOR_ALL</span>
+and <span class="inline_code">BVSCALEDEF_VENDOR_GENERAL</span> are shared by all implementations.</p>
+<p><span class="inline_code">BVSCALEDEF_VENDOR_ALL</span> can be used to specify an implicit scale type. This type
+is converted to an explicit type by the implementation:</p>
+<table class="indent">
+ <tr>
+ <td class="inline_code">BVSCALE_FASTEST</td>
+ <td>The fastest method of scaling available is used. This may include nearest neighbor. The value of
+ this enumeration is purposely 0, and is the default scale type. No implementation will return an error for
+ this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_FASTEST_NOT_NEAREST_NEIGHBOR</td>
+ <td>The fastest method of scaling available that is not nearest neighbor is used. This may include an alternative
+ point sample technique.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_FASTEST_POINT_SAMPLE</td>
+ <td>The fastest method of scaling using a point sample technique.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_FASTEST_INTERPOLATED</td>
+ <td>The fastest method of scaling using an interpolation technique.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_FASTEST_PHOTO</td>
+ <td>The fastest method of scaling appropriate for photographs is used. This may include nearest neighbor.
+ No implementation will return an error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_FASTEST_DRAWING</td>
+ <td>The fastest method of scaling appropriate for drawings is used. This may include nearest neighbor.
+ No implementation will return an error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_GOOD</td>
+ <td>A scaling technique is chosen that may be higher quality than the <span class="inline_code">BVSCALE_FASTEST</span>
+ choice. This may include nearest neighbor. No implementation will return an error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_GOOD_POINT_SAMPLE</td>
+ <td>A point sample scaling technique is chosen that may be higher quality than the <span class="inline_code">BVSCALE_FASTEST_POINT_SAMPLE</span>
+ choice. This may include nearest neighbor.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_GOOD_INTERPOLATED</td>
+ <td>An interpolated scaling technique is chosen that may be higher quality than the <span class="inline_code">BVSCALE_FASTEST_INTERPOLATED</span>
+ choice.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_GOOD_PHOTO</td>
+ <td>A scaling technique appropriate for photographs is chosen that may be higher quality than the
+ <span class="inline_code">BVSCALE_FASTEST_PHOTO</span> choice. This may include nearest neighbor. No
+ implementation will return an error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_GOOD_DRAWING</td>
+ <td>A scaling technique appropriate for drawings is chosen that may be higher quality than the
+ <span class="inline_code">BVSCALE_FASTEST_DRAWING</span> choice. This may include nearest neighbor.
+ No implementation will return an error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_BETTER</td>
+ <td>A scaling technique is chosen that may be higher quality than the <span class="inline_code">BVSCALE_GOOD</span>
+ choice. This may include nearest neighbor. No implementation will return an error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_BETTER_POINT_SAMPLE</td>
+ <td>A point sample scaling technique is chosen that may be higher quality than the <span class="inline_code">BVSCALE_GOOD_POINT_SAMPLE</span>
+ choice. This may include nearest neighbor.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_BETTER_INTERPOLATED</td>
+ <td>An interpolated scaling technique is chosen that may be higher quality than the <span class="inline_code">BVSCALE_GOOD_INTERPOLATED</span>
+ choice.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_BETTER_PHOTO</td>
+ <td>A scaling technique appropriate for photographs is chosen that may be higher quality than the
+ <span class="inline_code">BVSCALE_GOOD_PHOTO</span> choice. This may include nearest neighbor. No implementation
+ will return an error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_BETTER_DRAWING</td>
+ <td>A scaling technique appropriate for drawings is chosen that may be higher quality than the
+ <span class="inline_code">BVSCALE_GOOD_DRAWING</span> choice. This may include nearest neighbor. No
+ implementation will return an error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_BEST</td>
+ <td>The highest quality scaling technique is chosen. This may include nearest neighbor. No implementation
+ will return an error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_BEST_POINT_SAMPLE</td>
+ <td>The highest quality point sample technique is chosen.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_BEST_INTERPOLATED</td>
+ <td>The highest quality interpolated scaling technique is chosen.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_BEST_PHOTO</td>
+ <td>The highest quality scaling technique appropriate for photographs is chosen. This may include nearest
+ neighbor. No implementation will return an error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_BEST_DRAWING</td>
+ <td>The highest quality scaling technique appropriate for drawings is chosen. This may include nearest neighbor.
+ No implementation will return an error for this setting.</td>
+ </tr>
+</table>
+<br />
+<span class="inline_code">BVSCALEDEF_VENDOR_GENERAL</span> can be used to specify one of the shared explicit scale types.
+At this point, only a limited number of explicit scale types are defined: <br />
+<br />
+<table class="indent">
+ <tr>
+ <td class="inline_code">BVSCALE_NEAREST_NEIGHBOR</td>
+ <td>This is a point sample scaling technique where the resampled destination pixel is set to the value of the closest
+ source pixel.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_BILINEAR</td>
+ <td>This is an interpolated scaling technique where the resampled destination pixel is set to a value linearly interpolated
+ in two dimensions from the four closest source pixels.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_BICUBIC</td>
+ <td>This is an interpolated scaling technique where the resampled destination pixel is set to a value calculated
+ using cubic interpolation in two dimensions.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_3x3_TAP</td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_5x5_TAP</td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_7x7_TAP</td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVSCALE_9x9_TAP</td>
+ <td> </td>
+ </tr>
+</table>
+<p>If the client wants to know the explicit type chosen by a given implementation, it can set <span class="inline_code">
+BVFLAG_SCALE_RETURN</span> in the <span class="inline_code"><a href="#flags">bvbltparams.flags</a></span> member, and the
+explicit scale type is returned in the <span class="inline_code">scalemode</span> member.</p>
+<p class="note">NOTE: Extending the <span class="inline_code">BVSCALEDEF_VENDOR_GENERAL</span> scale types or obtaining
+a vendor ID can be accomplished by submitting a patch.</p>
+<p class="Code_Header_2"><a name="dithermode">bvbltparams.dithermode</a></p>
+<p class="code_block">enum bvdithermode dithermode; /* input/output */</p>
+<p>This member allows the client to specify the type of dithering to be used, when the output format has fewer bits of depth
+than the internal calculation. The enumeration begins with 8 bits indicating the vendor. The remaining bits
+are defined by the vendor. <span class="inline_code">BVDITHERDEF_VENDOR_ALL</span> and <span class="inline_code">BVDITHERDEF_VENDOR_GENERAL</span>
+are shared by all implementations.</p>
+<p><span class="inline_code">BVDITHERDEF_VENDOR_ALL</span> can be used to specify an implicit dither type. This type
+is converted to an explicit type by the implementation:</p>
+<table class="indent">
+ <tr>
+ <td class="inline_code">BVDITHER_FASTEST</td>
+ <td>The fastest method of dithering available is used. This may include no dithering (truncation). The
+ value of this enumeration is purposely 0, and is the default dither type. No implementation will return an
+ error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_FASTEST_ON</td>
+ <td>The fastest method of dithering available is used. This will not include no dithering.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_FASTEST_RANDOM</td>
+ <td>The fastest method of dithering using a random technique.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_FASTEST_ORDERED</td>
+ <td>The fastest method of dithering using an ordered diffusion technique.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_FASTEST_DIFFUSED</td>
+ <td>The fastest method of dithering using an error diffusion technique.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_FASTEST_PHOTO</td>
+ <td>The fastest method of dithering appropriate for photographs is used. This may include no dithering.
+ No implementation will return an error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_FASTEST_DRAWING</td>
+ <td>The fastest method of dithering appropriate for drawings is used. This may include no dithering.
+ No implementation will return an error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_GOOD</td>
+ <td>A dithering technique is chosen that may be higher quality than the <span class="inline_code">BVDITHER_FASTEST</span>
+ choice. This may include no dithering. No implementation will return an error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_GOOD_ON</td>
+ <td>Any dithering technique available is used. This will not include no dithering. This may be higher
+ quality than <span class="inline_code">BVDITHER_FASTEST_ON</span>.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_GOOD_RANDOM</td>
+ <td>A random dithering technique is chosen that may be higher quality than the <span class="inline_code">BVDITHER_FASTEST_RANDOM</span>
+ choice.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_GOOD_ORDERED</td>
+ <td>An ordered dithering technique is chosen that may be higher quality than the <span class="inline_code">BVDITHER_FASTEST_ORDERED</span>
+ choice.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_GOOD_DIFFUSED</td>
+ <td>A diffused dithering technique is chosen that may be higher quality than the <span class="inline_code">BVDITHER_FASTEST_DIFFUSED</span>
+ choice.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_GOOD_PHOTO</td>
+ <td>A dithering technique appropriate for photographs is chosen that may be higher quality than the
+ <span class="inline_code">BVDITHER_FASTEST_PHOTO</span> choice. This may include no dithering. No implementation
+ will return an error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_GOOD_DRAWING</td>
+ <td>A dithering technique appropriate for drawings is chosen that may be higher quality than the
+ <span class="inline_code">BVDITHER_FASTEST_DRAWING</span> choice. This may include no dithering. No
+ implementation will return an error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_BETTER</td>
+ <td>A dithering technique is chosen that may be higher quality than the <span class="inline_code">BVDITHER_GOOD</span>
+ choice. This may include no dithering. No implementation will return an error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_BETTER_ON</td>
+ <td>Any dithering technique available is used. This will not include no dithering. This may be higher
+ quality than <span class="inline_code">BVDITHER_GOOD_ON</span>.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_BETTER_RANDOM</td>
+ <td>A random dithering technique is chosen that may be higher quality than the <span class="inline_code">BVDITHER_GOOD_RANDOM</span>
+ choice.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_BETTER_ORDERED</td>
+ <td>An ordered dithering technique is chosen that may be higher quality than the <span class="inline_code">BVDITHER_GOOD_ORDERED</span>
+ choice.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_BETTER_DIFFUSED</td>
+ <td>A diffused dithering technique is chosen that may be higher quality than the <span class="inline_code">BVDITHER_GOOD_DIFFUSED</span>
+ choice.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_BETTER_PHOTO</td>
+ <td>A scaling technique appropriate for photographs is chosen that may be higher quality than the
+ <span class="inline_code">BVSCALE_GOOD_PHOTO</span> choice. No implementation will return an error for this
+ setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_BETTER_DRAWING</td>
+ <td>A scaling technique appropriate for drawings is chosen that may be higher quality than the
+ <span class="inline_code">BVSCALE_GOOD_DRAWING</span> choice. No implementation will return an error for this
+ setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_BEST</td>
+ <td>The highest quality dithering technique is chosen. This may include no dithering. No implementation
+ will return an error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_BEST_ON</td>
+ <td>Any dithering technique available is used. This will not include no dithering. This may be higher
+ quality than <span class="inline_code">BVDITHER_BEST_ON</span>.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_BEST_RANDOM</td>
+ <td>The highest quality random dithering technique is chosen.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_BEST_ORDERED</td>
+ <td>The highest quality ordered dithering technique is chosen.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_BEST_DIFFUSED</td>
+ <td>The highest quality diffused dithering technique is chosen.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_BEST_PHOTO</td>
+ <td>The highest quality dithering technique appropriate for photographs is chosen. This may include no dithering.
+ No implementation will return an error for this setting.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_BEST_DRAWING</td>
+ <td>The highest quality dithering technique appropriate for drawings is chosen. This may include no dithering.
+ No implementation will return an error for this setting.</td>
+ </tr>
+</table>
+<br />
+<span class="inline_code">BVDITHERDEF_VENDOR_GENERAL</span> can be used to specify one of the shared explicit dithering
+types. At this point, only a limited number of explicit dither types are defined:<br />
+<br />
+<table class="indent">
+ <tr>
+ <td class="inline_code">BVDITHER_NONE</td>
+ <td>No dithering is performed. Internal pixel component values are truncated to the destination component
+ bit depth.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_ORDERED_2x2</td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_ORDERED_4x4</td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVDITHER_ORDERED_2x2_4x4</td>
+ <td>2x2 ordered dither is used for components with the lowest bit reduction. 4x4 ordered dither is used for
+ the components with the highest bit reduction. (E.g. RGB24 to RGB565 will use 2x2 ordered dither for the green
+ component and 4x4 ordered dither for the red and blue components.)</td>
+ </tr>
+</table>
+<p>If the client wants to know the explicit type chosen by a given implementation, it can set <span class="inline_code">
+BVFLAG_DITHER_RETURN</span> in the <span class="inline_code"><a href="#flags">bvbltparams.flags</a></span> member, and the
+explicit scale type is returned in the <span class="inline_code">dithermode</span> member.</p>
+<p class="note">NOTE: Extending the <span class="inline_code">BVDITHERDEF_VENDOR_GENERAL</span> scale types or obtaining
+a vendor ID can be accomplished by submitting a patch.</p>
+<p class="Code_Header_2"><a name="dstdesc">bvbltparams.dstdesc</a></p>
+<p class="code_block"><a href="#bvbuffdesc">struct bvbuffdesc</a> *dstdesc;</p>
+<p><span class="inline_code">dstdesc</span> is used to specify the destination buffer. If the buffer has not been
+mapped with a call to <span class="inline_code"><a href="#bv_map">bv_map()</a></span>, <span class="inline_code">
+<a href="#bv_blt">bv_blt()</a></span> will map the buffer as necessary to perform the BLT and then unmap afterwards.
+See <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> for details.</p>
+<p class="Code_Header_2"><a name="dstgeom">bvbltparams.dstgeom</a></p>
+<p class="code_block"><a href="#bvsurfgeom">struct bvsurfgeom</a> *dstgeom;</p>
+<p><span class="inline_code">dstgeom</span> is used to specify the geometry of the surface contained in the destination
+buffer. See <span class="inline_code"><a href="#bvsurfgeom">bvsurfgeom</a></span> for details.</p>
+<p class="Code_Header_2"><a name="dstrect">bvbltparams.dstrect</a></p>
+<p class="code_block"><a href="#bvrect">struct bvrect</a> dstrect;</p>
+<p><span class="inline_code">dstrect</span> is used to specify the destination rectangle to receive the BLT. This
+rectangle is clipped by <span class="inline_code"><a href="#cliprect">bvbltparams.cliprect</a></span> when
+<span class="inline_code"><a href="#BVFLAG_CLIP">BVFLAG_CLIP</a></span> is set in the <span class="inline_code">
+<a href="#flags">bvbltparams.flags</a></span> member.</p>
+<p class="Code_Header_2">bvbltparams.<a name="src1.desc">src1</a>/<a name="src2.desc">src2</a>/<a name="mask.desc">mask.desc</a></p>
+<p class="code_block"><a href="#bvbuffdesc">struct bvbuffdesc</a> *src1.desc;<br />
+<a href="#bvbuffdesc">struct bvbuffdesc</a> *src2.desc;<br />
+<a href="#bvbuffdesc">struct bvbuffdesc</a> *mask.desc;</p>
+<p>These members are used to identify the buffer for the source1, source2, and mask surfaces when the associated
+<span class="inline_code">BVFLAG_TILE_*</span> flag is not set. The buffer is the memory in which the surface lies.
+See the <span class="inline_code"><a href="#src1geom">bvbltparams.src1/src2/maskgeom</a></span> for the format and layout/geometry
+of the surface.</p>
+<p class="note">NOTE WELL: Clients should never change the value of a <span class="inline_code">
+<a href="#bvbuffdesc">bvbuffdesc</a></span> structure while a buffer is mapped.</p>
+<p class="Code_Header_2">bvbltparams.<a name="src1.tileparams">src1</a>/<a name="src2.tileparams">src2</a>/<a name="mask.tileparams">mask.tileparams</a></p>
+<p class="code_block"><a href="#bvtileparams">struct bvtileparams</a> *src1.tileparams;<br />
+<a href="#bvtileparams">struct bvtileparams</a> *src2.tileparams;<br />
+<a href="#bvtileparams">struct bvtileparams</a> *mask.tileparams;</p>
+<p>These members are used to identify the buffer for the source1, source2, and mask surfaces when the associated
+<span class="inline_code">BVFLAG_TILE_*</span> flag is set. The buffer is the memory in which the surface lies.
+This differs from the <span class="inline_code"><a href="#src1.desc">src1/src2/mask.desc</a></span> identity by providing
+more information needed for tiling and by not requiring mapping (for hardware implementations that support tiling, the tile
+data is usually moved into an on-chip cache).</p>
+<p class="Code_Header_2">bvbltparams.<a name="src1geom">src1</a>/<a name="src2geom">src2</a>/<a name="maskgeom">maskgeom</a></p>
+<p class="code_block"><a href="#bvsurfgeom">struct bvsurfgeom</a> src1geom;<br />
+<a href="#bvsurfgeom">struct bvsurfgeom</a> src2geom;<br />
+<a href="#bvsurfgeom">struct bvsurfgeom</a> maskgeom;</p>
+<p>These members describe the format and layout/geometry of their respective surfaces. Separating
+<span class="inline_code"><a href="#bvsurfgeom">bvsurfgeom</a></span> from the <span class="inline_code">
+<a href="#bvbuffdesc">bvbuffdesc</a></span> allows easy use of buffers for multiple geometries without remapping.
+See <span class="inline_code"><a href="#bvsurfgeom">bvsurfgeom</a></span> and <span class="inline_code">
+<a href="#bvbuffdesc">bvbuffdesc</a></span> for details.</p>
+<p class="Code_Header_2">bbvbltparams.src1/src2/maskrect</p>
+<p class="code_block"><a href="#bvrect">struct bvrect</a> src1rect;<br />
+<a href="#bvrect">struct bvrect</a> src2rect;<br />
+<a href="#bvrect">struct bvrect</a> maskrect;</p>
+<p>These members specify the rectangle from which data is read for the BLT. These rectangles are clipped by a scaled
+version of the <span class="inline_code"><a href="#cliprect">bvbltparams.cliprect</a></span> (scaling is based on
+the relationship between them and the <span class="inline_code"><a href="#dstrect">bvbltparams.dstrect</a></span>) when
+<span class="inline_code"><a href="#BVFLAG_CLIP">BVFLAG_CLIP</a></span> is set in the <span class="inline_code">
+<a href="#flags">bvbltparams.flags</a></span> member.</p>
+<table class="example">
+ <tr>
+ <td>
+ <p><strong>Example:</strong></p>
+ <a href="#src1rect" class="inline_code">src1rect</a> = (0, 0) - (400 x 200)<br />
+ <a href="#dstrect" class="inline_code">dstrect</a> = (0, 0) - (800 x 600)<br />
+ <a href="#cliprect" class="inline_code">cliprect</a> = (10, 30) - (300 x 300)<p>The scaling ratio of the
+ <a href="#dstrect" class="inline_code">dstrect</a> to the <a href="#src1rect" class="inline_code">src1rect</a> is
+ (800/400, 600/300) or (2, 3). Using this, the effective source 1 clipping rectangle becomes (10/2, 30/3)
+ - (300/2 x 300/3) or (5, 10) - (150 x 100).</p>
+ </td>
+ </tr>
+</table>
+<p>This approach allows fractional clipping at the source using a method which is simpler to implement than fractional coordinates.</p>
+<p class="note">NOTE: In BLTsville, reading outside the source rectangle is forbidden. So scaling algorithms
+which require pixels around a particular source pixel must utilize boundary techniques (mirror, repeat, clamp, etc.) at
+the edges of the source rectangle. However, if the clipping rectangle, when translated back to the source rectangle,
+leaves space between it and the source rectangle, pixels outside the clipped region may be accessed by the implementation.</p>
+<p class="Code_Header_2"><a name="cliprect">bvbltparams.cliprect</a></p>
+<p class="code_block"><a href="#bvrect">struct bvrect</a> cliprect;</p>
+<p><span class="inline_code">cliprect</span> is used to specify a rectangle that limits what region of the destination is
+written. This is most useful for scaling operations, where the necessary scaling factor will not allow translation
+of the destination rectangle back to the source on an integer pixel boundary.</p>
+<p class="note">NOTE: If <span class="inline_code">cliprect</span> exceeds the destination surface, the behavior is
+undefined. </p>
+<p>For example, if the goal is to show a 640 x 480 video on a 1920 x 1080 screen, the video would be stretched to 1440 x
+1080 to maintain the proper aspect ratio. So the relevant rectangles would be:</p>
+<table class="indent">
+ <tr>
+ <td class="thin_bord"><strong>src1rect</strong></td>
+ <td class="thin_bord"><strong>dstrect</strong></td>
+ </tr>
+ <tr>
+ <td class="thin_bord">(0, 0) - 640 x 480</td>
+ <td class="thin_bord">(240, 0) - 1440 x 1080</td>
+ </tr>
+</table>
+<p>However, to handle a 640 x 480 pop-up window that appears centered on the screen, in front of the video, the single BLT
+may be broken into four smaller BLTs pieced around the popup. These rectangles would need to be:</p>
+<table class="indent">
+ <tr>
+ <td class="thin_bord"><strong>src1rect</strong></td>
+ <td class="thin_bord"><strong>dstrect</strong></td>
+ </tr>
+ <tr>
+ <td class="thin_bord">(0, 0) - 640 x 133.333...</td>
+ <td class="thin_bord">(240, 0) - 1440 x 300</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">(0, 133.333...) - 284.444... x 213.333...</td>
+ <td class="thin_bord">(240, 300) - 400 x 480</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">(568.888..., 133.333...) - 284.444... x 213.333...</td>
+ <td class="thin_bord">(1280, 300) - 400 x 480</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">(0, 346.666...) - 640 x 133.333...</td>
+ <td class="thin_bord">(240, 780) - 1440 x 300</td>
+ </tr>
+</table>
+<p>Since this is a scaling factor of 2.25x, translating the required destination rectangles back to the source results in
+non-integer coordinates and dimensions, as illustrated above. And adjusting the source rectangles to the nearest integer
+values will result in visible discontinuities at the boundaries between the rectangles.</p>
+<p>Instead, using the <span class="inline_code">cliprect</span>, this situation can be handled more easily:</p>
+<table class="indent">
+ <tr>
+ <td class="thin_bord"><strong>src1rect</strong></td>
+ <td class="thin_bord"><strong>dstrect</strong></td>
+ <td class="thin_bord"><strong>cliprect</strong></td>
+ </tr>
+ <tr>
+ <td class="thin_bord">(0, 0) - 640 x 480</td>
+ <td class="thin_bord">(240, 0) - 1440 x 1080</td>
+ <td class="thin_bord">(240, 0) - 1440 x 300</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">(0, 0) - 640 x 480</td>
+ <td class="thin_bord">(240, 0) - 1440 x 1080</td>
+ <td class="thin_bord">(240, 300) - 400 x 480</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">(0, 0) - 640 x 480</td>
+ <td class="thin_bord">(240, 0) - 1440 x 1080</td>
+ <td class="thin_bord">(1280, 300) - 400 x 480</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">(0, 0) - 640 x 480</td>
+ <td class="thin_bord">(240, 0) - 1440 x 1080</td>
+ <td class="thin_bord">(240, 780) - 1440 x 300</td>
+ </tr>
+</table>
+<p class="Code_Header_2"><a name="batchflags">bvbltparams.batchflags</a></p>
+<p class="code_block">unsigned long batchflags;</p>
+<p><span class="inline_code">batchflags</span> are used by the client as a hint to indicate to the implementation which
+parameters are changing between successive BLTs of a batch. The flags may be used when the
+<span class="inline_code"><a href="#flags">bvbltparams.flags</a></span> has <span class="inline_code">
+<a href="#BVFLAG_BATCH_CONTINUE">BVFLAG_BATCH_CONTINUE</a></span> or <span class="inline_code">
+<a href="#BVFLAG_BATCH_END">BVFLAG_BATCH_END</a></span> set.</p>
+<table style="" class="indent">
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_OP">BVBATCH_OP</a></span></td>
+ <td>indicates that the operation type (<span class="inline_code"><a href="#BVFLAG_ROP">BVFLAG_ROP</a></span>,
+ <span class="inline_code"><a href="#BVFLAG_BLEND">BVFLAG_BLEND</a></span>, <span class="inline_code">
+ <a href="#BVFLAG_FILTER">BVFLAG_FILTER</a></span>, etc.) has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_KEY">BVBATCH_KEY</a></span></td>
+ <td>indicates that the <span class="inline_code"><a href="#colorkey">bvbltparams.colorkey</a></span> or the color
+ key mode (<span class="inline_code"><a href="#BVFLAG_KEY_SRC">BVFLAG_KEY_SRC</a></span>/<span class="inline_code"><a href="#BVFLAG_KEY_DST">BVFLAG_KEY_DST</a></span>)
+ has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_MISCFLAGS">BVBATCH_MISCFLAGS</a></span></td>
+ <td>indicates that <span class="inline_code"><a href="#flags">bvbltparams.flags</a></span> other than the operation,
+ color key, or clip flag have changes.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_ALPHA">BVBATCH_ALPHA</a></span></td>
+ <td>indicates that <span class="inline_code"><a href="#globalalpha">bvbltparams.globalalpha</a></span> or global
+ alpha type has changed.</td>
+ </tr>
+ <tr>
+ <td><a name="BVBATCH_DITHER" class="inline_code">BVBATCH_DITHER</a></td>
+ <td>indicates that <span class="inline_code"><a href="#dithermode">bvbltparams.dithermode</a></span> has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_SCALE">BVBATCH_SCALE</a></span></td>
+ <td>indicates that <span class="inline_code"><a href="#scalemode">bvbltparams.scalemode</a></span> has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_DST">BVBATCH_DST</a></span></td>
+ <td>indicates that the destination surface (<span class="inline_code"><a href="#dstdesc">bvbltparams.dstdesc</a></span>,
+ <span class="inline_code"><a href="#dstgeom">bvbltparams.dstgeom</a></span> ,or <span class="inline_code">
+ <a href="#dstrect">bvbltparams.dstrect</a></span>) has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_SRC1">BVBATCH_SRC1</a></span> </td>
+ <td>indicates that the source 1 surface (<span class="inline_code"><a href="#src1.desc">bvbltparams.src1.desc</a></span>
+ or <span class="inline_code"><a href="#src1.tileparams">bvbltparams.src1.tileparams</a></span>, or
+ <span class="inline_code"><a href="#src1geom">bvbltparams.src1geom</a></span>) has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_SRC2">BVBATCH_SRC2</a></span> </td>
+ <td>indicates that the source 2 surface (<span class="inline_code"><a href="#src2.desc">bvbltparams.src2.desc</a></span>
+ or <span class="inline_code"><a href="#src2.tileparams">bvbltparams.src2.tileparams</a></span>, or
+ <span class="inline_code"><a href="#src2geom">bvbltparams.src2geom</a></span>) has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_MASK">BVBATCH_MASK</a></span> </td>
+ <td>indicates that the mask surface (<span class="inline_code"><a href="#mask.desc">bvbltparams.mask.desc</a></span>
+ or <span class="inline_code"><a href="#mask.tileparams">bvbltparams.mask.tileparams</a></span>, or
+ <span class="inline_code"><a href="#maskgeom">bvbltparams.maskgeom</a></span>) has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_DSTRECT_ORIGIN">BVBATCH_DSTRECT_ORIGIN</a></span></td>
+ <td>indicates that <span class="inline_code"><a href="#dstrect">bvbltparams.dstrect.left</a></span> or
+ <span class="inline_code"><a href="#dstrect">top</a></span> has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_DSTRECT_SIZE">BVBATCH_DSTRECT_SIZE</a></span></td>
+ <td>indicates that the <span class="inline_code"><a href="#dstrect">bvbltparams.dstrect.width</a></span> or
+ <a href="#dstrect">height</a> has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_SRC1RECT_ORIGIN">BVBATCH_SRC1RECT_ORIGIN</a></span></td>
+ <td>indicates that <span class="inline_code"><a href="#src1rect">bvbltparams.src1rect.left</a></span> or
+ <span class="inline_code"><a href="#dstrect">top</a></span> has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_SRC1RECT_SIZE">BVBATCH_SRC1RECT_SIZE</a></span></td>
+ <td>indicates that the <span class="inline_code"><a href="#src1rect">bvbltparams.src1rect.width</a></span> or
+ <a href="#src1rect">height</a> has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_SRC2RECT_ORIGIN">BVBATCH_SRC2RECT_ORIGIN</a></span></td>
+ <td>indicates that <span class="inline_code"><a href="#src2rect">bvbltparams.src2rect.left</a></span> or
+ <span class="inline_code"><a href="#src2rect">top</a></span> has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_SRC2RECT_SIZE">BVBATCH_SRC2RECT_SIZE</a></span></td>
+ <td>indicates that the <span class="inline_code"><a href="#src2rect">bvbltparams.src2rect.width</a></span> or
+ <a href="#src2rect">height</a> has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_MASKRECT_ORIGIN">BVBATCH_MASKRECT_ORIGIN</a></span></td>
+ <td>indicates that <span class="inline_code"><a href="#maskrect">bvbltparams.maskrect.left</a></span> or
+ <span class="inline_code"><a href="#maskrect">top</a></span> has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_MASKRECT_SIZE">BVBATCH_MASKRECT_SIZE</a></span></td>
+ <td>indicates that the <span class="inline_code"><a href="#maskrect">bvbltparams.maskrect.width</a></span> or
+ <a href="#maskrect">height</a> has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_CLIPRECT_ORIGIN">BVBATCH_CLIPRECT_ORIGIN</a></span></td>
+ <td>indicates that <span class="inline_code"><a href="#cliprect">bvbltparams.cliprect.left</a></span> or
+ <span class="inline_code"><a href="#cliprect">top</a></span> has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_CLIPRECT_SIZE">BVBATCH_CLIPRECT_SIZE</a></span></td>
+ <td>indicates that the <span class="inline_code"><a href="#cliprect">bvbltparams.cliprect.width</a></span> or
+ <a href="#cliprect">height</a> has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_TILE_SRC1">BVBATCH_TILE_SRC1</a></span></td>
+ <td>indicates that the <span class="inline_code"><a href="#src1.tileparams">bvbltparams.src1.tileparams</a></span>
+ has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_TILE_SRC2">BVBATCH_TILE_SRC2</a></span></td>
+ <td>indicates that the <span class="inline_code"><a href="#src2.tileparams">bvbltparams.src2.tileparams</a></span>
+ has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_TILE_MASK">BVBATCH_TILE_MASK</a></span></td>
+ <td>indicates that the <span class="inline_code"><a href="#mask.tileparams">bvbltparams.mask.tileparams</a></span>
+ has changed.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVBATCH_ENDNOP">BVBATCH_ENDNOP</a></span></td>
+ <td>is a special flag used with <span class="inline_code"><a href="#batch_end">BVFLAG_BATCH_END</a></span>, for
+ clients that do not have information that a batch is ending until after the last BLT has been issued. When
+ this flag is set, no BLT is done, but the batch is ended.</td>
+ </tr>
+</table>
+<p class="note">NOTE: These flags are hints, and may be used or not by a BLTsville implementation. So if
+<span class="inline_code"><a href="#bvbltparams">bvbltparams</a></span> members are changed between BLTs in a batch, but
+the <span class="inline_code">bvbltparams.batchflags</span> member is not correctly updated, the resulting behavior on different
+implementations will not be consistent.</p>
+<p class="Code_Header_2"><a name="batch">bvbltparams.batch</a></p>
+<p class="code_block"><a href="#bvbatch">struct bvbatch</a> *batch;</p>
+<p>This member is used as a batch handle, so that multiple batches can be under construction at the same time.</p>
+<p class="Code_Header_2"><a name="callbackfn">bvbltparams.callbackfn</a></p>
+<p class="code_block">void (*callbackfn)(<a href="#bvcallbackerror">struct bvcallbackerror</a> *err, unsigned long
+<a href="#callbackdata">callbackdata</a>);</p>
+<p>This member is a pointer to a client-supplied function which is called by the implementation when
+<span class="inline_code"><a href="#BVFLAG_ASYNC">BVFLAG_ASYNC</a></span> is set and the BLT is complete. If this
+member is NULL, no callback is performed. When there is no error, the <span class="inline_code">err</span>
+parameter will be set to 0;</p>
+<p class="note">NOTE: This function <span class="underline">can be called</span> before the
+<span class="inline_code"><a href="#bv_blt">bv_blt()</a></span> call has returned.</p>
+<p class="Code_Header_2"><a name="callbackdata">bvbltparams.callbackdata</a></p>
+<p class="code_block">unsigned long callbackdata;</p>
+<p>This member is used as the parameter passed back by the <span class="inline_code"><a href="#callbackfn">bvbltparams.callbackfn</a></span>.
+This can be anything from an identifying index to a pointer used by the client.</p>
+<p class="Code_Header_2">bvbltparams.<a name="src2auxdstrect">src2</a>/<a name="maskauxdstrect">maskauxdstrect</a></p>
+<p class="code_block">struct bvrect src2auxdstrect;<br />
+struct bvrect maskauxdstrect;</p>
+<p>These two members are used only when the associated <span class="inline_code"><a href="#BVFLAG_SRC2_AUXDSTRECT">
+BVFLAG_SRC2</a></span>/<span class="inline_code"><a href="#BVFLAG_MASK_AUXDSTRECT">MASK_AUXDSTRECT</a></span> flags are
+set. They are only necessary (and should only be used) in the case where scaling of the inputs differs and the
+entire source images are not being used. <span class="inline_code"><a href="#dstrect">bvbltparams.dstrect</a></span> is always
+used to specify the destination of source 1 image. When the associated flags are set, these two members are used
+to specify the destination of the source 2 and mask images, instead of <span class="inline_code"><a href="#dstrect">
+bvbltparams.dstrect</a></span>.</p>
+<p>These flags must be used with the <span class="inline_code"><a href="#BVFLAG_CLIP">BVFLAG_CLIP</a></span> flag.
+And if the resulting clipped destination does not include all enabled destination rectangles, the results are undefined.</p>
+<div class="example"><strong>Example:</strong> We have two images that we want to merge and view on an 854x480 LCD panel. One
+image is a small background image with 16:9 (64x36) aspect ratio that we want to stretch to fill the screen.
+The other is a standard definition 720x480 (4:3 aspect ratio) image with transparency we want to blend on top of our
+background.<br />
+<table align="center">
+ <tr>
+ <td>
+ <table>
+ <tr>
+ <td class="ctr"><img alt="" src="concrete-64x36.png" width="64" height="36" /></td>
+ </tr>
+ <tr>
+ <td class="ctr">(shown actual size)</td>
+ </tr>
+ </table>
+ </td>
+ <td>
+ <table class="ctr">
+ <tr>
+ <td><img alt="" src="clock-720x480_4x3-fauxtrans.jpg" width="360" height="240" /></td>
+ </tr>
+ <tr>
+ <td class="ctr">(shown 1/2x; not adjusted for aspect ratio)</td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+</table>
+We want to blend the second image onto the center of the first, scaling both, so that it looks like this:<br />
+<table align="center">
+ <tr>
+ <td><img alt="" src="blend-854x480.jpg" width="427" height="240" /></td>
+ </tr>
+ <tr>
+ <td class="ctr">(shown 1/2x)</td>
+ </tr>
+</table>
+The screen is effectively a 16:9 aspect ratio (we can ignore the fraction of a pixel here), which matches our
+background image. So the background image just needs to be scaled from 64x36 to 854x480.<br />
+<br />
+ However, since the second image has a 4:3 aspect ratio, it will not cover the entire background image if we want to
+ maintain its aspect ratio. Our second image is not as wide as our 16:9 image, which means it's height will match
+ the screen height, but the width will be smaller. Since the screen is 480 lines (pixels) high, to maintain our 4:3
+ aspect ratio, our second image will need to be 640 pixels wide (4 * 480 / 3). So it will need to be scaled from
+ 720x480 to 640x480.<br />
+<br />
+As we mentioned, we would like to center the 640 pixel image on our 854 pixel wide screen. That means the left edge
+of the image will be at pixel 107 ( (854 - 640) / 2 ). So the leftmost 107 columns of pixels will just be a copy
+of the left portion of the background image. Likewise, the rightmost 107 columns will be a copy of the right
+portion of the background image. Only the middle section should be blended.<br />
+<table align="center">
+ <tr>
+ <td><img alt="" src="blend-854x480-threeblts.jpg" width="427" height="240" /></td>
+ </tr>
+ <tr>
+ <td class="ctr">(shown 1/2x)</td>
+ </tr>
+</table>
+ The side two BLTs are quite easy with BLTsville, by using the clipping rectangle:<br />
+<br />
+<table class="indent"><tr><td>
+<span class="inline_code">bvbltparams.flags = BVFLAG_ROP | BVFLAG_CLIP;<br />
+bvbltparams.op.rop = 0xCCCC;<br />
+<br />
+bvbltparams.src1.desc = bkgnddesc;<br />
+bvbltparams.src1geom = bkgndgeom;<br />
+bvbltparams.src1rect.left = 0;<br />
+bvbltparams.src1rect.top = 0;<br />
+bvbltparams.src1width = 64;<br />
+bvbltparams.src1height = 36;<br />
+<br />
+bvbltparams.dstdesc = screendesc;<br />
+bvbltparams.dstgeom = screengeom;<br />
+bvbltparams.dstrect.left = 0;<br />
+bvbltparams.dstrect.top = 0;<br />
+bvbltparams.dstrect.width = 854;<br />
+bvbltparams.dstrect.height = 480;<br />
+<br />
+bvbltparams.cliprect.left = 0;<br />
+bvbltparams.cliprect.top = 0;<br />
+bvbltparams.cliprect.width = 107;<br />
+bvbltparams.cliprect.height = 480;<br />
+bv_blt(&bvbltparams);<br />
+<br />
+bvbltparams.cliprect.left += 640;<br />
+bv_blt(&bvbltparams);</span></td></tr></table>
+<br />
+ However, if we try the same approach with the middle BLT, we run into problems:<br />
+<br />
+<table class="indent"><tr><td>
+<span class="inline_code">bvbltparams.flags = BVFLAG_BLEND | BVFLAG_CLIP;<br />
+bvbltparams.op.blend = BVBLEND_SRC1OVER;<br />
+<br />
+bvbltparams.src1.desc = foregnddesc;<br />
+bvbltparams.src1geom = foregndgeom;<br />
+bvbltparams.src1rect.left = 0;<br />
+bvbltparams.src1rect.top = 0;<br />
+bvbltparams.src1rect.width = 720;<br />
+bvbltparams.src1rect.height = 480;<br />
+<br />
+bvbltparams.src2.desc = bkgnddesc;<br />
+bvbltparams.src2geom = bkgndgeom;<br />
+bvbltparams.src2rect.left = 0;<br />
+bvbltparams.src2rect.top = 0;<br />
+bvbltparams.src2width = 64;<br />
+bvbltparams.src2height = 36;<br />
+<br />
+bvbltparams.cliprect.left = 107;<br />
+bvbltparams.cliprect.top = 0;<br />
+bvbltparams.cliprect.width = 640;<br />
+bvbltparams.cliprect.height = 480;<br />
+bv_blt(&bvbltparams);</span></td></tr></table>
+<table align="center">
+ <tr>
+ <td><img alt="" src="blend-854x480-bad.jpg" width="427" height="240" /></td>
+ </tr>
+ <tr>
+ <td class="ctr">(shown 1/2x)</td>
+ </tr>
+</table>
+ The result is that the foreground image is stretched horizontally. That's because the scaling factor is
+ derived from the source (1) rectangle and the destination rectangle, which is the full width of the screen.
+ Since we were also scaling the background, we set the destination rectangle to cover the screen, as we did in the
+ previous two BLTs.<br />
+ <br />
+ The edges of our foreground image are also cropped, since we were only modifying the middle of the screen.<br />
+ <br />
+ What if we change the destination rectangle?<br />
+ <br />
+<table class="indent"><tr><td>
+<span class="inline_code">bvbltparams.dstrect.left = 107;<br />
+bvbltparams.dstrect.top = 0;<br />
+bvbltparams.dstrect.width = 640;<br />
+bvbltparams.dstrect.height = 480;<br />
+<br />
+bv_blt(&bvbltparams);</span></td></tr></table>
+<table align="center">
+ <tr>
+ <td><img alt="" src="blend-854x480-bad2.jpg" width="427" height="240" /></td>
+ </tr>
+ <tr>
+ <td class="ctr">(shown 1/2x)</td>
+ </tr>
+</table>
+ Here we get the proper scaling of the foreground image, but the background image is scaled improperly.<br />
+ <br />
+ What if we adjust the source rectangles?
+For our purposes, we want all of the foreground image, but we only need the middle of the background image. So
+ we can manually specify the middle of the background image by modifying the source 2 rectangle:<br />
+ <br />
+<table class="indent"><tr><td>
+<span class="inline_code">bvbltparams.src2rect.left = 107 * 64 / 854;<br />
+bvbltparams.src2rect.width = 640 * 64 / 854;</span></td></tr></table><br />
+Nice, but what are those values?<br />
+<br />
+<table class="indent"><tr><td>
+107 * 1280 / 854 = 8.0187...<br />
+640 * 1280 / 854 = 47.9625...<br />
+</td></tr></table>
+<br />
+ In BLTsville, all rectangle parameters are expressed in integers (this also allows BLTsville to be used in the
+ kernels where floating point variables are not allowed). The clipping rectangle then handles introducing the
+ necessary source pixel subdivision (by translating the clipping rectangle back to the source rectangle in the
+ implementation). So what happens if we actually do use these values as integers?<br />
+<br />
+<table class="indent"><tr><td>
+<span class="inline_code">bvbltparams.src2rect.left = 8;<br />
+bvbltparams.src2rect.top = 0;<br />
+bvbltparams.src2rect.width = 47;<br />
+bvbltparams.src2height = 36;<br />
+<br />
+bv_blt(&bvbltparams);</span></td></tr></table>
+<br />
+ And this is what we get:<br />
+<table align="center">
+ <tr>
+ <td><img alt="" src="blend-854x480-roundingerror.jpg" width="427" height="240" /></td>
+ </tr>
+ <tr>
+ <td class="ctr">(shown 1/2x)</td>
+ </tr>
+</table>
+ Closer, but not quite. Rounding the values above to integers still results in visible errors at the boundaries
+ between the middle and the side BLTs (the one on the right is a bit more visible at this reduced size, but if you
+ view the full image, you'll see the left one as well), because the left edge and scaling (and right edge as a
+ result) don't match the alignment and scaling done for the BLTs on the side. <p class="note">NOTE: This artifact is not always obvious in still images.
+ The images here were chosen to make the artifacts obvious in this documentation. But even if the static images
+ appear correct, movement of the images (e.g. moving the foreground image across the background image) or changes in
+ the blending (e.g. fading the foreground image out and finally removing it), will show these less obvious
+ discrepancies.</p>This is actually what the
+ clipping rectangle is for. It's meant to allow us to always specify the source and destination rectangles the
+ same, but move the clipping window around on the destination to get just the pixels we want. That way the
+ scaling and alignment area always the same. Unfortunately, for this special case, we really need a way to
+ specify different scaling factors for the different inputs. The src2auxdstrect (and maskauxdstrect, when
+ needed) have been added to provide this capability.<br />
+ <br />
+ Here is how this set of BLTs can be done:<br />
+<br />
+<table class="indent"><tr><td>
+<span class="inline_code">bvbltparams.flags = BVFLAG_ROP | BVFLAG_CLIP;<br />
+bvbltparams.op.rop = 0xCCCC;<br />
+<br />
+bvbltparams.src1.desc = bkgnddesc;<br />
+bvbltparams.src1geom = bkgndgeom;<br />
+bvbltparams.src1rect.left = 0;<br />
+bvbltparams.src1rect.top = 0;<br />
+bvbltparams.src1width = 64;<br />
+bvbltparams.src1height = 36;<br />
+<br />
+bvbltparams.dstdesc = screendesc;<br />
+bvbltparams.dstgeom = screengeom;<br />
+bvbltparams.dstrect.left = 0;<br />
+bvbltparams.dstrect.top = 0;<br />
+bvbltparams.dstrect.width = 854;<br />
+bvbltparams.dstrect.height = 480;<br />
+<br />
+bvbltparams.cliprect.left = 0;<br />
+bvbltparams.cliprect.top = 0;<br />
+bvbltparams.cliprect.width = 107;<br />
+bvbltparams.cliprect.height = 480;<br />
+bv_blt(&bvbltparams);<br />
+<br />
+bvbltparams.cliprect.left += 640;<br />
+bv_blt(&bvbltparams);<br />
+<br />
+bvbltparams.flags = BVFLAG_BLEND | BVFLAG_CLIP | BVFLAG_SRC2_AUXDSTRECT;<br />
+bvbltparams.op.blend = BVBLEND_SRC1OVER;<br />
+<br />
+bvbltparams.src1.desc = foregnddesc;<br />
+bvbltparams.src1geom = foregndgeom;<br />
+bvbltparams.src1rect.left = 0;<br />
+bvbltparams.src1rect.top = 0;<br />
+bvbltparams.src1rect.width = 720;<br />
+bvbltparams.src1rect.height = 480;<br />
+<br />
+bvbltparams.dstrect.left = 107;<br />
+bvbltparams.dstrect.top = 0;<br />
+bvbltparams.dstrect.width = 640;<br />
+bvbltparams.dstrect.height = 480;<br />
+<br />
+bvbltparams.src2.desc = bkgnddesc;<br />
+bvbltparams.src2geom = bkgndgeom;<br />
+bvbltparams.src2rect.left = 0;<br />
+bvbltparams.src2rect.top = 0;<br />
+bvbltparams.src2width = 64;<br />
+bvbltparams.src2height = 36;<br />
+<br />
+bvbltparams.src2auxdstrect.left = 0;<br />
+bvbltparams.src2auxdstrect.top = 0;<br />
+bvbltparams.src2auxdstrect.width = 854;<br />
+bvbltparams.src2auxdstrect.height = 480;<br />
+<br />
+bvbltparams.cliprect.left = 107;<br />
+bvbltparams.cliprect.top = 0;<br />
+bvbltparams.cliprect.width = 640;<br />
+bvbltparams.cliprect.height = 480;<br />
+bv_blt(&bvbltparams);</span></td></tr></table>
+<br />
+Using this approach, we get the desired output:<br />
+<table align="center">
+ <tr>
+ <td><img alt="" src="blend-854x480.jpg" width="427" height="240" /></td>
+ </tr>
+ <tr>
+ <td class="ctr">(shown 1/2x)</td>
+ </tr>
+</table>
+ It may also be clear that in that last BLT, the clip rectangle isn't really necessary. This is good, because
+ it frees up the clipping rectangle to be used to further subdivide the image if necessary (e.g. if partially
+ occluded).<br />
+</div>
+<br />
+<hr />
+<p class="Code_Header"><a name="bvrect">bvrect</a></p>
+<p class="small_code_block">struct bvrect {<br />
+ int <a href="#bvrect.left">left</a>;<br />
+ int <a href="#bvrect.top">top</a>;<br />
+ unsigned int <a href="#bvrect.width">width</a>;<br />
+ unsigned int <a href="#bvrect.height">height</a>;<br />
+};</p>
+<p class="Code_Header_2"><a name="bvrect.left">bvrect.left</a></p>
+<p class="code_block">int left;</p>
+<p>This member indicates the left edge of the rectangle, measured in pixels from the left edge of the surface. Note
+that this value <span class="underline">can</span> be negative, indicating that the rectangle begins before the left edge
+of the surface. However, this is only allowed when a rectangle is clipped to the surface. If, after clipping,
+the left edge of the rectangle is still negative, this is an error.</p>
+<p class="Code_Header_2"><a name="bvrect.top">bvrect.top</a></p>
+<p class="code_block">int top;</p>
+<p>This member indicates the top edge of the rectangle, measured in lines of
+<a href="#bfbuffdesc.virtstride" class="inline_code">bvbuffdesc.virtstride</a> bytes from the top edge of the surface.
+Note that this value <span class="underline">can</span> be negative, indicating that the rectangle begins before the top
+edge of the surface. However, this is only allowed when a rectangle is clipped to the surface. If, after clipping,
+the top edge of the rectangle is still negative, this is an error.</p>
+<p class="Code_Header_2"><a name="bvrect.width">bvrect.width</a></p>
+<p class="code_block">unsigned int width;</p>
+<p>This member indicates the width of the rectangle, measured in pixels. Note that this value
+<span class="underline">cannot</span> be negative. (Horizontal flipping is indicated using the
+<span class="inline_code"><a href="#BVFLAG_HORZ_FLIP">BVFLAG_HORZ_FLIP_*</a></span> flags.) The value of this member
+may exceed the width of the associated surface. However, this is only allowed when a rectangle is clipped to the surface.
+If, after clipping, the right edge of the rectangle still exceeds the width of the surface, this is an error.</p>
+<p class="Code_Header_2"><a name="bvrect.height">bvrect.height</a></p>
+<p class="code_block">unsigned int height;</p>
+<p>This member indicates the height of the rectangle, measured in lines of <span class="inline_code">
+<a href="#bvbuffdesc.virtstride">bvbuffdesc.virtstride</a></span> bytes. Note that this value
+<span class="underline">cannot</span> be negative. (Vertical flipping is indicated using the
+<span class="inline_code"><a href="#BVFLAG_VERT_FLIP">BVFLAG_VERT_FLIP_*</a></span> flags.) The value of this member
+may exceed the width of the associated surface. However, this is only allowed when a rectangle is clipped to the surface.
+If, after clipping, the right edge of the rectangle still exceeds the height of the surface, this is an error.</p>
+<hr />
+<a name="bvcopparams" class="Code_Header">bvcopparams</a>
+<p><span class="inline_code">bvcopparams</span> is used to define the cache operation to be performed by
+<span class="inline_code"><a href="#bv_cache">bv_cache()</a></span>.</p>
+<p class="small_code_block">struct bvcopparams {<br />
+ unsigned int <a href="#bvcopparams.structsize">structsize</a>;<br />
+ <a href="#bvbuffdesc">struct bvbuffdesc</a> *<a href="#bvcopparams.desc">desc</a>;<br />
+ <a href="#bvsurfgeom">struct bvsurfgeom</a> *<a href="#bvcopparams.geom">geom</a>;<br />
+ <a href="#bvrect">struct bvrect</a> *<a href="#bvcopparams.rect">rect</a>;<br />
+ enum bvcacheop <a href="#bvcopparams.cacheop">cacheop</a>;<br />
+};</p>
+<a name="bvcopparams.structsize" class="Code_Header_2">bvcopparams.structsize</a>
+<p><span class="code_block">unsigned long structsize; /* input */</span></p>
+<p>This member is used for compatibility between BLTsville versions. (See <span class="inline_code">
+<a href="#bvbltparams.structsize">bvbltparams.structsize</a></span> for an explanation.) </p>
+<p class="Code_Header_2"><a name="bvcopparams.desc">bvcopparams.desc</a></p>
+<p class="code_block"><a href="#bvbuffdesc">struct bvbuffdesc</a> *desc;</p>
+<p>This member points to the <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> of the surface for which
+the cache is being manipulated. This buffer should have been mapped with a call to <span class="inline_code">
+<a href="#bv_map">bv_map()</a></span>.</p>
+<p class="note">NOTE: Implementations may choose to dynamically map the surface as with <span class="inline_code">
+<a href="#bv_blt">bv_blt()</a></span>, however in many systems, this will not function properly due to dynamic paging which
+can occur when a surface is not locked.</p>
+<p><span class="Code_Header_2"><a name="bvcopparams.geom">bvcopparams.geom</a></span></p>
+<p class="code_block"><a href="#bvsurfgeom">struct bvsurfgeom</a> *geom;</p>
+<p>This member points to the <span class="inline_code"><a href="#bvsurfgeom">bvsurfgeom</a></span> of the surface for which
+the cache is being manipulated.</p>
+<p><span class="Code_Header_2"><a name="bvcopparams.rect">bvcopparams.rect</a></span></p>
+<p class="code_block"><a href="#bvrect">struct bvrect</a> *rect;</p>
+<p>This member points to the <span class="inline_code"><a href="bvrect">bvrect</a></span> describing the rectangle of the
+surface which is being manipulated.</p>
+<p><span class="Code_Header_2"><a name="bvcopparams.cacheop">bvcopparams.cacheop</a></span></p>
+<p class="code_block">enum bvcacheop cacheop;</p>
+<p>This member specifies the cache operation to be performed. It is an enumeration from the following list:</p>
+<table style="" class="indent">
+ <tr>
+ <td><span class="inline_code"><a name="BVCACHE_BIDIRECTIONAL">BVCACHE_BIDIRECTIONAL</a></span></td>
+ <td>(This usually performs a cache flush operation.)</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVCACHE_CPU_TO_DEVICE">BVCACHE_CPU_TO_DEVICE</a></span></td>
+ <td>Performs the appropriate cache operation to ensure data can be transferred correctly when it was written with
+ the CPU, but will be read by the 2-D device. (This is usually a cache clean operation.)</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVCACHE_CPU_FROM_DEVICE">BVCACHE_CPU_FROM_DEVICE</a></span></td>
+ <td>Performs the appropriate cache operation to ensure data can be transferred correctly when it was written by
+ the 2-D device, but will be read by the CPU. (This is usually a cache invalidate operation.)</td>
+ </tr>
+</table>
+<br />
+<hr />
+<p class="Code_Header"><a name="bvbuffdesc">bvbuffdesc</a></p>
+<p>This structure is used in conjunction with a <span class="inline_code"><a href="#bvsurfgeom">bvsurfgeom</a></span> structure
+to specify the characteristics of a graphic surface. This structure specifies the memory buffer itself.</p>
+<p class="small_code_block">struct bvbuffdesc {<br />
+ unsigned int <a href="#bvbuffdesc.structsize">structsize</a>;<br />
+ void *<a href="#bvbuffdesc.virtaddr">virtaddr</a>;<br />
+ unsigned long <a href="#bvbuffdesc.length">length</a>;<br />
+ <a href="#bvbuffmap">struct bvbuffmap</a> *<a href="#bvbuffdesc.map">map</a>;<br />
+ enum bvauxtype <a href="#bvbuffdesc.auxtype">auxtype</a>;<br />
+ void *<a href="#bvbuffdesc.auxptr">auxptr</a>;<br />
+};</p>
+<p class="Code_Header_2"><a name="bvbuffdesc.structsize">bvbuffdesc.structsize</a></p>
+<p class="code_block">unsigned int structsize;</p>
+<p>This member is used for compatibility between BLTsville versions. (See <span class="inline_code">
+<a href="#bvbltparams.structsize">bvbltparams.structsize</a></span> for an explanation.) </p>
+<p class="Code_Header_2"><a name="bvbuffdesc.virtaddr">bvbuffdesc.virtaddr</a></p>
+<p class="code_block">void *virtaddr;</p>
+<p>This member is used to indicate the CPU virtual address of the start of the buffer. This value must be provided
+unless the <span class="inline_code"><a href="#bvbuffdesc.auxtype">auxtype</a></span>/<span class="inline_code"><a href="#bvbuffdesc.auxptr">auxptr</a></span>
+members below are used. At that time, this member is optional, and the <span class="inline_code">
+<a href="#auxptr">auxptr</a></span> usually has higher priority than this member.</p>
+<p class="imponly"><strong>Implementations Only</strong><br />
+<br />
+Note that this is always the beginning of the buffer. This means that if the <span class="inline_code">
+<a href="#bvsurfgeom.virtaddr">bvsurfgeom.virtstride</a></span> is negative, or the <a href="#bvsurfgeom.orientation">bvsurfgeom.orientation</a>
+does not normalize to 0º (i.e. <span class="inline_code">orientation % 360 != 0</span>), implementations may need
+to use a modified version of <span class="inline_code">virtaddr</span> internally to operate correctly.</p>
+<p class="Code_Header_2"><a name="bvbuffdesc.length">bvbuffdesc.length</a></p>
+<p class="code_block">unsigned long length;</p>
+<p>This member specifies the length of the buffer in bytes.</p>
+<p class="note">NOTE: When used with a <span class="inline_code"><a href="#bvsurfgeom">bvsurfgeom</a></span> structure,
+<span class="inline_code">length</span> should be greater than or equal to <span class="inline_code">
+<a href="#bvsurfgeom.height">bvsurfgeom.height</a> * <a href="#bvsurfgeom.virtstride">bvsurfgeom.virtstride</a></span>.</p>
+<p class="Code_Header_2"><a name="bvbuffdesc.map">bvbuffdesc.map</a></p>
+<p class="code_block">struct bvbuffmap *map;</p>
+<p>This member is used by the implementations and should <span class="underline"><strong>NEVER</strong></span> be manipulated
+by the client. When the <span class="inline_code">bvbuffdesc</span> structure is created, this member should be set
+to 0, indicating that no implementations have mapped the buffer. After a buffer has been mapped using a call to
+<span class="inline_code"><a href="#bv_map">bv_map()</a></span>, this member should be left as-is by clients. (The
+implementation will set this back to 0 before returning from <span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span>.)</p>
+<p class="imponly"><strong>Implementations Only</strong><br />
+<br />
+This member points to a linked list of <span class="inline_code"><a href="#bvbuffmap">bvbuffmap</a></span> structures associated
+with the buffer. Each <span class="inline_code"><a href="#bvbuffmap">bvbuffmap</a></span> is added to the list as
+the buffer is mapped by a given implementation. This may be done with an explicit call to
+<span class="inline_code"><a href="#bv_map">bv_map()</a></span>, or implicitly with a call to <span class="inline_code">
+<a href="#bv_blt">bv_blt()</a></span>, after a call to <span class="inline_code"><a href="#bv_map">bv_map()</a></span> from
+a different implementation.<br />
+<br />
+Implementations should not assume that the first entry in the list is their <span class="inline_code">
+<a href="#bvbuffmap">bvbuffmap</a></span>. Instead, implementations should compare the <span class="inline_code">
+<a href="#bv_unmap">bv_unmap()</a></span> pointer in the structure to their own function address.</p>
+<p class="Code_Header_2"><a name="bvbuffdesc.auxtype">bvbuffdesc.auxtype</a></p>
+<p class="code_block">enum bvauxtype auxtype;</p>
+<p>This member is used to identify the type of additional information about the buffer provided by
+<span class="inline_code"><a href="#bvbuffdesc.auxptr">auxptr</a></span>. Currently no values are defined for the
+user mode interface, so it should be initialized to 0 or <span class="inline_code">BVAT_NONE</span>. See the
+<a href="#Kernel_Mode_Interface">Kernel Mode Interface</a> for details on the values defined for the kernel mode interface.</p>
+<p class="Code_Header_2"><a name="bvbuffdesc.auxptr">bvbuffdesc.auxptr</a></p>
+<p class="code_block">void *auxptr;</p>
+<p>This member is used to point to additional information about the buffer. The type of this pointer is determined
+by the <span class="inline_code"><a href="#auxtype">auxtype</a></span> value. Currently there are no types defined
+for the user mode interface, so this member is ignored. See the <a href="#Kernel_Mode_Interface">Kernel Mode Interface</a>
+for details on the types defined for the kernel mode interface. </p>
+<hr /><br />
+<table style="" class="imponly">
+ <tr>
+ <td>
+ <p><strong>Implementations Only</strong></p>
+ <p class="Code_Header"><a name="bvbuffmap">bvbuffmap</a></p>
+ <p>This structure is used from the bvbuffdesc.map member to allow implementations to associate their own data with
+ a buffer.</p>
+ <p class="small_code_block"><span class="small_code_block_in_table">struct bvbuffmap {<br />
+ unsigned int <a href="#bvbuffmap.structsize">structsize</a>;<br />
+ BVFN_UNMAP <a href="#bvbuffmap.bv_unmap">bv_unmap</a>;<br />
+ unsigned long <a href="#bvbuffmap.handle">handle</a>;<br />
+ struct bvbuffmap *<a href="#bvbuffmap.nextmap">nextmap</a>;<br />
+ };</span></p>
+ <p class="Code_Header_2"><a name="bvbuffmap.structsize">bvbuffmap.structsize</a></p>
+ <p class="code_block">unsigned int structsize;</p>
+ <p>This member is used for compatibility between BLTsville versions. (See <span class="inline_code">
+ <a href="#bvbltparams.structsize">bvbltparams.structsize</a></span> for an explanation.) </p>
+ <p class="Code_Header_2"><a name="bvbuffmap.bv_unmap">bvbuffmap.bv_unmap</a></p>
+ <p class="code_block">BVFN_UNMAP bv_unmap;</p>
+ <p>This member holds the pointer to the <span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span> function
+ of the implementation associated with the <span class="inline_code">bvbuffmap</span> structure. It serves
+ to allow implementations to identify their <span class="inline_code">bvbuffmap</span> structure in the linked list,
+ as well as to allow implementations to call each other's <span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span>
+ calls from their own.</p>
+ <p class="Code_Header_2"><a name="bvbuffmap.handle">bvbuffmap.handle</a></p>
+ <p class="code_block">unsigned long handle;</p>
+ <p>This member is used to hold an implementation-specific piece of data.</p>
+ <p class="Code_Header_2"><a name="bvbuffmap.nextmap">bvbuffmap.nextmap</a></p>
+ <p class="code_block">struct bvbuffmap *nextmap;</p>
+ <p>This member holds a pointer to the next bvbuffmap structure in the linked list. If this member is 0, there
+ are no more entries in the list.<br />
+ <br />
+ <span class="note">NOTE: The Linux/Android Kernel Mode Interface differs slightly from this structure.
+ Refer to the <a href="#Kernel_Mode_Interface">Kernel Mode Interface</a> section for details.</span></p>
+ </td>
+ </tr>
+</table>
+<br />
+<hr />
+<p class="Code_Header"><a name="bvsurfgeom">bvsurfgeom</a></p>
+<p>This structure is used in conjunction with a <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> structure
+to specify the characteristics of a graphic surface. This structure specifies the surface geometric characteristics.</p>
+<p class="note">NOTE: This structure was separated from <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span>
+to afford much flexibility to the client. Using the same <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span>
+structure with different <span class="inline_code">bvsurfgeom</span> structures or using the same
+<span class="inline_code">bvsurfgeom</span> structure with different <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span>
+structures may be of benefit. See the <a href="#bvsurfgeom_examples">examples</a> at the bottom of this section.</p>
+<p class="small_code_block">struct bvcopparams {<br />
+ unsigned int <a href="#bvsurfgeom.structsize">structsize</a>;<br />
+ <a href="http://graphics.github.com/ocd/">enum ocdformat</a> format;<br />
+ unsigned int width;<br />
+ unsigned int height;<br />
+ int orientation;<br />
+ long virtstride;<br />
+ <a href="http://graphics.github.com/ocd/">enum ocdformat</a> paletteformat;<br />
+ void *palette;<br />
+};</p>
+<p class="Code_Header_2"><a name="bvsurfgeom.structsize">bvsurfgeom.structsize</a></p>
+<p class="inline_code">unsigned int structsize;</p>
+<p>This member is used for compatibility between BLTsville versions. (See <span class="inline_code">
+<a href="#bvbltparams.structsize">bvbltparams.structsize</a></span> for an explanation.) </p>
+<p class="Code_Header_2"><a name="bvsurfgeom.format">bvsurfgeom.format</a></p>
+<p class="code_block"><a href="http://graphics.github.com/ocd/">enum ocdformat</a> format;</p>
+<p>This member specifies the format of the surface using the <a href="http://graphics.github.com/ocd">Open Color format
+Definitions (OCD)</a>.</p>
+<p class="Code_Header_2"><a name="bvsurfgeom.width">bvsurfgeom.width</a></p>
+<p class="code_block">unsigned int width;</p>
+<p>This member specifies the width of the surface in pixels. This size does not have to be equivalent to the
+<span class="inline_code"><a href="#bvsurfgeom.virtstride">virtstride</a></span> size.</p>
+<p class="imponly"><strong>Implementations Only</strong><br />
+<br />
+Implementations should never assume that <span class="inline_code">width</span> is equivalent to
+<span class="inline_code"><a href="#bvsurfgeom.virtstride">virtstride</a></span>.</p>
+<p class="Code_Header_2"><a name="bvsurfgeom.height">bvsurfgeom.height</a></p>
+<p class="code_block">unsigned int height;</p>
+<p>This member specifies the height of the surface in lines of <span class="inline_code">
+<a href="#bvsurfgeom.virtstride">virtstride</a></span> width.</p>
+<p class="Code_Header_2"><a name="bvsurfgeom.orientation">bvsurfgeom.orientation</a></p>
+<p class="code_block">int orientation;</p>
+<p>This member specifies the orientation or angle of the surface in degrees. Since BLTsville is designed only to specify
+orthogonal rectangles, this value must be a multiple of 90º. This value <span class="underline">may</span> be negative.
+<em>(Extending BLTsville to handle non-orthogonal rectangles may be considered if there is sufficient interest.)</em></p>
+<p class="imponly"><strong>Implementations Only</strong><br />
+<br />
+Implementations should normalize orientation angles. For example, a client that sets the orientation to -450º should
+behave as if the value of 270º were specified. </p>
+<p class="Code_Header_2"><a name="bvsurfgeom.virtstride">bvsurfgeom.virtstride</a></p>
+<p class="code_block">long virtstride;</p>
+<p>This member specifies the horizontal stride of the surface in bytes for an unrotated surface. The stride represents
+the number of bytes needed to move from one pixel to the pixel immediately below it. This value
+<span class="underline">may</span> be negative.</p>
+<p class="note">NOTE: This means the <span class="inline_code">orientation</span> does not affect the
+<span class="inline_code">virtstride</span>. However, rotating a surface usually results in a different configuration
+(i.e. <span class="inline_code">width</span>), which <span class="underline">will</span> affect the
+<span class="inline_code">virtstride</span>. For example, a 320 x 240 x 32 bpp 0º surface might have a
+<span class="inline_code">virtstride</span> of 1280 bytes (320 pixels/line * 32 bits/pixel / 8 bits/byte). When the
+orientation is set to 180º, the <span class="inline_code">virtstride</span> would be the same. But when the orientation
+is set to 90º (or 270º), the <span class="inline_code">virtstride</span> would most likely need to be set to 960 bytes (240
+pixels/line * 32 bits/pixel / 8 bits/byte). </p>
+<p class="imponly"><strong>Implementations Only</strong><br />
+<br />
+Implementations that do not support a negative <span class="inline_code">virtstride</span> must compensate using whatever
+mechanism is appropriate for the implementation. For example, using a vertical flipping/mirroring setting.</p>
+<p class="note">NOTE: The <span class="inline_code">virtstride</span> name must be maintained for backwards compatibility.
+However, no situation should arise where the client would need to provide two different strides for the virtual and physical
+views of a surface (there are situations where a physical stride will need to be available within the implementation, but
+the client will not be the one to supply it), so <em>physstride</em> will most likely never be needed. However, when
+a client provides a physical description of the buffer (see the <a href="#Kernel_Mode_Interface">Kernel Mode Interface</a>
+section below), the <span class="inline_code">virtstride</span> entry should be used to provide the physical stride.</p>
+<p class="Code_Header_2"><a name="bvsurfgeom.paletteformat">bvsurfgeom.paletteformat</a></p>
+<p class="code_block"><a href="http://graphics.github.com/ocd/">enum ocdformat</a> paletteformat;</p>
+<p>This member specifies the format of the palette supplied via the <span class="inline_code">
+<a href="#bvsurfgeom.palette">palette</a></span> member for palettized formats using the
+<a href="http://graphics.github.com/ocd">Open Color format Definitions (OCD)</a>.</p>
+<p class="Code_Header_2"><a name="bvsurfgeom.palette">bvsurfgeom.palette</a></p>
+<p class="code_block">void *palette;</p>
+<p>This member points to a palette used for palettized formats. The format of the palette is specified by the
+<span class="inline_code"><a href="#bvsurfgeom.palette">paletteformat</a></span> member. Palettes are packed based
+on their container size:</p>
+<table class="indent">
+ <tr>
+ <td class="ctr_thin_bord"><strong>Palette Format</strong></td>
+ <td class="ctr_thin_bord"><strong>Palette Layout (byte address)</strong></td>
+ <td class="ctr_thin_bord"><strong>Palette Layout (little endian)</strong></td>
+ </tr>
+ <tr class="small_code_block_in_table">
+ <td class="thin_bord">OCDFMT_xRGB12</td>
+ <td class="ctr_thin_bord">n/a</td>
+ <td class="thin_bord">
+ <table style="width: 100%">
+ <tr>
+ <td class="thin_bord">*(((unsigned short *)palette) + 0)</td>
+ <td class="thin_bord">0xFrgb</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned short *)palette) + 1)</td>
+ <td class="thin_bord">0xFrgb</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">...</td>
+ <td class="thin_bord">...</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned short *)palette) + n - 1)</td>
+ <td class="thin_bord">0xFrgb</td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ <tr class="small_code_block_in_table">
+ <td class="thin_bord">OCDFMT_RGB24</td>
+ <td class="thin_bord">
+ <table style="width: 100%">
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + 0)</td>
+ <td class="thin_bord">red0</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + 1)</td>
+ <td class="thin_bord">green0</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + 2)</td>
+ <td class="thin_bord">blue0</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + 3)</td>
+ <td class="thin_bord">red1</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + 4)</td>
+ <td class="thin_bord">green1</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + 5)</td>
+ <td class="thin_bord">blue1</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">...</td>
+ <td class="thin_bord"> </td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + (3 * n) - 3)</td>
+ <td class="thin_bord">redNm1</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + (3 * n) - 2)</td>
+ <td class="thin_bord">greenNm1</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + (3 * n) - 1)</td>
+ <td class="thin_bord">blueNm1</td>
+ </tr>
+ </table>
+ </td>
+ <td class="ctr_thin_bord">n/a</td>
+ </tr>
+ <tr class="small_code_block_in_table">
+ <td class="thin_bord">OCDFMT_RGBx24</td>
+ <td class="thin_bord">
+ <table style="width: 100%">
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + 0)</td>
+ <td class="thin_bord">red0</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + 1)</td>
+ <td class="thin_bord">green0</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + 2)</td>
+ <td class="thin_bord">blue0</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + 3)</td>
+ <td class="thin_bord">0xFF</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + 4)</td>
+ <td class="thin_bord">red1</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + 5)</td>
+ <td class="thin_bord">green1</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + 6)</td>
+ <td class="thin_bord">blue1</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + 7)</td>
+ <td class="thin_bord">0xFF</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">...</td>
+ <td class="thin_bord"> </td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + (4 * n) - 4)</td>
+ <td class="thin_bord">redNm1</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + (4 * n) - 3)</td>
+ <td class="thin_bord">greenNm1</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + (4 * n) - 2)</td>
+ <td class="thin_bord">blueNm1</td>
+ </tr>
+ <tr>
+ <td class="thin_bord">*(((unsigned char *)palette) + (4 * n) - 1)</td>
+ <td class="thin_bord">0xFF</td>
+ </tr>
+ </table>
+ </td>
+ <td class="thin_bord">
+ <table style="width: 100%">
+ <tr>
+ <td class="thin_bord">*(((unsigned long *)palette) + 0)</td>
+ <td class="thin_bord">0xFFbbggrr<br />
+ </td>
+ </tr>
+ <tr class="thin_bord">
+ <td class="thin_bord"> </td>
+ <td class="thin_bord"> </td>
+ </tr>
+ <tr class="thin_bord">
+ <td class="thin_bord"> </td>
+ <td class="thin_bord"> </td>
+ </tr>
+ <tr class="thin_bord">
+ <td class="thin_bord"> </td>
+ <td class="thin_bord"> </td>
+ </tr>
+ <tr class="thin_bord">
+ <td class="thin_bord">*(((unsigned long *)palette) + 1)<br />
+ </td>
+ <td class="thin_bord">0xFFbbggrr<br />
+ </td>
+ </tr>
+ <tr class="thin_bord">
+ <td class="thin_bord"> </td>
+ <td class="thin_bord"> </td>
+ </tr>
+ <tr class="thin_bord">
+ <td class="thin_bord"> </td>
+ <td class="thin_bord"> </td>
+ </tr>
+ <tr class="thin_bord">
+ <td class="thin_bord"> </td>
+ <td class="thin_bord"> </td>
+ </tr>
+ <tr class="thin_bord">
+ <td class="thin_bord">...</td>
+ <td class="thin_bord"> </td>
+ </tr>
+ <tr class="thin_bord">
+ <td class="thin_bord">*(((unsigned long *)palette) + n - 1)|<br />
+ </td>
+ <td class="thin_bord">0xFFbbggrr<br />
+ </td>
+ </tr>
+ <tr class="thin_bord">
+ <td class="thin_bord"> </td>
+ <td class="thin_bord"> </td>
+ </tr>
+ <tr class="thin_bord">
+ <td class="thin_bord"> </td>
+ <td class="thin_bord"> </td>
+ </tr>
+ <tr class="thin_bord">
+ <td class="thin_bord"> </td>
+ <td class="thin_bord"> </td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+</table>
+<p class="note">NOTE: Use of subsampled formats for <span class="inline_code">paletteformat</span> is currently undefined.</p>
+<p class="Header4"><a name="bvsurfgeom_examples">Examples</a></p>
+<p>Mixing and matching <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> and
+<span class="inline_code">bvsurfgeom</span> structures provides maximum flexibility for a client.</p>
+<table style="width: 100%" class="example">
+ <tr>
+ <td><strong>Example:</strong> Using two different <span class="inline_code">bvsurfgeom</span> structures with
+ the same <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> structure allows in-place format
+ conversion:</td>
+ </tr>
+ <tr>
+ <td>
+ <p class="indent"><span class="small_code_block_in_table">...<br />
+ // Convert premultiplied image to non-premultiplied in place<br />
+ struct
+ bvbltparams parms;<br />
+ ...<br />
+ struct
+ bvbuffdesc buff;<br />
+ ...<br />
+ struct
+ bvsurfgeom srcgeom, dstgeom;<br />
+ ...<br />
+ srcgeom.format = OCDFMT_RGBA24;<br />
+ dstgeom.format = OCDFMT_nRGBA24;<br />
+ ...<br />
+ parms.src1.desc = &buff;<br />
+ parms.src1geom = &srcgeom;<br />
+ parms.dstdesc = &buff;<br />
+ parms.dstgeom = &dstgeom;<br />
+ ...<br />
+ bv_blt(&parms);<br />
+ ... </span></p>
+ </td>
+ </tr>
+</table>
+<br />
+<table style="width: 100%" class="example">
+ <tr>
+ <td><strong>Example:</strong> Using three different <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span>
+ structures with the same <span class="inline_code">bvsurfgeom</span> structure reduces code and copy errors:</td>
+ </tr>
+ <tr>
+ <td>
+ <p class="indent"><span class="small_code_block_in_table">...<br />
+ // Blend two images of the same size<br />
+ struct
+ bvbltparams parms;<br />
+ ...<br />
+ struct
+ bvbuffdesc src1buff, src2buff, dstbuff;<br />
+ ...<br />
+ struct
+ bvsurfgeom geom;<br />
+ ...<br />
+ parms.src1.desc = &src1buff;<br />
+ parms.src1geom = &geom;<br />
+ parms.src2.desc = &src2buff;<br />
+ parms.src2geom = &geom;<br />
+ parms.dstdesc = &dstbuff;<br />
+ parms.dstgeom = &dstgeom;<br />
+ ...<br />
+ bv_blt(&parms);<br />
+ ... </span></p>
+ </td>
+ </tr>
+</table>
+<br />
+<hr />
+<p class="Code_Header"><a name="bvtileparams">bvtileparams</a></p>
+<p>This structure is used to define the parameters necessary to use a small image as a tile or block that will be repeated
+when used as a source. This structure is used in conjunction with the associated <span class="inline_code">
+<a href="#bvsurfgeom">bvsurfgeom</a></span> and the associated <span class="inline_code"><a href="#bvrect">bvrect</a></span>
+to determine the operation that is performed.</p>
+<p class="small_code_block">struct bvcopparams {<br />
+ unsigned int <a href="#bvtileparams.structsize">structsize</a>;<br />
+ unsigned long <a href="#bvtileparams.flags">flags</a>;<br />
+ void *<a href="#bvtileparams.virtaddr">virtaddr</a>;<br />
+ int <a href="#bvtileparams.dstleft">dstleft</a>;<br />
+ int <a href="#bvtileparams.dsttop">dsttop</a>;<br />
+ unsigned int <a href="#bvtileparams.srcwidth">srcwidth</a>;<br />
+ unsigned int <a href="#bvtileparams.srcheight">srcheight</a>;<br />
+};</p>
+<p class="Code_Header_2"><a name="bvtileparams.structsize">bvtileparams.structsize</a></p>
+<p class="code_block">unsigned int structsize;</p>
+<p>This member is used for compatibility between BLTsville versions. (See <span class="inline_code">
+<a href="#bvbltparams.structsize">bvbltparams.structsize</a></span> for an explanation.) </p>
+<p class="Code_Header_2"><a name="bvtileparams.flags">bvtileparams.flags</a></p>
+<p class="code_block">unsigned long flags;</p>
+<p>This member specifies some additional information for the tiling operation. It can be composed as the binary OR
+of one selection for each edge (left, top, right, and bottom) from the following flags:</p>
+<table style="" class="indent">
+ <tr>
+ <td><span class="inline_code"><a name="BVTILE_LEFT_REPEAT">BVTILE_LEFT_REPEAT</a></span></td>
+ <td>indicates that the tile is repeated to the left of the destination alignment location.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVTILE_TOP_REPEAT">BVTILE_TOP_REPEAT</a></span></td>
+ <td>indicates that the tile is repeated above the destination alignment location.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVTILE_RIGHT_REPEAT">BVTILE_RIGHT_REPEAT</a></span></td>
+ <td>indicates that the tile is repeated to the right of the destination alignment location.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVTILE_BOTTOM_REPEAT">BVTILE_BOTTOM_REPEAT</a></span></td>
+ <td>indicates that the tile is repeated below the destination alignment location.</td>
+ </tr>
+ <tr>
+ <td><a name="BVTILE_LEFT_MIRROR" class="inline_code">BVTILE_LEFT_MIRROR</a></td>
+ <td>indicates that the tile is mirrored to the left of the destination alignment location.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVTILE_TOP_MIRROR">BVTILE_TOP_MIRROR</a></span></td>
+ <td>indicates that the tile is mirrored above the destination alignment location.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVTILE_RIGHT_MIRROR">BVTILE_RIGHT_MIRROR</a></span></td>
+ <td>indicates that the tile is mirrored to the right of the destination alignment location.</td>
+ </tr>
+ <tr>
+ <td><span class="inline_code"><a name="BVTILE_BOTTOM_MIRROR">BVTILE_BOTTOM_MIRROR</a></span></td>
+ <td>indicates that the tile is mirrored below the destination alignment location.</td>
+ </tr>
+</table>
+<p class="Code_Header_2"><a name="bvtileparams.virtaddr">bvtileparams.virtaddr</a></p>
+<p class="code_block">void *virtaddr;</p>
+<p>This member is used to indicate the CPU virtual address of the start of the buffer.</p>
+<p class="imponly"><strong>Implementations Only</strong><br />
+<br />
+Note that this is always the beginning of the buffer. This means that if the <span class="inline_code">
+<a href="#bvsurfgeom.virtaddr">bvsurfgeom.virtstride</a></span> is negative, or the <a href="#bvsurfgeom.orientation">bvsurfgeom.orientation</a>
+does not normalize to 0º (i.e. <span class="inline_code">orientation % 360 != 0</span>), implementations may need
+to use a modified version of <span class="inline_code">virtaddr</span> internally to operate correctly.</p>
+<p class="Code_Header_2"><a name="bvtileparams.dstleft">bvtileparams.dstleft</a></p>
+<p class="code_block">int dstleft;</p>
+<p>This member is used to designate the left edge of the location of the tile in the destination for alignment purposes
+(alignment location). Note that the <span class="inline_code"><a href="#bvrect">bvrect</a></span> of the destination
+specifies the region which is filled by the tile.</p>
+<p class="Code_Header_2"><a name="bvtileparams.dsttop">bvtileparams.dsttop</a></p>
+<p class="code_block">int dsttop;</p>
+<p>This member is used to designate the top edge of the location of the tile in the destination for alignment purposes (alignment
+location). Note that the <span class="inline_code"><a href="#bvrect">bvrect</a></span> of the destination specifies
+the region which is filled by the tile.</p>
+<p class="Code_Header_2"><a name="bvtileparams.srcwidth">bvtileparams.srcwidth</a></p>
+<p class="code_block">unsigned int srcwidth;</p>
+<p>This member is used to designate the width of the source for purposes of scaling. The relationship between this
+field and the <span class="inline_code"><a href="#bvrect.width">bvrect.width</a></span> of the associated source surface
+determines the horizontal scaling factor.</p>
+<p class="Code_Header_2"><a name="bvtileparams.srcheight">bvtileparams.srcheight</a></p>
+<p class="code_block">unsigned int srcheight;</p>
+<p>This member is used to designate the height of the source for purposes of scaling. The relationship between this
+field and the <span class="inline_code"><a href="#bvrect.height">bvrect.height</a></span> of the associated source surface
+determines the vertical scaling factor.</p>
+<hr />
+<p class="Code_Header"><a name="bvcallbackerror">bvcallbackerror</a></p>
+<p>This structure is used to provide error information to the client of a BLT that failed within an asynchronous operation.
+The errors will be limited to those that occur within the implementation.</p>
+<p class="note">NOTE: Parameter errors should never be returned in this structure. These should have been returned
+to the client before the BLT was ever initiated.</p>
+<p class="small_code_block">struct bvcallbackerror {<br />
+ unsigned int <a href="#bvcallbackerror.structsize">structsize</a>;<br />
+ <a href="#bverror">enum bverror</a> <a href="#bvcallbackerror.error">error</a>;<br />
+ char *<a href="#bvcallbackerror.errdesc">errdesc</a>;<br />
+};</p>
+<p class="Code_Header_2"><a name="bvcallbackerror.structsize">bvcallbackerror.structsize</a></p>
+<p class="code_block">unsigned int structsize;</p>
+<p>This member is used for compatibility between BLTsville versions. (See <span class="inline_code">
+<a href="#bvbltparams.structsize">bvbltparams.structsize</a></span> for an explanation.) </p>
+<p class="Code_Header_2"><a name="bvcallbackerror.error">bvcallbackerror.error</a></p>
+<p class="code_block"><a href="#bverror">enum bverror</a> error;</p>
+<p>This member is used to indicate the error encountered. In general, these will be error like these:</p>
+<table class="indent">
+ <tr>
+ <td class="inline_code">BVERR_OP_FAILED</td>
+ <td>The operation failed for unspecified reasons. The destination buffer was not modified.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVERR_OP_INCOMPLETE</td>
+ <td>The operation only partially completed. The destination buffer is in an undefined state.</td>
+ </tr>
+ <tr>
+ <td class="inline_code">BVERR_MEMORY_ERROR</td>
+ <td>The operation resulted in a memory error, most likely due to an attempt to access invalid memory. The
+ destination buffer is in an undefined state.</td>
+ </tr>
+</table>
+<p class="Code_Header_2"><a name="bvcallbackerror.errdesc">bvcallbackerror.errdesc</a></p>
+<p class="code_block">char *errdesc;</p>
+<p><span class="inline_code">errdesc</span> is optionally used by implementations to pass a 0-terminated string with additional
+debugging information back to clients for debugging purposes. <span class="inline_code">errdesc</span> is not localized
+or otherwise meant to provide information that is displayed to users.</p>
+<hr />
+<p class="Header1">Batching<a name="batching"></a></p>
+<p>Batching is the single most powerful feature in BLTsville. It is used for two major purposes:</p>
+<ol>
+ <li>To group similar BLTs which use most of the same parameters so that they can be handled more efficiently by the
+ implementation.</li>
+ <li>To group BLTs that should go together so that implementations can use special features that go beyond what seems
+ to be expressed by the BLTsville API.</li>
+</ol>
+<p class="note">NOTE: It is important to realize that BLTs batched together may be done <span class="underline">in
+any order</span>, and in fact may not even be done in the way specified. This includes the BLTs being done as they
+are submitted, or no operations performed until the batch submission is completed with
+<a href="#BVFLAG_BATCH_END" class="inline_code">BVFLAG_BATCH_END</a>. This means the client must not rely on intermediate
+results within a batch.</p>
+<p class="note">NOTE: Because BLTs can be performed in a variety of ways, callbacks for individual BLTs would have
+no consistent meaning. So, when batching is mixed with <span class="inline_code"><a href="#BVFLAG_ASYNC">BVFLAG_ASYNC</a></span>,
+only the callback for the last BLT occurs.</p>
+<p class="note">NOTE: Since implementations can perform batched BLTs in a variety of ways, even synchronous batched
+BLTs can be effectively asynchronous. Therefore, only the last BLT determines the synchronicity of the entire batch.
+i.e. the <span class="inline_code"><a href="#BVFLAG_ASYNC">BVFLAG_ASYNC</a></span> flag is only heeded when combined with
+<span class="inline_code"><a href="#BVFLAG_BATCH_END">BVFLAG_BATCH_END</a>.</span></p>
+<p class="note">NOTE: Failure during the performance of a batch (different from an error on submission--indicated by the
+contents of the <a href="#bvcallbackerror" class="inline_code">bvcallbackerror</a> structure) will result in an unknown
+state for all destination buffers. Do not assume that a given implementation's state in this case represents the state
+which will be encountered for a different implementation.</p>
+<p class="note">NOTE: Because of the indeterminate nature of the execution of a batch of BLTs, a "batch abort" would not
+result in a known state either. As stated above, a given implementation may have already performed earlier BLTs in
+a batch as the batch is submitted. So errors encountered during the submission of a batch must be handled by the client,
+and then the batch must be terminated normally using <a href="#BVFLAG_BATCH_END" class="inline_code">BVFLAG_BATCH_END</a>.</p>
+<p class="Header2">Batches For Grouping Similar BLTs</p>
+<p>Often, groups of similar BLTs are performed, with changes to only a few parameters. Some implementations have the
+ability to re-use previous settings, coupled with these changes, to perform new BLTs.</p>
+<p>One good example of this in in rendering text, similar to that you are reading now. In most systems, a glyph cache
+is maintained to hold the characters of a given font, rasterized with the specific characteristics desired (e.g. bold, italics,
+etc.). Each font in the glyph cache is normally created using a font rasterization engine from a vector-based font,
+such as FreeType. This technology allows fonts to be described in terms of curves and lines instead of pixels, which
+means they can be created as needed, in any size desirable.</p>
+<table style="" class="glyph_cache">
+ <tr>
+ <td class="glyph_cache"> !"#$%&'()*+'-./0123456789:;<=>?<br />
+ @ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_<br />
+ `abcdefghijklmnopqrstuvwxyz{|}~</td>
+ </tr>
+</table>
+<p>Then, when a character needs to be rendered, it is copied from the pre-rendered glyph cache. This is much more
+efficient than performing the font rasterization from the vector description each time a character is used.</p>
+<p>With some hardware implementations, the setup to trigger the copy of these characters from the glyph cache to the target
+surface can be quite significant, when compared to the number of pixels actually affected. For example, each character
+might consist of something on the order of 10 x 14, or about 140 pixels. Programming a typical hardware BLTer
+may require tens of commands for each character.</p>
+<p>But note that each of these BLTs differs by only a few parameters. Specifically, once the source and destination
+surfaces have been specified, and the operation described, only the source and destination rectangles change between BLTs.
+To alleviate much of this overhead, most implementations will allow the configuration of a previous BLT to be used again,
+with only those parameters which change provided for the subsequent BLTs.</p>
+<p>BLTsville provides access to this capability via the batch mechanism.</p>
+<p>For rendering a word using a monospaced font like this, the client might construct the batch like this:</p>
+<p class="small_code_block">struct bvbuffdesc screendesc = {sizeof(struct bvbuffdesc}, 0};<br />
+struct bvsurfgeom screengeom = {sizeof(struct bvsurfgeom), 0};<br />
+struct bvbuffdesc glyphcachedesc = {sizeof(struct bvbuffdesc), 0};<br />
+struct bvsurfgeom glyphcachegeom = {sizeof(struct bvsurfgeom), 0};<br />
+struct bvtileparams solidcolortileparams = {sizeof(struct bvtileparams), 0};<br />
+struct bvbuffgeom solidcolorgeom = {sizeof(struct bvsurfgeom), 0};<br />
+<br />
+struct bvbltparams bltparams = {sizeof(struct bvbltparams), 0};<br />
+<br />
+int charsperline = 32;<br />
+int fontwidth = 10;<br />
+int fontheight = 14;<br />
+int i = 0;<br />
+<br />
+screendesc.virtaddr = screenaddr;<br />
+screendesc.length = screenstride * screenheight;<br />
+screengeom.format = OCDFMT_RGB24;<br />
+screengeom.width = screenwidth;<br />
+screengeom.height = screenheight;<br />
+screengeom.virtstride = screenstride;<br />
+<br />
+glyphcachedesc.virtaddr = glyphcacheaddr;<br />
+glyphcachedesc.length = glyphcachestride * glyphcacheheight;<br />
+glyphcachegeom.format = OCDFMT_ALPHA8;<br />
+glyphcachegeom.width = glyphcachewidth;<br />
+glyphcachegeom.height = glyphcacheheight;<br />
+glyphcachegeom.virtstride = glyphstride;<br />
+<br />
+solidcolortileparams.virtaddr = &solidcolor;<br />
+solidcolortileparams.srcwidth = 1;<br />
+solidcolortileparams.srcheight = 1;<br />
+solidcolorgeom.format = OCDFMT_RGB24;<br />
+<br />
+bltparams.flags = BVFLAG_BLEND | BVFLAG_SRC1_TILED | BVFLAG_BATCH_BEGIN;<br />
+bltparams.op.blend = BVBLEND_SRCOVER + BVBLENDDEF_REMOTE;<br />
+bltparams.dstdesc = &screendesc;<br />
+bltparams.dstgeom = &screengeom;<br />
+bltparams.src1.tileparams = &solidcolortileparams;<br />
+bltparams.src1geom = &solidcolorgeom;<br />
+bltparams.src2.desc = &screendesc;<br />
+bltparams.src2geom = &screengeom;<br />
+bltparams.mask.desc = &glyphcachedesc;<br />
+bltparams.maskgeom = &glyphcachegeom;<br />
+<br />
+bltparams.dstrect.left = bltparams.src2rect.left = screenrect.left;<br />
+bltparams.dstrect.top = bltparams.src2rect.top = screenrect.top;<br />
+<br />
+bltparams.maskrect.width = bltparams.dstrect.width = bltparams.src2rect.width = fontwidth;<br />
+bltparams.maskrect.height = bltparams.dstrect.height = bltparams.src2rect.height = fontheight;<br />
+<br />
+bltparams.maskrect.left = ((text[i] - ' ') % charsperline) * fontwidth;<br />
+bltparams.maskrect.top = ((text[i] - ' ') / charsperline) * fontheight;<br />
+<br />
+bv_blt(&bltparams);<br />
+<br />
+i++;<br />
+if(i < textlen)<br />
+{<br />
+ bltparams.flags = (bltparams.flags & ~BVFLAG_BATCH_MASK) | BVFLAG_BATCH_CONTINUE;<br />
+ bltparams.batchflags = BVBATCH_DSTRECT_ORIGIN | BVBATCH_SRC2RECT_ORIGIN | BVBATCH_MASKRECT_ORIGIN;<br />
+<br />
+ do<br />
+ {<br />
+ bltparams.dstrect.left += fontwidth;<br />
+ bltparams.src2rect.left = bltparams.dstrect.left;<br />
+<br />
+ bltparams.maskrect.left = ((text[i] - ' ') % charsperline) * fontwidth;<br />
+ bltparams.maskrect.top = ((text[i] - ' ') / charsperline) * fontheight;<br />
+<br />
+ bv_blt(&bltparams);<br />
+<br />
+ i++;<br />
+ }while(i < textlen);<br />
+}<br />
+<br />
+bltparams.flags = (bltparams.flags & ~BVFLAG_BATCH_MASK) | BVFLAG_BATCH_END;<br />
+bltparams.batchflags = BVBATCH_ENDNOP;<br />
+<br />
+bv_blt(&bltparams);</p>
+<p class="note">NOTE: bvbltparams.batchflags is just a hit. Not all implementations support deltas in
+batching, so clients must not change the values of members of <span class="inline_code"><a href="#bvbltparams">
+bvbltparams</a></span> (or structures it
+references) between BLTs. These values may be used.</p>
+<p class="Header2">Batches For Special Feature BLTs</p>
+<p>Enabling special features of some implementations is a special challenge. But BLTsville is up the task.</p>
+<p>For example, perhaps an implementation is capable of blending four layers at the same time. But BLTsville only allows
+blending to be specified using two layers at a time. How can this be accomplished?</p>
+<p>The most prevalent blending reference used is the <a href="http://dx.doi.org/10.1145/800031.808606">Porter-Duff
+whitepaper</a>, which specifies blending of two sources (A and B). So any N-source blend (N > 2) would require the blends to be
+specified as a grouping of N - 1 two-source blends in order to utilize the
+Porter-Duff equations. That's how such a blend is specified in BLTsville:</p>
+<p class="small_code_block">bltparams.dstrect.width = bltparams.src1rect.width = bltparams.src2rect.width = dstgeom.width;<br />
+bltparams.dstrect.height = bltparams.src1rect.height = bltparams.src2rect.height = dstgeom.height; <br />
+<br />
+bltparams.flags = BVFLAG_BLEND | BVFLAG_BATCH_BEGIN;<br />
+bltparams.op.blend = BVBLEND_SRCOVER;<br />
+bltparams.dstdesc = &dstdesc;<br />
+bltparams.dstgeom = &dstgeom;<br />
+bltparams.src1.desc = &src1desc;<br />
+bltparams.src1geom = &src1geom;<br />
+bltparams.src2.desc = &src2desc;<br />
+bltparams.src2geom = &src2geom;<br />
+<br />
+bv_blt(&bltparams);<br />
+<br />
+bltparams.src1.desc = &src3desc;<br />
+bltparams.src1geom = &src3geom;<br />
+bltparams.dstdesc = &dstdesc;<br />
+bltparams.dstgeom = &dstgeom;<br />
+<br />
+bltparams.flags = (bltparams.flags & ~BVFLAG_BATCH_MASK) | BVFLAG_BATCH_CONTINUE;<br />
+bltparams.batch = BVBATCH_SRC1 | BVBATCH_SRC2;<br />
+<br />
+bv_blt(&bltparams);<br />
+<br />
+bltparams.src1.desc = &src4desc;<br />
+bltparams.src1geom = &src4geom;<br />
+<br />
+bltparams.flags = (bltparams.flags & ~BVFLAG_BATCH_MASK) | BVFLAG_BATCH_END;<br />
+bltparams.batch = BVBATCH_SRC1;<br />
+<br />
+bv_blt(&bltparams);</p>
+<p>The driver for an implementation that can perform this pair of operations as one BLT would be tasked with recognizing
+that the batch contained BLTs which can be combined.</p>
+<p>The fantastic thing about this approach is that an implementation without the ability to blend N sources in one pass would perform
+the blends separately, but the result would be identical. Moreover, implementations with the ability to combine
+different numbers of operations would likewise produce the same results, even they they used a different number of
+internal steps. Here's an example:</p>
+<table align="center">
+ <tr>
+ <td>
+<table>
+ <tr>
+ <td class="ctr_thin_bord"><strong>Number of<br />
+ Layers to<br />
+ Blend</strong></td>
+ <td class="ctr_thin_bord"><strong>BLTsville<br />
+ Operations</strong></td>
+ <td class="ctr_thin_bord"><strong>Implementation<br />
+ Capable of<br />
+ Blending One<br />
+ Source with a<br />
+ Destination</strong><br />
+ (2 inputs)</td>
+ <td class="ctr_thin_bord"><strong>Implementation<br />
+ Capable of<br />
+ Blending Two<br />
+ Sources to a<br />
+ Destination</strong><br />
+ (2 inputs)</td>
+ <td class="ctr_thin_bord"><strong>Implementation<br />
+ Capable of<br />
+ Blending Four<br />
+ Sources to a<br />
+ Destination</strong><br />
+ (4 inputs)</td>
+ <td class="ctr_thin_bord"><strong>Implementation<br />
+ Capable of<br />
+ Blending Eight<br />
+ Sources with<br />
+ a Destination</strong><br />
+ (5 inputs)</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">2</td>
+ <td class="nowrap">A over B => O</td>
+ <td class="nowrap">B => O<br />
+ A over O => O</td>
+ <td class="nowrap">A over B => O</td>
+ <td class="nowrap">A over B => O</td>
+ <td class="nowrap">A over B => O</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">3</td>
+ <td class="nowrap">B over C => O<br />
+ A over O => O</td>
+ <td class="nowrap">C => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap">B over C => O<br />
+ A over O => O</td>
+ <td class="nowrap">A over B over C => O</td>
+ <td class="nowrap">A over B over C => O</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">4</td>
+ <td class="nowrap">C over D => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap">D => O<br />
+ C over O => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap"> C over D => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap"> A over B over C over D => O</td>
+ <td class="nowrap"> A over B over C over D => O</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">5</td>
+ <td class="nowrap">D over E => O<br />
+ C over O => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap">E => O<br />
+ D over O => O<br />
+ C over O => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap">D over E => O<br />
+ C over O => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap">D over E => O<br />
+ A over B over C over O => O</td>
+ <td class="nowrap">E => O<br />
+ A over B over C over D over O => O</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">6</td>
+ <td class="nowrap">E over F => O<br />
+ D over O => O<br />
+ C over O => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap">F => O<br />
+ E over O => O<br />
+ D over O => O<br />
+ C over O => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap">E over F => O<br />
+ D over O => O<br />
+ C over O => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap">D over E over F => O<br />
+ A over B over C over O => O</td>
+ <td class="nowrap">E over F => O<br />
+ A over B over C over D over O => O</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">7</td>
+ <td class="nowrap">F over G => O<br />
+ E over O => O<br />
+ D over O => O<br />
+ C over O => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap">G => O<br />
+ F over O => O<br />
+ E over O => O<br />
+ D over O => O<br />
+ C over O => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap">F over G => O<br />
+ E over O => O<br />
+ D over O => O<br />
+ C over O => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap">D over E over F over G => O<br />
+ A over B over C over O => O</td>
+ <td class="nowrap">E over F over G => O<br />
+ A over B over C over D over O => O</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">8</td>
+ <td class="nowrap">G over H => O<br />
+ F over O => O<br />
+ E over O => O<br />
+ D over O => O<br />
+ C over O => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap">H => O<br />
+ G over O => O<br />
+ F over O => O<br />
+ E over O => O<br />
+ D over O => O<br />
+ C over O => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap">G over H => O<br />
+ F over O => O<br />
+ E over O => O<br />
+ D over O => O<br />
+ C over O => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap">G over H => O<br />
+ D over E over F over O => O<br />
+ A over B over C over O => O</td>
+ <td class="nowrap">E over F over G over H => O<br />
+ A over B over C over D over O => O</td>
+ </tr>
+ <tr>
+ <td class="ctr_thin_bord">9</td>
+ <td class="nowrap">H over I => O<br />
+ G over O => O<br />
+ F over O => O<br />
+ E over O => O<br />
+ D over O => O<br />
+ C over O => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap">I => O<br />
+ H over O => O<br />
+ G over O => O<br />
+ F over O => O<br />
+ E over O => O<br />
+ D over O => O<br />
+ C over O => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap">H over I => O<br />
+ G over O => O<br />
+ F over O => O<br />
+ E over O => O<br />
+ D over O => O<br />
+ C over O => O<br />
+ B over O => O<br />
+ A over O => O</td>
+ <td class="nowrap">G over H over I => O<br />
+ D over E over F over O => O<br />
+ A over B over C over O => O</td>
+ <td class="nowrap">I => O<br />
+ E over F over G over H over O => O<br />
+ A over B over C over D over O => O</td>
+ </tr>
+</table>
+</td>
+ </tr>
+ <tr>
+ <td class="ctr">Comparison of batched BLTsville calls with internal operations, based on implementation capabilities.
+</td>
+ </tr>
+</table>
+<p class="note">NOTE: As mentioned above a batch of BLTs may be serviced in any number of ways. In this example, the
+destination buffer may be used for intermediate results, so it is important that this buffer not be used during the batch--i.e.
+as a displayed buffer.</p>
+<hr />
+<p class="Header1"><a name="start">Where to Start</a></p>
+<p><em>(Note that error checking is omitted in all the examples below for clarity.)</em> </p>
+<p>1. Clients begin by opening one or more BLTsville implementations dynamically. The specific method of doing
+this is dependent on the operating system. For example, Linux might do this like this:</p>
+<p class="small_code_block">struct bltsvillelib<br />
+{<br />
+ char* name;<br />
+ void* handle;<br />
+ BVFN_MAP bv_map;<br />
+ BVFN_BLT bv_blt;<br />
+ BVFN_UNMAP bv_unmap;<br />
+}; <br />
+<br />
+struct bltsville bvlib[] =<br />
+{<br />
+ { "libbltsville_cpu.so", 0 },<br />
+ { "libbltsville_2d.so", 0 }<br />
+};<br />
+const int NUMBVLIBS = sizeof(bvlib) / sizeof(struct bltsvillelib);<br />
+<br />
+for(int i = 0; i < NUMLIBS; i++)<br />
+{<br />
+ bvlib[i].handle = dlopen(bvlib[i].name, RTLD_LOCAL | RTLD_LAZY);<br />
+ bvlib[i].bv_map = (BVFN_MAP)dlsym(bvlib[i].handle, "bv_map");<br />
+ bvlib[i].bv_blt = (BVFN_BLT)dlsym(bvlib[i].handle, "bv_blt");<br />
+ bvlib[i].bv_unmap = (BVFN_BLT)dlsym(bvlib[i].handle, "bv_unmap");<br />
+}<br />
+</p>
+<p>2. Clients then need to create a <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> object for
+each buffer to be accessed in BLTsville:</p>
+<table class="indent">
+ <tr>
+ <td valign="top">
+ <p class="small_code_block_in_table">struct bvbuffdesc buff =<br />
+ {sizeof(struct bvbuffdesc), 0};<br />
+ <br />
+ buff.virtaddr = buffptr;<br />
+ buff.length = bufflength;</p>
+ </td>
+ <td class="ctr"> or </td>
+ <td valign="top">
+ <p class="inline_code"><span class="small_code_block_in_table">struct bvbuffdesc buff;<br />
+ <br />
+ memset(&buff, 0, sizeof(buff));<br />
+ buff.structsize = sizeof(buff);<br />
+ buff.virtaddr = buffptr;<br />
+ buff.length = bufflength;</span></p>
+ </td>
+ </tr>
+</table>
+<p class="strong_emphasis">Note that the client must ensure that the map element and any additional members in
+<span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span> are initialized to 0.</p>
+<p>3. Next the buffer can be mapped to give the hardware implementations a chance to associate any necessary resources
+with the buffer:</p>
+<table class="indent">
+ <tr>
+ <td valign="top">
+ <p class="small_code_block_in_table">/* do nothing */ </p>
+ </td>
+ <td class="ctr"> or </td>
+ <td valign="top">
+ <p class="small_code_block_in_table">bvlib[0].bv_map(&buff); </p>
+ </td>
+ <td class="ctr"> or </td>
+ <td valign="top">
+ <p class="small_code_block_in_table">for(int i = 0; i < NUMLIBS; i++)<br />
+ {<br />
+ if(bvlib[i].bv_map)<br />
+ bvlib[i].bv_map(&buff);<br />
+ }</p>
+ </td>
+ </tr>
+</table>
+<br />
+<table style="width: 100%">
+ <tr>
+ <td valign="top">a. </td>
+ <td>This step is actually optional, as indicated above. However, if the client does not explicitly call
+ <span class="inline_code"><a href="#bv_map">bv_map()</a></span>, the mapping must be done by the implementation
+ to associate the necessary resources with the buffer. So this mapping must be done later, when
+ <span class="inline_code"><a href="#bv_blt">bv_blt()</a></span> is called. Additionally, since the client
+ did not call <span class="inline_code"><a href="#bv_map">bv_map()</a></span>, it is unlikely that the client will
+ call <span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span> to allow the implementation to free the
+ resources associated with the buffer. So the implementation will internally unmap the resources after completing
+ the BLT. This means that the mapping and unmapping overhead will be encountered on every call to
+ <span class="inline_code"><a href="#bv_blt">bv_blt()</a></span>.<br />
+ <em><br />
+ In general, the CPU implementations have (almost) no overhead associated with mapping and unmapping. So opting
+ not to make the <span class="inline_code"><a href="#bv_map">bv_map()</a></span> call for CPU implementations is
+ likely to have negligible difference in <span class="inline_code"><a href="#bv_blt">bv_blt()</a></span> performance.<br />
+ </em></td>
+ </tr>
+ <tr>
+ <td valign="top">b. </td>
+ <td>Calling <span class="inline_code"><a href="#bv_map">bv_map()</a></span> once for each buffer is enough to tell
+ the implementations that the client can be trusted to call <span class="inline_code"><a href="#bv_unmap">bv_unmap()</a></span>
+ when work with the buffer is complete, as indicated above. It does not matter which implementation's
+ <span class="inline_code"><a href="#bv_map">bv_map()</a></span> is called. However, that implementation is
+ the only one which will perform the mapping immediately. All other implementations will perform a <em>lazy
+ mapping</em> only when their <span class="inline_code"><a href="#bv_blt">bv_blt()</a></span> call is invoked.<br />
+ <br />
+ This allows the client to avoid the overhead of mapping and unmapping the buffers on each
+ <span class="inline_code"><a href="#bv_blt">bv_blt()</a></span> call. It also avoids the associated mapping
+ and unmapping overhead if a given implementation is never used.<br />
+ <br />
+ <em>As mentioned above, the CPU implementations have (almost) no overhead associated with mapping and unmapping,
+ so they are a good choice to use for the call to <span class="inline_code"><a href="#bv_map">bv_map()</a></span>.<br />
+ </em></td>
+ </tr>
+ <tr>
+ <td valign="top">c. </td>
+ <td>If the client wants direct control over the mapping and unmapping overhead, it can call the
+ <span class="inline_code"><a href="#bv_map">bv_map()</a></span> function of each implementation, as indicated above.
+ Each implementation will perform the mapping at that time, so that the overhead will not appear on subsequent calls
+ to <span class="inline_code"><a href="#bv_blt">bv_blt()</a></span>. </td>
+ </tr>
+</table>
+<p>4. Next the client must create <span class="inline_code"><a href="#bvsurfgeom">bvsurfgeom</a></span> objects for
+each way in which a buffer will be accessed. Often, there is only one way in which a buffer is accessed, so there
+will be the same number of buffers, <span class="inline_code"><a href="#bvbuffdesc">bvbuffdesc</a></span>, and
+<span class="inline_code"><a href="#bvsurfgeom">bvsurfgeom</a></span> objects. If that's the case, it may be convenient
+for the client to combine them into a parent structure. It may even be possible to share a single bvbuffgeom structure
+among buffers. Or there will be times when it is necessary to treat a buffer in different ways for different BLTs.
+Having these two structures separated allows all of these combinations.</p>
+<table class="indent">
+ <tr>
+ <td valign="top">
+ <p class="small_code_block_in_table">struct bvsurfgeom geom =<br />
+ {sizeof(struct bvsurfgeom), 0};<br />
+ <br />
+ geom.format = OCDFMT_RGB24;<br />
+ geom.width = width;<br />
+ geom.height = height;<br />
+ geom.virtstride = stride;</p>
+ </td>
+ <td class="ctr"> or </td>
+ <td valign="top">
+ <p class="inline_code"><span class="small_code_block_in_table">struct bvsurfgeom geom;
+ <br />
+ memset(&geom, 0, sizeof(geom));<br />
+ geom.structsize = sizeof(geom);<br />
+ geom.width = width;<br />
+ geom.height = height;<br />
+ geom.virtstride = stride;</span></p>
+ </td>
+ </tr>
+</table>
+<p class="strong_emphasis">Note that the client must ensure that any additional members in <span class="inline_code">
+<a href="#bvsurfgeom">bvsurfgeom</a></span> are initialized to 0 for future compatibility.</p>
+<p>5. Now the client is ready to fill in a bvbltparams structure to specify the type of BLT requested. Here
+is an example of a simple copy from the lower right corner of a surface to the upper left:</p>
+<p class="small_code_block">struct bvbltparams bltparams = {sizeof(struct bvbltparams), 0};<br />
+<br />
+bltparams.flags = BVFLAG_ROP;<br />
+bltparams.op.rop = 0xCCCC; /* SRCCOPY */<br />
+bltparams.dstdesc = &buff;<br />
+bltparams.dstgeom = &geom;<br />
+bltparams.dstrect.left = 0;<br />
+bltparams.dstrect.top = 0;<br />
+bltparams.dstwidth = width / 2;<br />
+bltparams.dstheight = height / 2;<br />
+bltparams.src1.desc = &buff;<br />
+bltparams.src1geom = &geom;<br />
+bltparams.src1rect.left = width / 2;<br />
+bltparams.src1rect.top = height / 2;<br />
+bltparams.src1rect.width = width / 2;<br />
+bltparams.src1rect.height = height / 2;</p>
+<p>6. And next the client can trigger the BLT by calling <span class="inline_code"><a href="#bv_blt">bv_blt()</a></span>:</p>
+<p class="small_code_block">bv_blt(&bltparams); </p>
+<p><em>If the client cannot complete the requested BLT, it returns a </em><span class="inline_code"><a href="#bverror">
+<em>bverror</em></a></span><em> indicating the issue. </em></p>
+<p>7. Finally, the client should clean up:</p>
+<p class="small_code_block">bv_unmap(&buff); </p>
+<hr />
+<p class="Header1"><a name="Kernel_Mode_Interface">Kernel Mode Interface</a></p>
+<p>The kernel mode interface differs only slightly from the user mode interface. Currently there are two differences
+in the general kernel interface, and one in the Linux/Android interface:</p>
+<p class="Code_Header_2">bvbuffdesc.auxtype/auxptr</p>
+<p><span class="inline_code"><a href="#bvbuffdesc.auxtype">bvbuffdesc.auxtype</a></span> is an <span class="inline_code">enum</span>,
+indicating the type of the
+<span class="inline_code"><a href="#bvbuffdesc.auxptr">bvbuffdesc.auxptr</a></span>. The enumeration values and
+the associated types are:</p>
+<table class="indent_thick_bord">
+ <tr>
+ <td class="thin_bord_dbl_botbord"><span class="inline_code"><a href="#bvbuffdesc.auxtype">bvbuffdesc.auxtype</a></span></td>
+ <td class="thin_bord_dbl_botbord">
+<span class="inline_code"><a href="#bvbuffdesc.auxptr">bvbuffdesc.auxptr</a></span> type</td>
+ <td class="thin_bord_dbl_botbord">Notes</td>
+ </tr>
+ <tr>
+ <td class="thin_bord"><span class="inline_code"><a name="BVAT_PHYSDESC">BVAT_PHYSDESC</a></span></td>
+ <td class="thin_bord">
+<a href="#bvphysdesc" class="inline_code">bvphysdesc</a></td>
+ <td class="thin_bord">Used to specify the physical pages of a physically discontiguous buffer constructed using
+ a single page size. This may be used with physically contiguous buffers as well, but
+ <span class="inline_code"><a href="#BVAT_PHYSADDR">BVAT_PHYSADDR</a></span> is preferred.</td>
+ </tr>
+ <tr>
+ <td class="thin_bord"><span class="inline_code"><a name="BVAT_PHYSADDR">BVAT_PHYSADDR</a></span></td>
+ <td class="thin_bord">physical address</td>
+ <td class="thin_bord">Used to specify the starting physical address of a physically contiguous buffer.</td>
+ </tr>
+</table>
+<p>The methods of describing the buffer using physical addresses is not exposed in user mode for security reasons.</p>
+<hr />
+<p class="Code_Header"><a name="bvphysdesc">bvphysdesc</a></p>
+<p class="small_code_block">struct bvphysdesc {<br />
+ unsigned int <a href="#bvphysdesc.structsize">structsize</a>;<br />
+ unsigned long <a href="#bvphysdesc.pagesize">pagesize</a>;<br />
+ unsigned long *<a href="#bvphysdesc.pagearray">pagearray</a>;<br />
+ unsigned int <a href="#bvphysdesc.pagecount">pagecount</a>;<br />
+ unsigned long <a href="#bvphysdesc.pageoffset">pageoffset</a>;<br />
+};</p>
+<p class="Code_Header_2"><a name="bvphysdesc.structsize">bvphysdesc.structsize</a></p>
+<p class="code_block">unsigned int structsize;</p>
+<p>This member is used for compatibility between BLTsville versions. (See <span class="inline_code">
+<a href="#bvbltparams.structsize">bvbltparams.structsize</a></span> for an explanation.) </p>
+<p class="Code_Header_2"><a name="bvphysdesc.pagesize">bvphysdesc.pagesize</a></p>
+<p class="code_block">unsigned long pagesize;</p>
+<p>This member indicates the size of the physical pages containing the buffer. <span class="inline_code">BVAT_PHYSDESC</span>/<span class="inline_code">bvphysdesc
+</span>does not support buffers which reside in pages that are not all the same size. <span class="inline_code">
+bvphysdesc.pagesize</span> is used to indicate the length of the pages in the <span class="inline_code">
+<a href="#bvphysdesc.pagearray">bvphysdesc.pagearray</a></span> as well as the expected alignment of those pages. If this value is 0, the default
+page size of the system is assumed.</p>
+<p class="note">NOTE: When used with physically contiguous buffers, this member should be set to the length of the
+buffer, which is the same as the value in <span class="inline_code"><a href="#bvbuffdesc.length">bvbuffdesc.length</a></span>.</p>
+<p class="Code_Header_2"><a name="bvphysdesc.pagearray">bvphysdesc.pagearray</a></p>
+<p class="code_block">unsigned long *pagearray;</p>
+<p>This member is an array of <span class="inline_code">unsigned long</span>s holding the physical addresses of the pages
+holding the buffer. The array contains <span class="inline_code"><a href="#bvphysdesc.pagecount">pagecount</a></span>
+entries. The specific format of the physical addresses is O/S dependent. However, <span class="inline_code">
+BVAT_PHYSDESC</span>/<span class="inline_code">bvphysdesc</span> only supports 32-bit physical addresses.</p>
+<p>Addresses in this array must be aligned on <span class="inline_code"><a href="#bvphysdesc.pagesize">
+bvphysdesc.pagesize</a></span> boundaries. Use the <span class="inline_code"><a href="#bvphysdesc.pageoffset">
+bvphysdesc.pageoffset</a></span> member to indicate the offset from the start of the first page to the beginning of the
+buffer.</p>
+<p class="note">NOTE: When used with physically contiguous buffers, the first (only) address in this array should
+be aligned on the system default page boundary, and the <span class="inline_code"><a href="#bvphysdesc.pageoffset">
+bvphysdesc.pageoffset</a></span> member should be used to indicate the offset from that address to the beginning of the
+buffer.</p>
+<p class="Code_Header_2"><a name="bvphysdesc.pagecount">bvphysdesc.pagecount</a></p>
+<p class="code_block">unsigned int pagecount;</p>
+<p>This member indicates the number of pages in the array pointed to by <span class="inline_code">
+<a href="#bvphysdesc.pagearray">bvphysdesc.pagearray</a></span>.</p>
+<p class="note">NOTE: When used with physically contiguous buffers, this member should be set to 1.</p>
+<p class="Code_Header_2"><a name="bvphysdesc.pageoffset">bvphysdesc.pageoffset</a></p>
+<p class="code_block">unsigned long pageoffset;</p>
+<p>This member indicates the number of bytes from the start of the first page (<span class="inline_code">*pagearray</span>)
+to the start of the buffer. The value must be less than <span class="inline_code"><a href="#bvphysdesc.pagesize">
+bvphysdesc.pagesize</a></span>.</p>
+<p class="imponly"><strong>Implementations Only</strong><br />
+<br />
+Implementations should not ignore this member.</p>
+<hr />
+<p class="Header2">bventry</p>
+<p>Kernel mode entry cannot be the same as the user mode. The specific method of accessing the kernel interface is
+O/S specific. However, the following interface is currently defined for the specified O/Ss:</p>
+<table class="example">
+ <tr>
+ <td>
+ <p class="Header4">Linux/Android</p>
+ <p class="Code_Header"><a name="bventry">bventry</a></p>
+ <p>This structure is used to obtain the pointers to the implementation's BLTsville calls. The client can call
+ the default <span class="inline_code">bv2d_entry()</span> function to obtain the pointers to the implementation
+ chosen by the system integrators, or it can call a specific function to get the pointers for a specific implementation
+ (e.g. <span class="inline_code">gcbv_entry()</span>).</p>
+ <p class="small_code_block">struct bventry {<br />
+ unsigned int <a href="#bventry.structsize">structsize</a>;<br />
+ <a href="#bv_map">BVFN_MAP</a> <a href="#bventry.bv_map">bv_map</a>;<br />
+ <a href="#bv_unmap">BVFN_UNMAP</a> <a href="#bventry.bv_unmap">bv_unmap</a>;<br />
+ <a href="#bv_blt">BVFN_BLT</a> <a href="#bventry.bv_blt">bv_blt</a>;<br />
+ <a href="#bv_cache">BVFN_CACHE</a> <a href="#bventry.bv_cache">bv_cache</a>;<br />
+ };</p>
+ <p class="Code_Header_2"><a name="bventry.structsize">bventry.structsize</a></p>
+ <p class="code_block">unsigned int structsize;</p>
+ <p>This member is used for compatibility between BLTsville versions. (See <span class="inline_code">
+ <a href="#bvbltparams.structsize">bvbltparams.structsize</a></span> for an explanation.) </p>
+ <p class="Code_Header_2"><a name="bventry.bv_map">bventry.bv_map</a>/<a name="bventry.bv_unmap">bv_unmap</a>/<a name="bventry.bv_blt">bv_blt</a>/<a name="bventry.bv_cache">bv_cache</a></p>
+ <p class="code_block">BVFN_MAP bv_map;<br />
+ BVFN_UNMAP bv_unmap;<br />
+ BVFN_BLT bv_blt;<br />
+ BVFN_CACHE bv_cache;</p>
+ <p>These members hold pointers to the functions for the specific implementation queried with a call to
+ <span class="inline_code">*_entry()</span>.</p>
+ <p class="note">NOTE: <span class="inline_code"><a href="#bv_cache">bv_cache()</a></span> is optional, so
+ this pointer may be set to 0.</p>
+ </td>
+ </tr>
+</table>
+<br />
+<hr /><br />
+<p class="Header2">Linux/Android Deviation</p>
+<p>Although the linked list used in the <span class="inline_code"><a href="#bvbuffmap">bvbuffmap</a></span> structure is
+not complicated, there may be a requirement to use the standard Linux/Android kernel linked list in that environment.
+To facilitate this, the <span class="inline_code"><a href="#bvbuffmap.map">bvbuffmap.map</a></span> entry is replaced by
+the following entry for Linux/Android <span class="underline">kernel mode only</span>:</p>
+<p class="Code_Header"><a name="bvbuffmap.node" class="Code_Header_2">bvbuffmap.node</a></p>
+<p class="code_block">struct list_head node;</p>
+<p>This member is used to reference the containing linked list for the <span class="inline_code"><a href="#bvbuffmap">bvbuffmap</a></span>
+structures associated with the buffer.</p>
+
+</body>
+
+</html> |