rs_allocation.rsh revision 50bfc354e61e174a465893fd0dafe913f1954478
1/* 2 * Copyright (C) 2011 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 17/*! \mainpage notitle 18 * 19 * Renderscript is a high-performance runtime that provides graphics rendering and 20 * compute operations at the native level. Renderscript code is compiled on devices 21 * at runtime to allow platform-independence as well. 22 * This reference documentation describes the Renderscript runtime APIs, which you 23 * can utilize to write Renderscript code in C99. The Renderscript header 24 * files are automatically included for you, except for the rs_graphics.rsh header. If 25 * you are doing graphics rendering, include the graphics header file like this: 26 * 27 * <code>#include "rs_graphics.rsh"</code> 28 * 29 * To use Renderscript, you need to utilize the Renderscript runtime APIs documented here 30 * as well as the Android framework APIs for Renderscript. 31 * For documentation on the Android framework APIs, see the <a href= 32 * "http://developer.android.com/reference/android/renderscript/package-summary.html"> 33 * android.renderscript</a> package reference. 34 * For more information on how to develop with Renderscript and how the runtime and 35 * Android framework APIs interact, see the <a href= 36 * "http://developer.android.com/guide/topics/renderscript/index.html">Renderscript 37 * developer guide</a> and the <a href= 38 * "http://developer.android.com/resources/samples/RenderScript/index.html"> 39 * Renderscript samples</a>. 40 */ 41 42/** @file rs_allocation.rsh 43 * \brief Allocation routines 44 * 45 * 46 */ 47 48#ifndef __RS_ALLOCATION_RSH__ 49#define __RS_ALLOCATION_RSH__ 50 51/** 52 * Returns the Allocation for a given pointer. The pointer should point within 53 * a valid allocation. The results are undefined if the pointer is not from a 54 * valid allocation. 55 */ 56extern rs_allocation __attribute__((overloadable)) 57 rsGetAllocation(const void *); 58 59/** 60 * Query the dimension of an allocation. 61 * 62 * @return uint32_t The X dimension of the allocation. 63 */ 64extern uint32_t __attribute__((overloadable)) 65 rsAllocationGetDimX(rs_allocation); 66 67/** 68 * Query the dimension of an allocation. 69 * 70 * @return uint32_t The Y dimension of the allocation. 71 */ 72extern uint32_t __attribute__((overloadable)) 73 rsAllocationGetDimY(rs_allocation); 74 75/** 76 * Query the dimension of an allocation. 77 * 78 * @return uint32_t The Z dimension of the allocation. 79 */ 80extern uint32_t __attribute__((overloadable)) 81 rsAllocationGetDimZ(rs_allocation); 82 83/** 84 * Query an allocation for the presence of more than one LOD. 85 * 86 * @return uint32_t Returns 1 if more than one LOD is present, 0 otherwise. 87 */ 88extern uint32_t __attribute__((overloadable)) 89 rsAllocationGetDimLOD(rs_allocation); 90 91/** 92 * Query an allocation for the presence of more than one face. 93 * 94 * @return uint32_t Returns 1 if more than one face is present, 0 otherwise. 95 */ 96extern uint32_t __attribute__((overloadable)) 97 rsAllocationGetDimFaces(rs_allocation); 98 99#if (defined(RS_VERSION) && (RS_VERSION >= 14)) 100 101/** 102 * Copy part of an allocation from another allocation. 103 * 104 * @param dstAlloc Allocation to copy data into. 105 * @param dstOff The offset of the first element to be copied in 106 * the destination allocation. 107 * @param dstMip Mip level in the destination allocation. 108 * @param count The number of elements to be copied. 109 * @param srcAlloc The source data allocation. 110 * @param srcOff The offset of the first element in data to be 111 * copied in the source allocation. 112 * @param srcMip Mip level in the source allocation. 113 */ 114extern void __attribute__((overloadable)) 115 rsAllocationCopy1DRange(rs_allocation dstAlloc, 116 uint32_t dstOff, uint32_t dstMip, 117 uint32_t count, 118 rs_allocation srcAlloc, 119 uint32_t srcOff, uint32_t srcMip); 120 121/** 122 * Copy a rectangular region into the allocation from another 123 * allocation. 124 * 125 * @param dstAlloc allocation to copy data into. 126 * @param dstXoff X offset of the region to update in the 127 * destination allocation. 128 * @param dstYoff Y offset of the region to update in the 129 * destination allocation. 130 * @param dstMip Mip level in the destination allocation. 131 * @param dstFace Cubemap face of the destination allocation, 132 * ignored for allocations that aren't cubemaps. 133 * @param width Width of the incoming region to update. 134 * @param height Height of the incoming region to update. 135 * @param srcAlloc The source data allocation. 136 * @param srcXoff X offset in data of the source allocation. 137 * @param srcYoff Y offset in data of the source allocation. 138 * @param srcMip Mip level in the source allocation. 139 * @param srcFace Cubemap face of the source allocation, 140 * ignored for allocations that aren't cubemaps. 141 */ 142extern void __attribute__((overloadable)) 143 rsAllocationCopy2DRange(rs_allocation dstAlloc, 144 uint32_t dstXoff, uint32_t dstYoff, 145 uint32_t dstMip, 146 rs_allocation_cubemap_face dstFace, 147 uint32_t width, uint32_t height, 148 rs_allocation srcAlloc, 149 uint32_t srcXoff, uint32_t srcYoff, 150 uint32_t srcMip, 151 rs_allocation_cubemap_face srcFace); 152 153#endif //defined(RS_VERSION) && (RS_VERSION >= 14) 154 155/** 156 * Extract a single element from an allocation. 157 */ 158extern const void * __attribute__((overloadable)) 159 rsGetElementAt(rs_allocation, uint32_t x); 160/** 161 * \overload 162 */ 163extern const void * __attribute__((overloadable)) 164 rsGetElementAt(rs_allocation, uint32_t x, uint32_t y); 165/** 166 * \overload 167 */ 168extern const void * __attribute__((overloadable)) 169 rsGetElementAt(rs_allocation, uint32_t x, uint32_t y, uint32_t z); 170 171/** 172 * @param a allocation to get data from 173 * @return element describing allocation layout 174 */ 175extern rs_element __attribute__((overloadable)) 176 rsAllocationGetElement(rs_allocation a); 177 178/** 179 * @param m mesh to get data from 180 * @return number of allocations in the mesh that contain vertex 181 * data 182 */ 183extern uint32_t __attribute__((overloadable)) 184 rsMeshGetVertexAllocationCount(rs_mesh m); 185 186/** 187 * @param m mesh to get data from 188 * @return number of primitive groups in the mesh. This would 189 * include simple primitives as well as allocations 190 * containing index data 191 */ 192extern uint32_t __attribute__((overloadable)) 193 rsMeshGetPrimitiveCount(rs_mesh m); 194 195/** 196 * @param m mesh to get data from 197 * @param index index of the vertex allocation 198 * @return allocation containing vertex data 199 */ 200extern rs_allocation __attribute__((overloadable)) 201 rsMeshGetVertexAllocation(rs_mesh m, uint32_t index); 202 203/** 204 * @param m mesh to get data from 205 * @param index index of the index allocation 206 * @return allocation containing index data 207 */ 208extern rs_allocation __attribute__((overloadable)) 209 rsMeshGetIndexAllocation(rs_mesh m, uint32_t index); 210 211/** 212 * @param m mesh to get data from 213 * @param index index of the primitive 214 * @return primitive describing how the mesh is rendered 215 */ 216extern rs_primitive __attribute__((overloadable)) 217 rsMeshGetPrimitive(rs_mesh m, uint32_t index); 218 219/** 220 * @param e element to get data from 221 * @return number of sub-elements in this element 222 */ 223extern uint32_t __attribute__((overloadable)) 224 rsElementGetSubElementCount(rs_element e); 225 226/** 227 * @param e element to get data from 228 * @param index index of the sub-element to return 229 * @return sub-element in this element at given index 230 */ 231extern rs_element __attribute__((overloadable)) 232 rsElementGetSubElement(rs_element, uint32_t index); 233 234/** 235 * @param e element to get data from 236 * @param index index of the sub-element to return 237 * @return length of the sub-element name including the null 238 * terminator (size of buffer needed to write the name) 239 */ 240extern uint32_t __attribute__((overloadable)) 241 rsElementGetSubElementNameLength(rs_element e, uint32_t index); 242 243/** 244 * @param e element to get data from 245 * @param index index of the sub-element 246 * @param name array to store the name into 247 * @param nameLength length of the provided name array 248 * @return number of characters actually written, excluding the 249 * null terminator 250 */ 251extern uint32_t __attribute__((overloadable)) 252 rsElementGetSubElementName(rs_element e, uint32_t index, char *name, uint32_t nameLength); 253 254/** 255 * @param e element to get data from 256 * @param index index of the sub-element 257 * @return array size of sub-element in this element at given 258 * index 259 */ 260extern uint32_t __attribute__((overloadable)) 261 rsElementGetSubElementArraySize(rs_element e, uint32_t index); 262 263/** 264 * @param e element to get data from 265 * @param index index of the sub-element 266 * @return offset in bytes of sub-element in this element at 267 * given index 268 */ 269extern uint32_t __attribute__((overloadable)) 270 rsElementGetSubElementOffsetBytes(rs_element e, uint32_t index); 271 272/** 273 * @param e element to get data from 274 * @return total size of the element in bytes 275 */ 276extern uint32_t __attribute__((overloadable)) 277 rsElementGetSizeBytes(rs_element e); 278 279/** 280 * @param e element to get data from 281 * @return element's data type 282 */ 283extern rs_data_type __attribute__((overloadable)) 284 rsElementGetDataType(rs_element e); 285 286/** 287 * @param e element to get data from 288 * @return element's data size 289 */ 290extern rs_data_kind __attribute__((overloadable)) 291 rsElementGetDataKind(rs_element e); 292 293#endif 294 295