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