You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
380 lines
12 KiB
380 lines
12 KiB
#
|
|
# Copyright (C) 2014 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.
|
|
#
|
|
|
|
header:
|
|
summary: Object Characteristics Functions
|
|
description:
|
|
The functions below can be used to query the characteristics of an Allocation, Element,
|
|
or Sampler object. These objects are created from Java. You can't create them from a
|
|
script.
|
|
|
|
<h5>Allocations:</h5>
|
|
|
|
Allocations are the primary method used to pass data to and from RenderScript kernels.
|
|
|
|
They are a structured collection of cells that can be used to store bitmaps, textures,
|
|
arbitrary data points, etc.
|
|
|
|
This collection of cells may have many dimensions (X, Y, Z, Array0, Array1, Array2, Array3),
|
|
faces (for cubemaps), and level of details (for mipmapping).
|
|
|
|
See the <a href='http://developer.android.com/reference/android/renderscript/Allocation.html'>android.renderscript.Allocation</a> for details on to create Allocations.
|
|
|
|
<h5>Elements:</h5>
|
|
|
|
The term "element" is used a bit ambiguously in RenderScript, as both type information
|
|
for the cells of an Allocation and the instantiation of that type. For example:<ul>
|
|
<li>@rs_element is a handle to a type specification, and</li>
|
|
<li>In functions like @rsGetElementAt(), "element" means the instantiation of the type,
|
|
i.e. a cell of an Allocation.</li></ul>
|
|
|
|
The functions below let you query the characteristics of the type specificiation.
|
|
|
|
An Element can specify a simple data types as found in C, e.g. an integer, float, or
|
|
boolean. It can also specify a handle to a RenderScript object. See @rs_data_type for
|
|
a list of basic types.
|
|
|
|
Elements can specify fixed size vector (of size 2, 3, or 4) versions of the basic types.
|
|
Elements can be grouped together into complex Elements, creating the equivalent of
|
|
C structure definitions.
|
|
|
|
Elements can also have a kind, which is semantic information used to interpret pixel
|
|
data. See @rs_data_kind.
|
|
|
|
When creating Allocations of common elements, you can simply use one of the many predefined
|
|
Elements like <a href='http://developer.android.com/reference/android/renderscript/Element.html#F32_2(android.renderscript.RenderScript)'>F32_2</a>.
|
|
|
|
To create complex Elements, use the <a href='http://developer.android.com/reference/android/renderscript/Element.Builder.html'>Element.Builder</a> Java class.
|
|
|
|
<h5>Samplers:</h5>
|
|
|
|
Samplers objects define how Allocations can be read as structure within a kernel.
|
|
See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.S</a>.
|
|
end:
|
|
|
|
function: rsAllocationGetDimFaces
|
|
ret: uint32_t, "Returns 1 if more than one face is present, 0 otherwise."
|
|
arg: rs_allocation a
|
|
summary: Presence of more than one face
|
|
description:
|
|
If the Allocation is a cubemap, this function returns 1 if there's more than one face
|
|
present. In all other cases, it returns 0.
|
|
|
|
Use @rsGetDimHasFaces() to get the dimension of a currently running kernel.
|
|
test: none
|
|
end:
|
|
|
|
function: rsAllocationGetDimLOD
|
|
ret: uint32_t, "Returns 1 if more than one LOD is present, 0 otherwise."
|
|
arg: rs_allocation a
|
|
summary: Presence of levels of detail
|
|
description:
|
|
Query an Allocation for the presence of more than one Level Of Detail. This is useful
|
|
for mipmaps.
|
|
|
|
Use @rsGetDimLod() to get the dimension of a currently running kernel.
|
|
test: none
|
|
end:
|
|
|
|
function: rsAllocationGetDimX
|
|
ret: uint32_t, "X dimension of the Allocation."
|
|
arg: rs_allocation a
|
|
summary: Size of the X dimension
|
|
description:
|
|
Returns the size of the X dimension of the Allocation.
|
|
|
|
Use @rsGetDimX() to get the dimension of a currently running kernel.
|
|
test: none
|
|
end:
|
|
|
|
function: rsAllocationGetDimY
|
|
ret: uint32_t, "Y dimension of the Allocation."
|
|
arg: rs_allocation a
|
|
summary: Size of the Y dimension
|
|
description:
|
|
Returns the size of the Y dimension of the Allocation. If the Allocation has less
|
|
than two dimensions, returns 0.
|
|
|
|
Use @rsGetDimY() to get the dimension of a currently running kernel.
|
|
test: none
|
|
end:
|
|
|
|
function: rsAllocationGetDimZ
|
|
ret: uint32_t, "Z dimension of the Allocation."
|
|
arg: rs_allocation a
|
|
summary: Size of the Z dimension
|
|
description:
|
|
Returns the size of the Z dimension of the Allocation. If the Allocation has less
|
|
than three dimensions, returns 0.
|
|
|
|
Use @rsGetDimZ() to get the dimension of a currently running kernel.
|
|
test: none
|
|
end:
|
|
|
|
function: rsAllocationGetElement
|
|
ret: rs_element, "Element describing Allocation layout."
|
|
arg: rs_allocation a, "Allocation to get data from."
|
|
summary: Get the object that describes the cell of an Allocation
|
|
description:
|
|
Get the Element object describing the type, kind, and other characteristics of a cell
|
|
of an Allocation. See the rsElement* functions below.
|
|
test: none
|
|
end:
|
|
|
|
function: rsClearObject
|
|
t: rs_element, rs_type, rs_allocation, rs_sampler, rs_script
|
|
ret: void
|
|
arg: #1* dst
|
|
summary: Release an object
|
|
description:
|
|
Tells the run time that this handle will no longer be used to access the the related
|
|
object. If this was the last handle to that object, resource recovery may happen.
|
|
|
|
After calling this function, *dst will be set to an empty handle. See @rsIsObject().
|
|
test: none
|
|
end:
|
|
|
|
function: rsIsObject
|
|
t: rs_element, rs_type, rs_allocation, rs_sampler, rs_script
|
|
ret: bool
|
|
arg: #1 v
|
|
summary: Check for an empty handle
|
|
description:
|
|
Returns true if the handle contains a non-null reference.
|
|
|
|
This function does not validate that the internal pointer used in the handle
|
|
points to an actual valid object; it only checks for null.
|
|
|
|
This function can be used to check the Element returned by @rsElementGetSubElement()
|
|
or see if @rsClearObject() has been called on a handle.
|
|
test: none
|
|
end:
|
|
|
|
function: rsElementGetBytesSize
|
|
version: 16
|
|
ret: uint32_t
|
|
arg: rs_element e
|
|
summary: Size of an Element
|
|
description:
|
|
Returns the size in bytes that an instantiation of this Element will occupy.
|
|
test: none
|
|
end:
|
|
|
|
function: rsElementGetDataKind
|
|
version: 16
|
|
ret: rs_data_kind
|
|
arg: rs_element e
|
|
summary: Kind of an Element
|
|
description:
|
|
Returns the Element's data kind. This is used to interpret pixel data.
|
|
|
|
See @rs_data_kind.
|
|
test: none
|
|
end:
|
|
|
|
function: rsElementGetDataType
|
|
version: 16
|
|
ret: rs_data_type
|
|
arg: rs_element e
|
|
summary: Data type of an Element
|
|
description:
|
|
Returns the Element's base data type. This can be a type similar to C/C++ (e.g.
|
|
RS_TYPE_UNSIGNED_8), a handle (e.g. RS_TYPE_ALLOCATION and RS_TYPE_ELEMENT), or a
|
|
more complex numerical type (e.g. RS_TYPE_UNSIGNED_5_6_5 and RS_TYPE_MATRIX_4X4).
|
|
See @rs_data_type.
|
|
|
|
If the Element describes a vector, this function returns the data type of one of its items.
|
|
Use @rsElementGetVectorSize to get the size of the vector.
|
|
|
|
If the Element describes a structure, RS_TYPE_NONE is returned. Use the rsElementGetSub*
|
|
functions to explore this complex Element.
|
|
test: none
|
|
end:
|
|
|
|
function: rsElementGetSubElement
|
|
version: 16
|
|
ret: rs_element, "Sub-element at the given index."
|
|
arg: rs_element e, "Element to query."
|
|
arg: uint32_t index, "Index of the sub-element to return."
|
|
summary: Sub-element of a complex Element
|
|
description:
|
|
For Elements that represents a structure, this function returns the sub-element at the
|
|
specified index.
|
|
|
|
If the Element is not a structure or the index is greater or equal to the number of
|
|
sub-elements, an invalid handle is returned.
|
|
test: none
|
|
end:
|
|
|
|
function: rsElementGetSubElementArraySize
|
|
version: 16
|
|
ret: uint32_t, "Array size of the sub-element."
|
|
arg: rs_element e, "Element to query."
|
|
arg: uint32_t index, "Index of the sub-element."
|
|
summary: Array size of a sub-element of a complex Element
|
|
description:
|
|
For complex Elements, sub-elements can be statically sized arrays. This function
|
|
returns the array size of the sub-element at the index. This sub-element repetition
|
|
is different than fixed size vectors.
|
|
test: none
|
|
end:
|
|
|
|
function: rsElementGetSubElementCount
|
|
version: 16
|
|
ret: uint32_t, "Number of sub-elements."
|
|
arg: rs_element e, "Element to get data from."
|
|
summary: Number of sub-elements
|
|
description:
|
|
Elements can be simple, such as an int or a float, or a structure with multiple
|
|
sub-elements. This function returns zero for simple Elements and the number of
|
|
sub-elements for complex Elements.
|
|
test: none
|
|
end:
|
|
|
|
function: rsElementGetSubElementName
|
|
version: 16
|
|
ret: uint32_t, "Number of characters copied, excluding the null terminator."
|
|
arg: rs_element e, "Element to get data from."
|
|
arg: uint32_t index, "Index of the sub-element."
|
|
arg: char* name, "Address of the array to store the name into."
|
|
arg: uint32_t nameLength, "Length of the provided name array."
|
|
summary: Name of a sub-element
|
|
description:
|
|
For complex Elements, this function returns the name of the sub-element at the
|
|
specified index.
|
|
test: none
|
|
end:
|
|
|
|
function: rsElementGetSubElementNameLength
|
|
version: 16
|
|
ret: uint32_t, "Length of the sub-element name including the null terminator."
|
|
arg: rs_element e, "Element to get data from."
|
|
arg: uint32_t index, "Index of the sub-element."
|
|
summary: Length of the name of a sub-element
|
|
description:
|
|
For complex Elements, this function returns the length of the name of the sub-element
|
|
at the specified index.
|
|
test: none
|
|
end:
|
|
|
|
function: rsElementGetSubElementOffsetBytes
|
|
version: 16
|
|
ret: uint32_t, "Offset in bytes."
|
|
arg: rs_element e, "Element to get data from."
|
|
arg: uint32_t index, "Index of the sub-element."
|
|
summary: Offset of the instantiated sub-element
|
|
description:
|
|
This function returns the relative position of the instantiation of the specified
|
|
sub-element within the instantiation of the Element.
|
|
|
|
For example, if the Element describes a 32 bit float followed by a 32 bit integer,
|
|
the offset return for the first will be 0 and the second 4.
|
|
test: none
|
|
end:
|
|
|
|
function: rsElementGetVectorSize
|
|
version: 16
|
|
ret: uint32_t, "Length of the element vector."
|
|
arg: rs_element e, "Element to get data from."
|
|
summary: Vector size of the Element
|
|
description:
|
|
Returns the Element's vector size. If the Element does not represent a vector,
|
|
1 is returned.
|
|
test: none
|
|
end:
|
|
|
|
function: rsGetAllocation
|
|
ret: rs_allocation
|
|
arg: const void* p
|
|
deprecated: 22, This function is deprecated and will be removed from the SDK in a future release.
|
|
summary: Return the Allocation for a given pointer
|
|
description:
|
|
Returns the Allocation for a given pointer. The pointer should point within a valid
|
|
allocation. The results are undefined if the pointer is not from a valid Allocation.
|
|
test: none
|
|
end:
|
|
|
|
function: rsSamplerGetAnisotropy
|
|
version: 16
|
|
ret: float
|
|
arg: rs_sampler s
|
|
summary: Anisotropy of the Sampler
|
|
description:
|
|
Get the Sampler's anisotropy.
|
|
|
|
See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.S</a>.
|
|
test: none
|
|
end:
|
|
|
|
function: rsSamplerGetMagnification
|
|
version: 16
|
|
ret: rs_sampler_value
|
|
arg: rs_sampler s
|
|
summary: Sampler magnification value
|
|
description:
|
|
Get the Sampler's magnification value.
|
|
|
|
See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.S</a>.
|
|
test: none
|
|
end:
|
|
|
|
function: rsSamplerGetMinification
|
|
version: 16
|
|
ret: rs_sampler_value
|
|
arg: rs_sampler s
|
|
summary: Sampler minification value
|
|
description:
|
|
Get the Sampler's minification value.
|
|
|
|
See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.S</a>.
|
|
test: none
|
|
end:
|
|
|
|
function: rsSamplerGetWrapS
|
|
version: 16
|
|
ret: rs_sampler_value
|
|
arg: rs_sampler s
|
|
summary: Sampler wrap S value
|
|
description:
|
|
Get the Sampler's wrap S value.
|
|
|
|
See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.S</a>.
|
|
test: none
|
|
end:
|
|
|
|
function: rsSamplerGetWrapT
|
|
version: 16
|
|
ret: rs_sampler_value
|
|
arg: rs_sampler s
|
|
summary: Sampler wrap T value
|
|
description:
|
|
Get the sampler's wrap T value.
|
|
|
|
See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.S</a>.
|
|
test: none
|
|
end:
|
|
|
|
function: rsSetObject
|
|
t: rs_element, rs_type, rs_allocation, rs_sampler, rs_script
|
|
ret: void
|
|
arg: #1* dst
|
|
arg: #1 src
|
|
hidden:
|
|
summary: For internal use.
|
|
description:
|
|
test: none
|
|
end:
|