renderscript/1.0/IContext.hal

   1 /*
   2  * Copyright (C) 2017 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 package android.hardware.renderscript@1.0;
  18
  19 import android.hardware.renderscript@1.0::types;
  20
  21 // TODO: is there any way to keep this documentation in sync with the
  22 // corresponding Java doc?
  23 //
  24 // TODO: Some of the documentation was taken from Java docs, whereas others were
  25 // undocumented. Because of this, there's somewhat two different styles of
  26 // comments. Look into having a consistent convention.
  27 //
  28 // TODO: There was some confusion as to why some paramters use vec<> and others
  29 // use Ptr/Size. The convention is that vec<> is used whenever the paramter is
  30 // only an input parameter. HIDL is not supposed to include any output
  31 // parameters, so a more explicit Ptr/Size is used.
  32
  33 interface IContext {
  34
  35     /**
  36      * TODO: Do we need to define "selectors"? It may be a property of the
  37      * "adapted allocation" that's returned.
  38      *
  39      * Creates an arbitrary window into the base allocation. The type describes
  40      * the shape of the window. Any dimensions present in the type must be
  41      * equal to or smaller than the dimensions in the source allocation. A
  42      * dimension present in the allocation that is not present in the type must
  43      * be constrained away with the selectors. If a dimension is present in
  44      * both the type and allocation, one of two things must happen. If the type
  45      * is smaller than the allocation, a window must be created, the selected
  46      * value in the adapter for that dimension must act as the base address,
  47      * and the type must describe the size of the view starting at that point.
  48      * If the type and allocation dimension are of the same size, then setting
  49      * the selector for the dimension must be an error.
  50      *
  51      * @param type Type describing data layout
  52      * @param baseAlloc Allocation
  53      * @return subAlloc AllocationAdapter
  54      */
  55     @callflow(next={"*"})
  56     allocationAdapterCreate(Type type, Allocation baseAlloc)
  57                  generates (AllocationAdapter subAlloc);
  58
  59     /**
  60      * TODO: Need to relate "offset" back to the terminology in
  61      * allocationAdapterCreate() -- the latter uses the terms "selector" and
  62      * "selected value". Can we use consistent terminology? Are "offset" and
  63      * "selector" actually two different things?
  64      *
  65      * TODO: Explain the flattened layout in the offsets vec
  66      *
  67      * Sets the offsets for an Allocation Adapter.
  68      *
  69      * @param alloc AllocationAdapter
  70      * @param offsets Collection of offsets
  71      */
  72     @callflow(next={"*"})
  73     allocationAdapterOffset(AllocationAdapter alloc, vec<uint32_t> offsets);
  74
  75     /**
  76      * TODO: add more explanation here.
  77      *
  78      * Returns the Type of the Allocation.
  79      *
  80      * @param allocation Allocation
  81      * @return type Allocation's Type
  82      */
  83     @callflow(next={"*"})
  84     allocationGetType(Allocation allocation) generates (Type type);
  85
  86     /**
  87      * TODO: more clarification needed describing if the pointer can be aliased
  88      * or if the data can outlive the allocation.
  89      *
  90      * Creates an Allocation for use by scripts with a given Type and a backing
  91      * pointer. For use with ALLOCATION_USAGE_SHARED.
  92      *
  93      * @param type Type describing data layout
  94      * @param mips AllocationMipmapControl specifies desired mipmap behavior for
  95      *             the allocation
  96      * @param usage Bit field specifying how the Allocation is utilized
  97      * @param ptr Pointer to client-side data
  98      * @return allocation Created Allocation
  99      */
 100     @callflow(next={"*"})
 101     allocationCreateTyped(Type type, AllocationMipmapControl mips,
 102                           bitfield<AllocationUsageType> usage, Ptr ptr)
 103                generates (Allocation allocation);
 104
 105     /**
 106      * Creates an Allocation from a Bitmap.
 107      *
 108      * @param type Type describing data layout
 109      * @param mips AllocationMipmapControl specifies desired mipmap behavior for
 110      *             the allocation
 111      * @param bitmap Bitmap source for the allocation data
 112      * @param usage Bit field specifying how the Allocation is utilized
 113      * @return allocation Created Allocation containing bitmap data
 114      */
 115     @callflow(next={"*"})
 116     allocationCreateFromBitmap(Type type, AllocationMipmapControl mips,
 117                                vec<uint8_t> bitmap,
 118                                bitfield<AllocationUsageType> usage)
 119                     generates (Allocation allocation);
 120
 121     /**
 122      * Creates a Cubemapped Allocation from a Bitmap.
 123      *
 124      * @param type Type describing data layout
 125      * @param mips AllocationMipmapControl specifies desired mipmap behavior
 126      *             for the allocation
 127      * @param bitmap Bitmap with cubemap faces layed out in the following
 128      *               format: right, left, top, bottom, front, back
 129      * @param usage Bit field specifying how the Allocation is used
 130      * @return allocation Created Allocation containing cubemap data
 131      */
 132     @callflow(next={"*"})
 133     allocationCubeCreateFromBitmap(Type type, AllocationMipmapControl mips,
 134                                    vec<uint8_t> bitmap,
 135                                    bitfield<AllocationUsageType> usage)
 136                         generates (Allocation allocation);
 137
 138     /**
 139      * Returns the handle to a raw buffer that is being managed by the screen
 140      * compositor. This operation is only valid for Allocations with
 141      * USAGE_IO_INPUT.
 142      *
 143      * @param allocation Allocation
 144      * @return nativeWindow NativeWindow object associated with allocation
 145      */
 146     @callflow(next={"*"})
 147     allocationGetNativeWindow(Allocation allocation)
 148                    generates (NativeWindow nativeWindow);
 149
 150     /**
 151      * TODO: more clarification needed
 152      *
 153      * Sets the NativeWindow of an Allocation. This operation is only valid
 154      * for Allocations with USAGE_IO_INPUT.
 155      *
 156      * @param allocation Allocation to be modified
 157      * @pram nativeWindow NativeWindow to associate with allocation
 158      */
 159     @callflow(next={"*"})
 160     allocationSetNativeWindow(Allocation allocation, NativeWindow nativewindow);
 161
 162     /**
 163      * Initialize BufferQueue with specified max number of buffers.
 164      *
 165      * @param alloc Allocation
 166      * @param numBuffer Maximum number of buffers
 167      */
 168     @callflow(next={"*"})
 169     allocationSetupBufferQueue(Allocation alloc, uint32_t numBuffer);
 170
 171     /**
 172      * TODO: clearly define baseAlloc vs subAlloc
 173      *
 174      * Shares the BufferQueue with another Allocation. Both must be
 175      * USAGE_IO_INPUT Allocations.
 176      *
 177      * @param baseAlloc Base Allocation
 178      * @param subAlloc Allocation to use the same buffer queue as the Base
 179      *                 Allocation
 180      */
 181     @callflow(next={"*"})
 182     allocationShareBufferQueue(Allocation baseAlloc, Allocation subAlloc);
 183
 184     /**
 185      * Copies from the Allocation into a Bitmap. The bitmap must match the
 186      * dimensions of the Allocation.
 187      *
 188      * HIDL is always running in Passthrough mode for RenderScript, so the
 189      * buffer is modified directly by the driver.
 190      *
 191      * @param allocation Allocation
 192      * @param data Buffer to be copied into
 193      * @param sizeBytes Size of the buffer pointed to by "data"
 194      */
 195     @callflow(next={"*"})
 196     allocationCopyToBitmap(Allocation allocation, Ptr data, Size sizeBytes);
 197
 198     /**
 199      * TODO: should we consolidate all [123]DWrite functions or [123]DRead
 200      * functions into the same API call? Our current plan is to be very similar
 201      * to the dispatch table API. How much should we deviate from the original
 202      * API?
 203      * TODO: better description on Vec3/Vec4 and padding.
 204      *
 205      * Copies data into a 1D region of this Allocation.
 206      *
 207      * When this HAL entry is executed, all Vec3 elements have been explicitly
 208      * padded as Vec4 elements.
 209      *
 210      * The size of the region is: count * Element's size.
 211      *
 212      * @param allocation Allocation to be modified
 213      * @param offset The offset of the first element to be copied
 214      * @param lod Selected mipmap level of detail
 215      * @param count Number of elements to be copied
 216      * @param data Source data to be copied to Allocation
 217      */
 218     @callflow(next={"*"})
 219     allocation1DWrite(Allocation allocation, uint32_t offset, uint32_t lod,
 220                       uint32_t count, vec<uint8_t> data);
 221
 222     /**
 223      * Copies a value into a single sub-Element of this Allocation.
 224      *
 225      * @param allocation Allocation to be updated
 226      * @param x X position of the first element in the Allocation to be updated
 227      * @param y Y position of the first element in the Allocation to be
 228      *          updated; for a 1D Allocation, this value must be 0
 229      * @param z Z position of the first element in the Allocation to be
 230      *          updated; for a 1D or 2D Allocation, this value must be 0
 231      * @param lod Selected mipmap level of detail
 232      * @param data Data to be copied from
 233      * @param compIdx Component number to identify which sub-Element is updated
 234      */
 235     @callflow(next={"*"})
 236     allocationElementWrite(Allocation allocation, uint32_t x, uint32_t y,
 237                            uint32_t z, uint32_t lod, vec<uint8_t> data,
 238                            Size compIdx);
 239
 240     /**
 241      * Copies from an array into a rectangular region in this Allocation.
 242      *
 243      * When this HAL entry is executed, all Vec3 elements have been explicitly
 244      * padded as Vec4 elements.
 245      *
 246      * The size of the region is: w * h * Element's size.
 247      *
 248      * @param allocation Allocation to be modified
 249      * @param xoff X offset of the region to update in this Allocation
 250      * @param yoff Y offset of the region to update in this Allocation
 251      * @param lod Selected mipmap level of detail
 252      * @param face AllocationCubemapFace
 253      * @param w Width of the region to update
 254      * @param h Height of the region to update
 255      * @param data Data to be placed into the Allocation
 256      * @param stride For 1D Allocation, the stride must be the number of bytes
 257      *               of this Allocation. For 2D and 3D Allocations, the stride
 258      *               must be the stride in X dimension measuring in bytes.
 259      */
 260     @callflow(next={"*"})
 261     allocation2DWrite(Allocation allocation, uint32_t xoff, uint32_t yoff,
 262                       uint32_t lod, AllocationCubemapFace face, uint32_t w,
 263                       uint32_t h, vec<uint8_t> data, Size stride);
 264
 265     /**
 266      * Copies from an array into a 3D region in this Allocation.
 267      *
 268      * When this HAL entry is executed, all Vec3 elements have been explicitly
 269      * padded as Vec4 elements.
 270      *
 271      * The size of the region is: w * h * d * Element's size.
 272      *
 273      * @param allocation Allocation to be modified
 274      * @param xoff X offset of the region to update in this Allocation
 275      * @param yoff Y offset of the region to update in this Allocation
 276      * @param zoff Z offset of the region to update in this Allocation
 277      * @param lod Selected mipmap level of detail
 278      * @param w Width of the region to update
 279      * @param h Height of the region to update
 280      * @param d Depth of the region to update
 281      * @param data Data to be placed in the Allocation
 282      * @param stride For 1D Allocation, the stride must be the number of bytes
 283      *               of this Allocation. For 2D and 3D Allocations, the stride
 284      *               must be the stride in X dimension measuring in bytes.
 285      */
 286     @callflow(next={"*"})
 287     allocation3DWrite(Allocation allocation, uint32_t xoff, uint32_t yoff,
 288                       uint32_t zoff, uint32_t lod, uint32_t w, uint32_t h,
 289                       uint32_t d, vec<uint8_t> data, Size stride);
 290
 291     /**
 292      * Generates a mipmap chain. This is only valid if the Type of the
 293      * Allocation includes mipmaps.
 294      *
 295      * This function generates a complete set of mipmaps from the top level
 296      * LOD.
 297      *
 298      * If the Allocation is also using other memory spaces, a call to
 299      * allocationSyncAll(context, allocation, usage) is required.
 300      *
 301      * @param allocation Allocation which has its top LOD read and lower LOD
 302      *                   written to
 303      */
 304     @callflow(next={"*"})
 305     allocationGenerateMipmaps(Allocation allocation);
 306
 307     /**
 308      * Copies all of an Allocation's data into an array.
 309      *
 310      * All Vec3 elements of an Allocation are padded to be Vec4, so the data
 311      * returned by this function automatically includes padding.
 312      *
 313      * HIDL is always running in Passthrough mode for RenderScript, so the
 314      * buffer is modified directly by the driver.
 315      *
 316      * @param allocation Allocation to be read
 317      * @param data Buffer to be copied into
 318      * @param sizeBytes Size of the buffer pointed to by "data"
 319      */
 320     @callflow(next={"*"})
 321     allocationRead(Allocation allocation, Ptr data, Size sizeBytes);
 322
 323     /**
 324      * Copies a 1D region of this Allocation into an array.
 325      *
 326      * All Vec3 elements of an Allocation are padded to be Vec4, so the data
 327      * returned by this function automatically includes padding.
 328      *
 329      * The size of the region is: count * Element's size.
 330      *
 331      * HIDL is always running in Passthrough mode for RenderScript, so the
 332      * buffer is modified directly by the driver.
 333      *
 334      * @param allocation Allocation to be read
 335      * @param xoff X offset of the first element to be copied
 336      * @param lod Mipmap level of detail
 337      * @param count The number of elements to be copied
 338      * @param data Buffer to be copied into
 339      * @param sizeBytes Size of the buffer pointed to by "data"
 340      */
 341     @callflow(next={"*"})
 342     allocation1DRead(Allocation allocation, uint32_t xoff, uint32_t lod,
 343                      uint32_t count, Ptr data, Size sizeBytes);
 344
 345     /**
 346      * Returns the value of a single sub-Element of this Allocation.
 347      *
 348      * HIDL is always running in Passthrough mode for RenderScript, so the
 349      * buffer is modified directly by the driver.
 350      *
 351      * @param allocation Allocation to be read
 352      * @param x X position of the first element in the Allocation to be read
 353      * @param y Y position of the first element in the Allocation to be read
 354      * @param z Z position of the first element in the Allocation to be read
 355      * @param lod Mipmap level of detail
 356      * @param data Buffer to be copied into
 357      * @param sizeBytes Size of the buffer pointed to by "data"
 358      * @param compIdx Component number to identify which sub-Element is updated
 359      */
 360     @callflow(next={"*"})
 361     allocationElementRead(Allocation allocation, uint32_t x, uint32_t y,
 362                           uint32_t z, uint32_t lod, Ptr data, Size sizeBytes,
 363                           Size compIdx);
 364
 365     /**
 366      * Copies from a rectangular region in this Allocation to an array.
 367      *
 368      * All Vec3 elements of an Allocation are padded to be Vec4, so the data
 369      * returned by this function automatically includes padding.
 370      *
 371      * The size of the region is: w * h * Element's size.
 372      *
 373      * HIDL is always running in Passthrough mode for RenderScript, so the
 374      * buffer is modified directly by the driver.
 375      *
 376      * @param allocation Allocation to be read
 377      * @param xoff X offset of the region to copy in this array
 378      * @param yoff Y offset of the region to copy in this array
 379      * @param lod Mipmap level of detail
 380      * @param face AllocationCubemapFace
 381      * @param w Width of the region to copy
 382      * @param h Height of the region to copy
 383      * @param data Buffer to be copied into
 384      * @param sizeBytes Size of the buffer pointed to by "data"
 385      * @param stride For 1D Allocation, the stride must be the number of bytes
 386      *               of this Allocation. For 2D and 3D Allocations, the stride
 387      *               must be the stride in X dimension measuring in bytes.
 388      */
 389     @callflow(next={"*"})
 390     allocation2DRead(Allocation allocation, uint32_t xoff, uint32_t yoff,
 391                      uint32_t lod, AllocationCubemapFace face, uint32_t w,
 392                      uint32_t h, Ptr data, Size sizeBytes, Size stride);
 393
 394     /**
 395      * Copies from a rectangular cuboid region in this Allocation to an array.
 396      *
 397      * All Vec3 elements of an Allocation are padded to be Vec4, so the data
 398      * returned by this function automatically includes padding.
 399      *
 400      * The size of the region is: w * h * d * Element's size.
 401      *
 402      * HIDL is always running in Passthrough mode for RenderScript, so the
 403      * buffer is modified directly by the driver.
 404      *
 405      * @param allocation Allocation to be read
 406      * @param xoff X offset of the region to copy in this array
 407      * @param yoff Y offset of the region to copy in this array
 408      * @param zoff Z offset of the region to copy in this array
 409      * @param lod Mipmap level of detail
 410      * @param w Width of the region to copy
 411      * @param h Height of the region to copy
 412      * @param d Depth of the region to copy
 413      * @param data Buffer to be copied into
 414      * @param sizeBytes Size of the buffer pointed to by "data"
 415      * @param stride For 1D Allocation, the stride must be the number of bytes
 416      *               of this Allocation. For 2D and 3D Allocations, the stride
 417      *               must be the stride in X dimension measuring in bytes.
 418      */
 419     @callflow(next={"*"})
 420     allocation3DRead(Allocation allocation, uint32_t xoff, uint32_t yoff,
 421                      uint32_t zoff, uint32_t lod, uint32_t w, uint32_t h,
 422                      uint32_t d, Ptr data, Size sizeBytes, Size stride);
 423
 424     /**
 425      * Propagates changes from one usage of the Allocation to the other usages
 426      * of the Allocation.
 427      *
 428      * @param allocation First usage of the Allocation
 429      * @param usageType Allocation usage type
 430      */
 431     @callflow(next={"*"})
 432     allocationSyncAll(Allocation allocation, AllocationUsageType usageType);
 433
 434     /**
 435      * TODO: describe the functionality of resize1D better
 436      * TODO: original Java Doc description seems to contradict itself ("with
 437      * null contents and the region is otherwise undefined")
 438      * TODO: should "new elements" be "new cells"?
 439      * TODO: what does "objects are created" mean?
 440      * TODO: what does "new dimension" mean? IS the type of the resized
 441      * allocation different than the type before resizing?
 442      *
 443      * Resizes a 1D allocation. The contents of the allocation are preserved.
 444      * If new elements are allocated, objects are created with null contents
 445      * and the new region is otherwise undefined.
 446      *
 447      * If the new region is smaller, the references of any object outside the
 448      * new region must be released.
 449      *
 450      * A new type must be created with the new dimension.
 451      *
 452      * @param allocation Allocation to be resized
 453      * @param dimX New size along the x dimension of the Allocation
 454      */
 455     @callflow(next={"*"})
 456     allocationResize1D(Allocation allocation, uint32_t dimX);
 457
 458     /**
 459      * TODO: There are allocationCopy2DRange and 3DRange, but no 1DRange. Should
 460      * the interface be cleaned up more?
 461      *
 462      * Copies a rectangular region from an Allocation into a rectangular region
 463      * in this Allocation.
 464      *
 465      * @param dstAlloc Allocation to be updated
 466      * @param dstXoff X offset of the region to update
 467      * @param dstYoff Y offset of the region to update
 468      * @param dstMip Selected mipmap level of the Allocation to update
 469      * @param dstFace Destination AllocationCubemapFace
 470      * @param width Width of the region to update
 471      * @param height Height of the region to update
 472      * @param srcAlloc Source Allocation, to be read
 473      * @param srcXoff X offset of the region in the source Allocation
 474      * @param srcYoff Y offset of the region in the source Allocation
 475      * @param srcMip Selected mipmap level of the source Allocation
 476      * @param srcFace Source AllocationCubemapFace
 477      */
 478     @callflow(next={"*"})
 479     allocationCopy2DRange(Allocation dstAlloc, uint32_t dstXoff,
 480                           uint32_t dstYoff, uint32_t dstMip,
 481                           AllocationCubemapFace dstFace, uint32_t width,
 482                           uint32_t height, Allocation srcAlloc,
 483                           uint32_t srcXoff, uint32_t srcYoff, uint32_t srcMip,
 484                           AllocationCubemapFace srcFace);
 485
 486     /**
 487      * Copies a rectangular cuboid region into the allocation from another
 488      * Allocation.
 489      *
 490      * @param dstAlloc Allocation to be updated
 491      * @param dstXoff X offset of the region to update
 492      * @param dstYoff Y offset of the region to update
 493      * @param dstZoff Z offset of the region to update
 494      * @param dstMip Selected mipmap level of the Allocation to update
 495      * @param width Width of the region to update
 496      * @param height Height of the region to update
 497      * @param depth Depth of the region to update
 498      * @param srcAlloc Source Allocation, to be read
 499      * @param srcXoff Source X offset of the region in the source Allocation
 500      * @param srcYoff Source Y offset of the region in the source Allocation
 501      * @param srcZoff Source Z offset of the region in the souce Allocation
 502      * @param srcMip Selected mipmap level of the Allocation to read
 503      */
 504     @callflow(next={"*"})
 505     allocationCopy3DRange(Allocation dstAlloc, uint32_t dstXoff,
 506                           uint32_t dstYoff, uint32_t dstZoff, uint32_t dstMip,
 507                           uint32_t width, uint32_t height, uint32_t depth,
 508                           Allocation srcAlloc, uint32_t srcXoff,
 509                           uint32_t srcYoff, uint32_t srcZoff, uint32_t srcMip);
 510
 511     /**
 512      * TODO: define buffer and output stream
 513      *
 514      * Sends a buffer to the output stream. The contents of the Allocation may
 515      * be undefined after this operation. This operation is only valid if
 516      * USAGE_IO_OUTPUT is set on the Allocation.
 517      *
 518      * @param allocation Allocation to be sent
 519      */
 520     @callflow(next={"*"})
 521     allocationIoSend(Allocation allocation);
 522
 523     /**
 524      * Receives the latest input into the Allocation. This operation is only
 525      * valid if USAGE_IO_INPUT is set on the Allocation, otherwise an error
 526      * must be reported and no operations may be executed.
 527      *
 528      * @param allocation Allocation to be updated
 529      */
 530     @callflow(next={"*"})
 531     allocationIoReceive(Allocation allocation);
 532
 533     /**
 534      * TODO: describe default values for lod, face, and z better.
 535      * TODO: what cases can invalidate the pointer? Resize? It should be
 536      * clarified that this method should always return a valid pointer, but the
 537      * returned pointer might become invalid later.
 538      *
 539      * Retrieves the pointer to the actual data an Allocation contains as well
 540      * as the data's stride.
 541      *
 542      * If Allocation lacks the corresponding dimension for lod, face, or z, an
 543      * error message must be sent to the message queue and nullptr must be
 544      * returned for dataPtr and 0 for stride. All missing values must be 0 or
 545      * NONE in the corresponding enum.
 546      *
 547      * @param allocation Allocation
 548      * @param lod Mipmap level of detail
 549      * @param face AllocationCubemapFace
 550      * @param z Z position
 551      * @return pointer Pointer to the server-side data; if this points to an
 552      *                 invalid location in memory (because the buffer was
 553      *                 freed), this may result in undefined behavior
 554      * @return stride For 1D Allocation, the stride must be the number of bytes
 555      *                of this Allocation. For 2D and 3D Allocations, the stride
 556      *                must be the stride in X dimension measuring in bytes.
 557      */
 558     @callflow(next={"*"})
 559     allocationGetPointer(Allocation allocation, uint32_t lod,
 560                          AllocationCubemapFace face, uint32_t z)
 561               generates (Ptr dataPtr, Size stride);
 562
 563     /**
 564      * Retrieves an Element's metadata from native code.
 565      *
 566      * @param element Element to be read
 567      * @return elemData Element data
 568      */
 569     @callflow(next={"*"})
 570     elementGetNativeMetadata(Element element)
 571                   generates (vec<uint32_t> elemData);
 572
 573     /**
 574      * TODO: define Sub-Element handles better.
 575      *
 576      * Retrieves an Element's sub Elements, specifically their identifiers,
 577      * names, and sizes.
 578      *
 579      * @param element Element to be read
 580      * @param numSubElem Number of sub-Elements
 581      * @return ids Sub-Element handles
 582      * @return names Sub-Element Names
 583      * @return arraySizes Sizes of sub-Element arrays
 584      */
 585     @callflow(next={"*"})
 586     elementGetSubElements(Element element, Size numSubElem)
 587                generates (vec<Element> ids, vec<string> names,
 588                           vec<Size> arraySizes);
 589
 590     /**
 591      * TODO: can normalization flag be removed?
 592      *
 593      * Creates an Element.
 594      *
 595      * @param dt Data type
 596      * @param dk Data kind
 597      * @param norm Flag for normalization
 598      * @param size Vector length, with scalar = 1
 599      * @return element Created Element
 600      */
 601     @callflow(next={"*"})
 602     elementCreate(DataType dt, DataKind dk, bool norm, uint32_t size)
 603        generates (Element element);
 604
 605     /**
 606      * Creates a complex Element.
 607      *
 608      * @param einsPtr Container of input Elements
 609      * @param namesPtr Container of input names
 610      * @param arraySizesPtr Container of array sizes
 611      * @return element Created Element
 612      */
 613     @callflow(next={"*"})
 614     elementComplexCreate(vec<Element> einsPtr, vec<string> names,
 615                          vec<Size> arraySizesPtr)
 616               generates (Element element);
 617
 618     /**
 619      * Retrives a Type's metadata from native code.
 620      *
 621      * @param type Type describing data layout
 622      * @return metadata Type's native metadata
 623      */
 624     @callflow(next={"*"})
 625     typeGetNativeMetadata(Type type) generates (vec<OpaqueHandle> metadata);
 626
 627     /**
 628      * Creates a new Type.
 629      *
 630      * If Type is 1D, Y and Z must be 0. If Type is 2D, Z must be 0.
 631      *
 632      * @param element Element of the Type
 633      * @param dimX X dimension
 634      * @param dimY Y dimension
 635      * @param dimZ Z dimension
 636      * @param mipmaps Flag indicating whether Type has mipmaps
 637      * @param faces Flag indicating whether Type has faces
 638      * @param yuv Enumeration specifying which type of YUV format, if any, Type
 639      *            uses
 640      * @return type Created Type
 641      */
 642     @callflow(next={"*"})
 643     typeCreate(Element element, uint32_t dimX, uint32_t dimY, uint32_t dimZ,
 644                bool mipmaps, bool faces, YuvFormat yuv)
 645     generates (Type type);
 646
 647     /**
 648      * Destroys provided RenderScript context, including all objects created in
 649      * this context.
 650      */
 651     @exit
 652     contextDestroy();
 653
 654     /**
 655      * TODO: provide overview of messaging model and figure out if this should
 656      * be part of HAL or not.
 657      * TODO: what is the "client" for purposes of this interface?
 658      * TODO: consider using send/receive to be more similar to other calls
 659      * TODO: define the purpose of size more
 660      *
 661      * Fills the provided buffer with message data. "size" should be at least
 662      * as large as the message size. Returns the MessageType and size of the
 663      * message are returned.
 664      *
 665      * @param data A pointer to a buffer to be filled with a message
 666      * @param size Size in bytes of the buffer pointed to by "data"
 667      * @return messageType Type of message sent to the client
 668      * @return receiveLen Length of the message in bytes
 669      */
 670     @callflow(next={"*"})
 671     contextGetMessage(Ptr data, Size size)
 672            generates (MessageToClientType messageType, Size receiveLen);
 673
 674     /**
 675      * TODO: define subID better.
 676      *
 677      * Gets the metadata of a message to ensure entire message can be properly
 678      * received. Can be used to determine size of data to allocate when calling
 679      * contextGetMessage.
 680      *
 681      * @return messageType Type of message sent to the client
 682      * @return receiveLen Length of message
 683      * @return subID Message sub identifier
 684      */
 685     @callflow(next={"*"})
 686     contextPeekMessage()
 687             generates (MessageToClientType messageType, Size receiveLen,
 688                        uint32_t subID);
 689
 690     /**
 691      * TODO: Define "previous commands" better
 692      * TODO: Is the message identifier the same as subID?
 693      *
 694      * Places a message into the message queue to be sent back to the message
 695      * handler once all previous commands have been executed. The message data
 696      * is copied into the queue and can be discarded by the client after this
 697      * call.
 698      *
 699      * @param id Message identifier
 700      * @param data Message data
 701      */
 702     @callflow(next={"*"})
 703     contextSendMessage(uint32_t id, vec<uint8_t> data);
 704
 705     /**
 706      * TODO: Can this be done automatically as part of context creation? What
 707      * happens if we perform message operations before doing this?
 708      *
 709      * Initializes the messaging thread, so that the front-end API can receive
 710      * messages from the driver. This call also waits for the messaging FIFO to
 711      * start up.
 712      */
 713     @callflow(next={"*"})
 714     contextInitToClient();
 715
 716     /**
 717      * TODO: Why doesn't this happen automatically as part of context
 718      * destruction? What happens if the FIFO is not empty?
 719      *
 720      * Deinitializes a the messaging thread. Shuts down the FIFO.
 721      */
 722     @callflow(next={"*"})
 723     contextDeinitToClient();
 724
 725     /**
 726      * TODO: do we need to mark asynchronous operations in this interface
 727      * definition?
 728      *
 729      * Waits for any pending asynchronous operations (such as copies to a RS
 730      * allocation or RS script executions) to complete.
 731      */
 732     @callflow(next={"*"})
 733     contextFinish();
 734
 735     /**
 736      * Prints the currently available debugging information about the state of
 737      * the RS context to the logcat.
 738      */
 739     @callflow(next={"*"})
 740     contextLog();
 741
 742     /**
 743      * TODO: full path? relative path? Investigate further.
 744      *
 745      * Sets the cache directory of the context.
 746      *
 747      * @param cacheDir Name of the application's cache directory
 748      */
 749     @callflow(next={"*"})
 750     contextSetCacheDir(string cacheDir);
 751
 752     /**
 753      * TODO: does this apply to the GPU as well?
 754      *
 755      * Changes the priority of the cpu worker threads for this context.
 756      *
 757      * @param priority Priority of the thread
 758      */
 759     @callflow(next={"*"})
 760     contextSetPriority(ThreadPriorities priority);
 761
 762     /**
 763      * TODO: does this need to be part of the HAL? What if the object already
 764      * has a name?
 765      *
 766      * Assigns a name to a base object.
 767      *
 768      * @param obj Object to be named
 769      * @param name Assigned name
 770      */
 771     @callflow(next={"*"})
 772     assignName(ObjectBase obj, string name);
 773
 774     /**
 775      * TODO: what if the object has no name?
 776      *
 777      * Returns the name of an object.
 778      *
 779      * @param obj Object to be read
 780      * @return name Name of the object
 781      */
 782     @callflow(next={"*"})
 783     getName(ObjectBase obj) generates (string name);
 784
 785     /**
 786      * TODO: starting here we have a set of interfaces for use with
 787      * ScriptGroups. At the very least we should indicate for each one that's
 788      * what it's for. Should we include ScriptGroup in the interface names?
 789      * TODO: sweep whole file and remove prefix "v" from all parameter names
 790      * TODO: there are some places where we use Size for size, and others where
 791      * we use int32_t. Is there a reason it's int32_t? In some cases, it
 792      * requires a negative value.
 793      *
 794      * Creates a Closure which represents a function call to a ForEach Kernel
 795      * combined with arguments and values for global variables.
 796      *
 797      * @param kernelID Kernel identifier
 798      * @param returnValue Allocation used in output of Closure
 799      * @param fieldIDS Collection of Script's Field identifiers
 800      * @param values Collection of Script's data values
 801      * @param sizes Collection of Script's data sizes
 802      * @param depClosures Collection of Closures
 803      * @param depFieldIDS Collection of Script's dependent Field identifiers
 804      * @return closure Created Closure
 805      */
 806     @callflow(next={"*"})
 807     closureCreate(ScriptKernelID kernelID, Allocation returnValue,
 808                   vec<ScriptFieldID> fieldIDS, vec<int64_t> values,
 809                   vec<int32_t> sizes, vec<Closure> depClosures,
 810                   vec<ScriptFieldID> depFieldIDS)
 811        generates (Closure closure);
 812
 813     /**
 814      * Creates a Closure which represents a function call to a invocable
 815      * function, combined with arguments and values for global variables.
 816      *
 817      * @param invokeID Invokable function identifier
 818      * @param params Collection of Invoke script parameters
 819      * @param fieldIDS Collection of Script Field identifiers
 820      * @param values Collection of values
 821      * @param sizes Collection of sizes
 822      * @return closure Created Closure
 823      */
 824     @callflow(next={"*"})
 825     invokeClosureCreate(ScriptInvokeID invokeID, vec<uint8_t> params,
 826                         vec<ScriptFieldID> fieldIDS, vec<int64_t> values,
 827                         vec<int32_t> sizes)
 828              generates (Closure closure);
 829
 830     /**
 831      * Sets the argument of a Closure at specified index and size to provided
 832      * value.
 833      *
 834      * @param closure Closure to be modified
 835      * @param index Index
 836      * @param value Value
 837      * @param size Size
 838      */
 839     @callflow(next={"*"})
 840     closureSetArg(Closure closure, uint32_t index, Ptr value, int32_t size);
 841
 842     /**
 843      * Sets a global variable in a Closure.
 844      *
 845      * @param closure Closure
 846      * @param fieldID Global's Field identifier
 847      * @param value Value
 848      * @param size Size
 849      */
 850     @callflow(next={"*"})
 851     closureSetGlobal(Closure closure, ScriptFieldID fieldID, int64_t value,
 852                      int32_t size);
 853
 854     /**
 855      * TODO: should slot be unsigned? (applies to other two ID interfaces, too)
 856      *
 857      * Creates a Script Kernel ID.
 858      *
 859      * @param script Script
 860      * @param slot Slot
 861      * @param sig Bitfield describing Kernel signature and operation
 862      * @return scriptKernelID Script's Kernel identifier
 863      */
 864     @callflow(next={"*"})
 865     scriptKernelIDCreate(Script script, int32_t slot,
 866                          bitfield<MetadataSignatureBitval> sig)
 867               generates (ScriptKernelID scriptKernelID);
 868
 869     /**
 870      * Creates a Script Invoke ID.
 871      *
 872      * @param script Script
 873      * @param slot Slot
 874      * @return scriptInvokeID Invoke Script's identifier
 875      */
 876     @callflow(next={"*"})
 877     scriptInvokeIDCreate(Script script, int32_t slot)
 878               generates (ScriptInvokeID scriptInvokeID);
 879
 880     /**
 881      * TODO: describe the return value better. What is it?
 882      *
 883      * Creates a Script Field ID.
 884      *
 885      * @param script Script
 886      * @param slot Slot
 887      * @return scriptFieldID Script's Field identifier
 888      */
 889     @callflow(next={"*"})
 890     scriptFieldIDCreate(Script script, int32_t slot)
 891              generates (ScriptFieldID scriptFieldID);
 892
 893     /**
 894      * TODO: add more description
 895      *
 896      * Creates a Script Group.
 897      *
 898      * @param kernels Collection of Scripts' Kernel identifiers
 899      * @param srcK Source Kernel identifiers
 900      * @param dstK Destination Kernel identifiers
 901      * @param dstF Destination Script Field identifiers
 902      * @param types Collection of Types describing data layout
 903      * @return scriptGroup Created Script Group
 904      */
 905     @callflow(next={"*"})
 906     scriptGroupCreate(vec<ScriptKernelID> kernels, vec<ScriptKernelID> srcK,
 907                       vec<ScriptKernelID> dstK, vec<ScriptFieldID> dstF,
 908                       vec<Type> types)
 909            generates (ScriptGroup scriptGroup);
 910
 911     /**
 912      * Creates a Script Group.
 913      *
 914      * @param name Name
 915      * @param cacheDir Cache directory
 916      * @param closures Collection of Closures
 917      * @return scriptGroup2 Created Script Group
 918      */
 919     @callflow(next={"*"})
 920     scriptGroup2Create(string name, string cacheDir, vec<Closure> closures)
 921             generates (ScriptGroup2 scriptGroup2);
 922
 923     /**
 924      * TODO: if SetInput/Output corresponds to the Java API setInput() and
 925      * setOutput(), which are documented as deprecated in API 23, do we need to
 926      * support them? Or can we fallback to the CPU when they're used? Or can't
 927      * we tell whether they're used early enough to do fallback?
 928      *
 929      * Sets an output of the ScriptGroup. This specifies an Allocation to be
 930      * used for the kernels that require an output Allocation visible after the
 931      * ScriptGroup is executed.
 932      *
 933      * @param sg Script Group
 934      * @param kid Script's Kernel identifier to be changed
 935      * @param alloc Allocation to be filled by output
 936      */
 937     @callflow(next={"*"})
 938     scriptGroupSetOutput(ScriptGroup sg, ScriptKernelID kid, Allocation alloc);
 939
 940     /**
 941      * Sets an input of the Script Group. This specifies an Allocation to be
 942      * used for kernels that require an input Allocation provided from outside
 943      * of the Script Group.
 944      *
 945      * @param sg Script Group
 946      * @param kid Script's Kernel identifier to be changed
 947      * @param alloc Allocation to be read as input
 948      */
 949     @callflow(next={"*"})
 950     scriptGroupSetInput(ScriptGroup sg, ScriptKernelID kid, Allocation alloc);
 951
 952     /**
 953      * Executes a Script Group.
 954      *
 955      * @param sg Script Group to be executed.
 956      */
 957     @callflow(next={"*"})
 958     scriptGroupExecute( ScriptGroup sg);
 959
 960     /**
 961      * Frees any native resources associated with this object. The primary use
 962      * is to force immediate cleanup of resources when it is believed the GC
 963      * may not respond quickly enough.
 964      *
 965      * @param handle Opaque handle to the server-side object to be destroyed
 966      */
 967     @callflow(next={"*"})
 968     objDestroy(ObjectBase obj);
 969
 970     /**
 971      * Creates a Sampler.
 972      *
 973      * @param magFilter Magnification value for the filter
 974      * @param minFilter Minification value for the filter
 975      * @param wrapS S wrapping mode for the sampler
 976      * @param wrapT T wrapping mode for the sampler
 977      * @param wrapR R wrapping mode for the sampler
 978      * @param aniso Anisotropy setting for the sampler
 979      * @return sampler Created Sampler
 980      */
 981     @callflow(next={"*"})
 982     samplerCreate(SamplerValue magFilter, SamplerValue minFilter,
 983                   SamplerValue wrapS, SamplerValue wrapT, SamplerValue wrapR,
 984                   float aniso)
 985        generates (Sampler sampler);
 986
 987     /**
 988      * Binds an Allocation to a global pointer in the Script.
 989      *
 990      * @param script Script to be bound to
 991      * @param allocation Allocation to be bound
 992      * @param slot Slot of a global variable
 993      */
 994     @callflow(next={"*"})
 995     scriptBindAllocation(Script script, Allocation allocation, uint32_t slot);
 996
 997     /**
 998      * TODO: is this necessary?
 999      *
1000      * Sets the timezone of a Script.
1001      *
1002      * @param script Script to be altered
1003      * @param timeZone Time Zone value as text
1004      */
1005     @callflow(next={"*"})
1006     scriptSetTimeZone(Script script, string timeZone);
1007
1008     /**
1009      * TODO: can scriptInvoke be combined with scriptInvokeV?
1010      *
1011      * Launches an invokable function.
1012      *
1013      * @param vs Script to be invoked
1014      * @param slot Slot of invokable function
1015      */
1016     @callflow(next={"*"})
1017     scriptInvoke(Script vs, uint32_t slot);
1018
1019     /**
1020      * Invokes a Script with values.
1021      *
1022      * @param vs Script to be invoked
1023      * @param slot Slot
1024      * @param data Data buffer of packed arguments
1025      */
1026     @callflow(next={"*"})
1027     scriptInvokeV(Script vs, uint32_t slot, vec<uint8_t> data);
1028
1029     /**
1030      * TODO: add documentation for params
1031      * TODO: Should we rename "ScriptCall" to "LaunchOptions"?
1032      *
1033      * Launches a ForEach kernel.
1034      *
1035      * @param vs Script
1036      * @param slot Slot of ForEach Kernel
1037      * @param vains Collection of input Allocations or null
1038      * @param vaout Output Allocation or null
1039      * @param params Collection of parameters
1040      * @param sc Pointer to a ScriptCall, nullptr if unused
1041      */
1042     @callflow(next={"*"})
1043     scriptForEach(Script vs, uint32_t slot, vec<Allocation> vains,
1044                   Allocation vaout, vec<uint8_t> params, Ptr sc);
1045
1046     /**
1047      * Launches a Reduction kernel.
1048      *
1049      * @param vs Script
1050      * @param slot Slot of Reduction Kernel
1051      * @param vains Collection of input Allocations
1052      * @param vaout Output Allocation
1053      * @param sc Pointer to a ScriptCall, nullptr if unused
1054      */
1055     @callflow(next={"*"})
1056     scriptReduce(Script vs, uint32_t slot, vec<Allocation> vains,
1057                  Allocation vaout, Ptr sc);
1058
1059     /**
1060      * Sets a Script's integer variable to a value.
1061      *
1062      * @param vs RenderScript Script
1063      * @param slot Slot number of variable to be updated
1064      * @param value Value to be pushed to variable
1065      */
1066     @callflow(next={"*"})
1067     scriptSetVarI(Script vs, uint32_t slot, int32_t value);
1068
1069     /**
1070      * Sets a Script's Object variable to a value
1071      *
1072      * @param vs RenderScript Script
1073      * @param slot Slot number of variable to be updated
1074      * @param obj ObjectBase
1075      */
1076     @callflow(next={"*"})
1077     scriptSetVarObj( Script vs,  uint32_t slot, ObjectBase obj);
1078
1079     /**
1080      * Sets a Script's long variable to a value.
1081      *
1082      * @param vs RenderScript Script
1083      * @param slot Slot number of variable to be updated
1084      * @param value Value to be pushed to variable
1085      */
1086     @callflow(next={"*"})
1087     scriptSetVarJ(Script vs, uint32_t slot, int64_t value);
1088
1089     /**
1090      * Sets a Script's float variable to a value.
1091      *
1092      * @param vs RenderScript Script
1093      * @param slot Slot number of variable to be updated
1094      * @param value Value to be pushed to variable
1095      */
1096     @callflow(next={"*"})
1097     scriptSetVarF(Script vs, uint32_t slot, float value);
1098
1099     /**
1100      * Sets a Script's double variable to a value.
1101      *
1102      * @param vs RenderScript Script
1103      * @param slot Slot number of variable to be updated
1104      * @param value Value to be pushed to variable
1105      */
1106     @callflow(next={"*"})
1107     scriptSetVarD(Script vs, uint32_t slot, double value);
1108
1109     /**
1110      * Sets a Script's struct variable to a value.
1111      *
1112      * @param vs RenderScript Script
1113      * @param slot Slot number of variable to be updated
1114      * @param data Data to be pushed to variable
1115      */
1116     @callflow(next={"*"})
1117     scriptSetVarV(Script vs, uint32_t slot, vec<uint8_t> data);
1118
1119     /**
1120      * TODO: Why do we have typed setters but only untyped getter?
1121      *
1122      * Retrieves the value from a global variable in a script.
1123      *
1124      * @param vs RenderScript Script
1125      * @param slot Slot number of variable to be read
1126      * @param len Size of data to be filled
1127      * @return data Data to be updated
1128      */
1129     @callflow(next={"*"})
1130     scriptGetVarV(Script vs, uint32_t slot, Size len)
1131        generates (vec<uint8_t> data);
1132
1133     /**
1134      * TODO: Is this a value to be replicated for each member of the array? Or
1135      * is there a representation for each separate member?
1136      *
1137      * Sets the value of a global array of structs, given the Element and
1138      * dimension.
1139      *
1140      * @param vs RenderScript Script
1141      * @param slot Slot number of variable to be updated
1142      * @param data Data
1143      * @param ve Element
1144      * @param dims Collection of dimensions
1145      */
1146     @callflow(next={"*"})
1147     scriptSetVarVE(Script vs, uint32_t slot, vec<uint8_t> data, Element ve,
1148                    vec<uint32_t> dims);
1149
1150     /**
1151      * TODO: is cacheDir redundant with createCache() function? Can we remove
1152      * it?
1153      * TODO: define resName more clearly
1154      *
1155      * Creates a RenderScript C99 kernel script.
1156      *
1157      * @param resName Resource name of the bitcode
1158      * @param cacheDir Cache directory name
1159      * @param text The kernel's bitcode as a uint8_t vector
1160      * @return script Created Script
1161      */
1162     @callflow(next={"*"})
1163     scriptCCreate(string resName, string cacheDir, vec<uint8_t> text)
1164        generates (Script script);
1165
1166     /**
1167      * Creates a RenderScript Intrinsic script.
1168      *
1169      * @param id Intrinsic Script identifier
1170      * @param elem Element
1171      * @return script Created Script
1172      */
1173     @callflow(next={"*"})
1174     scriptIntrinsicCreate(ScriptIntrinsicID id, Element elem)
1175                generates (Script script);
1176
1177 };