1#
2# Copyright (C) 2015 The Android Open Source Project
3#
4# Licensed under the Apache License, Version 2.0 (the "License");
5# you may not use this file except in compliance with the License.
6# You may obtain a copy of the License at
7#
8#      http://www.apache.org/licenses/LICENSE-2.0
9#
10# Unless required by applicable law or agreed to in writing, software
11# distributed under the License is distributed on an "AS IS" BASIS,
12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13# See the License for the specific language governing permissions and
14# limitations under the License.
15#
16
17header:
18summary: Allocation Data Access Functions
19description:
20 The functions below can be used to get and set the cells that comprise
21 an allocation.
22 <ul>
23 <li>Individual cells are accessed using the rsGetElementAt* and
24   @rsSetElementAt functions.</li>
25 <li>Multiple cells can be copied using the rsAllocationCopy* and
26   rsAllocationV* functions.</li>
27 <li>For getting values through a sampler, use @rsSample.</li>
28 </ul>
29 The @rsGetElementAt and rsSetElement* functions are somewhat misnamed.
30 They don't get or set elements, which are akin to data types; they get
31 or set cells.  Think of them as rsGetCellAt and and rsSetCellAt.
32end:
33
34function: rsAllocationCopy1DRange
35version: 14
36ret: void
37arg: rs_allocation dstAlloc, "Allocation to copy cells into."
38arg: uint32_t dstOff, "Offset in the destination of the first cell to be copied into."
39arg: uint32_t dstMip, "Mip level in the destination allocation.  0 if mip mapping is not used."
40arg: uint32_t count, "Number of cells to be copied."
41arg: rs_allocation srcAlloc, "Source allocation."
42arg: uint32_t srcOff, "Offset in the source of the first cell to be copied."
43arg: uint32_t srcMip, "Mip level in the source allocation.  0 if mip mapping is not used."
44summary: Copy consecutive cells between allocations
45description:
46 Copies the specified number of cells from one allocation to another.
47
48 The two allocations must be different.  Using this function to copy whithin
49 the same allocation yields undefined results.
50
51 The function does not validate whether the offset plus count exceeds the size
52 of either allocation.  Be careful!
53
54 This function should only be called between 1D allocations.  Calling it
55 on other allocations is undefined.
56
57 This function should not be called from inside a kernel, or from any function
58 that may be called directly or indirectly from a kernel. Doing so would cause a
59 runtime error.
60test: none
61end:
62
63function: rsAllocationCopy2DRange
64version: 14
65ret: void
66arg: rs_allocation dstAlloc, "Allocation to copy cells into."
67arg: uint32_t dstXoff, "X offset in the destination of the region to be set."
68arg: uint32_t dstYoff, "Y offset in the destination of the region to be set."
69arg: uint32_t dstMip, "Mip level in the destination allocation.  0 if mip mapping is not used."
70arg: rs_allocation_cubemap_face dstFace, "Cubemap face of the destination allocation.  Ignored for allocations that aren't cubemaps."
71arg: uint32_t width, "Width of the incoming region to update."
72arg: uint32_t height, "Height of the incoming region to update."
73arg: rs_allocation srcAlloc, "Source allocation."
74arg: uint32_t srcXoff, "X offset in the source."
75arg: uint32_t srcYoff, "Y offset in the source."
76arg: uint32_t srcMip, "Mip level in the source allocation.  0 if mip mapping is not used."
77arg: rs_allocation_cubemap_face srcFace, "Cubemap face of the source allocation.  Ignored for allocations that aren't cubemaps."
78summary: Copy a rectangular region of cells between allocations
79description:
80 Copies a rectangular region of cells from one allocation to another.
81 (width * heigth) cells are copied.
82
83 The two allocations must be different.  Using this function to copy whithin
84 the same allocation yields undefined results.
85
86 The function does not validate whether the the source or destination region
87 exceeds the size of its respective allocation.  Be careful!
88
89 This function should only be called between 2D allocations.  Calling it
90 on other allocations is undefined.
91
92 This function should not be called from inside a kernel, or from any function
93 that may be called directly or indirectly from a kernel. Doing so would cause a
94 runtime error.
95test: none
96end:
97
98function: rsAllocationVLoadX_#2#1
99version: 22
100w: 2, 3, 4
101t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
102ret: #2#1
103arg: rs_allocation a, "Allocation to get the data from."
104arg: uint32_t x, "X offset in the allocation of the first cell to be copied from."
105summary: Get a vector from an allocation of scalars
106description:
107 This function returns a vector composed of successive cells of the allocation.
108 It assumes that the allocation contains scalars.
109
110 The "X" in the name indicates that successive values are extracted by
111 increasing the X index.  There are currently no functions to get successive
112 values incrementing other dimensions.  Use multiple calls to rsGetElementAt()
113 instead.
114
115 For example, when calling rsAllocationVLoadX_int4(a, 20, 30), an int4 composed
116 of a[20, 30], a[21, 30], a[22, 30], and a[23, 30] is returned.
117
118 When retrieving from a three dimensional allocations, use the x, y, z variant.
119 Similarly, use the x, y variant for two dimensional allocations and x for the
120 mono dimensional allocations.
121
122 For efficiency, this function does not validate the inputs.  Trying to wrap
123 the X index, exceeding the size of the allocation, or using indices incompatible
124 with the dimensionality of the allocation yields undefined results.
125
126 See also @rsAllocationVStoreX().
127test: none
128end:
129
130function: rsAllocationVLoadX_#2#1
131version: 22
132w: 2, 3, 4
133t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
134ret: #2#1
135arg: rs_allocation a
136arg: uint32_t x
137arg: uint32_t y, "Y offset in the allocation of the first cell to be copied from."
138test: none
139end:
140
141function: rsAllocationVLoadX_#2#1
142version: 22
143w: 2, 3, 4
144t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
145ret: #2#1
146arg: rs_allocation a
147arg: uint32_t x
148arg: uint32_t y
149arg: uint32_t z, "Z offset in the allocation of the first cell to be copied from."
150test: none
151end:
152
153function: rsAllocationVStoreX_#2#1
154version: 22
155w: 2, 3, 4
156t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
157ret: void
158arg: rs_allocation a, "Allocation to store the data into."
159arg: #2#1 val, "Value to be stored."
160arg: uint32_t x, "X offset in the allocation of the first cell to be copied into."
161summary: Store a vector into an allocation of scalars
162description:
163 This function stores the entries of a vector into successive cells of an allocation.
164 It assumes that the allocation contains scalars.
165
166 The "X" in the name indicates that successive values are stored by increasing
167 the X index.  There are currently no functions to store successive values
168 incrementing other dimensions.  Use multiple calls to rsSetElementAt() instead.
169
170 For example, when calling rsAllocationVStoreX_int3(a, v, 20, 30), v.x is stored
171 at a[20, 30], v.y at a[21, 30], and v.z at a[22, 30].
172
173 When storing into a three dimensional allocations, use the x, y, z variant.
174 Similarly, use the x, y variant for two dimensional allocations and x for the
175 mono dimensional allocations.
176
177 For efficiency, this function does not validate the inputs.  Trying to wrap the
178 X index, exceeding the size of the allocation, or using indices incompatible
179 with the dimensionality of the allocation yiels undefined results.
180
181 See also @rsAllocationVLoadX().
182test: none
183end:
184
185function: rsAllocationVStoreX_#2#1
186version: 22
187w: 2, 3, 4
188t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
189ret: void
190arg: rs_allocation a
191arg: #2#1 val
192arg: uint32_t x
193arg: uint32_t y, "Y offset in the allocation of the first cell to be copied into."
194test: none
195end:
196
197function: rsAllocationVStoreX_#2#1
198version: 22
199w: 2, 3, 4
200t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
201ret: void
202arg: rs_allocation a
203arg: #2#1 val
204arg: uint32_t x
205arg: uint32_t y
206arg: uint32_t z, "Z offset in the allocation of the first cell to be copied into."
207test: none
208end:
209
210function: rsGetElementAt
211ret: const void*
212arg: rs_allocation a
213arg: uint32_t x
214summary: Return a cell from an allocation
215description:
216 This function extracts a single cell from an allocation.
217
218 When retrieving from a three dimensional allocations, use the x, y, z variant.
219 Similarly, use the x, y variant for two dimensional allocations and x for the
220 mono dimensional allocations.
221
222 This function has two styles.  One returns the address of the value using a void*,
223 the other returns the actual value, e.g. rsGetElementAt() vs. rsGetElementAt_int4().
224 For primitive types, always use the latter as it is more efficient.
225test: none
226end:
227
228function: rsGetElementAt
229ret: const void*
230arg: rs_allocation a
231arg: uint32_t x
232arg: uint32_t y
233test: none
234end:
235
236function: rsGetElementAt
237ret: const void*
238arg: rs_allocation a
239arg: uint32_t x
240arg: uint32_t y
241arg: uint32_t z
242test: none
243end:
244
245function: rsGetElementAt_#2#1
246version: 9 17
247w: 1, 2, 3, 4
248t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
249ret: #2#1
250arg: rs_allocation a
251arg: uint32_t x
252inline:
253 return ((#2#1 *)rsGetElementAt(a, x))[0];
254test: none
255end:
256
257function: rsGetElementAt_#2#1
258version: 9 17
259w: 1, 2, 3, 4
260t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
261ret: #2#1
262arg: rs_allocation a
263arg: uint32_t x
264arg: uint32_t y
265inline:
266 return ((#2#1 *)rsGetElementAt(a, x, y))[0];
267test: none
268end:
269
270function: rsGetElementAt_#2#1
271version: 9 17
272w: 1, 2, 3, 4
273t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
274ret: #2#1
275arg: rs_allocation a
276arg: uint32_t x
277arg: uint32_t y
278arg: uint32_t z
279inline:
280 return ((#2#1 *)rsGetElementAt(a, x, y, z))[0];
281test: none
282end:
283
284function: rsGetElementAt_#2#1
285version: 18
286w: 1, 2, 3, 4
287t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
288ret: #2#1
289arg: rs_allocation a
290arg: uint32_t x
291test: none
292end:
293
294function: rsGetElementAt_#2#1
295version: 18
296w: 1, 2, 3, 4
297t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
298ret: #2#1
299arg: rs_allocation a
300arg: uint32_t x
301arg: uint32_t y
302test: none
303end:
304
305function: rsGetElementAt_#2#1
306version: 18
307w: 1, 2, 3, 4
308t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
309ret: #2#1
310arg: rs_allocation a
311arg: uint32_t x
312arg: uint32_t y
313arg: uint32_t z
314test: none
315end:
316
317function: rsGetElementAt_#2#1
318version: 23
319w: 1, 2, 3, 4
320t: f16
321ret: #2#1
322arg: rs_allocation a
323arg: uint32_t x
324test: none
325end:
326
327function: rsGetElementAt_#2#1
328version: 23
329w: 1, 2, 3, 4
330t: f16
331ret: #2#1
332arg: rs_allocation a
333arg: uint32_t x
334arg: uint32_t y
335test: none
336end:
337
338function: rsGetElementAt_#2#1
339version: 23
340w: 1, 2, 3, 4
341t: f16
342ret: #2#1
343arg: rs_allocation a
344arg: uint32_t x
345arg: uint32_t y
346arg: uint32_t z
347test: none
348end:
349
350function: rsGetElementAtYuv_uchar_U
351version: 18
352ret: uchar
353arg: rs_allocation a
354arg: uint32_t x
355arg: uint32_t y
356summary: Get the U component of an allocation of YUVs
357description:
358 Extracts the U component of a single YUV value from a 2D allocation of YUVs.
359
360 Inside an allocation, Y, U, and V components may be stored if different planes
361 and at different resolutions.  The x, y coordinates provided here are in the
362 dimensions of the Y plane.
363
364 See @rsGetElementAtYuv_uchar_Y().
365test: none
366end:
367
368function: rsGetElementAtYuv_uchar_V
369version: 18
370ret: uchar
371arg: rs_allocation a
372arg: uint32_t x
373arg: uint32_t y
374summary: Get the V component of an allocation of YUVs
375description:
376 Extracts the V component of a single YUV value from a 2D allocation of YUVs.
377
378 Inside an allocation, Y, U, and V components may be stored if different planes
379 and at different resolutions.  The x, y coordinates provided here are in the
380 dimensions of the Y plane.
381
382 See @rsGetElementAtYuv_uchar_Y().
383test: none
384end:
385
386function: rsGetElementAtYuv_uchar_Y
387version: 18
388ret: uchar
389arg: rs_allocation a
390arg: uint32_t x
391arg: uint32_t y
392summary: Get the Y component of an allocation of YUVs
393description:
394 Extracts the Y component of a single YUV value from a 2D allocation of YUVs.
395
396 Inside an allocation, Y, U, and V components may be stored if different planes
397 and at different resolutions.  The x, y coordinates provided here are in the
398 dimensions of the Y plane.
399
400 See @rsGetElementAtYuv_uchar_U() and @rsGetElementAtYuv_uchar_V().
401test: none
402end:
403
404function: rsSample
405version: 16
406ret: float4
407arg: rs_allocation a, "Allocation to sample from."
408arg: rs_sampler s, "Sampler state."
409arg: float location, "Location to sample from."
410summary: Sample a value from a texture allocation
411description:
412 Fetches a value from a texture allocation in a way described by the sampler.
413
414 If your allocation is 1D, use the variant with float for location.  For 2D,
415 use the float2 variant.
416
417 See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.Sampler</a> for more details.
418test: none
419end:
420
421function: rsSample
422version: 16
423ret: float4
424arg: rs_allocation a
425arg: rs_sampler s
426arg: float location
427arg: float lod, "Mip level to sample from, for fractional values mip levels will be interpolated if RS_SAMPLER_LINEAR_MIP_LINEAR is used."
428test: none
429end:
430
431function: rsSample
432version: 16
433ret: float4
434arg: rs_allocation a
435arg: rs_sampler s
436arg: float2 location
437test: none
438end:
439
440function: rsSample
441version: 16
442ret: float4
443arg: rs_allocation a
444arg: rs_sampler s
445arg: float2 location
446arg: float lod
447test: none
448end:
449
450function: rsSetElementAt
451version: 18
452ret: void
453arg: rs_allocation a
454arg: void* ptr
455arg: uint32_t x
456summary: Set a cell of an allocation
457description:
458 This function stores a value into a single cell of an allocation.
459
460 When storing into a three dimensional allocations, use the x, y, z variant.
461 Similarly, use the x, y variant for two dimensional allocations and x for
462 the mono dimensional allocations.
463
464 This function has two styles.  One passes the value to be stored using a void*,
465 the other has the actual value as an argument, e.g. rsSetElementAt() vs.
466 rsSetElementAt_int4().  For primitive types, always use the latter as it is
467 more efficient.
468
469 See also @rsGetElementAt().
470test: none
471end:
472
473function: rsSetElementAt
474version: 18
475ret: void
476arg: rs_allocation a
477arg: void* ptr
478arg: uint32_t x
479arg: uint32_t y
480test: none
481end:
482
483function: rsSetElementAt_#2#1
484version: 18
485w: 1, 2, 3, 4
486t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
487ret: void
488arg: rs_allocation a
489arg: #2#1 val
490arg: uint32_t x
491test: none
492end:
493
494function: rsSetElementAt_#2#1
495version: 18
496w: 1, 2, 3, 4
497t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
498ret: void
499arg: rs_allocation a
500arg: #2#1 val
501arg: uint32_t x
502arg: uint32_t y
503test: none
504end:
505
506function: rsSetElementAt_#2#1
507version: 18
508w: 1, 2, 3, 4
509t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
510ret: void
511arg: rs_allocation a
512arg: #2#1 val
513arg: uint32_t x
514arg: uint32_t y
515arg: uint32_t z
516test: none
517end:
518
519function: rsSetElementAt_#2#1
520version: 23
521w: 1, 2, 3, 4
522t: f16
523ret: void
524arg: rs_allocation a
525arg: #2#1 val
526arg: uint32_t x
527test: none
528end:
529
530function: rsSetElementAt_#2#1
531version: 23
532w: 1, 2, 3, 4
533t: f16
534ret: void
535arg: rs_allocation a
536arg: #2#1 val
537arg: uint32_t x
538arg: uint32_t y
539test: none
540end:
541
542function: rsSetElementAt_#2#1
543version: 23
544w: 1, 2, 3, 4
545t: f16
546ret: void
547arg: rs_allocation a
548arg: #2#1 val
549arg: uint32_t x
550arg: uint32_t y
551arg: uint32_t z
552test: none
553end:
554