blob: 08abd8ee56a4c9b6f2176e2a936b46240343fd22 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.10">
<title>cl_img_use_gralloc_ptr</title>
<style>
/*! normalize.css v2.1.2 | MIT License | git.io/normalize */
/* ========================================================================== HTML5 display definitions ========================================================================== */
/** Correct `block` display not defined in IE 8/9. */
article, aside, details, figcaption, figure, footer, header, hgroup, main, nav, section, summary { display: block; }
/** Correct `inline-block` display not defined in IE 8/9. */
audio, canvas, video { display: inline-block; }
/** Prevent modern browsers from displaying `audio` without controls. Remove excess height in iOS 5 devices. */
audio:not([controls]) { display: none; height: 0; }
/** Address `[hidden]` styling not present in IE 8/9. Hide the `template` element in IE, Safari, and Firefox < 22. */
[hidden], template { display: none; }
script { display: none !important; }
/* ========================================================================== Base ========================================================================== */
/** 1. Set default font family to sans-serif. 2. Prevent iOS text size adjust after orientation change, without disabling user zoom. */
html { font-family: sans-serif; /* 1 */ -ms-text-size-adjust: 100%; /* 2 */ -webkit-text-size-adjust: 100%; /* 2 */ }
/** Remove default margin. */
body { margin: 0; }
/* ========================================================================== Links ========================================================================== */
/** Remove the gray background color from active links in IE 10. */
a { background: transparent; }
/** Address `outline` inconsistency between Chrome and other browsers. */
a:focus { outline: thin dotted; }
/** Improve readability when focused and also mouse hovered in all browsers. */
a:active, a:hover { outline: 0; }
/* ========================================================================== Typography ========================================================================== */
/** Address variable `h1` font-size and margin within `section` and `article` contexts in Firefox 4+, Safari 5, and Chrome. */
h1 { font-size: 2em; margin: 0.67em 0; }
/** Address styling not present in IE 8/9, Safari 5, and Chrome. */
abbr[title] { border-bottom: 1px dotted; }
/** Address style set to `bolder` in Firefox 4+, Safari 5, and Chrome. */
b, strong { font-weight: bold; }
/** Address styling not present in Safari 5 and Chrome. */
dfn { font-style: italic; }
/** Address differences between Firefox and other browsers. */
hr { -moz-box-sizing: content-box; box-sizing: content-box; height: 0; }
/** Address styling not present in IE 8/9. */
mark { background: #ff0; color: #000; }
/** Correct font family set oddly in Safari 5 and Chrome. */
code, kbd, pre, samp { font-family: monospace, serif; font-size: 1em; }
/** Improve readability of pre-formatted text in all browsers. */
pre { white-space: pre-wrap; }
/** Set consistent quote types. */
q { quotes: "\201C" "\201D" "\2018" "\2019"; }
/** Address inconsistent and variable font size in all browsers. */
small { font-size: 80%; }
/** Prevent `sub` and `sup` affecting `line-height` in all browsers. */
sub, sup { font-size: 75%; line-height: 0; position: relative; vertical-align: baseline; }
sup { top: -0.5em; }
sub { bottom: -0.25em; }
/* ========================================================================== Embedded content ========================================================================== */
/** Remove border when inside `a` element in IE 8/9. */
img { border: 0; }
/** Correct overflow displayed oddly in IE 9. */
svg:not(:root) { overflow: hidden; }
/* ========================================================================== Figures ========================================================================== */
/** Address margin not present in IE 8/9 and Safari 5. */
figure { margin: 0; }
/* ========================================================================== Forms ========================================================================== */
/** Define consistent border, margin, and padding. */
fieldset { border: 1px solid #c0c0c0; margin: 0 2px; padding: 0.35em 0.625em 0.75em; }
/** 1. Correct `color` not being inherited in IE 8/9. 2. Remove padding so people aren't caught out if they zero out fieldsets. */
legend { border: 0; /* 1 */ padding: 0; /* 2 */ }
/** 1. Correct font family not being inherited in all browsers. 2. Correct font size not being inherited in all browsers. 3. Address margins set differently in Firefox 4+, Safari 5, and Chrome. */
button, input, select, textarea { font-family: inherit; /* 1 */ font-size: 100%; /* 2 */ margin: 0; /* 3 */ }
/** Address Firefox 4+ setting `line-height` on `input` using `!important` in the UA stylesheet. */
button, input { line-height: normal; }
/** Address inconsistent `text-transform` inheritance for `button` and `select`. All other form control elements do not inherit `text-transform` values. Correct `button` style inheritance in Chrome, Safari 5+, and IE 8+. Correct `select` style inheritance in Firefox 4+ and Opera. */
button, select { text-transform: none; }
/** 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio` and `video` controls. 2. Correct inability to style clickable `input` types in iOS. 3. Improve usability and consistency of cursor style between image-type `input` and others. */
button, html input[type="button"], input[type="reset"], input[type="submit"] { -webkit-appearance: button; /* 2 */ cursor: pointer; /* 3 */ }
/** Re-set default cursor for disabled elements. */
button[disabled], html input[disabled] { cursor: default; }
/** 1. Address box sizing set to `content-box` in IE 8/9. 2. Remove excess padding in IE 8/9. */
input[type="checkbox"], input[type="radio"] { box-sizing: border-box; /* 1 */ padding: 0; /* 2 */ }
/** 1. Address `appearance` set to `searchfield` in Safari 5 and Chrome. 2. Address `box-sizing` set to `border-box` in Safari 5 and Chrome (include `-moz` to future-proof). */
input[type="search"] { -webkit-appearance: textfield; /* 1 */ -moz-box-sizing: content-box; -webkit-box-sizing: content-box; /* 2 */ box-sizing: content-box; }
/** Remove inner padding and search cancel button in Safari 5 and Chrome on OS X. */
input[type="search"]::-webkit-search-cancel-button, input[type="search"]::-webkit-search-decoration { -webkit-appearance: none; }
/** Remove inner padding and border in Firefox 4+. */
button::-moz-focus-inner, input::-moz-focus-inner { border: 0; padding: 0; }
/** 1. Remove default vertical scrollbar in IE 8/9. 2. Improve readability and alignment in all browsers. */
textarea { overflow: auto; /* 1 */ vertical-align: top; /* 2 */ }
/* ========================================================================== Tables ========================================================================== */
/** Remove most spacing between table cells. */
table { border-collapse: collapse; border-spacing: 0; }
meta.foundation-mq-small { font-family: "only screen and (min-width: 768px)"; width: 768px; }
meta.foundation-mq-medium { font-family: "only screen and (min-width:1280px)"; width: 1280px; }
meta.foundation-mq-large { font-family: "only screen and (min-width:1440px)"; width: 1440px; }
*, *:before, *:after { -moz-box-sizing: border-box; -webkit-box-sizing: border-box; box-sizing: border-box; }
html, body { font-size: 100%; }
body { background: white; color: #222222; padding: 0; margin: 0; font-family: "Helvetica Neue", "Helvetica", Helvetica, Arial, sans-serif; font-weight: normal; font-style: normal; line-height: 1; position: relative; cursor: auto; }
a:hover { cursor: pointer; }
img, object, embed { max-width: 100%; height: auto; }
object, embed { height: 100%; }
img { -ms-interpolation-mode: bicubic; }
#map_canvas img, #map_canvas embed, #map_canvas object, .map_canvas img, .map_canvas embed, .map_canvas object { max-width: none !important; }
.left { float: left !important; }
.right { float: right !important; }
.text-left { text-align: left !important; }
.text-right { text-align: right !important; }
.text-center { text-align: center !important; }
.text-justify { text-align: justify !important; }
.hide { display: none; }
.antialiased { -webkit-font-smoothing: antialiased; }
img { display: inline-block; vertical-align: middle; }
textarea { height: auto; min-height: 50px; }
select { width: 100%; }
object, svg { display: inline-block; vertical-align: middle; }
.center { margin-left: auto; margin-right: auto; }
.spread { width: 100%; }
p.lead, .paragraph.lead > p, #preamble > .sectionbody > .paragraph:first-of-type p { font-size: 1.21875em; line-height: 1.6; }
.subheader, .admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { line-height: 1.4; color: black; font-weight: 300; margin-top: 0.2em; margin-bottom: 0.5em; }
/* Typography resets */
div, dl, dt, dd, ul, ol, li, h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6, pre, form, p, blockquote, th, td { margin: 0; padding: 0; direction: ltr; }
/* Default Link Styles */
a { color: #0068b0; text-decoration: none; line-height: inherit; }
a:hover, a:focus { color: #333333; }
a img { border: none; }
/* Default paragraph styles */
p { font-family: Noto, sans-serif; font-weight: normal; font-size: 1em; line-height: 1.6; margin-bottom: 0.75em; text-rendering: optimizeLegibility; }
p aside { font-size: 0.875em; line-height: 1.35; font-style: italic; }
/* Default header styles */
h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { font-family: Noto, sans-serif; font-weight: normal; font-style: normal; color: black; text-rendering: optimizeLegibility; margin-top: 0.5em; margin-bottom: 0.5em; line-height: 1.2125em; }
h1 small, h2 small, h3 small, #toctitle small, .sidebarblock > .content > .title small, h4 small, h5 small, h6 small { font-size: 60%; color: #4d4d4d; line-height: 0; }
h1 { font-size: 2.125em; }
h2 { font-size: 1.6875em; }
h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.375em; }
h4 { font-size: 1.125em; }
h5 { font-size: 1.125em; }
h6 { font-size: 1em; }
hr { border: solid #dddddd; border-width: 1px 0 0; clear: both; margin: 1.25em 0 1.1875em; height: 0; }
/* Helpful Typography Defaults */
em, i { font-style: italic; line-height: inherit; }
strong, b { font-weight: bold; line-height: inherit; }
small { font-size: 60%; line-height: inherit; }
code { font-family: Consolas, "Liberation Mono", Courier, monospace; font-weight: normal; color: #264357; }
/* Lists */
ul, ol, dl { font-size: 1em; line-height: 1.6; margin-bottom: 0.75em; list-style-position: outside; font-family: Noto, sans-serif; }
ul, ol { margin-left: 1.5em; }
ul.no-bullet, ol.no-bullet { margin-left: 1.5em; }
/* Unordered Lists */
ul li ul, ul li ol { margin-left: 1.25em; margin-bottom: 0; font-size: 1em; /* Override nested font-size change */ }
ul.square li ul, ul.circle li ul, ul.disc li ul { list-style: inherit; }
ul.square { list-style-type: square; }
ul.circle { list-style-type: circle; }
ul.disc { list-style-type: disc; }
ul.no-bullet { list-style: none; }
/* Ordered Lists */
ol li ul, ol li ol { margin-left: 1.25em; margin-bottom: 0; }
/* Definition Lists */
dl dt { margin-bottom: 0.3em; font-weight: bold; }
dl dd { margin-bottom: 0.75em; }
/* Abbreviations */
abbr, acronym { text-transform: uppercase; font-size: 90%; color: black; border-bottom: 1px dotted #dddddd; cursor: help; }
abbr { text-transform: none; }
/* Blockquotes */
blockquote { margin: 0 0 0.75em; padding: 0.5625em 1.25em 0 1.1875em; border-left: 1px solid #dddddd; }
blockquote cite { display: block; font-size: 0.8125em; color: #5e93b8; }
blockquote cite:before { content: "\2014 \0020"; }
blockquote cite a, blockquote cite a:visited { color: #5e93b8; }
blockquote, blockquote p { line-height: 1.6; color: #333333; }
/* Microformats */
.vcard { display: inline-block; margin: 0 0 1.25em 0; border: 1px solid #dddddd; padding: 0.625em 0.75em; }
.vcard li { margin: 0; display: block; }
.vcard .fn { font-weight: bold; font-size: 0.9375em; }
.vevent .summary { font-weight: bold; }
.vevent abbr { cursor: auto; text-decoration: none; font-weight: bold; border: none; padding: 0 0.0625em; }
@media only screen and (min-width: 768px) { h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.4; }
h1 { font-size: 2.75em; }
h2 { font-size: 2.3125em; }
h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.6875em; }
h4 { font-size: 1.4375em; } }
/* Tables */
table { background: white; margin-bottom: 1.25em; border: solid 1px #d8d8ce; }
table thead, table tfoot { background: -webkit-linear-gradient(top, #add386, #90b66a); font-weight: bold; }
table thead tr th, table thead tr td, table tfoot tr th, table tfoot tr td { padding: 0.5em 0.625em 0.625em; font-size: inherit; color: white; text-align: left; }
table tr th, table tr td { padding: 0.5625em 0.625em; font-size: inherit; color: #6d6e71; }
table tr.even, table tr.alt, table tr:nth-of-type(even) { background: #edf2f2; }
table thead tr th, table tfoot tr th, table tbody tr td, table tr td, table tfoot tr td { display: table-cell; line-height: 1.4; }
body { -moz-osx-font-smoothing: grayscale; -webkit-font-smoothing: antialiased; tab-size: 4; }
h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.4; }
a:hover, a:focus { text-decoration: underline; }
.clearfix:before, .clearfix:after, .float-group:before, .float-group:after { content: " "; display: table; }
.clearfix:after, .float-group:after { clear: both; }
*:not(pre) > code { font-size: inherit; font-style: normal !important; letter-spacing: 0; padding: 0; background-color: white; -webkit-border-radius: 0; border-radius: 0; line-height: inherit; word-wrap: break-word; }
*:not(pre) > code.nobreak { word-wrap: normal; }
*:not(pre) > code.nowrap { white-space: nowrap; }
pre, pre > code { line-height: 1.6; color: #264357; font-family: Consolas, "Liberation Mono", Courier, monospace; font-weight: normal; }
em em { font-style: normal; }
strong strong { font-weight: normal; }
.keyseq { color: #333333; }
kbd { font-family: Consolas, "Liberation Mono", Courier, monospace; display: inline-block; color: black; font-size: 0.65em; line-height: 1.45; background-color: #f7f7f7; border: 1px solid #ccc; -webkit-border-radius: 3px; border-radius: 3px; -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; margin: 0 0.15em; padding: 0.2em 0.5em; vertical-align: middle; position: relative; top: -0.1em; white-space: nowrap; }
.keyseq kbd:first-child { margin-left: 0; }
.keyseq kbd:last-child { margin-right: 0; }
.menuseq, .menuref { color: #000; }
.menuseq b:not(.caret), .menuref { font-weight: inherit; }
.menuseq { word-spacing: -0.02em; }
.menuseq b.caret { font-size: 1.25em; line-height: 0.8; }
.menuseq i.caret { font-weight: bold; text-align: center; width: 0.45em; }
b.button:before, b.button:after { position: relative; top: -1px; font-weight: normal; }
b.button:before { content: "["; padding: 0 3px 0 2px; }
b.button:after { content: "]"; padding: 0 2px 0 3px; }
#header, #content, #footnotes, #footer { width: 100%; margin-left: auto; margin-right: auto; margin-top: 0; margin-bottom: 0; max-width: 62.5em; *zoom: 1; position: relative; padding-left: 1.5em; padding-right: 1.5em; }
#header:before, #header:after, #content:before, #content:after, #footnotes:before, #footnotes:after, #footer:before, #footer:after { content: " "; display: table; }
#header:after, #content:after, #footnotes:after, #footer:after { clear: both; }
#content { margin-top: 1.25em; }
#content:before { content: none; }
#header > h1:first-child { color: black; margin-top: 2.25rem; margin-bottom: 0; }
#header > h1:first-child + #toc { margin-top: 8px; border-top: 1px solid #dddddd; }
#header > h1:only-child, body.toc2 #header > h1:nth-last-child(2) { border-bottom: 1px solid #dddddd; padding-bottom: 8px; }
#header .details { border-bottom: 1px solid #dddddd; line-height: 1.45; padding-top: 0.25em; padding-bottom: 0.25em; padding-left: 0.25em; color: #5e93b8; display: -ms-flexbox; display: -webkit-flex; display: flex; -ms-flex-flow: row wrap; -webkit-flex-flow: row wrap; flex-flow: row wrap; }
#header .details span:first-child { margin-left: -0.125em; }
#header .details span.email a { color: #333333; }
#header .details br { display: none; }
#header .details br + span:before { content: "\00a0\2013\00a0"; }
#header .details br + span.author:before { content: "\00a0\22c5\00a0"; color: #333333; }
#header .details br + span#revremark:before { content: "\00a0|\00a0"; }
#header #revnumber { text-transform: capitalize; }
#header #revnumber:after { content: "\00a0"; }
#content > h1:first-child:not([class]) { color: black; border-bottom: 1px solid #dddddd; padding-bottom: 8px; margin-top: 0; padding-top: 1rem; margin-bottom: 1.25rem; }
#toc { border-bottom: 0 solid #dddddd; padding-bottom: 0.5em; }
#toc > ul { margin-left: 0.125em; }
#toc ul.sectlevel0 > li > a { font-style: italic; }
#toc ul.sectlevel0 ul.sectlevel1 { margin: 0.5em 0; }
#toc ul { font-family: Noto, sans-serif; list-style-type: none; }
#toc li { line-height: 1.3334; margin-top: 0.3334em; }
#toc a { text-decoration: none; }
#toc a:active { text-decoration: underline; }
#toctitle { color: black; font-size: 1.2em; }
@media only screen and (min-width: 768px) { #toctitle { font-size: 1.375em; }
body.toc2 { padding-left: 15em; padding-right: 0; }
#toc.toc2 { margin-top: 0 !important; background-color: white; position: fixed; width: 15em; left: 0; top: 0; border-right: 1px solid #dddddd; border-top-width: 0 !important; border-bottom-width: 0 !important; z-index: 1000; padding: 1.25em 1em; height: 100%; overflow: auto; }
#toc.toc2 #toctitle { margin-top: 0; margin-bottom: 0.8rem; font-size: 1.2em; }
#toc.toc2 > ul { font-size: 0.9em; margin-bottom: 0; }
#toc.toc2 ul ul { margin-left: 0; padding-left: 1em; }
#toc.toc2 ul.sectlevel0 ul.sectlevel1 { padding-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; }
body.toc2.toc-right { padding-left: 0; padding-right: 15em; }
body.toc2.toc-right #toc.toc2 { border-right-width: 0; border-left: 1px solid #dddddd; left: auto; right: 0; } }
@media only screen and (min-width: 1280px) { body.toc2 { padding-left: 20em; padding-right: 0; }
#toc.toc2 { width: 20em; }
#toc.toc2 #toctitle { font-size: 1.375em; }
#toc.toc2 > ul { font-size: 0.95em; }
#toc.toc2 ul ul { padding-left: 1.25em; }
body.toc2.toc-right { padding-left: 0; padding-right: 20em; } }
#content #toc { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: white; -webkit-border-radius: 0; border-radius: 0; }
#content #toc > :first-child { margin-top: 0; }
#content #toc > :last-child { margin-bottom: 0; }
#footer { max-width: 100%; background-color: none; padding: 1.25em; }
#footer-text { color: black; line-height: 1.44; }
#content { margin-bottom: 0.625em; }
.sect1 { padding-bottom: 0.625em; }
@media only screen and (min-width: 768px) { #content { margin-bottom: 1.25em; }
.sect1 { padding-bottom: 1.25em; } }
.sect1:last-child { padding-bottom: 0; }
.sect1 + .sect1 { border-top: 0 solid #dddddd; }
#content h1 > a.anchor, h2 > a.anchor, h3 > a.anchor, #toctitle > a.anchor, .sidebarblock > .content > .title > a.anchor, h4 > a.anchor, h5 > a.anchor, h6 > a.anchor { position: absolute; z-index: 1001; width: 1.5ex; margin-left: -1.5ex; display: block; text-decoration: none !important; visibility: hidden; text-align: center; font-weight: normal; }
#content h1 > a.anchor:before, h2 > a.anchor:before, h3 > a.anchor:before, #toctitle > a.anchor:before, .sidebarblock > .content > .title > a.anchor:before, h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { content: "\00A7"; font-size: 0.85em; display: block; padding-top: 0.1em; }
#content h1:hover > a.anchor, #content h1 > a.anchor:hover, h2:hover > a.anchor, h2 > a.anchor:hover, h3:hover > a.anchor, #toctitle:hover > a.anchor, .sidebarblock > .content > .title:hover > a.anchor, h3 > a.anchor:hover, #toctitle > a.anchor:hover, .sidebarblock > .content > .title > a.anchor:hover, h4:hover > a.anchor, h4 > a.anchor:hover, h5:hover > a.anchor, h5 > a.anchor:hover, h6:hover > a.anchor, h6 > a.anchor:hover { visibility: visible; }
#content h1 > a.link, h2 > a.link, h3 > a.link, #toctitle > a.link, .sidebarblock > .content > .title > a.link, h4 > a.link, h5 > a.link, h6 > a.link { color: black; text-decoration: none; }
#content h1 > a.link:hover, h2 > a.link:hover, h3 > a.link:hover, #toctitle > a.link:hover, .sidebarblock > .content > .title > a.link:hover, h4 > a.link:hover, h5 > a.link:hover, h6 > a.link:hover { color: black; }
.audioblock, .imageblock, .literalblock, .listingblock, .stemblock, .videoblock { margin-bottom: 1.25em; }
.admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { text-rendering: optimizeLegibility; text-align: left; }
table.tableblock > caption.title { white-space: nowrap; overflow: visible; max-width: 0; }
.paragraph.lead > p, #preamble > .sectionbody > .paragraph:first-of-type p { color: black; }
table.tableblock #preamble > .sectionbody > .paragraph:first-of-type p { font-size: inherit; }
.admonitionblock > table { border-collapse: separate; border: 0; background: none; width: 100%; }
.admonitionblock > table td.icon { text-align: center; width: 80px; }
.admonitionblock > table td.icon img { max-width: initial; }
.admonitionblock > table td.icon .title { font-weight: bold; font-family: Noto, sans-serif; text-transform: uppercase; }
.admonitionblock > table td.content { padding-left: 1.125em; padding-right: 1.25em; border-left: 1px solid #dddddd; color: #5e93b8; }
.admonitionblock > table td.content > :last-child > :last-child { margin-bottom: 0; }
.exampleblock > .content { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: white; -webkit-border-radius: 0; border-radius: 0; }
.exampleblock > .content > :first-child { margin-top: 0; }
.exampleblock > .content > :last-child { margin-bottom: 0; }
.sidebarblock { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: white; -webkit-border-radius: 0; border-radius: 0; }
.sidebarblock > :first-child { margin-top: 0; }
.sidebarblock > :last-child { margin-bottom: 0; }
.sidebarblock > .content > .title { color: black; margin-top: 0; }
.exampleblock > .content > :last-child > :last-child, .exampleblock > .content .olist > ol > li:last-child > :last-child, .exampleblock > .content .ulist > ul > li:last-child > :last-child, .exampleblock > .content .qlist > ol > li:last-child > :last-child, .sidebarblock > .content > :last-child > :last-child, .sidebarblock > .content .olist > ol > li:last-child > :last-child, .sidebarblock > .content .ulist > ul > li:last-child > :last-child, .sidebarblock > .content .qlist > ol > li:last-child > :last-child { margin-bottom: 0; }
.literalblock pre, .listingblock pre:not(.highlight), .listingblock pre[class="highlight"], .listingblock pre[class^="highlight "], .listingblock pre.CodeRay, .listingblock pre.prettyprint { background: #eeeeee; }
.sidebarblock .literalblock pre, .sidebarblock .listingblock pre:not(.highlight), .sidebarblock .listingblock pre[class="highlight"], .sidebarblock .listingblock pre[class^="highlight "], .sidebarblock .listingblock pre.CodeRay, .sidebarblock .listingblock pre.prettyprint { background: #f2f1f1; }
.literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { border: 1px hidden #666666; -webkit-border-radius: 0; border-radius: 0; word-wrap: break-word; padding: 1.25em 1.5625em 1.125em 1.5625em; font-size: 0.8125em; }
.literalblock pre.nowrap, .literalblock pre[class].nowrap, .listingblock pre.nowrap, .listingblock pre[class].nowrap { overflow-x: auto; white-space: pre; word-wrap: normal; }
@media only screen and (min-width: 768px) { .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { font-size: 0.90625em; } }
@media only screen and (min-width: 1280px) { .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] { font-size: 1em; } }
.literalblock.output pre { color: #eeeeee; background-color: #264357; }
.listingblock pre.highlightjs { padding: 0; }
.listingblock pre.highlightjs > code { padding: 1.25em 1.5625em 1.125em 1.5625em; -webkit-border-radius: 0; border-radius: 0; }
.listingblock > .content { position: relative; }
.listingblock code[data-lang]:before { display: none; content: attr(data-lang); position: absolute; font-size: 0.75em; top: 0.425rem; right: 0.5rem; line-height: 1; text-transform: uppercase; color: #999; }
.listingblock:hover code[data-lang]:before { display: block; }
.listingblock.terminal pre .command:before { content: attr(data-prompt); padding-right: 0.5em; color: #999; }
.listingblock.terminal pre .command:not([data-prompt]):before { content: "$"; }
table.pyhltable { border-collapse: separate; border: 0; margin-bottom: 0; background: none; }
table.pyhltable td { vertical-align: top; padding-top: 0; padding-bottom: 0; line-height: 1.6; }
table.pyhltable td.code { padding-left: .75em; padding-right: 0; }
pre.pygments .lineno, table.pyhltable td:not(.code) { color: #999; padding-left: 0; padding-right: .5em; border-right: 1px solid #dddddd; }
pre.pygments .lineno { display: inline-block; margin-right: .25em; }
table.pyhltable .linenodiv { background: none !important; padding-right: 0 !important; }
.quoteblock { margin: 0 1em 0.75em 1.5em; display: table; }
.quoteblock > .title { margin-left: -1.5em; margin-bottom: 0.75em; }
.quoteblock blockquote, .quoteblock blockquote p { color: #333333; font-size: 1.15rem; line-height: 1.75; word-spacing: 0.1em; letter-spacing: 0; font-style: italic; text-align: justify; }
.quoteblock blockquote { margin: 0; padding: 0; border: 0; }
.quoteblock blockquote:before { content: "\201c"; float: left; font-size: 2.75em; font-weight: bold; line-height: 0.6em; margin-left: -0.6em; color: black; text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1); }
.quoteblock blockquote > .paragraph:last-child p { margin-bottom: 0; }
.quoteblock .attribution { margin-top: 0.5em; margin-right: 0.5ex; text-align: right; }
.quoteblock .quoteblock { margin-left: 0; margin-right: 0; padding: 0.5em 0; border-left: 3px solid #5e93b8; }
.quoteblock .quoteblock blockquote { padding: 0 0 0 0.75em; }
.quoteblock .quoteblock blockquote:before { display: none; }
.verseblock { margin: 0 1em 0.75em 1em; }
.verseblock pre { font-family: "Open Sans", "DejaVu Sans", sans; font-size: 1.15rem; color: #333333; font-weight: 300; text-rendering: optimizeLegibility; }
.verseblock pre strong { font-weight: 400; }
.verseblock .attribution { margin-top: 1.25rem; margin-left: 0.5ex; }
.quoteblock .attribution, .verseblock .attribution { font-size: 0.8125em; line-height: 1.45; font-style: italic; }
.quoteblock .attribution br, .verseblock .attribution br { display: none; }
.quoteblock .attribution cite, .verseblock .attribution cite { display: block; letter-spacing: -0.025em; color: #5e93b8; }
.quoteblock.abstract { margin: 0 0 0.75em 0; display: block; }
.quoteblock.abstract blockquote, .quoteblock.abstract blockquote p { text-align: left; word-spacing: 0; }
.quoteblock.abstract blockquote:before, .quoteblock.abstract blockquote p:first-of-type:before { display: none; }
table.tableblock { max-width: 100%; border-collapse: separate; }
table.tableblock td > .paragraph:last-child p > p:last-child, table.tableblock th > p:last-child, table.tableblock td > p:last-child { margin-bottom: 0; }
table.tableblock, th.tableblock, td.tableblock { border: 0 solid #d8d8ce; }
table.grid-all > thead > tr > .tableblock, table.grid-all > tbody > tr > .tableblock { border-width: 0 1px 1px 0; }
table.grid-all > tfoot > tr > .tableblock { border-width: 1px 1px 0 0; }
table.grid-cols > * > tr > .tableblock { border-width: 0 1px 0 0; }
table.grid-rows > thead > tr > .tableblock, table.grid-rows > tbody > tr > .tableblock { border-width: 0 0 1px 0; }
table.grid-rows > tfoot > tr > .tableblock { border-width: 1px 0 0 0; }
table.grid-all > * > tr > .tableblock:last-child, table.grid-cols > * > tr > .tableblock:last-child { border-right-width: 0; }
table.grid-all > tbody > tr:last-child > .tableblock, table.grid-all > thead:last-child > tr > .tableblock, table.grid-rows > tbody > tr:last-child > .tableblock, table.grid-rows > thead:last-child > tr > .tableblock { border-bottom-width: 0; }
table.frame-all { border-width: 1px; }
table.frame-sides { border-width: 0 1px; }
table.frame-topbot { border-width: 1px 0; }
th.halign-left, td.halign-left { text-align: left; }
th.halign-right, td.halign-right { text-align: right; }
th.halign-center, td.halign-center { text-align: center; }
th.valign-top, td.valign-top { vertical-align: top; }
th.valign-bottom, td.valign-bottom { vertical-align: bottom; }
th.valign-middle, td.valign-middle { vertical-align: middle; }
table thead th, table tfoot th { font-weight: bold; }
tbody tr th { display: table-cell; line-height: 1.4; background: -webkit-linear-gradient(top, #add386, #90b66a); }
tbody tr th, tbody tr th p, tfoot tr th, tfoot tr th p { color: white; font-weight: bold; }
p.tableblock > code:only-child { background: none; padding: 0; }
p.tableblock { font-size: 1em; }
td > div.verse { white-space: pre; }
ol { margin-left: 1.75em; }
ul li ol { margin-left: 1.5em; }
dl dd { margin-left: 1.125em; }
dl dd:last-child, dl dd:last-child > :last-child { margin-bottom: 0; }
ol > li p, ul > li p, ul dd, ol dd, .olist .olist, .ulist .ulist, .ulist .olist, .olist .ulist { margin-bottom: 0.375em; }
ul.checklist, ul.none, ol.none, ul.no-bullet, ol.no-bullet, ol.unnumbered, ul.unstyled, ol.unstyled { list-style-type: none; }
ul.no-bullet, ol.no-bullet, ol.unnumbered { margin-left: 0.625em; }
ul.unstyled, ol.unstyled { margin-left: 0; }
ul.checklist { margin-left: 0.625em; }
ul.checklist li > p:first-child > .fa-square-o:first-child, ul.checklist li > p:first-child > .fa-check-square-o:first-child { width: 1.25em; font-size: 0.8em; position: relative; bottom: 0.125em; }
ul.checklist li > p:first-child > input[type="checkbox"]:first-child { margin-right: 0.25em; }
ul.inline { display: -ms-flexbox; display: -webkit-box; display: flex; -ms-flex-flow: row wrap; -webkit-flex-flow: row wrap; flex-flow: row wrap; list-style: none; margin: 0 0 0.375em -0.75em; }
ul.inline > li { margin-left: 0.75em; }
.unstyled dl dt { font-weight: normal; font-style: normal; }
ol.arabic { list-style-type: decimal; }
ol.decimal { list-style-type: decimal-leading-zero; }
ol.loweralpha { list-style-type: lower-alpha; }
ol.upperalpha { list-style-type: upper-alpha; }
ol.lowerroman { list-style-type: lower-roman; }
ol.upperroman { list-style-type: upper-roman; }
ol.lowergreek { list-style-type: lower-greek; }
.hdlist > table, .colist > table { border: 0; background: none; }
.hdlist > table > tbody > tr, .colist > table > tbody > tr { background: none; }
td.hdlist1, td.hdlist2 { vertical-align: top; padding: 0 0.625em; }
td.hdlist1 { font-weight: bold; padding-bottom: 0.75em; }
.literalblock + .colist, .listingblock + .colist { margin-top: -0.5em; }
.colist > table tr > td:first-of-type { padding: 0.4em 0.75em 0 0.75em; line-height: 1; vertical-align: top; }
.colist > table tr > td:first-of-type img { max-width: initial; }
.colist > table tr > td:last-of-type { padding: 0.25em 0; }
.thumb, .th { line-height: 0; display: inline-block; border: solid 4px white; -webkit-box-shadow: 0 0 0 1px #dddddd; box-shadow: 0 0 0 1px #dddddd; }
.imageblock.left, .imageblock[style*="float: left"] { margin: 0.25em 0.625em 1.25em 0; }
.imageblock.right, .imageblock[style*="float: right"] { margin: 0.25em 0 1.25em 0.625em; }
.imageblock > .title { margin-bottom: 0; }
.imageblock.thumb, .imageblock.th { border-width: 6px; }
.imageblock.thumb > .title, .imageblock.th > .title { padding: 0 0.125em; }
.image.left, .image.right { margin-top: 0.25em; margin-bottom: 0.25em; display: inline-block; line-height: 0; }
.image.left { margin-right: 0.625em; }
.image.right { margin-left: 0.625em; }
a.image { text-decoration: none; display: inline-block; }
a.image object { pointer-events: none; }
sup.footnote, sup.footnoteref { font-size: 0.875em; position: static; vertical-align: super; }
sup.footnote a, sup.footnoteref a { text-decoration: none; }
sup.footnote a:active, sup.footnoteref a:active { text-decoration: underline; }
#footnotes { padding-top: 0.75em; padding-bottom: 0.75em; margin-bottom: 0.625em; }
#footnotes hr { width: 20%; min-width: 6.25em; margin: -0.25em 0 0.75em 0; border-width: 1px 0 0 0; }
#footnotes .footnote { padding: 0 0.375em 0 0.225em; line-height: 1.3334; font-size: 0.875em; margin-left: 1.2em; margin-bottom: 0.2em; }
#footnotes .footnote a:first-of-type { font-weight: bold; text-decoration: none; margin-left: -1.05em; }
#footnotes .footnote:last-of-type { margin-bottom: 0; }
#content #footnotes { margin-top: -0.625em; margin-bottom: 0; padding: 0.75em 0; }
.gist .file-data > table { border: 0; background: #fff; width: 100%; margin-bottom: 0; }
.gist .file-data > table td.line-data { width: 99%; }
div.unbreakable { page-break-inside: avoid; }
.big { font-size: larger; }
.small { font-size: smaller; }
.underline { text-decoration: underline; }
.overline { text-decoration: overline; }
.line-through { text-decoration: line-through; }
.aqua { color: #00bfbf; }
.aqua-background { background-color: #00fafa; }
.black { color: black; }
.black-background { background-color: black; }
.blue { color: #0000bf; }
.blue-background { background-color: #0000fa; }
.fuchsia { color: #bf00bf; }
.fuchsia-background { background-color: #fa00fa; }
.gray { color: #606060; }
.gray-background { background-color: #7d7d7d; }
.green { color: #006000; }
.green-background { background-color: #007d00; }
.lime { color: #00bf00; }
.lime-background { background-color: #00fa00; }
.maroon { color: #600000; }
.maroon-background { background-color: #7d0000; }
.navy { color: #000060; }
.navy-background { background-color: #00007d; }
.olive { color: #606000; }
.olive-background { background-color: #7d7d00; }
.purple { color: #600060; }
.purple-background { background-color: #7d007d; }
.red { color: #bf0000; }
.red-background { background-color: #fa0000; }
.silver { color: #909090; }
.silver-background { background-color: #bcbcbc; }
.teal { color: #006060; }
.teal-background { background-color: #007d7d; }
.white { color: #bfbfbf; }
.white-background { background-color: #fafafa; }
.yellow { color: #bfbf00; }
.yellow-background { background-color: #fafa00; }
span.icon > .fa { cursor: default; }
a span.icon > .fa { cursor: inherit; }
.admonitionblock td.icon [class^="fa icon-"] { font-size: 2.5em; text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5); cursor: default; }
.admonitionblock td.icon .icon-note:before { content: "\f05a"; color: #29475c; }
.admonitionblock td.icon .icon-tip:before { content: "\f0eb"; text-shadow: 1px 1px 2px rgba(155, 155, 0, 0.8); color: #111; }
.admonitionblock td.icon .icon-warning:before { content: "\f071"; color: #bf6900; }
.admonitionblock td.icon .icon-caution:before { content: "\f06d"; color: #bf3400; }
.admonitionblock td.icon .icon-important:before { content: "\f06a"; color: #bf0000; }
.conum[data-value] { display: inline-block; color: #fff !important; background-color: black; -webkit-border-radius: 100px; border-radius: 100px; text-align: center; font-size: 0.75em; width: 1.67em; height: 1.67em; line-height: 1.67em; font-family: "Open Sans", "DejaVu Sans", sans-serif; font-style: normal; font-weight: bold; }
.conum[data-value] * { color: #fff !important; }
.conum[data-value] + b { display: none; }
.conum[data-value]:after { content: attr(data-value); }
pre .conum[data-value] { position: relative; top: -0.125em; }
b.conum * { color: inherit !important; }
.conum:not([data-value]):empty { display: none; }
h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { border-bottom: 1px solid #dddddd; }
.sect1 { padding-bottom: 0; }
#toctitle { color: #00406F; font-weight: normal; margin-top: 1.5em; }
.sidebarblock { border-color: #aaa; }
code { -webkit-border-radius: 4px; border-radius: 4px; }
p.tableblock.header { color: #6d6e71; }
.literalblock pre, .listingblock pre { background: #eeeeee; }
</style>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<link rel="stylesheet" href="../katex/katex.min.css">
<script src="../katex/katex.min.js"></script>
<script src="../katex/contrib/auto-render.min.js"></script>
<!-- Use KaTeX to render math once document is loaded, see
https://github.com/Khan/KaTeX/tree/master/contrib/auto-render -->
<script>
document.addEventListener("DOMContentLoaded", function () {
renderMathInElement(
document.body,
{
delimiters: [
{ left: "$$", right: "$$", display: true},
{ left: "\\[", right: "\\]", display: true},
{ left: "$", right: "$", display: false},
{ left: "\\(", right: "\\)", display: false}
]
}
);
});
</script></head>
<body class="book">
<div id="header">
<h1>cl_img_use_gralloc_ptr</h1>
<div class="details">
<span id="revnumber">version v3.0.5-12-gc767071,</span>
<span id="revdate">Mon, 23 Nov 2020 10:54:25 +0000</span>
<br><span id="revremark">from git branch: master commit: c767071fb1d0c1052fa039843d211fb795c2409c</span>
</div>
</div>
<div id="content">
<div class="sect1">
<h2 id="_name_strings"><a class="anchor" href="#_name_strings"></a>Name Strings</h2>
<div class="sectionbody">
<div class="paragraph">
<p><code>cl_img_use_gralloc_ptr</code></p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_contact"><a class="anchor" href="#_contact"></a>Contact</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Imagination Technologies Developer Forum:<br>
<a href="https://forums.imgtec.com/" class="bare">https://forums.imgtec.com/</a></p>
</div>
<div class="paragraph">
<p>Jeremy Kemp, Imagination Technologies (Jeremy.Kemp 'at' imgtec.com)</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_contributors"><a class="anchor" href="#_contributors"></a>Contributors</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Robert Quill, Imagination Technologies.<br>
Paul Fradgley, Imagination Technologies.<br>
Jeremy Kemp, Imagination Technologies.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_notice"><a class="anchor" href="#_notice"></a>Notice</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Copyright (c) 2020 Imagination Technologies Ltd. All Rights Reserved.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_status"><a class="anchor" href="#_status"></a>Status</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Shipping</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_version"><a class="anchor" href="#_version"></a>Version</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Built On: 2020-11-10<br>
Version: 1.0.0</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_dependencies"><a class="anchor" href="#_dependencies"></a>Dependencies</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Requires OpenCL version 1.2 or later. Android OS is required.</p>
</div>
<div class="paragraph">
<p>This extension is written against the wording of the OpenCL 3.0
Specification.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_overview"><a class="anchor" href="#_overview"></a>Overview</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This extension extends the functionality provided by <strong>clCreateBuffer</strong> and <strong>clCreateImage</strong>.
It allows applications to pass an Android memory allocation to these functions and thus avoid having to copy data back and forth between the host and the device.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_new_api_enums"><a class="anchor" href="#_new_api_enums"></a>New API Enums</h2>
<div class="sectionbody">
<div class="paragraph">
<p>New command types <code>cl_command_type</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="c">CL_COMMAND_ACQUIRE_GRALLOC_OBJECTS_IMG <span class="hex">0x40D2</span>
CL_COMMAND_RELEASE_GRALLOC_OBJECTS_IMG <span class="hex">0x40D3</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>New error codes:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="c">CL_GRALLOC_RESOURCE_NOT_ACQUIRED_IMG <span class="hex">0x40D4</span>
CL_INVALID_GRALLOC_OBJECT_IMG <span class="hex">0x40D5</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Accepted value for the <em>flags</em> parameter to <strong>clCreateBuffer</strong> and <strong>clCreateImage</strong>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="c">CL_MEM_USE_GRALLOC_PTR_IMG (<span class="integer">1</span> &lt;&lt; <span class="integer">28</span>)</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_new_api_functions"><a class="anchor" href="#_new_api_functions"></a>New API Functions</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>cl_int CL_API_CALL clEnqueueAcquireGrallocObjectsIMG(
cl_command_queue command_queue,
cl_uint num_objects,
const cl_mem *mem_objects,
cl_uint num_events_in_wait_list,
const cl_event *event_wait_list,
cl_event *event);
cl_int CL_API_CALL clEnqueueReleaseGrallocObjectsIMG(
cl_command_queue command_queue,
cl_uint num_objects,
const cl_mem *mem_objects,
cl_uint num_events_in_wait_list,
const cl_event *event_wait_list,
cl_event *event);</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_modifications_to_the_opencl_api_specification"><a class="anchor" href="#_modifications_to_the_opencl_api_specification"></a>Modifications to the OpenCL API Specification</h2>
<div class="sectionbody">
<div class="dlist">
<dl>
<dt class="hdlist1">(Modify Section 5.2, <strong>Buffer Objects</strong>) </dt>
<dd>
<div class="openblock">
<div class="content">
<div class="dlist">
<dl>
<dt class="hdlist1">(Add the following to Table 5, <em>List of supported memory flag values</em>) </dt>
<dd>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 20%;">
<col style="width: 80%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Memory Flags</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>CL_MEM_USE_GRALLOC_PTR_IMG</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">This flag is only valid of <em>host_ptr</em> is not <code>NULL</code>. The value given in <em>host_ptr</em> is an Android memory allocation.</p>
<p class="tableblock">If this flag is specified to <strong>clCreateBuffer</strong>, then <em>host_ptr</em> must be an Android <code>buffer_handle_t</code>. It means that the application wants the OpenCL implementation to use memory referenced by the <code>buffer_handle_t</code> as the storage bits for the memory object.</p>
<p class="tableblock">If this flag is specified to <strong>clCreateImage</strong>, then <em>host_ptr</em> must be an Android <code>ANativeWindowBuffer</code>. It means that the application wants the OpenCL implementation to use memory referenced by the <code>ANativeWindowBuffer</code> as the storage bits for the memory object.</p>
<p class="tableblock"><em>size</em> must be 0 if this flag is set when given to <strong>clCreateBuffer</strong>. The size of the buffer is determined from the size of the Android allocation.</p></td>
</tr>
</tbody>
</table>
</dd>
<dt class="hdlist1">(Add the following to Section 5.2.1, <em>Creating Buffer Objects</em>) </dt>
<dd>
<div class="dlist">
<dl>
<dt class="hdlist1">(Add the following error conditions to the list after this section) </dt>
<dd>
<p><code>CL_INVALID_BUFER_SIZE</code> if <em>size</em> is non-zero and <em>flags</em> contains <code>CL_MEM_USE_GRALLOC_PTR_IMG</code>.</p>
</dd>
<dt class="hdlist1">(Replace the following paragraph) </dt>
<dd>
<p><code>CL_INVALID_HOST_PTR</code> if <em>host_ptr</em> is <code>NULL</code> and <code>CL_MEM_USE_HOST_PTR</code> or <code>CL_MEM_COPY_HOST_PTR</code> are set in <em>flags</em> or if <em>host_ptr</em> is not <code>NULL</code> but <code>CL_MEM_COPY_HOST_PTR</code> or <code>CL_MEM_USE_HOST_PTR</code> are not set in <em>flags</em>.</p>
<div class="paragraph">
<p>with</p>
</div>
<div class="paragraph">
<p><code>CL_INVALID_HOST_PTR</code> if <em>host_ptr</em> is <code>NULL</code> and <code>CL_MEM_USE_HOST_PTR</code>, <code>CL_MEM_COPY_HOST_PTR</code> or <code>CL_MEM_USE_GRALLOC_PTR_IMG</code> are set in <em>flags</em> or if <em>host_ptr</em> is not <code>NULL</code> but <code>CL_MEM_COPY_HOST_PTR</code>, <code>CL_MEM_USE_HOST_PTR</code> or <code>CL_MEM_USE_GRALLOC_PTR_IMG</code> are not set in <em>flags</em>.</p>
</div>
</dd>
</dl>
</div>
</dd>
</dl>
</div>
</div>
</div>
</dd>
<dt class="hdlist1">(Modify Section 5.3, <strong>Image Objects</strong>) </dt>
<dd>
<div class="openblock">
<div class="content">
<div class="dlist">
<dl>
<dt class="hdlist1">(Add the following to Section 5.3.1, <em>Creating Image Objects</em>) </dt>
<dd>
<div class="dlist">
<dl>
<dt class="hdlist1">(Replace the following paragraph) </dt>
<dd>
<p><code>CL_INVALID_IMAGE_DESCRIPTOR</code> if values specified in <em>image_desc</em> are not valid or if <em>image_desc</em> is <code>NULL</code>.</p>
<div class="paragraph">
<p>with</p>
</div>
<div class="paragraph">
<p><code>CL_INVALID_IMAGE_DESCRIPTOR</code> if <em>image_desc</em> is <code>NULL</code> and <em>flags</em> does not contain <code>CL_MEM_USE_GRALLOC_PTR_IMG</code>, or if <em>image_desc</em> is not <code>NULL</code> and <em>flags</em> contains <code>CL_MEM_USE_GRALLOC_PTR_IMG</code>, or if values specified in <em>image_desc</em> are not valid.</p>
</div>
</dd>
<dt class="hdlist1">(Replace the following paragraph) </dt>
<dd>
<p><code>CL_INVALID_HOST_PTR</code> if <em>host_ptr</em> is <code>NULL</code> and <code>CL_MEM_USE_HOST_PTR</code> or <code>CL_MEM_COPY_HOST_PTR</code> are set in <em>flags</em> or if <em>host_ptr</em> is not <code>NULL</code> but <code>CL_MEM_COPY_HOST_PTR</code> or <code>CL_MEM_USE_HOST_PTR</code> are not set in <em>flags</em>.</p>
<div class="paragraph">
<p>with</p>
</div>
<div class="paragraph">
<p><code>CL_INVALID_HOST_PTR</code> if <em>host_ptr</em> is <code>NULL</code> and <code>CL_MEM_USE_HOST_PTR</code>, <code>CL_MEM_COPY_HOST_PTR</code> or <code>CL_MEM_USE_GRALLOC_PTR_IMG</code> are set in <em>flags</em> or if <em>host_ptr</em> is not <code>NULL</code> but <code>CL_MEM_COPY_HOST_PTR</code>, <code>CL_MEM_USE_HOST_PTR</code> or <code>CL_MEM_USE_GRALLOC_PTR_IMG</code> are not set in <em>flags</em>.</p>
</div>
</dd>
</dl>
</div>
</dd>
</dl>
</div>
</div>
</div>
</dd>
<dt class="hdlist1">(Add a new Section 5.16, <em>Sharing OpenCL and Gralloc Objects</em>) </dt>
<dd>
<div class="dlist">
<dl>
<dt class="hdlist1">(Add a new Section 5.16.1, <em>Synchronizing OpenCL and Android Access to Shared Gralloc Objects</em>) </dt>
<dd>
<p>In order to ensure data integrity, the application is responsible for synchronizing access to shared CL/gralloc objects by their respective APIs. Failure to provide such synchronization may result in race conditions and other undefined behaviour including non-portability between implementations.</p>
<div class="paragraph">
<p>Prior to calling <strong>clEnqueueAcquireGrallocObjectsIMG</strong>, the application must ensure that any pending operations which access the objects specified in <em>mem_objects</em> have completed. This may be accomplished in a portable way by ceasing all client operations on the resource. Implementations may offer more efficient synchronization methods, such as synchronisation primitives or fence operations.</p>
</div>
<div class="paragraph">
<p>Similarly, after calling <strong>clEnqueueReleaseGrallocObjectsIMG</strong>, the application is responsible for ensuring that any pending OpenCL operations which access the objects specified in <em>mem_objects</em> have completed prior to executing subsequent commands in other APIs which reference these objects. This may be accomplished in a portable way by calling <strong>clWaitForEvents</strong> with the event object returned by <strong>clEnqueueReleaseGrallocObjects</strong>, or by calling <strong>clFinish</strong>. As above, some implementations may offer more efficient methods.</p>
</div>
<div class="paragraph">
<p>Attempting to access the data store of a gralloc allocation after it has been acquired by OpenCL and before it has been released will result in undefined behaviour. Similarly, attempting to access a shared gralloc object from OpenCL before it has been acquired by the OpenCL command queue or after it has been released, will result in undefined behaviour.</p>
</div>
</dd>
<dt class="hdlist1">(Add a new Section 5.16.2, <em>Sharing Memory Objects Created From Gralloc Resources With OpenCL Contexts</em>) </dt>
<dd>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p>The function</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>cl_int CL_API_CALL clEnqueueAcquireGrallocObjectsIMG(
cl_command_queue command_queue,
cl_uint num_objects,
const cl_mem *mem_objects,
cl_uint num_events_in_wait_list,
const cl_event *event_wait_list,
cl_event *event);</code></pre>
</div>
</div>
<div class="paragraph">
<p>is used to acquire OpenCL memory objects that have been created from gralloc resources. The gralloc objects are acquired by the OpenCL context associated with <em>command_queue</em> and can therefore be used by all command-queues associated with the OpenCL context.</p>
</div>
<div class="paragraph">
<p>OpenCL memory objects created from gralloc resources must be acquired before they can be used by any OpenCL commands queued to a command-queue. If an OpenCL memory object created from a gralloc resource is used while it is not currently acquired by OpenCL, the call attempting to use that OpenCL memory object will return <code>CL_GRALLOC_RESOURCE_NOT_ACQUIRED_IMG</code>.</p>
</div>
<div class="paragraph">
<p>This function has no affect on memory objects in <em>mem_objects</em> that have already been acquired, ignoring them silently. The function returns CL_SUCCESS even if all of the memory objects are ignored in this way.</p>
</div>
<div class="paragraph">
<p><em>command_queue</em> is a valid command-queue.</p>
</div>
<div class="paragraph">
<p><em>num_objects</em> is the number of memory objects to be acquired in <em>mem_objects</em>.</p>
</div>
<div class="paragraph">
<p><em>mem_objects</em> is a pointer to a list of OpenCL memory objects that were created from gralloc resources, within the context associate with <em>command_queue</em>.</p>
</div>
<div class="paragraph">
<p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to complete before this particular command can be executed. If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait on any event to complete. If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be greater than 0. The events specified in <em>event_wait_list</em> act as synchronization points.</p>
</div>
<div class="paragraph">
<p><em>event</em> returns an event object that identifies this particular command and can be used to query or queue a wait for this particular command to complete. <em>event</em> can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.</p>
</div>
<div class="paragraph">
<p><strong>clEnqueueAcquireGrallocObjectsIMG</strong> returns <code>CL_SUCCESS</code> if the function is executed successfully. If <em>num_objects</em> is 0 and <em>mem_objects</em> is <code>NULL</code> then the function does nothing and returns <code>CL_SUCCESS</code>. Otherwise it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>CL_INVALID_VALUE</code> if <em>num_objects</em> is zero and <em>mem_objects</em> is not a <code>NULL</code> value or if <em>num_objects</em> 0 and <em>mem_objects</em> is <code>NULL</code>.</p>
</li>
<li>
<p><code>CL_INVALID_MEM_OBJECT</code> if memory objects in <em>mem_objects</em> are not valid OpenCL memory objects in the context associated with <em>command_queue</em>.</p>
</li>
<li>
<p><code>CL_INVALID_GRALLOC_OBJECT_IMG</code> if memory objects in <em>mem_objects</em> have not been created from gralloc resources.</p>
</li>
<li>
<p><code>CL_INVALID_COMMAND_QUEUE</code> if <em>command_queue</em> is not a valid command-queue.</p>
</li>
<li>
<p><code>CL_INVALID_EVENT_WAIT_LIST</code> if <em>event_wait_list</em> is <code>NULL</code> and <em>num_events_in_wait_list</em> 0, or <em>event_wait_list</em> is not <code>NULL</code> and <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> are not valid events.</p>
</li>
<li>
<p><code>CL_OUT_OF_RESOURCES</code> if there is a failure to allocate resources required by the OpenCL implementation on the device.</p>
</li>
<li>
<p><code>CL_OUT_OF_HOST_MEMORY</code> if there is a failure to allocate resources required by the OpenCL implementation on the host.</p>
</li>
<li>
<p><code>CL_INVALID_OPERATION</code> if the queue on which the command is enqueued is associated with a device which does not support <code>cl_img_use_gralloc_ptr</code>.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The function</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code>cl_int CL_API_CALL clEnqueueReleaseGrallocObjectsIMG(
cl_command_queue command_queue,
cl_uint num_objects,
const cl_mem *mem_objects,
cl_uint num_events_in_wait_list,
const cl_event *event_wait_list,
cl_event *event);</code></pre>
</div>
</div>
<div class="paragraph">
<p>is used to release OpenCL memory objects that have been created from gralloc resources. The gralloc objects are released by the OpenCL context associated with <em>command_queue</em>.</p>
</div>
<div class="paragraph">
<p>OpenCL memory objects created from gralloc resources which have been acquired by OpenCL must be released by OpenCL before they may be accessed by Android client APIs. Accessing a gralloc resource while its corresponding OpenCL memory object is acquired is in error and will result in undefined behaviour, including but not limited to possible OpenCL errors, data corruption, and program termination.</p>
</div>
<div class="paragraph">
<p><em>command_queue</em> is a valid command-queue.</p>
</div>
<div class="paragraph">
<p><em>mem_objects</em> is a pointer to a list of OpenCL memory objects that were created from gralloc resources, within the context associated with <em>command_queue</em>.</p>
</div>
<div class="paragraph">
<p><em>event_wait_list</em> and <em>num_events_in_wait_list</em> specify events that need to complete before this particular command can be executed. If <em>event_wait_list</em> is <code>NULL</code>, then this particular command does not wait on any event to complete. If <em>event_wait_list</em> is <code>NULL</code>, <em>num_events_in_wait_list</em> must be 0. If <em>event_wait_list</em> is not <code>NULL</code>, the list of events pointed to by <em>event_wait_list</em> must be valid and <em>num_events_in_wait_list</em> must be greater than 0.</p>
</div>
<div class="paragraph">
<p><em>event</em> returns an event object that identifies this particular command and can be used to query or queue a wait for this particular command to complete. <em>event</em> can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.</p>
</div>
<div class="paragraph">
<p><strong>clEnqueueReleaseGrallocObjectsIMG</strong> returns <code>CL_SUCCESS</code> if the function is executed successfully. If <em>num_objects</em> is 0 and <em>mem_objects</em> is <code>NULL</code> the function does nothing and returns <code>CL_SUCCESS</code>. Otherwise it returns one of the following errors:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>CL_INVALID_VALUE</code> if <em>num_objects</em> is zero and <em>mem_objects</em> is not a <code>NULL</code> value or if <em>num_objects</em> 0 and <em>mem_objects</em> is <code>NULL</code>.</p>
</li>
<li>
<p><code>CL_INVALID_MEM_OBJECT</code> if memory objects in <em>mem_objects</em> are not valid OpenCL memory objects in the context associated with <em>command_queue</em>.</p>
</li>
<li>
<p><code>CL_INVALID_GRALLOC_OBJECT_IMG</code> if memory objects in <em>mem_objects</em> have not been created from gralloc resources.</p>
</li>
<li>
<p><code>CL_INVALID_COMMAND_QUEUE</code> if <em>command_queue</em> is not a valid command-queue.</p>
</li>
<li>
<p><code>CL_GRALLOC_RESOURCE_NOT_ACQUIRED_IMG</code> if memory objects in <em>mem_objects</em> have not previously acquired with <strong>clEnqueueAcquireGrallocObjectsIMG</strong>, or have been released using <strong>clEnqueueReleaseGrallocObjectsIMG</strong> since the last time that they were acquired.</p>
</li>
<li>
<p><code>CL_INVALID_EVENT_WAIT_LIST</code> if <em>event_wait_list</em> is NULL and <em>num_events_in_wait_list</em> 0, or <em>event_wait_list</em> is not <code>NULL</code> and <em>num_events_in_wait_list</em> is 0, or if event objects in <em>event_wait_list</em> are not valid events.</p>
</li>
<li>
<p><code>CL_OUT_OF_RESOURCES</code> if there is a failure to allocate resources required by the OpenCL implementation on the device.</p>
</li>
<li>
<p><code>CL_OUT_OF_HOST_MEMORY</code> if there is a failure to allocate resources required by the OpenCL implementation on the host.</p>
</li>
</ul>
</div>
</div>
</div>
</dd>
</dl>
</div>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_issues"><a class="anchor" href="#_issues"></a>Issues</h2>
<div class="sectionbody">
<div class="olist arabic">
<ol class="arabic">
<li>
<p>This extension does not support reference counting of the images, so the onus is on the application to behave sensibly and not release the underlying <code>cl_mem</code> object while the gralloc object is still being used.</p>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p><strong>INFORMATION</strong></p>
</div>
</div>
</div>
</li>
<li>
<p>In order to ensure data integrity, the application is responsible for synchronizing access to shared CL/gralloc objects by their respective APIs. Failure to provide such synchronization may result in race conditions and other undefined behaviour. This may be accomplished by calling <strong>clWaitForEvents</strong> with the event objects returned by any OpenCL commands which use the shared image object or by calling <strong>clFinish</strong>.</p>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p><strong>INFORMATION</strong></p>
</div>
</div>
</div>
</li>
<li>
<p>Currently restricted to buffer objects.</p>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p><strong>RESOLVED</strong></p>
</div>
</div>
</div>
</li>
</ol>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_revision_history"><a class="anchor" href="#_revision_history"></a>Revision History</h2>
<div class="sectionbody">
<table class="tableblock frame-all grid-rows stretch">
<colgroup>
<col style="width: 4.7619%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 66.6667%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Version</th>
<th class="tableblock halign-left valign-top">Date</th>
<th class="tableblock halign-left valign-top">Author</th>
<th class="tableblock halign-left valign-top">Changes</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">1.0.0</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">2020-11-10</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Jeremy Kemp</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Refreshed to AsciiDoc. Updated Contributors. Updated copyright notice. Updated the OpenCL spec which this extension spec is written against. Spelling fixes.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">0.2.0</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">2017-10-17</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Paul Fradgley</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Added support for images.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">0.1.0</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">2014-08-08</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Robert Quill</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Initial revision.</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Version v3.0.5-12-gc767071<br>
Last updated 2020-11-10 18:13:57 UTC
</div>
</div>
<style>
/* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
pre.CodeRay{background:#f7f7f8}
.CodeRay .line-numbers{border-right:1px solid currentColor;opacity:.35;padding:0 .5em 0 0}
.CodeRay span.line-numbers{display:inline-block;margin-right:.75em}
.CodeRay .line-numbers strong{color:#000}
table.CodeRay{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.CodeRay td{vertical-align:top;line-height:inherit}
table.CodeRay td.line-numbers{text-align:right}
table.CodeRay td.code{padding:0 0 0 .75em}
.CodeRay .debug{color:#fff !important;background:#000080 !important}
.CodeRay .annotation{color:#007}
.CodeRay .attribute-name{color:#000080}
.CodeRay .attribute-value{color:#700}
.CodeRay .binary{color:#509}
.CodeRay .comment{color:#998;font-style:italic}
.CodeRay .char{color:#04d}
.CodeRay .char .content{color:#04d}
.CodeRay .char .delimiter{color:#039}
.CodeRay .class{color:#458;font-weight:bold}
.CodeRay .complex{color:#a08}
.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
.CodeRay .color{color:#099}
.CodeRay .class-variable{color:#369}
.CodeRay .decorator{color:#b0b}
.CodeRay .definition{color:#099}
.CodeRay .delimiter{color:#000}
.CodeRay .doc{color:#970}
.CodeRay .doctype{color:#34b}
.CodeRay .doc-string{color:#d42}
.CodeRay .escape{color:#666}
.CodeRay .entity{color:#800}
.CodeRay .error{color:#808}
.CodeRay .exception{color:inherit}
.CodeRay .filename{color:#099}
.CodeRay .function{color:#900;font-weight:bold}
.CodeRay .global-variable{color:#008080}
.CodeRay .hex{color:#058}
.CodeRay .integer,.CodeRay .float{color:#099}
.CodeRay .include{color:#555}
.CodeRay .inline{color:#000}
.CodeRay .inline .inline{background:#ccc}
.CodeRay .inline .inline .inline{background:#bbb}
.CodeRay .inline .inline-delimiter{color:#d14}
.CodeRay .inline-delimiter{color:#d14}
.CodeRay .important{color:#555;font-weight:bold}
.CodeRay .interpreted{color:#b2b}
.CodeRay .instance-variable{color:#008080}
.CodeRay .label{color:#970}
.CodeRay .local-variable{color:#963}
.CodeRay .octal{color:#40e}
.CodeRay .predefined{color:#369}
.CodeRay .preprocessor{color:#579}
.CodeRay .pseudo-class{color:#555}
.CodeRay .directive{font-weight:bold}
.CodeRay .type{font-weight:bold}
.CodeRay .predefined-type{color:inherit}
.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
.CodeRay .key{color:#808}
.CodeRay .key .delimiter{color:#606}
.CodeRay .key .char{color:#80f}
.CodeRay .value{color:#088}
.CodeRay .regexp .delimiter{color:#808}
.CodeRay .regexp .content{color:#808}
.CodeRay .regexp .modifier{color:#808}
.CodeRay .regexp .char{color:#d14}
.CodeRay .regexp .function{color:#404;font-weight:bold}
.CodeRay .string{color:#d20}
.CodeRay .string .string .string{background:#ffd0d0}
.CodeRay .string .content{color:#d14}
.CodeRay .string .char{color:#d14}
.CodeRay .string .delimiter{color:#d14}
.CodeRay .shell{color:#d14}
.CodeRay .shell .delimiter{color:#d14}
.CodeRay .symbol{color:#990073}
.CodeRay .symbol .content{color:#a60}
.CodeRay .symbol .delimiter{color:#630}
.CodeRay .tag{color:#008080}
.CodeRay .tag-special{color:#d70}
.CodeRay .variable{color:#036}
.CodeRay .insert{background:#afa}
.CodeRay .delete{background:#faa}
.CodeRay .change{color:#aaf;background:#007}
.CodeRay .head{color:#f8f;background:#505}
.CodeRay .insert .insert{color:#080}
.CodeRay .delete .delete{color:#800}
.CodeRay .change .change{color:#66f}
.CodeRay .head .head{color:#f4f}
</style>
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_HTMLorMML"></script>
</body>
</html>