1177 lines
44 KiB
Text
1177 lines
44 KiB
Text
/*
|
|
* Copyright (C) 2017 The Android Open Source Project
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
package android.hardware.renderscript@1.0;
|
|
|
|
import android.hardware.renderscript@1.0::types;
|
|
|
|
// TODO: is there any way to keep this documentation in sync with the
|
|
// corresponding Java doc?
|
|
//
|
|
// TODO: Some of the documentation was taken from Java docs, whereas others were
|
|
// undocumented. Because of this, there's somewhat two different styles of
|
|
// comments. Look into having a consistent convention.
|
|
//
|
|
// TODO: There was some confusion as to why some paramters use vec<> and others
|
|
// use Ptr/Size. The convention is that vec<> is used whenever the paramter is
|
|
// only an input parameter. HIDL is not supposed to include any output
|
|
// parameters, so a more explicit Ptr/Size is used.
|
|
|
|
interface IContext {
|
|
|
|
/**
|
|
* TODO: Do we need to define "selectors"? It may be a property of the
|
|
* "adapted allocation" that's returned.
|
|
*
|
|
* Creates an arbitrary window into the base allocation. The type describes
|
|
* the shape of the window. Any dimensions present in the type must be
|
|
* equal to or smaller than the dimensions in the source allocation. A
|
|
* dimension present in the allocation that is not present in the type must
|
|
* be constrained away with the selectors. If a dimension is present in
|
|
* both the type and allocation, one of two things must happen. If the type
|
|
* is smaller than the allocation, a window must be created, the selected
|
|
* value in the adapter for that dimension must act as the base address,
|
|
* and the type must describe the size of the view starting at that point.
|
|
* If the type and allocation dimension are of the same size, then setting
|
|
* the selector for the dimension must be an error.
|
|
*
|
|
* @param type Type describing data layout
|
|
* @param baseAlloc Allocation
|
|
* @return subAlloc AllocationAdapter
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationAdapterCreate(Type type, Allocation baseAlloc)
|
|
generates (AllocationAdapter subAlloc);
|
|
|
|
/**
|
|
* TODO: Need to relate "offset" back to the terminology in
|
|
* allocationAdapterCreate() -- the latter uses the terms "selector" and
|
|
* "selected value". Can we use consistent terminology? Are "offset" and
|
|
* "selector" actually two different things?
|
|
*
|
|
* TODO: Explain the flattened layout in the offsets vec
|
|
*
|
|
* Sets the offsets for an Allocation Adapter.
|
|
*
|
|
* @param alloc AllocationAdapter
|
|
* @param offsets Collection of offsets
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationAdapterOffset(AllocationAdapter alloc, vec<uint32_t> offsets);
|
|
|
|
/**
|
|
* TODO: add more explanation here.
|
|
*
|
|
* Returns the Type of the Allocation.
|
|
*
|
|
* @param allocation Allocation
|
|
* @return type Allocation's Type
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationGetType(Allocation allocation) generates (Type type);
|
|
|
|
/**
|
|
* TODO: more clarification needed describing if the pointer can be aliased
|
|
* or if the data can outlive the allocation.
|
|
*
|
|
* Creates an Allocation for use by scripts with a given Type and a backing
|
|
* pointer. For use with ALLOCATION_USAGE_SHARED.
|
|
*
|
|
* @param type Type describing data layout
|
|
* @param mips AllocationMipmapControl specifies desired mipmap behavior for
|
|
* the allocation
|
|
* @param usage Bit field specifying how the Allocation is utilized
|
|
* @param ptr Pointer to client-side data
|
|
* @return allocation Created Allocation
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationCreateTyped(Type type, AllocationMipmapControl mips,
|
|
bitfield<AllocationUsageType> usage, Ptr ptr)
|
|
generates (Allocation allocation);
|
|
|
|
/**
|
|
* Creates an Allocation from a Bitmap.
|
|
*
|
|
* @param type Type describing data layout
|
|
* @param mips AllocationMipmapControl specifies desired mipmap behavior for
|
|
* the allocation
|
|
* @param bitmap Bitmap source for the allocation data
|
|
* @param usage Bit field specifying how the Allocation is utilized
|
|
* @return allocation Created Allocation containing bitmap data
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationCreateFromBitmap(Type type, AllocationMipmapControl mips,
|
|
vec<uint8_t> bitmap,
|
|
bitfield<AllocationUsageType> usage)
|
|
generates (Allocation allocation);
|
|
|
|
/**
|
|
* Creates a Cubemapped Allocation from a Bitmap.
|
|
*
|
|
* @param type Type describing data layout
|
|
* @param mips AllocationMipmapControl specifies desired mipmap behavior
|
|
* for the allocation
|
|
* @param bitmap Bitmap with cubemap faces layed out in the following
|
|
* format: right, left, top, bottom, front, back
|
|
* @param usage Bit field specifying how the Allocation is used
|
|
* @return allocation Created Allocation containing cubemap data
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationCubeCreateFromBitmap(Type type, AllocationMipmapControl mips,
|
|
vec<uint8_t> bitmap,
|
|
bitfield<AllocationUsageType> usage)
|
|
generates (Allocation allocation);
|
|
|
|
/**
|
|
* Returns the handle to a raw buffer that is being managed by the screen
|
|
* compositor. This operation is only valid for Allocations with
|
|
* USAGE_IO_INPUT.
|
|
*
|
|
* @param allocation Allocation
|
|
* @return nativeWindow NativeWindow object associated with allocation
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationGetNativeWindow(Allocation allocation)
|
|
generates (NativeWindow nativeWindow);
|
|
|
|
/**
|
|
* TODO: more clarification needed
|
|
*
|
|
* Sets the NativeWindow of an Allocation. This operation is only valid
|
|
* for Allocations with USAGE_IO_INPUT.
|
|
*
|
|
* @param allocation Allocation to be modified
|
|
* @pram nativeWindow NativeWindow to associate with allocation
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationSetNativeWindow(Allocation allocation, NativeWindow nativewindow);
|
|
|
|
/**
|
|
* Initialize BufferQueue with specified max number of buffers.
|
|
*
|
|
* @param alloc Allocation
|
|
* @param numBuffer Maximum number of buffers
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationSetupBufferQueue(Allocation alloc, uint32_t numBuffer);
|
|
|
|
/**
|
|
* TODO: clearly define baseAlloc vs subAlloc
|
|
*
|
|
* Shares the BufferQueue with another Allocation. Both must be
|
|
* USAGE_IO_INPUT Allocations.
|
|
*
|
|
* @param baseAlloc Base Allocation
|
|
* @param subAlloc Allocation to use the same buffer queue as the Base
|
|
* Allocation
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationShareBufferQueue(Allocation baseAlloc, Allocation subAlloc);
|
|
|
|
/**
|
|
* Copies from the Allocation into a Bitmap. The bitmap must match the
|
|
* dimensions of the Allocation.
|
|
*
|
|
* HIDL is always running in Passthrough mode for RenderScript, so the
|
|
* buffer is modified directly by the driver.
|
|
*
|
|
* @param allocation Allocation
|
|
* @param data Buffer to be copied into
|
|
* @param sizeBytes Size of the buffer pointed to by "data"
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationCopyToBitmap(Allocation allocation, Ptr data, Size sizeBytes);
|
|
|
|
/**
|
|
* TODO: should we consolidate all [123]DWrite functions or [123]DRead
|
|
* functions into the same API call? Our current plan is to be very similar
|
|
* to the dispatch table API. How much should we deviate from the original
|
|
* API?
|
|
* TODO: better description on Vec3/Vec4 and padding.
|
|
*
|
|
* Copies data into a 1D region of this Allocation.
|
|
*
|
|
* When this HAL entry is executed, all Vec3 elements have been explicitly
|
|
* padded as Vec4 elements.
|
|
*
|
|
* The size of the region is: count * Element's size.
|
|
*
|
|
* @param allocation Allocation to be modified
|
|
* @param offset The offset of the first element to be copied
|
|
* @param lod Selected mipmap level of detail
|
|
* @param count Number of elements to be copied
|
|
* @param data Source data to be copied to Allocation
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocation1DWrite(Allocation allocation, uint32_t offset, uint32_t lod,
|
|
uint32_t count, vec<uint8_t> data);
|
|
|
|
/**
|
|
* Copies a value into a single sub-Element of this Allocation.
|
|
*
|
|
* @param allocation Allocation to be updated
|
|
* @param x X position of the first element in the Allocation to be updated
|
|
* @param y Y position of the first element in the Allocation to be
|
|
* updated; for a 1D Allocation, this value must be 0
|
|
* @param z Z position of the first element in the Allocation to be
|
|
* updated; for a 1D or 2D Allocation, this value must be 0
|
|
* @param lod Selected mipmap level of detail
|
|
* @param data Data to be copied from
|
|
* @param compIdx Component number to identify which sub-Element is updated
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationElementWrite(Allocation allocation, uint32_t x, uint32_t y,
|
|
uint32_t z, uint32_t lod, vec<uint8_t> data,
|
|
Size compIdx);
|
|
|
|
/**
|
|
* Copies from an array into a rectangular region in this Allocation.
|
|
*
|
|
* When this HAL entry is executed, all Vec3 elements have been explicitly
|
|
* padded as Vec4 elements.
|
|
*
|
|
* The size of the region is: w * h * Element's size.
|
|
*
|
|
* @param allocation Allocation to be modified
|
|
* @param xoff X offset of the region to update in this Allocation
|
|
* @param yoff Y offset of the region to update in this Allocation
|
|
* @param lod Selected mipmap level of detail
|
|
* @param face AllocationCubemapFace
|
|
* @param w Width of the region to update
|
|
* @param h Height of the region to update
|
|
* @param data Data to be placed into the Allocation
|
|
* @param stride For 1D Allocation, the stride must be the number of bytes
|
|
* of this Allocation. For 2D and 3D Allocations, the stride
|
|
* must be the stride in X dimension measuring in bytes.
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocation2DWrite(Allocation allocation, uint32_t xoff, uint32_t yoff,
|
|
uint32_t lod, AllocationCubemapFace face, uint32_t w,
|
|
uint32_t h, vec<uint8_t> data, Size stride);
|
|
|
|
/**
|
|
* Copies from an array into a 3D region in this Allocation.
|
|
*
|
|
* When this HAL entry is executed, all Vec3 elements have been explicitly
|
|
* padded as Vec4 elements.
|
|
*
|
|
* The size of the region is: w * h * d * Element's size.
|
|
*
|
|
* @param allocation Allocation to be modified
|
|
* @param xoff X offset of the region to update in this Allocation
|
|
* @param yoff Y offset of the region to update in this Allocation
|
|
* @param zoff Z offset of the region to update in this Allocation
|
|
* @param lod Selected mipmap level of detail
|
|
* @param w Width of the region to update
|
|
* @param h Height of the region to update
|
|
* @param d Depth of the region to update
|
|
* @param data Data to be placed in the Allocation
|
|
* @param stride For 1D Allocation, the stride must be the number of bytes
|
|
* of this Allocation. For 2D and 3D Allocations, the stride
|
|
* must be the stride in X dimension measuring in bytes.
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocation3DWrite(Allocation allocation, uint32_t xoff, uint32_t yoff,
|
|
uint32_t zoff, uint32_t lod, uint32_t w, uint32_t h,
|
|
uint32_t d, vec<uint8_t> data, Size stride);
|
|
|
|
/**
|
|
* Generates a mipmap chain. This is only valid if the Type of the
|
|
* Allocation includes mipmaps.
|
|
*
|
|
* This function generates a complete set of mipmaps from the top level
|
|
* LOD.
|
|
*
|
|
* If the Allocation is also using other memory spaces, a call to
|
|
* allocationSyncAll(context, allocation, usage) is required.
|
|
*
|
|
* @param allocation Allocation which has its top LOD read and lower LOD
|
|
* written to
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationGenerateMipmaps(Allocation allocation);
|
|
|
|
/**
|
|
* Copies all of an Allocation's data into an array.
|
|
*
|
|
* All Vec3 elements of an Allocation are padded to be Vec4, so the data
|
|
* returned by this function automatically includes padding.
|
|
*
|
|
* HIDL is always running in Passthrough mode for RenderScript, so the
|
|
* buffer is modified directly by the driver.
|
|
*
|
|
* @param allocation Allocation to be read
|
|
* @param data Buffer to be copied into
|
|
* @param sizeBytes Size of the buffer pointed to by "data"
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationRead(Allocation allocation, Ptr data, Size sizeBytes);
|
|
|
|
/**
|
|
* Copies a 1D region of this Allocation into an array.
|
|
*
|
|
* All Vec3 elements of an Allocation are padded to be Vec4, so the data
|
|
* returned by this function automatically includes padding.
|
|
*
|
|
* The size of the region is: count * Element's size.
|
|
*
|
|
* HIDL is always running in Passthrough mode for RenderScript, so the
|
|
* buffer is modified directly by the driver.
|
|
*
|
|
* @param allocation Allocation to be read
|
|
* @param xoff X offset of the first element to be copied
|
|
* @param lod Mipmap level of detail
|
|
* @param count The number of elements to be copied
|
|
* @param data Buffer to be copied into
|
|
* @param sizeBytes Size of the buffer pointed to by "data"
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocation1DRead(Allocation allocation, uint32_t xoff, uint32_t lod,
|
|
uint32_t count, Ptr data, Size sizeBytes);
|
|
|
|
/**
|
|
* Returns the value of a single sub-Element of this Allocation.
|
|
*
|
|
* HIDL is always running in Passthrough mode for RenderScript, so the
|
|
* buffer is modified directly by the driver.
|
|
*
|
|
* @param allocation Allocation to be read
|
|
* @param x X position of the first element in the Allocation to be read
|
|
* @param y Y position of the first element in the Allocation to be read
|
|
* @param z Z position of the first element in the Allocation to be read
|
|
* @param lod Mipmap level of detail
|
|
* @param data Buffer to be copied into
|
|
* @param sizeBytes Size of the buffer pointed to by "data"
|
|
* @param compIdx Component number to identify which sub-Element is updated
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationElementRead(Allocation allocation, uint32_t x, uint32_t y,
|
|
uint32_t z, uint32_t lod, Ptr data, Size sizeBytes,
|
|
Size compIdx);
|
|
|
|
/**
|
|
* Copies from a rectangular region in this Allocation to an array.
|
|
*
|
|
* All Vec3 elements of an Allocation are padded to be Vec4, so the data
|
|
* returned by this function automatically includes padding.
|
|
*
|
|
* The size of the region is: w * h * Element's size.
|
|
*
|
|
* HIDL is always running in Passthrough mode for RenderScript, so the
|
|
* buffer is modified directly by the driver.
|
|
*
|
|
* @param allocation Allocation to be read
|
|
* @param xoff X offset of the region to copy in this array
|
|
* @param yoff Y offset of the region to copy in this array
|
|
* @param lod Mipmap level of detail
|
|
* @param face AllocationCubemapFace
|
|
* @param w Width of the region to copy
|
|
* @param h Height of the region to copy
|
|
* @param data Buffer to be copied into
|
|
* @param sizeBytes Size of the buffer pointed to by "data"
|
|
* @param stride For 1D Allocation, the stride must be the number of bytes
|
|
* of this Allocation. For 2D and 3D Allocations, the stride
|
|
* must be the stride in X dimension measuring in bytes.
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocation2DRead(Allocation allocation, uint32_t xoff, uint32_t yoff,
|
|
uint32_t lod, AllocationCubemapFace face, uint32_t w,
|
|
uint32_t h, Ptr data, Size sizeBytes, Size stride);
|
|
|
|
/**
|
|
* Copies from a rectangular cuboid region in this Allocation to an array.
|
|
*
|
|
* All Vec3 elements of an Allocation are padded to be Vec4, so the data
|
|
* returned by this function automatically includes padding.
|
|
*
|
|
* The size of the region is: w * h * d * Element's size.
|
|
*
|
|
* HIDL is always running in Passthrough mode for RenderScript, so the
|
|
* buffer is modified directly by the driver.
|
|
*
|
|
* @param allocation Allocation to be read
|
|
* @param xoff X offset of the region to copy in this array
|
|
* @param yoff Y offset of the region to copy in this array
|
|
* @param zoff Z offset of the region to copy in this array
|
|
* @param lod Mipmap level of detail
|
|
* @param w Width of the region to copy
|
|
* @param h Height of the region to copy
|
|
* @param d Depth of the region to copy
|
|
* @param data Buffer to be copied into
|
|
* @param sizeBytes Size of the buffer pointed to by "data"
|
|
* @param stride For 1D Allocation, the stride must be the number of bytes
|
|
* of this Allocation. For 2D and 3D Allocations, the stride
|
|
* must be the stride in X dimension measuring in bytes.
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocation3DRead(Allocation allocation, uint32_t xoff, uint32_t yoff,
|
|
uint32_t zoff, uint32_t lod, uint32_t w, uint32_t h,
|
|
uint32_t d, Ptr data, Size sizeBytes, Size stride);
|
|
|
|
/**
|
|
* Propagates changes from one usage of the Allocation to the other usages
|
|
* of the Allocation.
|
|
*
|
|
* @param allocation First usage of the Allocation
|
|
* @param usageType Allocation usage type
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationSyncAll(Allocation allocation, AllocationUsageType usageType);
|
|
|
|
/**
|
|
* TODO: describe the functionality of resize1D better
|
|
* TODO: original Java Doc description seems to contradict itself ("with
|
|
* null contents and the region is otherwise undefined")
|
|
* TODO: should "new elements" be "new cells"?
|
|
* TODO: what does "objects are created" mean?
|
|
* TODO: what does "new dimension" mean? IS the type of the resized
|
|
* allocation different than the type before resizing?
|
|
*
|
|
* Resizes a 1D allocation. The contents of the allocation are preserved.
|
|
* If new elements are allocated, objects are created with null contents
|
|
* and the new region is otherwise undefined.
|
|
*
|
|
* If the new region is smaller, the references of any object outside the
|
|
* new region must be released.
|
|
*
|
|
* A new type must be created with the new dimension.
|
|
*
|
|
* @param allocation Allocation to be resized
|
|
* @param dimX New size along the x dimension of the Allocation
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationResize1D(Allocation allocation, uint32_t dimX);
|
|
|
|
/**
|
|
* TODO: There are allocationCopy2DRange and 3DRange, but no 1DRange. Should
|
|
* the interface be cleaned up more?
|
|
*
|
|
* Copies a rectangular region from an Allocation into a rectangular region
|
|
* in this Allocation.
|
|
*
|
|
* @param dstAlloc Allocation to be updated
|
|
* @param dstXoff X offset of the region to update
|
|
* @param dstYoff Y offset of the region to update
|
|
* @param dstMip Selected mipmap level of the Allocation to update
|
|
* @param dstFace Destination AllocationCubemapFace
|
|
* @param width Width of the region to update
|
|
* @param height Height of the region to update
|
|
* @param srcAlloc Source Allocation, to be read
|
|
* @param srcXoff X offset of the region in the source Allocation
|
|
* @param srcYoff Y offset of the region in the source Allocation
|
|
* @param srcMip Selected mipmap level of the source Allocation
|
|
* @param srcFace Source AllocationCubemapFace
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationCopy2DRange(Allocation dstAlloc, uint32_t dstXoff,
|
|
uint32_t dstYoff, uint32_t dstMip,
|
|
AllocationCubemapFace dstFace, uint32_t width,
|
|
uint32_t height, Allocation srcAlloc,
|
|
uint32_t srcXoff, uint32_t srcYoff, uint32_t srcMip,
|
|
AllocationCubemapFace srcFace);
|
|
|
|
/**
|
|
* Copies a rectangular cuboid region into the allocation from another
|
|
* Allocation.
|
|
*
|
|
* @param dstAlloc Allocation to be updated
|
|
* @param dstXoff X offset of the region to update
|
|
* @param dstYoff Y offset of the region to update
|
|
* @param dstZoff Z offset of the region to update
|
|
* @param dstMip Selected mipmap level of the Allocation to update
|
|
* @param width Width of the region to update
|
|
* @param height Height of the region to update
|
|
* @param depth Depth of the region to update
|
|
* @param srcAlloc Source Allocation, to be read
|
|
* @param srcXoff Source X offset of the region in the source Allocation
|
|
* @param srcYoff Source Y offset of the region in the source Allocation
|
|
* @param srcZoff Source Z offset of the region in the souce Allocation
|
|
* @param srcMip Selected mipmap level of the Allocation to read
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationCopy3DRange(Allocation dstAlloc, uint32_t dstXoff,
|
|
uint32_t dstYoff, uint32_t dstZoff, uint32_t dstMip,
|
|
uint32_t width, uint32_t height, uint32_t depth,
|
|
Allocation srcAlloc, uint32_t srcXoff,
|
|
uint32_t srcYoff, uint32_t srcZoff, uint32_t srcMip);
|
|
|
|
/**
|
|
* TODO: define buffer and output stream
|
|
*
|
|
* Sends a buffer to the output stream. The contents of the Allocation may
|
|
* be undefined after this operation. This operation is only valid if
|
|
* USAGE_IO_OUTPUT is set on the Allocation.
|
|
*
|
|
* @param allocation Allocation to be sent
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationIoSend(Allocation allocation);
|
|
|
|
/**
|
|
* Receives the latest input into the Allocation. This operation is only
|
|
* valid if USAGE_IO_INPUT is set on the Allocation, otherwise an error
|
|
* must be reported and no operations may be executed.
|
|
*
|
|
* @param allocation Allocation to be updated
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationIoReceive(Allocation allocation);
|
|
|
|
/**
|
|
* TODO: describe default values for lod, face, and z better.
|
|
* TODO: what cases can invalidate the pointer? Resize? It should be
|
|
* clarified that this method should always return a valid pointer, but the
|
|
* returned pointer might become invalid later.
|
|
*
|
|
* Retrieves the pointer to the actual data an Allocation contains as well
|
|
* as the data's stride.
|
|
*
|
|
* If Allocation lacks the corresponding dimension for lod, face, or z, an
|
|
* error message must be sent to the message queue and nullptr must be
|
|
* returned for dataPtr and 0 for stride. All missing values must be 0 or
|
|
* NONE in the corresponding enum.
|
|
*
|
|
* @param allocation Allocation
|
|
* @param lod Mipmap level of detail
|
|
* @param face AllocationCubemapFace
|
|
* @param z Z position
|
|
* @return pointer Pointer to the server-side data; if this points to an
|
|
* invalid location in memory (because the buffer was
|
|
* freed), this may result in undefined behavior
|
|
* @return stride For 1D Allocation, the stride must be the number of bytes
|
|
* of this Allocation. For 2D and 3D Allocations, the stride
|
|
* must be the stride in X dimension measuring in bytes.
|
|
*/
|
|
@callflow(next={"*"})
|
|
allocationGetPointer(Allocation allocation, uint32_t lod,
|
|
AllocationCubemapFace face, uint32_t z)
|
|
generates (Ptr dataPtr, Size stride);
|
|
|
|
/**
|
|
* Retrieves an Element's metadata from native code.
|
|
*
|
|
* @param element Element to be read
|
|
* @return elemData Element data
|
|
*/
|
|
@callflow(next={"*"})
|
|
elementGetNativeMetadata(Element element)
|
|
generates (vec<uint32_t> elemData);
|
|
|
|
/**
|
|
* TODO: define Sub-Element handles better.
|
|
*
|
|
* Retrieves an Element's sub Elements, specifically their identifiers,
|
|
* names, and sizes.
|
|
*
|
|
* @param element Element to be read
|
|
* @param numSubElem Number of sub-Elements
|
|
* @return ids Sub-Element handles
|
|
* @return names Sub-Element Names
|
|
* @return arraySizes Sizes of sub-Element arrays
|
|
*/
|
|
@callflow(next={"*"})
|
|
elementGetSubElements(Element element, Size numSubElem)
|
|
generates (vec<Element> ids, vec<string> names,
|
|
vec<Size> arraySizes);
|
|
|
|
/**
|
|
* TODO: can normalization flag be removed?
|
|
*
|
|
* Creates an Element.
|
|
*
|
|
* @param dt Data type
|
|
* @param dk Data kind
|
|
* @param norm Flag for normalization
|
|
* @param size Vector length, with scalar = 1
|
|
* @return element Created Element
|
|
*/
|
|
@callflow(next={"*"})
|
|
elementCreate(DataType dt, DataKind dk, bool norm, uint32_t size)
|
|
generates (Element element);
|
|
|
|
/**
|
|
* Creates a complex Element.
|
|
*
|
|
* @param einsPtr Container of input Elements
|
|
* @param namesPtr Container of input names
|
|
* @param arraySizesPtr Container of array sizes
|
|
* @return element Created Element
|
|
*/
|
|
@callflow(next={"*"})
|
|
elementComplexCreate(vec<Element> einsPtr, vec<string> names,
|
|
vec<Size> arraySizesPtr)
|
|
generates (Element element);
|
|
|
|
/**
|
|
* Retrives a Type's metadata from native code.
|
|
*
|
|
* @param type Type describing data layout
|
|
* @return metadata Type's native metadata
|
|
*/
|
|
@callflow(next={"*"})
|
|
typeGetNativeMetadata(Type type) generates (vec<OpaqueHandle> metadata);
|
|
|
|
/**
|
|
* Creates a new Type.
|
|
*
|
|
* If Type is 1D, Y and Z must be 0. If Type is 2D, Z must be 0.
|
|
*
|
|
* @param element Element of the Type
|
|
* @param dimX X dimension
|
|
* @param dimY Y dimension
|
|
* @param dimZ Z dimension
|
|
* @param mipmaps Flag indicating whether Type has mipmaps
|
|
* @param faces Flag indicating whether Type has faces
|
|
* @param yuv Enumeration specifying which type of YUV format, if any, Type
|
|
* uses
|
|
* @return type Created Type
|
|
*/
|
|
@callflow(next={"*"})
|
|
typeCreate(Element element, uint32_t dimX, uint32_t dimY, uint32_t dimZ,
|
|
bool mipmaps, bool faces, YuvFormat yuv)
|
|
generates (Type type);
|
|
|
|
/**
|
|
* Destroys provided RenderScript context, including all objects created in
|
|
* this context.
|
|
*/
|
|
@exit
|
|
contextDestroy();
|
|
|
|
/**
|
|
* TODO: provide overview of messaging model and figure out if this should
|
|
* be part of HAL or not.
|
|
* TODO: what is the "client" for purposes of this interface?
|
|
* TODO: consider using send/receive to be more similar to other calls
|
|
* TODO: define the purpose of size more
|
|
*
|
|
* Fills the provided buffer with message data. "size" should be at least
|
|
* as large as the message size. Returns the MessageType and size of the
|
|
* message are returned.
|
|
*
|
|
* @param data A pointer to a buffer to be filled with a message
|
|
* @param size Size in bytes of the buffer pointed to by "data"
|
|
* @return messageType Type of message sent to the client
|
|
* @return receiveLen Length of the message in bytes
|
|
*/
|
|
@callflow(next={"*"})
|
|
contextGetMessage(Ptr data, Size size)
|
|
generates (MessageToClientType messageType, Size receiveLen);
|
|
|
|
/**
|
|
* TODO: define subID better.
|
|
*
|
|
* Gets the metadata of a message to ensure entire message can be properly
|
|
* received. Can be used to determine size of data to allocate when calling
|
|
* contextGetMessage.
|
|
*
|
|
* @return messageType Type of message sent to the client
|
|
* @return receiveLen Length of message
|
|
* @return subID Message sub identifier
|
|
*/
|
|
@callflow(next={"*"})
|
|
contextPeekMessage()
|
|
generates (MessageToClientType messageType, Size receiveLen,
|
|
uint32_t subID);
|
|
|
|
/**
|
|
* TODO: Define "previous commands" better
|
|
* TODO: Is the message identifier the same as subID?
|
|
*
|
|
* Places a message into the message queue to be sent back to the message
|
|
* handler once all previous commands have been executed. The message data
|
|
* is copied into the queue and can be discarded by the client after this
|
|
* call.
|
|
*
|
|
* @param id Message identifier
|
|
* @param data Message data
|
|
*/
|
|
@callflow(next={"*"})
|
|
contextSendMessage(uint32_t id, vec<uint8_t> data);
|
|
|
|
/**
|
|
* TODO: Can this be done automatically as part of context creation? What
|
|
* happens if we perform message operations before doing this?
|
|
*
|
|
* Initializes the messaging thread, so that the front-end API can receive
|
|
* messages from the driver. This call also waits for the messaging FIFO to
|
|
* start up.
|
|
*/
|
|
@callflow(next={"*"})
|
|
contextInitToClient();
|
|
|
|
/**
|
|
* TODO: Why doesn't this happen automatically as part of context
|
|
* destruction? What happens if the FIFO is not empty?
|
|
*
|
|
* Deinitializes a the messaging thread. Shuts down the FIFO.
|
|
*/
|
|
@callflow(next={"*"})
|
|
contextDeinitToClient();
|
|
|
|
/**
|
|
* TODO: do we need to mark asynchronous operations in this interface
|
|
* definition?
|
|
*
|
|
* Waits for any pending asynchronous operations (such as copies to a RS
|
|
* allocation or RS script executions) to complete.
|
|
*/
|
|
@callflow(next={"*"})
|
|
contextFinish();
|
|
|
|
/**
|
|
* Prints the currently available debugging information about the state of
|
|
* the RS context to the logcat.
|
|
*/
|
|
@callflow(next={"*"})
|
|
contextLog();
|
|
|
|
/**
|
|
* TODO: full path? relative path? Investigate further.
|
|
*
|
|
* Sets the cache directory of the context.
|
|
*
|
|
* @param cacheDir Name of the application's cache directory
|
|
*/
|
|
@callflow(next={"*"})
|
|
contextSetCacheDir(string cacheDir);
|
|
|
|
/**
|
|
* TODO: does this apply to the GPU as well?
|
|
*
|
|
* Changes the priority of the cpu worker threads for this context.
|
|
*
|
|
* @param priority Priority of the thread
|
|
*/
|
|
@callflow(next={"*"})
|
|
contextSetPriority(ThreadPriorities priority);
|
|
|
|
/**
|
|
* TODO: does this need to be part of the HAL? What if the object already
|
|
* has a name?
|
|
*
|
|
* Assigns a name to a base object.
|
|
*
|
|
* @param obj Object to be named
|
|
* @param name Assigned name
|
|
*/
|
|
@callflow(next={"*"})
|
|
assignName(ObjectBase obj, string name);
|
|
|
|
/**
|
|
* TODO: what if the object has no name?
|
|
*
|
|
* Returns the name of an object.
|
|
*
|
|
* @param obj Object to be read
|
|
* @return name Name of the object
|
|
*/
|
|
@callflow(next={"*"})
|
|
getName(ObjectBase obj) generates (string name);
|
|
|
|
/**
|
|
* TODO: starting here we have a set of interfaces for use with
|
|
* ScriptGroups. At the very least we should indicate for each one that's
|
|
* what it's for. Should we include ScriptGroup in the interface names?
|
|
* TODO: sweep whole file and remove prefix "v" from all parameter names
|
|
* TODO: there are some places where we use Size for size, and others where
|
|
* we use int32_t. Is there a reason it's int32_t? In some cases, it
|
|
* requires a negative value.
|
|
*
|
|
* Creates a Closure which represents a function call to a ForEach Kernel
|
|
* combined with arguments and values for global variables.
|
|
*
|
|
* @param kernelID Kernel identifier
|
|
* @param returnValue Allocation used in output of Closure
|
|
* @param fieldIDS Collection of Script's Field identifiers
|
|
* @param values Collection of Script's data values
|
|
* @param sizes Collection of Script's data sizes
|
|
* @param depClosures Collection of Closures
|
|
* @param depFieldIDS Collection of Script's dependent Field identifiers
|
|
* @return closure Created Closure
|
|
*/
|
|
@callflow(next={"*"})
|
|
closureCreate(ScriptKernelID kernelID, Allocation returnValue,
|
|
vec<ScriptFieldID> fieldIDS, vec<int64_t> values,
|
|
vec<int32_t> sizes, vec<Closure> depClosures,
|
|
vec<ScriptFieldID> depFieldIDS)
|
|
generates (Closure closure);
|
|
|
|
/**
|
|
* Creates a Closure which represents a function call to a invocable
|
|
* function, combined with arguments and values for global variables.
|
|
*
|
|
* @param invokeID Invokable function identifier
|
|
* @param params Collection of Invoke script parameters
|
|
* @param fieldIDS Collection of Script Field identifiers
|
|
* @param values Collection of values
|
|
* @param sizes Collection of sizes
|
|
* @return closure Created Closure
|
|
*/
|
|
@callflow(next={"*"})
|
|
invokeClosureCreate(ScriptInvokeID invokeID, vec<uint8_t> params,
|
|
vec<ScriptFieldID> fieldIDS, vec<int64_t> values,
|
|
vec<int32_t> sizes)
|
|
generates (Closure closure);
|
|
|
|
/**
|
|
* Sets the argument of a Closure at specified index and size to provided
|
|
* value.
|
|
*
|
|
* @param closure Closure to be modified
|
|
* @param index Index
|
|
* @param value Value
|
|
* @param size Size
|
|
*/
|
|
@callflow(next={"*"})
|
|
closureSetArg(Closure closure, uint32_t index, Ptr value, int32_t size);
|
|
|
|
/**
|
|
* Sets a global variable in a Closure.
|
|
*
|
|
* @param closure Closure
|
|
* @param fieldID Global's Field identifier
|
|
* @param value Value
|
|
* @param size Size
|
|
*/
|
|
@callflow(next={"*"})
|
|
closureSetGlobal(Closure closure, ScriptFieldID fieldID, int64_t value,
|
|
int32_t size);
|
|
|
|
/**
|
|
* TODO: should slot be unsigned? (applies to other two ID interfaces, too)
|
|
*
|
|
* Creates a Script Kernel ID.
|
|
*
|
|
* @param script Script
|
|
* @param slot Slot
|
|
* @param sig Bitfield describing Kernel signature and operation
|
|
* @return scriptKernelID Script's Kernel identifier
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptKernelIDCreate(Script script, int32_t slot,
|
|
bitfield<MetadataSignatureBitval> sig)
|
|
generates (ScriptKernelID scriptKernelID);
|
|
|
|
/**
|
|
* Creates a Script Invoke ID.
|
|
*
|
|
* @param script Script
|
|
* @param slot Slot
|
|
* @return scriptInvokeID Invoke Script's identifier
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptInvokeIDCreate(Script script, int32_t slot)
|
|
generates (ScriptInvokeID scriptInvokeID);
|
|
|
|
/**
|
|
* TODO: describe the return value better. What is it?
|
|
*
|
|
* Creates a Script Field ID.
|
|
*
|
|
* @param script Script
|
|
* @param slot Slot
|
|
* @return scriptFieldID Script's Field identifier
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptFieldIDCreate(Script script, int32_t slot)
|
|
generates (ScriptFieldID scriptFieldID);
|
|
|
|
/**
|
|
* TODO: add more description
|
|
*
|
|
* Creates a Script Group.
|
|
*
|
|
* @param kernels Collection of Scripts' Kernel identifiers
|
|
* @param srcK Source Kernel identifiers
|
|
* @param dstK Destination Kernel identifiers
|
|
* @param dstF Destination Script Field identifiers
|
|
* @param types Collection of Types describing data layout
|
|
* @return scriptGroup Created Script Group
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptGroupCreate(vec<ScriptKernelID> kernels, vec<ScriptKernelID> srcK,
|
|
vec<ScriptKernelID> dstK, vec<ScriptFieldID> dstF,
|
|
vec<Type> types)
|
|
generates (ScriptGroup scriptGroup);
|
|
|
|
/**
|
|
* Creates a Script Group.
|
|
*
|
|
* @param name Name
|
|
* @param cacheDir Cache directory
|
|
* @param closures Collection of Closures
|
|
* @return scriptGroup2 Created Script Group
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptGroup2Create(string name, string cacheDir, vec<Closure> closures)
|
|
generates (ScriptGroup2 scriptGroup2);
|
|
|
|
/**
|
|
* TODO: if SetInput/Output corresponds to the Java API setInput() and
|
|
* setOutput(), which are documented as deprecated in API 23, do we need to
|
|
* support them? Or can we fallback to the CPU when they're used? Or can't
|
|
* we tell whether they're used early enough to do fallback?
|
|
*
|
|
* Sets an output of the ScriptGroup. This specifies an Allocation to be
|
|
* used for the kernels that require an output Allocation visible after the
|
|
* ScriptGroup is executed.
|
|
*
|
|
* @param sg Script Group
|
|
* @param kid Script's Kernel identifier to be changed
|
|
* @param alloc Allocation to be filled by output
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptGroupSetOutput(ScriptGroup sg, ScriptKernelID kid, Allocation alloc);
|
|
|
|
/**
|
|
* Sets an input of the Script Group. This specifies an Allocation to be
|
|
* used for kernels that require an input Allocation provided from outside
|
|
* of the Script Group.
|
|
*
|
|
* @param sg Script Group
|
|
* @param kid Script's Kernel identifier to be changed
|
|
* @param alloc Allocation to be read as input
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptGroupSetInput(ScriptGroup sg, ScriptKernelID kid, Allocation alloc);
|
|
|
|
/**
|
|
* Executes a Script Group.
|
|
*
|
|
* @param sg Script Group to be executed.
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptGroupExecute( ScriptGroup sg);
|
|
|
|
/**
|
|
* Frees any native resources associated with this object. The primary use
|
|
* is to force immediate cleanup of resources when it is believed the GC
|
|
* may not respond quickly enough.
|
|
*
|
|
* @param handle Opaque handle to the server-side object to be destroyed
|
|
*/
|
|
@callflow(next={"*"})
|
|
objDestroy(ObjectBase obj);
|
|
|
|
/**
|
|
* Creates a Sampler.
|
|
*
|
|
* @param magFilter Magnification value for the filter
|
|
* @param minFilter Minification value for the filter
|
|
* @param wrapS S wrapping mode for the sampler
|
|
* @param wrapT T wrapping mode for the sampler
|
|
* @param wrapR R wrapping mode for the sampler
|
|
* @param aniso Anisotropy setting for the sampler
|
|
* @return sampler Created Sampler
|
|
*/
|
|
@callflow(next={"*"})
|
|
samplerCreate(SamplerValue magFilter, SamplerValue minFilter,
|
|
SamplerValue wrapS, SamplerValue wrapT, SamplerValue wrapR,
|
|
float aniso)
|
|
generates (Sampler sampler);
|
|
|
|
/**
|
|
* Binds an Allocation to a global pointer in the Script.
|
|
*
|
|
* @param script Script to be bound to
|
|
* @param allocation Allocation to be bound
|
|
* @param slot Slot of a global variable
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptBindAllocation(Script script, Allocation allocation, uint32_t slot);
|
|
|
|
/**
|
|
* TODO: is this necessary?
|
|
*
|
|
* Sets the timezone of a Script.
|
|
*
|
|
* @param script Script to be altered
|
|
* @param timeZone Time Zone value as text
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptSetTimeZone(Script script, string timeZone);
|
|
|
|
/**
|
|
* TODO: can scriptInvoke be combined with scriptInvokeV?
|
|
*
|
|
* Launches an invokable function.
|
|
*
|
|
* @param vs Script to be invoked
|
|
* @param slot Slot of invokable function
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptInvoke(Script vs, uint32_t slot);
|
|
|
|
/**
|
|
* Invokes a Script with values.
|
|
*
|
|
* @param vs Script to be invoked
|
|
* @param slot Slot
|
|
* @param data Data buffer of packed arguments
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptInvokeV(Script vs, uint32_t slot, vec<uint8_t> data);
|
|
|
|
/**
|
|
* TODO: add documentation for params
|
|
* TODO: Should we rename "ScriptCall" to "LaunchOptions"?
|
|
*
|
|
* Launches a ForEach kernel.
|
|
*
|
|
* @param vs Script
|
|
* @param slot Slot of ForEach Kernel
|
|
* @param vains Collection of input Allocations or null
|
|
* @param vaout Output Allocation or null
|
|
* @param params Collection of parameters
|
|
* @param sc Pointer to a ScriptCall, nullptr if unused
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptForEach(Script vs, uint32_t slot, vec<Allocation> vains,
|
|
Allocation vaout, vec<uint8_t> params, Ptr sc);
|
|
|
|
/**
|
|
* Launches a Reduction kernel.
|
|
*
|
|
* @param vs Script
|
|
* @param slot Slot of Reduction Kernel
|
|
* @param vains Collection of input Allocations
|
|
* @param vaout Output Allocation
|
|
* @param sc Pointer to a ScriptCall, nullptr if unused
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptReduce(Script vs, uint32_t slot, vec<Allocation> vains,
|
|
Allocation vaout, Ptr sc);
|
|
|
|
/**
|
|
* Sets a Script's integer variable to a value.
|
|
*
|
|
* @param vs RenderScript Script
|
|
* @param slot Slot number of variable to be updated
|
|
* @param value Value to be pushed to variable
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptSetVarI(Script vs, uint32_t slot, int32_t value);
|
|
|
|
/**
|
|
* Sets a Script's Object variable to a value
|
|
*
|
|
* @param vs RenderScript Script
|
|
* @param slot Slot number of variable to be updated
|
|
* @param obj ObjectBase
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptSetVarObj( Script vs, uint32_t slot, ObjectBase obj);
|
|
|
|
/**
|
|
* Sets a Script's long variable to a value.
|
|
*
|
|
* @param vs RenderScript Script
|
|
* @param slot Slot number of variable to be updated
|
|
* @param value Value to be pushed to variable
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptSetVarJ(Script vs, uint32_t slot, int64_t value);
|
|
|
|
/**
|
|
* Sets a Script's float variable to a value.
|
|
*
|
|
* @param vs RenderScript Script
|
|
* @param slot Slot number of variable to be updated
|
|
* @param value Value to be pushed to variable
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptSetVarF(Script vs, uint32_t slot, float value);
|
|
|
|
/**
|
|
* Sets a Script's double variable to a value.
|
|
*
|
|
* @param vs RenderScript Script
|
|
* @param slot Slot number of variable to be updated
|
|
* @param value Value to be pushed to variable
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptSetVarD(Script vs, uint32_t slot, double value);
|
|
|
|
/**
|
|
* Sets a Script's struct variable to a value.
|
|
*
|
|
* @param vs RenderScript Script
|
|
* @param slot Slot number of variable to be updated
|
|
* @param data Data to be pushed to variable
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptSetVarV(Script vs, uint32_t slot, vec<uint8_t> data);
|
|
|
|
/**
|
|
* TODO: Why do we have typed setters but only untyped getter?
|
|
*
|
|
* Retrieves the value from a global variable in a script.
|
|
*
|
|
* @param vs RenderScript Script
|
|
* @param slot Slot number of variable to be read
|
|
* @param len Size of data to be filled
|
|
* @return data Data to be updated
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptGetVarV(Script vs, uint32_t slot, Size len)
|
|
generates (vec<uint8_t> data);
|
|
|
|
/**
|
|
* TODO: Is this a value to be replicated for each member of the array? Or
|
|
* is there a representation for each separate member?
|
|
*
|
|
* Sets the value of a global array of structs, given the Element and
|
|
* dimension.
|
|
*
|
|
* @param vs RenderScript Script
|
|
* @param slot Slot number of variable to be updated
|
|
* @param data Data
|
|
* @param ve Element
|
|
* @param dims Collection of dimensions
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptSetVarVE(Script vs, uint32_t slot, vec<uint8_t> data, Element ve,
|
|
vec<uint32_t> dims);
|
|
|
|
/**
|
|
* TODO: is cacheDir redundant with createCache() function? Can we remove
|
|
* it?
|
|
* TODO: define resName more clearly
|
|
*
|
|
* Creates a RenderScript C99 kernel script.
|
|
*
|
|
* @param resName Resource name of the bitcode
|
|
* @param cacheDir Cache directory name
|
|
* @param text The kernel's bitcode as a uint8_t vector
|
|
* @return script Created Script
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptCCreate(string resName, string cacheDir, vec<uint8_t> text)
|
|
generates (Script script);
|
|
|
|
/**
|
|
* Creates a RenderScript Intrinsic script.
|
|
*
|
|
* @param id Intrinsic Script identifier
|
|
* @param elem Element
|
|
* @return script Created Script
|
|
*/
|
|
@callflow(next={"*"})
|
|
scriptIntrinsicCreate(ScriptIntrinsicID id, Element elem)
|
|
generates (Script script);
|
|
|
|
};
|