diff options
| author | Rick Tillery <rtillery@ti.com> | 2012-07-19 13:40:02 -0500 |
|---|---|---|
| committer | Rick Tillery <rtillery@ti.com> | 2012-07-19 14:18:26 -0500 |
| commit | 521f41023b2450808af932dc5068bff0838642b9 (patch) | |
| tree | 6e4ff7e1c66be053881dd8ad8750f4779c5b99c3 | |
| parent | 8f8325a8584a91ccaa678ed6ab2f8868549e7e0b (diff) | |
| download | hardware_ti_omap4-521f41023b2450808af932dc5068bff0838642b9.zip hardware_ti_omap4-521f41023b2450808af932dc5068bff0838642b9.tar.gz hardware_ti_omap4-521f41023b2450808af932dc5068bff0838642b9.tar.bz2 | |
BV: Update headers to 2.2: Add bvbltparams.src2auxdstrect,
bvbltparams.maskauxdstrect, BVFLAG_SRC2_AUXDSTRECT and BVFLAG_MASK_AUXDSTRECT;
Add BVAT_reserved2 bvauxtype; Updated documentation (+ new images)
Change-Id: I6a427019ab8d5ca4d6fd725d37f8d6abf8b2e55b
Signed-off-by: Rick Tillery <rtillery@ti.com>
| -rw-r--r-- | bltsville/blend-854x480-bad.jpg | bin | 0 -> 77198 bytes | |||
| -rw-r--r-- | bltsville/blend-854x480-bad2.jpg | bin | 0 -> 69838 bytes | |||
| -rw-r--r-- | bltsville/blend-854x480-roundingerror.jpg | bin | 0 -> 69458 bytes | |||
| -rw-r--r-- | bltsville/blend-854x480-threeblts.jpg | bin | 0 -> 76246 bytes | |||
| -rw-r--r-- | bltsville/blend-854x480.jpg | bin | 0 -> 69281 bytes | |||
| -rw-r--r--[-rwxr-xr-x] | bltsville/bvlogo.png | bin | 98635 -> 98635 bytes | |||
| -rw-r--r-- | bltsville/clock-720x480_4x3-fauxtrans.jpg | bin | 0 -> 70563 bytes | |||
| -rw-r--r-- | bltsville/clock-720x480_4x3.png | bin | 0 -> 560594 bytes | |||
| -rw-r--r-- | bltsville/concrete-64x36.png | bin | 0 -> 4783 bytes | |||
| -rw-r--r-- | bltsville/include/bltsville.h | 11 | ||||
| -rw-r--r-- | bltsville/include/bvbuffdesc.h | 3 | ||||
| -rw-r--r-- | bltsville/include/bverror.h | 2 | ||||
| -rw-r--r-- | bltsville/index.html | 6356 | ||||
| -rw-r--r--[-rwxr-xr-x] | bltsville/ocdtab.png | bin | 11854 -> 11854 bytes |
14 files changed, 3870 insertions, 2502 deletions
diff --git a/bltsville/blend-854x480-bad.jpg b/bltsville/blend-854x480-bad.jpg Binary files differnew file mode 100644 index 0000000..adc2d6d --- /dev/null +++ b/bltsville/blend-854x480-bad.jpg diff --git a/bltsville/blend-854x480-bad2.jpg b/bltsville/blend-854x480-bad2.jpg Binary files differnew file mode 100644 index 0000000..67a01f3 --- /dev/null +++ b/bltsville/blend-854x480-bad2.jpg diff --git a/bltsville/blend-854x480-roundingerror.jpg b/bltsville/blend-854x480-roundingerror.jpg Binary files differnew file mode 100644 index 0000000..9a12713 --- /dev/null +++ b/bltsville/blend-854x480-roundingerror.jpg diff --git a/bltsville/blend-854x480-threeblts.jpg b/bltsville/blend-854x480-threeblts.jpg Binary files differnew file mode 100644 index 0000000..3790a29 --- /dev/null +++ b/bltsville/blend-854x480-threeblts.jpg diff --git a/bltsville/blend-854x480.jpg b/bltsville/blend-854x480.jpg Binary files differnew file mode 100644 index 0000000..c76a433 --- /dev/null +++ b/bltsville/blend-854x480.jpg diff --git a/bltsville/bvlogo.png b/bltsville/bvlogo.png Binary files differindex 7f9944e..7f9944e 100755..100644 --- a/bltsville/bvlogo.png +++ b/bltsville/bvlogo.png diff --git a/bltsville/clock-720x480_4x3-fauxtrans.jpg b/bltsville/clock-720x480_4x3-fauxtrans.jpg Binary files differnew file mode 100644 index 0000000..fa3aa68 --- /dev/null +++ b/bltsville/clock-720x480_4x3-fauxtrans.jpg diff --git a/bltsville/clock-720x480_4x3.png b/bltsville/clock-720x480_4x3.png Binary files differnew file mode 100644 index 0000000..3a7f566 --- /dev/null +++ b/bltsville/clock-720x480_4x3.png diff --git a/bltsville/concrete-64x36.png b/bltsville/concrete-64x36.png Binary files differnew file mode 100644 index 0000000..cf21f0f --- /dev/null +++ b/bltsville/concrete-64x36.png diff --git a/bltsville/include/bltsville.h b/bltsville/include/bltsville.h index eb32bf8..96baebb 100644 --- a/bltsville/include/bltsville.h +++ b/bltsville/include/bltsville.h @@ -88,7 +88,11 @@ struct bvrect { #define BVFLAG_SCALE_RETURN 0x00100000 /* return scale type used */ #define BVFLAG_DITHER_RETURN 0x00200000 /* return dither type used */ -/**** Bits 31-22 reserved ****/ + + +#define BVFLAG_SRC2_AUXDSTRECT 0x00400000 /* src2auxdstrect used */ +#define BVFLAG_MASK_AUXDSTRECT 0x00800000 /* maskauxdstrect used */ +/**** Bits 31-24 reserved ****/ /* * BVIMPL_* - BLTsville implementations may be combined under managers to @@ -501,7 +505,7 @@ struct bvcallbackerror { struct bvbatch; /* - * bvinbuff - provides the buffer in bvbltparams + * bvinbuff - provides the buffer in bvbltparams */ union bvinbuff { struct bvbuffdesc *desc; /* buffer description when @@ -588,6 +592,9 @@ struct bvbltparams { error; handle contains callbackdata below */ unsigned long callbackdata; /* (i) callback data */ + + struct bvrect src2auxdstrect; + struct bvrect maskauxdstrect; }; #endif /* BLTSVILLE_H */ diff --git a/bltsville/include/bvbuffdesc.h b/bltsville/include/bvbuffdesc.h index d86e317..98934bc 100644 --- a/bltsville/include/bvbuffdesc.h +++ b/bltsville/include/bvbuffdesc.h @@ -37,6 +37,8 @@ enum bvauxtype { BVAT_NONE = 0, /* auxptr not used */ BVAT_reserved1 = /* reserved */ BVATDEF_VENDOR_ALL + 1, + BVAT_reserved2 = /* reserved */ + BVATDEF_VENDOR_ALL + 2, #ifdef BVAT_EXTERNAL_INCLUDE #include BVAT_EXTERNAL_INCLUDE #endif @@ -56,5 +58,4 @@ struct bvbuffdesc { type depends on auxtype */ }; - #endif /* BVBUFFDESC_H */ diff --git a/bltsville/include/bverror.h b/bltsville/include/bverror.h index 787dfaf..15c3ba7 100644 --- a/bltsville/include/bverror.h +++ b/bltsville/include/bverror.h @@ -293,7 +293,7 @@ enum bverror { BVERR_MEMORY_ERROR = /* async operation triggered memory error */ BVERRDEF_VENDOR_ALL + 51000, - BVERR_FORMAT = /* unsupported bvcopparams.bvsurfgeom.format */ + BVERR_FORMAT = /* unsupported format */ BVERRDEF_VENDOR_ALL + 52000, BVERR_CACHEOP = /* unsupported cache operation */ diff --git a/bltsville/index.html b/bltsville/index.html index fa935d0..4b3a96c 100644 --- a/bltsville/index.html +++ b/bltsville/index.html @@ -1,5 +1,5 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
+<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" />
@@ -52,10 +52,12 @@ text-align: left;
font-family: "Courier New", Courier, monospace;
}
-.indent1 {
+.imponly {
+ border: thin solid #666666;
margin-left: 40px;
-}
-.center {
+ background-color: #E5E5E5;
+ font-family: Arial, Helvetica, sans-serif;
+ color: #333333;
}
.Header1 {
margin: 0px 0 0 0;
@@ -71,6 +73,12 @@ 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;
@@ -108,13 +116,13 @@ border-bottom-width: 1px;
color: #0000FF;
}
-.blue_ctr_botbord {
+.blue_center_botbord {
text-align: center;
border-bottom-style: solid;
border-bottom-width: 1px;
color: #0000FF;
}
-.red_ctr {
+.red_center {
text-align: center;
color: #FF0000;
}
@@ -122,17 +130,17 @@ text-align: left;
color: #FF0000;
}
-.grn_ctr {
+.grn_center {
text-align: center;
color: #009900;
}
-.red_ctr_topbord {
+.red_center_topbord {
text-align: center;
border-top-style: solid;
border-top-width: 1px;
color: #FF0000;
}
-.blu_ctr_topbord {
+.blu_center_topbord {
text-align: center;
border-top-style: solid;
border-top-width: 1px;
@@ -144,10 +152,10 @@ margin-left: 40px;
}
.thin_bord {
- border: 1px solid #000000;
+ border-style: solid;
+ border-width: 1px;
}
.thin_bord_dbl_botbord {
- border-color: #000000;
border-left-style: solid;
border-left-width: 1px;
border-right-style: solid;
@@ -172,15 +180,47 @@ .ctr {
text-align: center;
}
-.red {
- color: #FF0000;
-}
.glyph_cache {
- font-family: "Courier New", Courier, monospace;
- font-size: medium;
- font-weight: normal;
- font-style: normal;
- margin-left: 40px;
+ 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>
@@ -188,983 +228,1157 @@ <body>
<table style="width: 100%; line-height: 100%;">
-<tr>
-<td style="width: 484px">
-<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>
-<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>.</p>
-</div>
-</td>
-</tr>
+ <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>
-<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>
+ <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 />
-<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" border="0"/></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" border="0"/></a>
-</div>
-<div>
-Get the source code on GitHub at <a href="http://github.com/graphics/bltsville">graphics/bltsville</a>, or download this project in either
-<a href="http://github.com/graphics/bltsville/zipball/master">zip</a> or
-<a href="http://github.com/graphics/bltsville/tarball/master">tar</a> formats.</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>
+<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 />
-<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>
+<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">Points of Interest in BLTsville</p>
-<table style="width: 100%">
-<tr>
-<td style="width: 50%" valign="top">
+<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>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>
+ <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>
-</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">
+<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>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>
+ <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>
-</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 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>BLTsville does not dictate capabilities of the
-implementations<ul>
-<li>Operation specified either works or returns
-a response indicating it's not supported</li>
+ <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>
-</li>
+<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">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.</p>
-<p><em>Note that the </em> <span class="underline_code"><em>bvinternal.h</em></span><em><span class="underline"> header is for
-implementations only</span> and should not be used by clients.</em></p>
-<p class="indent1">BLTsville currently has a user mode interface, but kernel
-mode is on the way.
-<em>Obviously, the kernel mode interface will have more operating system
-dependence, but as much as possible, the user mode itself is agnostic of
-operating system. However, the kernel mode interface will be quite similar
-to the user mode.</em></p>
<hr />
<p class="Header1">BLTsville Neighborhoods</p>
-<p>For most BLTsville clients, only one or both of the two main implementations
-will be used. These two implementations are the CPU and default 2-D hardware
-implementations. Clients use the standard names below to access these
-implementations. The specific
-name decoration will be dictated by the host Operating System (O/S):</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>
+ <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>
-</li>
-<li>2-D hardware: <span class="filename">bltsville_2d</span><ul>
-<li>Linux/Android: <span class="filename">libbltsville_2d.so</span></li>
-<li>Windows: <span class="filename">bltsville_2d.dll</span></li>
-<li>etc.</li>
+<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>
-</li>
+<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, or they may
-be symbolic links. In most cases, system integration will will connect the
-client
-with the most capable 2-D hardware available in the system. For example,
-<span class="filename">bltsville_2d</span> might be a symbolic link to
-<span class="filename">bltsville_vivante2d</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>
+<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 implementation: <span class="filename">bltsville_refcpu</span></li>
-<li>System DMA: <span class="filename">bltsville_mydma</span></li>
+ <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">Visiting BLTsville</p>
-<p>More than one BLTsville implementation may be available. To facilitate this, BLTsville
-implementation libraries are dynamically loaded by the client. Then the
-BLTsville
-entry points are imported. The specific procedure for this is dictated by the host
-O/S.</p>
-<hr />
<p class="Header1">Things To Do In BLTsville</p>
-<p>BLTsville's interface consists of three functions per implementation,
-which must be imported by the client at run time:</p>
-<ul class="code_block">
-<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>
+<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(struct bvbuffdesc* buffdesc);</p>
-<p><span class="strong_emphasis">BLTsville does not allocate buffers.</span>
-Clients must provide a buffer description via the <span class="inline_code">
-<a href="#bvbuffdesc">bvbuffdesc</a></span> structure so that BLTsville 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.</p>
-<p>Client are provided with <span class="inline_code">bv_map()</span> so they can control exactly when the
-mapping overhead is encountered. For a given buffer, the client can
-call the <span class="inline_code">bv_map()</span> in each implementation to establish that mapping immediately.</p>
-<p>As a special bonus, BLTsville clients are not required to call
-<span class="inline_code">bv_map()</span> for each implementation being used.
-One call to any implementation's <span class="inline_code">bv_map()</span> 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. As a result, the implementations can use
-<em>lazy mapping</em> only as necessary. This way a client that
-has multiple implementations available will not incur the overhead of the
-mapping at all, unless a <span class="inline_code"><a href="#bv_blt">bv_blt()</a></span>
-call to that implementation is made. 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.</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, the necessary mapping must be done automatically 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 must be 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><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>NOTE: Obviously any API cannot add capabilities beyond an implementation's
-capabilities. So if the
-implementation requires memory to be allocated from a special pool, that
-responsibility falls upon the client. The </em> <span class="inline_code"><em>bv_map()</em></span><em>
-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.</em></p>
+<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(struct bvbltparams* bltparams);</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>
+<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(struct bvbuffdesc* buffdesc);</p>
-<p><span class="inline_code">bv_unmap()</span> is used to free implementation
-resources associated with a buffer. 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> must 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) associated resources. </p>
-<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">struct bvbltparams {<br />
+<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 {<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 />
- } <a href="#op">op</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 />
- struct bvbuffdesc *<a href="#dstdesc">dstdesc</a>;<br />
- struct bvsurfgeom *<a href="#dstgeom">dstgeom</a>;<br />
- struct bvrect <a href="#dstrect">dstrect</a>;<br />
- union {<br />
-
-struct bvbuffdesc *<a href="#src1.desc">desc</a>;<br />
-
-struct bvtileparams *<a href="#src1.tileparams">tileparams</a>;<br />
- } <a href="#src1">src1</a>;<br />
- struct bvsurfgeom *<a href="#src1geom">src1geom</a>;<br />
- struct bvrect <a href="#src1rect">src1rect</a>;<br />
- union {<br />
-
-struct bvbuffdesc *<a href="#src2.desc">desc</a>;<br />
-
-struct bvtileparams *<a href="#src2.tileparams">tileparams</a>;<br />
- } <a href="#src2">src2</a>;<br />
- struct bvsurfgeom *<a href="#src2geom">src2geom</a>;<br />
- struct bvrect <a href="#src2rect">src2rect</a>;<br />
- union {<br />
-
-struct bvbuffdesc *<a href="#mask.desc">desc</a>;<br />
-
-struct bvtileparams *<a href="#mask.tileparams">tileparams</a>;<br />
- } <a href="#mask">mask</a>;<br />
- struct bvsurfgeom *<a href="#maskgeom">maskgeom</a>;<br />
- struct bvrect <a href="#maskrect">maskrect</a>;<br />
- struct bvrect <a href="#cliprect">cliprect</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 />
- void (*<a href="#callbackfn">callbackfn</a>)(struct
-bvcallbackerror* err,<br />
+<br />
+ void (*<a href="#callbackfn">callbackfn</a>)(<a href="#bvcallbackerror">struct
+bvcallbackerror</a> *err,<br />
-unsigned long handle);<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>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.</p>
-<p>Instead, BLTsville structures use the <span class="inline_code">structsize</span>
-member to indicate the number of bytes in the structure, which is used to
-communicate between the client and implementation which portions of the
-structure are current. This effectively bypasses the concept of a version
-and focuses on the specifics of what changes need to be considered to maintain
-compatibility.</p>
+<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>
+ <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>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="bvbltparams.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.
+<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><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>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 style="width: 100%">
-<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 />
-</p>
-<br />
-</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.</p>
-<p> </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>
+<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>
+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>
+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>
+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>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 - BVFLAG_HORZ/VERT_FLIP_*</p>
-<p>These flags indicate that the corresponding image is flipped horizontally or vertically as it is used by the
-operation.</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>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>
+<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>
+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>
+ <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 rop; /* 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>
+<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>
+ <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>
+<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>
+ <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>The table below is the magic decoder ring: </p>
-<table class="indent1">
-<tr>
-<td>
-Mask</td>
-<td class="ctr" style="width: 20px">
-1</td>
-<td class="ctr" style="width: 20px">
-1</td>
-<td class="ctr" style="width: 20px">
-1</td>
-<td class="ctr" style="width: 20px">
-1</td>
-<td class="ctr" style="width: 20px">
-1</td>
-<td class="ctr" style="width: 20px">
-1</td>
-<td class="ctr" style="width: 20px">
-1</td>
-<td class="ctr" style="width: 20px">
-1</td>
-<td class="ctr" style="width: 20px">
-0</td>
-<td class="ctr" style="width: 20px">
-0</td>
-<td class="ctr" style="width: 20px">
-0</td>
-<td class="ctr" style="width: 20px">
-0</td>
-<td class="ctr" style="width: 20px">
-0</td>
-<td class="ctr" style="width: 20px">
-0</td>
-<td class="ctr" style="width: 20px">
-0</td>
-<td class="ctr" style="width: 20px">
-0</td>
-</tr>
-<tr>
-<td class="red_left">
-Source 2 </td>
-<td class="red_ctr" style="width: 20px">
-1</td>
-<td class="red_ctr" style="width: 20px">
-1</td>
-<td class="red_ctr" style="width: 20px">
-1</td>
-<td class="red_ctr" style="width: 20px">
-1</td>
-<td class="red_ctr" style="width: 20px">
-0</td>
-<td class="red_ctr" style="width: 20px">
-0</td>
-<td class="red_ctr" style="width: 20px">
-0</td>
-<td class="red_ctr" style="width: 20px">
-0</td>
-<td class="red_ctr" style="width: 20px">
-1</td>
-<td class="red_ctr" style="width: 20px">
-1</td>
-<td class="red_ctr" style="width: 20px">
-1</td>
-<td class="red_ctr" style="width: 20px">
-1</td>
-<td class="red_ctr" style="width: 20px">
-0</td>
-<td class="red_ctr" style="width: 20px">
-0</td>
-<td class="red_ctr" style="width: 20px">
-0</td>
-<td class="red_ctr" style="width: 20px">
-0</td>
-</tr>
-<tr>
-<td class="grn_left">
-Source 1 </td>
-<td class="grn_ctr" style="width: 20px">
-1</td>
-<td class="grn_ctr" style="width: 20px">
-1</td>
-<td class="grn_ctr" style="width: 20px">
-0</td>
-<td class="grn_ctr" style="width: 20px">
-0</td>
-<td class="grn_ctr" style="width: 20px">
-1</td>
-<td class="grn_ctr" style="width: 20px">
-1</td>
-<td class="grn_ctr" style="width: 20px">
-0</td>
-<td class="grn_ctr" style="width: 20px">
-0</td>
-<td class="grn_ctr" style="width: 20px">
-1</td>
-<td class="grn_ctr" style="width: 20px">
-1</td>
-<td class="grn_ctr" style="width: 20px">
-0</td>
-<td class="grn_ctr" style="width: 20px">
-0</td>
-<td class="grn_ctr" style="width: 20px">
-1</td>
-<td class="grn_ctr" style="width: 20px">
-1</td>
-<td class="grn_ctr" style="width: 20px">
-0</td>
-<td class="grn_ctr" style="width: 20px">
-0</td>
-</tr>
-<tr>
-<td class="blue_left_botbord">
-Destination </td>
-<td class="blue_ctr_botbord" style="width: 20px">
-1</td>
-<td class="blue_ctr_botbord" style="width: 20px">
-0</td>
-<td class="blue_ctr_botbord" style="width: 20px">
-1</td>
-<td class="blue_ctr_botbord" style="width: 20px">
-0</td>
-<td class="blue_ctr_botbord" style="width: 20px">
-1</td>
-<td class="blue_ctr_botbord" style="width: 20px">
-0</td>
-<td class="blue_ctr_botbord" style="width: 20px">
-1</td>
-<td class="blue_ctr_botbord" style="width: 20px">
-0</td>
-<td class="blue_ctr_botbord" style="width: 20px">
-1</td>
-<td class="blue_ctr_botbord" style="width: 20px">
-0</td>
-<td class="blue_ctr_botbord" style="width: 20px">
-1</td>
-<td class="blue_ctr_botbord" style="width: 20px">
-0</td>
-<td class="blue_ctr_botbord" style="width: 20px">
-1</td>
-<td class="blue_ctr_botbord" style="width: 20px">
-0</td>
-<td class="blue_ctr_botbord" style="width: 20px">
-1</td>
-<td class="blue_ctr_botbord" style="width: 20px">
-0</td>
-</tr>
-<tr>
-<td class="left_topbord">
-Raster
-Operation </td>
-<td class="center_topbord" style="width: 20px">
-15</td>
-<td class="center_topbord" style="width: 20px">
-14</td>
-<td class="center_topbord" style="width: 20px">
-13</td>
-<td class="center_topbord" style="width: 20px">
-12</td>
-<td class="center_topbord" style="width: 20px">
-11</td>
-<td class="center_topbord" style="width: 20px">
-10</td>
-<td class="center_topbord" style="width: 20px">
-9</td>
-<td class="center_topbord" style="width: 20px">
-8</td>
-<td class="center_topbord" style="width: 20px">
-7</td>
-<td class="center_topbord" style="width: 20px">
-6</td>
-<td class="center_topbord" style="width: 20px">
-5</td>
-<td class="center_topbord" style="width: 20px">
-4</td>
-<td class="center_topbord" style="width: 20px">
-3</td>
-<td class="center_topbord" style="width: 20px">
-2</td>
-<td class="center_topbord" style="width: 20px">
-1</td>
-<td class="center_topbord" style="width: 20px">
-0</td>
-</tr>
+<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="indent1">
-<tr>
-<td class="left_topbord">
-Raster
-Operation </td>
-<td class="red_ctr_topbord" style="width: 20px">
-1</td>
-<td class="red_ctr_topbord" style="width: 20px">
-1</td>
-<td class="red_ctr_topbord" style="width: 20px">
-1</td>
-<td class="red_ctr_topbord" style="width: 20px">
-1</td>
-<td class="red_ctr_topbord" style="width: 20px">
-0</td>
-<td class="red_ctr_topbord" style="width: 20px">
-0</td>
-<td class="red_ctr_topbord" style="width: 20px">
-0</td>
-<td class="red_ctr_topbord" style="width: 20px">
-0</td>
-<td class="blu_ctr_topbord" style="width: 20px">
-1</td>
-<td class="blu_ctr_topbord" style="width: 20px">
-0</td>
-<td class="blu_ctr_topbord" style="width: 20px">
-1</td>
-<td class="blu_ctr_topbord" style="width: 20px">
-0</td>
-<td class="blu_ctr_topbord" style="width: 20px">
-1</td>
-<td class="blu_ctr_topbord" style="width: 20px">
-0</td>
-<td class="blu_ctr_topbord" style="width: 20px">
-1</td>
-<td class="blu_ctr_topbord" style="width: 20px">
-0</td>
-</tr>
+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 />
+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 />
-Here is a list of some commonly used raster
-operations that have been given names:<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">
-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">
-MERGECOPY</td>
-<td class="thin_bord">
-0xC0C0</td>
-<td class="thin_bord">
-Dest = Src1 &
-Src2</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">
-NOTSRCCOPY</td>
-<td class="thin_bord">
-0x3333</td>
-<td class="thin_bord">
-Dest = ~Src1</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">
-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">
-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">
-PATPAINT</td>
-<td class="thin_bord">
-0xFBFB</td>
-<td class="thin_bord">
-Dest = ~Src1 |
-Src2 | 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">
-SRCCOPY</td>
-<td class="thin_bord">
-0xCCCC</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">
-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">
-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">
-WHITENESS</td>
-<td class="thin_bord">
-0xFFFF</td>
-<td class="thin_bord">
-Set all
-destination bits
-to white (1).
-Dest = 1</td>
-</tr>
+ <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>
@@ -1177,623 +1391,659 @@ Dest = 1</td> <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 style="width: 100%">
-<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="indent1">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="indent1">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="indent1">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="indent1">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="indent1">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="indent1">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 />
-<div>
- <p class="indent1">00 00 00: undefined -> zero<br />
- 00 00 01: A1 (preferred)<br />
- 00 00 10: undefined<br />
- 00 00 11: A2 (preferred)<br />
- 00 01 00: 1-A1 (preferred)<br />
- 00 01 01: undefined<br />
- 00 01 10: 1-A1 (use 00 01 00)<br />
- 00 01 11: undefined<br />
- 00 10 00: undefined<br />
- 00 10 01: A1 (use 00 00 01)<br />
- 00 10 10: undefined<br />
- 00 10 11: A2 (use 00 00 11)<br />
- 00 11 00: 1-A2 (preferred)<br />
- 00 11 01: undefined<br />
- 00 11 10: 1-A2 (use 00 11 00)<br />
- 00 11 11: undefined<br />
- <br />
- 01 00 00: min(C1,1-C1)<br />
- 01 00 01: min(A1,1-C1)<br />
- 01 00 10: min(C2,1-C1)<br />
- 01 00 11: min(A2,1-C1)<br />
- 01 01 00: min(C1,1-A1)<br />
- 01 01 01: min(A1,1-A1)<br />
- 01 01 10: min(C2,1-A1)<br />
- 01 01 11: min(A2,1-A1)<br />
- 01 10 00: min(C1,1-C2)<br />
- 01 10 01: min(A1,1-C2)<br />
- 01 10 10: min(C2,1-C2)<br />
- 01 10 11: min(A2,1-C2)<br />
- 01 11 00: min(C1,1-A2)<br />
- 01 11 01: min(A1,1-A2)<br />
- 01 11 10: min(C2,1-A2)<br />
- 01 11 11: min(A2,1-A2)<br />
-<br />
-10 00 00:
-max(C1,1-C1)<br />
-10 00 01:
-max(A1,1-C1)<br />
-10 00 10:
-max(C2,1-C1)<br />
-10 00 11:
-max(A2,1-C1)<br />
-10 01 00:
-max(C1,1-A1)<br />
-10 01 01:
-max(A1,1-A1)<br />
-10 01 10:
-max(C2,1-A1)<br />
-10 01 11:
-max(A2,1-A1)<br />
-10 10 00:
-max(C1,1-C2)<br />
-10 10 01:
-max(A1,1-C2)<br />
-10 10 10:
-max(C2,1-C2)<br />
-10 10 11:
-max(A2,1-C2)<br />
-10 11 00:
-max(C1,1-A2)<br />
-10 11 01:
-max(A1,1-A2)<br />
-10 11 10:
-max(C2,1-A2)<br />
-10 11 11:
-max(A2,1-A2)<br />
-<br />
-11 00 00:
-undefined<br />
-11 00 01: 1-C1
-(use 11 00 11)<br />
-11 00 10:
-undefined<br />
-11 00 11: 1-C1
-(preferred)<br />
-11 01 00: C1
-(use 11 11 00)<br />
-11 01 01:
-undefined<br />
-11 01 10: C2
-(use 11 11 10)<br />
-11 01 11:
-undefined<br />
-11 10 00:
-undefined<br />
-11 10 01: 1-C2
-(use 11 10 11)<br />
-11 10 10:
-undefined<br />
-11 10 11: 1-C2
-(preferred)<br />
-11 11 00: C1
-(preferred)<br />
-11 11 01:
-undefined<br />
-11 11 10: C2
-(preferred)<br />
-11 11 11:
-undefined -> one</p>
-</div>
-<span class="Header4">DirectFB</span><br />
-<br />
-Putting these
-together into
-the proper
-constants, the
-blending
-equations can be
-built for
-DirectFB as
-well:<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 />
-binary value <-
-<span class="inline_code">
-<a href="http://directfb.org/docs/DirectFB_Reference_1_2/IDirectFBSurface_SetSrcBlendFunction.html">
-SetSrcBlendFunction()</a><div>
- <p class="indent1">
-<span class="inline_code">
-[--K1--]
-[--K2--]
-[--K3--]
-[--K4--]<br />
-0000 0000 00 00
-00 xx xx xx 00
-00 00 xx xx xx
-<-
-<a href="http://www.directfb.org/docs/DirectFB_Reference_1_5/types.html#DFBSurfaceBlendFunction">
-DSBF_ZERO</a><br />
-0000 0000 11 11
-11 xx xx xx 11
-11 11 xx xx xx
-<-
-<a href="http://www.directfb.org/docs/DirectFB_Reference_1_5/types.html#DFBSurfaceBlendFunction">
-DSBF_ONE</a><br />
-0000 0000 11 11
-00 xx xx xx 00
-00 01 xx xx xx
-<-
-<a href="http://www.directfb.org/docs/DirectFB_Reference_1_5/types.html#DFBSurfaceBlendFunction">
-DSBF_SRCCOLOR</a><br />
-0000 0000 11 00
-11 xx xx xx 00
-01 00 xx xx xx
-<-
-<a href="http://www.directfb.org/docs/DirectFB_Reference_1_5/types.html#DFBSurfaceBlendFunction">
-DSBF_INVSRCCOLOR</a><br />
-0000 0000 00 00
-01 xx xx xx 00
-00 01 xx xx xx
-<-
-<a href="http://www.directfb.org/docs/DirectFB_Reference_1_5/types.html#DFBSurfaceBlendFunction">
-DSBF_SRCALPHA</a><br />
-0000 0000 00 01
-00 xx xx xx 00
-01 00 xx xx xx
-<-
-<a href="http://www.directfb.org/docs/DirectFB_Reference_1_5/types.html#DFBSurfaceBlendFunction">
-DSBF_INVSRCALPHA</a><br />
-0000 0000 11 11
-10 xx xx xx 00
-00 11 xx xx xx
-<-
-<a href="http://www.directfb.org/docs/DirectFB_Reference_1_5/types.html#DFBSurfaceBlendFunction">
-DSBF_DESTCOLOR</a><br />
-0000 0000 11 10
-11 xx xx xx 00
-11 00 xx xx xx
-<-
-<a href="http://www.directfb.org/docs/DirectFB_Reference_1_5/types.html#DFBSurfaceBlendFunction">
-DSBF_INVDESTCOLOR</a><br />
-0000 0000 00 00
-11 xx xx xx 00
-00 11 xx xx xx
-<-
-<a href="http://www.directfb.org/docs/DirectFB_Reference_1_5/types.html#DFBSurfaceBlendFunction">
-DSBF_DESTALPHA</a><br />
-0000 0000 00 11
-00 xx xx xx 00
-11 00 xx xx xx
-<-
-<a href="http://www.directfb.org/docs/DirectFB_Reference_1_5/types.html#DFBSurfaceBlendFunction">
-DSBF_INVDESTALPHA</a><br />
-0000 0000 01 11
-01 xx xx xx 11
-11 11 xx xx xx
-<-
-<a href="http://www.directfb.org/docs/DirectFB_Reference_1_5/types.html#DFBSurfaceBlendFunction">
-DSBF_SRCALPHASAT</a></span></p>
-</div>
-</span>binary value <-
-<span class="inline_code">
-<a href="http://directfb.org/docs/DirectFB_Reference_1_2/IDirectFBSurface_SetDstBlendFunction.html">
-SetDstBlendFunction()</a><div>
- <p class="indent1">
-[--K1--]
-[--K2--]
-[--K3--]
-[--K4--]<br />
-0000 0000 xx xx
-xx 00 00 00 xx
-xx xx 00 00 00
-<-
-<a href="http://www.directfb.org/docs/DirectFB_Reference_1_5/types.html#DFBSurfaceBlendFunction">
-DSBF_ZERO</a><br />
-0000 0000 xx xx
-xx 11 11 11 xx
-xx xx 11 11 11
-<-
-<a href="http://www.directfb.org/docs/DirectFB_Reference_1_5/types.html#DFBSurfaceBlendFunction">
-DSBF_ONE</a><br />
-0000 0000 xx xx
-xx 11 11 00 xx
-xx xx 00 00 01
-<-
-<a href="http://www.directfb.org/docs/DirectFB_Reference_1_5/types.html#DFBSurfaceBlendFunction">
-DSBF_SRCCOLOR</a><br />
- etc.</p>
-</div>
-</span><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:<span class="inline_code"><div>
- <p class="indent1">params.op.blend
-=
-BVBLEND_SRC1OVER
-+<br />
-
-BVBLENDDEF_GLOBAL_UCHAR;</p>
-</div>
-</span>To include the
-remote alpha,
-the blend could
-be defined like
-this:<span class="inline_code"><div>
- <p class="indent1"><span class="inline_code">params.op.blend
-=
-BVBLEND_SRC1OVER
-+<br />
-
-BVBLENDDEF_REMOTE;</span></p>
-</div>
-</span>And to include
-both:<span class="inline_code"><div>
- <p class="indent1">params.op.blend
-=
-BVBLEND_SRC1OVER
-+<br />
-
-BVBLENDDEF_GLOBAL_UCHAR
-+<br />
-
-BVBLENDDEF_REMOTE;</p>
-</div>
-</span>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 />
-<div>
- <p class="indent1">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></p>
-</div>
-If the format of
-surface 1 is
-non-premultiplied,
-the equations
-are modified to
-include the
-multiplication
-explicitly:<br />
-<div>
- <p class="indent1">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></p>
-</div>
-Likewise, if the
-format of
-surface 2 is
-non-premultiplied,
-the
-equations are
-modified for
-this:<br />
-<div>
- <p class="indent1">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></p>
-</div>
-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 />
-<div>
- <p class="indent1">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><br />
- -or-<br />
- 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><br />
- -or-<br />
- 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></p>
- <p class="indent1"> </p>
-</div>
-<sub> </sub></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="indent1"><code>BVBLEND_LIGHTEN max(src1, src2)
+<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_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_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_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_VIVIDL_IGHT (src2 < 128) ? COLOR_BURN(src1,(2 * src2)) : COLOR_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_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>
+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>
@@ -1806,12 +2056,14 @@ BVBLEND_ALPHA alf * src1 + (1 - alf) * src2) <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>SSubsampled formats do not currently support color keying.</em></p>
+<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
@@ -1819,753 +2071,1655 @@ is the format of the color key if <span class="inline_code">BVFLAG_KEY_DST</span <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>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>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>
-<div class="indent1">
- <table>
-<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>
-</div>
-<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/>
-<div class="indent1">
-<table>
-<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 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>
-</div>
<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>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>
+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
+<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>
-<div class="indent1">
- <table>
-<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>
-</div>
-<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/>
-<div class="indent1">
-<table>
-<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 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>
-</div>
<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>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>
+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><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><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><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: NEVER change the value of bvbuffdesc.virtptr
-while a buffer is mapped.</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 />
+<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>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>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>
-<p>Example:</p>
-<p class="code_block"><a href="#src1rect">src1rect</a> = (0, 0) - (400 x 200)<br />
-<a href="#dstrect">dstrect</a> = (0, 0) - (800 x 600)<br />
-<a href="#cliprect">cliprect</a> = (10, 30) - (300 x 300)</p>
-<p>The scaling ratio of the <span class="inline_code"><a href="#dstrect">dstrect</a></span>
-to the <span class="inline_code"><a href="#src1rect">src1rect</a></span> 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>
-<p>Note that this approach allows fractional clipping at the source using a
-method which is simpler to implement than fractional coordinates.</p>
-<p>The convention in BLTsville is that interpolated scaling (and filtering)
-<span class="underline">can</span> fetch pixels outside of the source rectangle
-if needed for the scaling algorithm, as long as no attempt is made to fetch
-pixels outside of the surface boundaries. <span class="red"><em>Options
-to allow the client to specify limiting the source region are being considered
-at this time.</em></span></p>
-<p class="Code_Header_2">bvbltparams.cliprect</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><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="indent1">
-<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 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="indent1">
-<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>
+<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>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="indent1">
-<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 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">bvbltparams.batchflags</p>
+<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 to indicate to the implementation which
-parameters are changing between successive BLTs of a batch. The flags are
-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">
+<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>
-<p><span class="inline_code"><a name="BVBATCH_OP">BVBATCH_OP</a></span>
-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.</p>
-<p><span class="inline_code"><a name="BVBATCH_KEY">BVBATCH_KEY</a></span>
-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.</p>
-<p><span class="inline_code"><a name="BVBATCH_MISCFLAGS">BVBATCH_MISCFLAGS</a></span>
-indicates that <span class="inline_code"><a href="#flags">bvbltparams.flags</a></span>
-other than the operation, color key, or clip flag have changes.</p>
-<p><span class="inline_code"><a name="BVBATCH_ALPHA">BVBATCH_ALPHA</a></span>
-indicates that <span class="inline_code"><a href="#globalalpha">
-bvbltparams.globalalpha</a></span> or global alpha type has changed.</p>
-<p><a name="BVBATCH_DITHER" class="inline_code">BVBATCH_DITHER</a> indicates
-that <span class="inline_code"><a href="#dithermode">bvbltparams.dithermode</a></span>
-has changed.</p>
-<p><span class="inline_code"><a name="BVBATCH_SCALE">BVBATCH_SCALE</a></span>
-indicates that <span class="inline_code"><a href="#scalemode">
-bvbltparams.scalemode</a></span> has changed.</p>
-<p><span class="inline_code"><a name="BVBATCH_DST">BVBATCH_DST</a></span>
-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.</p>
-<p><span class="inline_code">BVBATCH_SRC1</span> 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.</p>
-<p><span class="inline_code">BVBATCH_SRC2</span> 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.</p>
-<p><span class="inline_code">BVBATCH_MASK</span> 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.</p>
-<p><span class="inline_code"><a name="BVBATCH_DSTRECT_ORIGIN">
-BVBATCH_DSTRECT_ORIGIN</a></span> 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.</p>
-<p><span class="inline_code"><a name="BVBATCH_DSTRECT_SIZE">BVBATCH_DSTRECT_SIZE</a></span>
-indicates that the <span class="inline_code"><a href="#dstrect">
-bvbltparams.dstrect.width</a></span> or <a href="#dstrect">height</a> has
-changed.</p>
-<p><span class="inline_code"><a name="BVBATCH_SRC1RECT_ORIGIN">
-BVBATCH_SRC1RECT_ORIGIN</a></span> 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.</p>
-<p><span class="inline_code"><a name="BVBATCH_SRC1RECT_SIZE">
-BVBATCH_SRC1RECT_SIZE</a></span> indicates that the <span class="inline_code">
-<a href="#src1rect">bvbltparams.src1rect.width</a></span> or <a href="#src1rect">
-height</a> has changed.</p>
-<p><span class="inline_code"><a name="BVBATCH_SRC2RECT_ORIGIN">
-BVBATCH_SRC2RECT_ORIGIN</a></span> 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.</p>
-<p><span class="inline_code"><a name="BVBATCH_SRC2RECT_SIZE">
-BVBATCH_SRC2RECT_SIZE</a></span> indicates that the <span class="inline_code">
-<a href="#src2rect">bvbltparams.src2rect.width</a></span> or <a href="#src2rect">
-height</a> has changed.</p>
-<p><span class="inline_code"><a name="BVBATCH_MASKRECT_ORIGIN">
-BVBATCH_MASKRECT_ORIGIN</a></span> 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.</p>
-<p><span class="inline_code"><a name="BVBATCH_MASKRECT_SIZE">
-BVBATCH_MASKRECT_SIZE</a></span> indicates that the <span class="inline_code">
-<a href="#maskrect">bvbltparams.maskrect.width</a></span> or <a href="#maskrect">
-height</a> has changed.</p>
-<p><span class="inline_code"><a name="BVBATCH_CLIPRECT_ORIGIN">
-BVBATCH_CLIPRECT_ORIGIN</a></span> 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.</p>
-<p><span class="inline_code"><a name="BVBATCH_CLIPRECT_SIZE">
-BVBATCH_CLIPRECT_SIZE</a></span> indicates that the <span class="inline_code">
-<a href="#cliprect">bvbltparams.cliprect.width</a></span> or <a href="#cliprect">
-height</a> has changed.</p>
-<p><span class="inline_code"><a name="BVBATCH_TILE_SRC1">BVBATCH_TILE_SRC1</a></span>
-indicates that the <span class="inline_code"><a href="#src1.tileparams">
-bvbltparams.src1.tileparams</a></span> has changed.</p>
-<p><span class="inline_code"><a name="BVBATCH_TILE_SRC2">BVBATCH_TILE_SRC2</a></span>
-indicates that the <span class="inline_code"><a href="#src2.tileparams">
-bvbltparams.src2.tileparams</a></span>
-has changed.</p>
-<p><span class="inline_code"><a name="BVBATCH_TILE_MASK">BVBATCH_TILE_MASK</a></span>
-indicates that the <span class="inline_code"><a href="#mask.tileparams">
-bvbltparams.mask.tileparams</a></span> has changed.</p>
-<p><span class="inline_code"><a name="BVBATCH_ENDNOP">BVBATCH_ENDNOP</a></span>
-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.</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>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.</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_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>.
+<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>
+<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>
+ <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, as well as no operations performed until the batch
-submission is completed with <a href="#BVFLAG_BATCH_END" class="inline_code">
-BVFLAG_BATCH_END</a>.</p>
+<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="width: 100%" class="glyph_cache">
-<tr>
-<td class="glyph_cache"> !"#$%&'()*+'-./0123456789:;<=>?<br />
-@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_<br />
-`abcdefghijklmnopqrstuvwxyz{|}~</td>
-</tr>
+<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>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 />
+<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 />
+struct bvbltparams bltparams = {sizeof(struct bvbltparams), 0};<br />
<br />
int charsperline = 32;<br />
int fontwidth = 10;<br />
@@ -2595,7 +3749,6 @@ 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 />
@@ -2606,10 +3759,8 @@ bltparams.maskgeom = &glyphcachegeom;<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 />
+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 />
@@ -2619,20 +3770,16 @@ bv_blt(&bltparams);<br /> i++;<br />
if(i < textlen)<br />
{<br />
- bltparams.flags = (bltparams.flags & ~BVFLAG_BATCH_MASK) |
-BVFLAG_BATCH_CONTINUE;<br />
- bltparams.batch = BVBATCH_DSTRECT_ORIGIN | BVBATCH_SRC2RECT_ORIGIN |
-BVBATCH_MASKRECT_ORIGIN;<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 />
+ bltparams.maskrect.left = ((text[i] - ' ') % charsperline) * fontwidth;<br />
+ bltparams.maskrect.top = ((text[i] - ' ') / charsperline) * fontheight;<br />
<br />
bv_blt(&bltparams);<br />
<br />
@@ -2641,30 +3788,28 @@ BVBATCH_MASKRECT_ORIGIN;<br /> }<br />
<br />
bltparams.flags = (bltparams.flags & ~BVFLAG_BATCH_MASK) | BVFLAG_BATCH_END;<br />
-bltparams.batch = BVBATCH_ENDNOP;<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 4 layers at the
-same time. But BLTsville only allows blending to be specified using 2
-layers at a time. How can this be accomplished?</p>
-<p>The most prevalent blending reference used is the Porter-Duff whitepaper,
-which specifies blending of 2 sources. So any N-source blend would require
-the blends to be specified as a grouping of 2 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 />
+<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 />
@@ -2677,8 +3822,7 @@ 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.flags = (bltparams.flags & ~BVFLAG_BATCH_MASK) | BVFLAG_BATCH_CONTINUE;<br />
bltparams.batch = BVBATCH_SRC1 | BVBATCH_SRC2;<br />
<br />
bv_blt(&bltparams);<br />
@@ -2690,57 +3834,232 @@ bltparams.flags = (bltparams.flags & ~BVFLAG_BATCH_MASK) | BVFLAG_BATCH_END; 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 linked.</p>
-<p>The fantastic thing about this approach is that an implementation without the
-ability to blend 4 sources would perform the 3 blends separately, with the
-identical result.</p>
-<p class="note">NOTE: A batch of BLTs may be serviced in any number of
-ways. For example, one implementation may perform each BLT as it is
-submitted, while another may take no action until the
-<a href="#BVFLAG_BATCH_END" class="inline_code">BVFLAG_BATCH_END</a> BLT is
-encountered. As a result, the client must be careful not to rely on any intermediate results. (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>
-<p class="note">NOTE: Failure during the performance of a batch (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>
-<hr />
-<p class="Code_Header"><a name="bvcallbackerror">bvcallbackerror</a></p>
-<p class="code_block">struct bvcallbackerror {<br />
- unsigned int structsize;<br />
- <a href="#bverror">enum bverror</a>
-error;<br />
- char* errdesc;<br />
-};</p>
-<p class="Code_Header_2"><a name="bvcallbackerror.structsize">
-bvcallbackerror.structsize</a></p>
-<p> </p>
-<p class="Code_Header_2"><a name="bvcallbackerror.error">bvcallbackerror.error</a></p>
-<p> </p>
-<p class="Code_Header_2"><a name="bvcallbackerror.errdesc">
-bvcallbackerror.errdesc</a></p>
-<p> </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><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 />
@@ -2748,14 +4067,12 @@ operating system. For example, Linux might do this like this:</p> BVFN_MAP bv_map;<br />
BVFN_BLT bv_blt;<br />
BVFN_UNMAP bv_unmap;<br />
-
-}; <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 />
@@ -2763,219 +4080,139 @@ 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="indent1">
-<tr>
-<td valign="top">
-<p class="small_code_block_in_table">struct
-bvbuffdesc
-buff =<br />
-
+<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 style="width: 30px" class="center">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>
+ <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="indent1">
-<tr>
-<td valign="top">
-<p class="small_code_block_in_table">/* do
-nothing */ </p>
-</td>
-<td style="width: 30px" class="center">or</td>
-<td valign="top">
-<p class="small_code_block_in_table">bvlib[0].bv_map(&buff); </p>
-
-</td>
-<td style="width: 30px" class="center">or</td>
-<td valign="top">
-<p class="small_code_block_in_table">for(int i =
-0; i < NUMLIBS; i++)<br />
-{<br />
+<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>
+ }</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 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="indent1">
-
-<tr>
-<td valign="top">
-<p class="small_code_block_in_table">struct bvsurfgeom
-geom =<br />
-
+<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 style="width: 30px" class="center">or</td>
-<td valign="top">
-<p class="inline_code">
-<span class="small_code_block_in_table">struct
-bvsurfgeom geom;<br />
-<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>
+ <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 />
+<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 />
@@ -2984,18 +4221,141 @@ 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>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>
+<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>
diff --git a/bltsville/ocdtab.png b/bltsville/ocdtab.png Binary files differindex 239c9bb..239c9bb 100755..100644 --- a/bltsville/ocdtab.png +++ b/bltsville/ocdtab.png |
