/*
* 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);
};