Improve the documentation of the RenderScript API.
Only the explanations should be changing.
Change-Id: I889b366e3be44f5ac7f44a199e4b9a47353665e2
diff --git a/api/rs_allocation_data.spec b/api/rs_allocation_data.spec
index fd1e215..27fad2e 100644
--- a/api/rs_allocation_data.spec
+++ b/api/rs_allocation_data.spec
@@ -15,54 +15,75 @@
#
header:
-summary: Allocation routines
+summary: Allocation Data Access Functions
description:
- TODO Adjust documentation.
-
- Functions that can be used to query the characteristics of an allocation,
- to set and get elements of the allocation.
+ The functions below can be used to get and set the cells that comprise
+ an allocation.
+ <ul>
+ <li>Individual cells are accessed using the rsGetElementAt* and
+ @rsSetElementAt functions.</li>
+ <li>Multiple cells can be copied using the rsAllocationCopy* and
+ rsAllocationV* functions.</li>
+ <li>For getting values through a sampler, use @rsSample.</li>
+ </ul>
+ The @rsGetElementAt and rsSetElement* functions are somewhat misnamed.
+ They don't get or set elements, which are akin to data types; they get
+ or set cells. Think of them as rsGetCellAt and and rsSetCellAt.
end:
function: rsAllocationCopy1DRange
version: 14
ret: void
-arg: rs_allocation dstAlloc, "Allocation to copy data into."
-arg: uint32_t dstOff, "The offset of the first element to be copied in the destination allocation."
-arg: uint32_t dstMip, "Mip level in the destination allocation."
-arg: uint32_t count, "The number of elements to be copied."
-arg: rs_allocation srcAlloc, "The source data allocation."
-arg: uint32_t srcOff, "The offset of the first element in data to be copied in the source allocation."
-arg: uint32_t srcMip, "Mip level in the source allocation."
-summary: Copy consecutive values between allocations
+arg: rs_allocation dstAlloc, "Allocation to copy cells into."
+arg: uint32_t dstOff, "Offset in the destination of the first cell to be copied into."
+arg: uint32_t dstMip, "Mip level in the destination allocation. 0 if mip mapping is not used."
+arg: uint32_t count, "Number of cells to be copied."
+arg: rs_allocation srcAlloc, "Source allocation."
+arg: uint32_t srcOff, "Offset in the source of the first cell to be copied."
+arg: uint32_t srcMip, "Mip level in the source allocation. 0 if mip mapping is not used."
+summary: Copy consecutive cells between allocations
description:
- Copies part of an allocation into another allocation.
+ Copies the specified number of cells from one allocation to another.
The two allocations must be different. Using this function to copy whithin
the same allocation yields undefined results.
+
+ The function does not validate whether the offset plus count exceeds the size
+ of either allocation. Be careful!
+
+ This function should only be called between 1D allocations. Calling it
+ on other allocations is undefined.
test: none
end:
function: rsAllocationCopy2DRange
version: 14
ret: void
-arg: rs_allocation dstAlloc, "Allocation to copy data into."
-arg: uint32_t dstXoff, "X offset of the region to update in the destination allocation."
-arg: uint32_t dstYoff, "Y offset of the region to update in the destination allocation."
-arg: uint32_t dstMip, "Mip level in the destination allocation."
-arg: rs_allocation_cubemap_face dstFace, "Cubemap face of the destination allocation, ignored for allocations that aren't cubemaps."
+arg: rs_allocation dstAlloc, "Allocation to copy cells into."
+arg: uint32_t dstXoff, "X offset in the destination of the region to be set."
+arg: uint32_t dstYoff, "Y offset in the destination of the region to be set."
+arg: uint32_t dstMip, "Mip level in the destination allocation. 0 if mip mapping is not used."
+arg: rs_allocation_cubemap_face dstFace, "Cubemap face of the destination allocation. Ignored for allocations that aren't cubemaps."
arg: uint32_t width, "Width of the incoming region to update."
arg: uint32_t height, "Height of the incoming region to update."
-arg: rs_allocation srcAlloc, "The source data allocation."
-arg: uint32_t srcXoff, "X offset in data of the source allocation."
-arg: uint32_t srcYoff, "Y offset in data of the source allocation."
-arg: uint32_t srcMip, "Mip level in the source allocation."
-arg: rs_allocation_cubemap_face srcFace, "Cubemap face of the source allocation, ignored for allocations that aren't cubemaps."
-summary: Copy a rectangular region between allocations
+arg: rs_allocation srcAlloc, "Source allocation."
+arg: uint32_t srcXoff, "X offset in the source."
+arg: uint32_t srcYoff, "Y offset in the source."
+arg: uint32_t srcMip, "Mip level in the source allocation. 0 if mip mapping is not used."
+arg: rs_allocation_cubemap_face srcFace, "Cubemap face of the source allocation. Ignored for allocations that aren't cubemaps."
+summary: Copy a rectangular region of cells between allocations
description:
- Copy a rectangular region into the allocation from another allocation.
+ Copies a rectangular region of cells from one allocation to another.
+ (width * heigth) cells are copied.
The two allocations must be different. Using this function to copy whithin
the same allocation yields undefined results.
+
+ The function does not validate whether the the source or destination region
+ exceeds the size of its respective allocation. Be careful!
+
+ This function should only be called between 2D allocations. Calling it
+ on other allocations is undefined.
test: none
end:
@@ -71,11 +92,41 @@
w: 2, 3, 4
t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
ret: #2#1
-arg: rs_allocation a
-arg: uint32_t x
-summary:
+arg: rs_allocation a, "Allocation to get the data from."
+arg: uint32_t x, "X offset in the allocation of the first cell to be copied from."
+summary: Get a vector from an allocation of scalars
description:
- Get a single element from an allocation.
+ This function returns a vector composed of successive cells of the allocation.
+ It assumes that the allocation contains scalars.
+
+ The "X" in the name indicates that successive values are extracted by
+ increasing the X index. There are currently no functions to get successive
+ values incrementing other dimensions. Use multiple calls to rsGetElementAt()
+ instead.
+
+ For example, when calling rsAllocationVLoadX_int4(a, 20, 30),
+ an int4 composed of a[20, 30], a[21, 30], a[22, 30], and a[23, 30] is returned.
+
+ When retrieving from a three dimensional allocations, use the x, y, z
+ variant. Similarly, use the x, y variant for two dimensional
+ allocations and x for the mono dimensional allocations.
+
+ For efficiency, this function does not validate the inputs. Trying to
+ wrap the X index, exceeding the size of the allocation, or using indexes
+ incompatible with the dimensionality of the allocation yields undefined results.
+
+ See also @rsAllocationVStoreX().
+test: none
+end:
+
+function: rsAllocationVLoadX_#2#1
+version: 22
+w: 2, 3, 4
+t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
+ret: #2#1
+arg: rs_allocation a
+arg: uint32_t x
+arg: uint32_t y, "Y offset in the allocation of the first cell to be copied from."
test: none
end:
@@ -87,18 +138,7 @@
arg: rs_allocation a
arg: uint32_t x
arg: uint32_t y
-test: none
-end:
-
-function: rsAllocationVLoadX_#2#1
-version: 22
-w: 2, 3, 4
-t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
-ret: #2#1
-arg: rs_allocation a
-arg: uint32_t x
-arg: uint32_t y
-arg: uint32_t z
+arg: uint32_t z, "Z offset in the allocation of the first cell to be copied from."
test: none
end:
@@ -107,12 +147,43 @@
w: 2, 3, 4
t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
ret: void
-arg: rs_allocation a
-arg: #2#1 val
-arg: uint32_t x
-summary:
+arg: rs_allocation a, "Allocation to store the data into."
+arg: #2#1 val, "Value to be stored."
+arg: uint32_t x, "X offset in the allocation of the first cell to be copied into."
+summary: Store a vector into an allocation of scalars
description:
- Set a single element of an allocation.
+ This function stores the entries of a vector into successive cells of an
+ allocation. It assumes that the allocation contains scalars.
+
+ The "X" in the name indicates that successive values are stored by
+ increasing the X index. There are currently no functions to store successive
+ values incrementing other dimensions. Use multiple calls to rsSetElementAt()
+ instead.
+
+ For example, when calling rsAllocationVStoreX_int3(a, v, 20, 30),
+ v.x is stored at a[20, 30], v.y at a[21, 30], and v.z at a[22, 30].
+
+ When storing into a three dimensional allocations, use the x, y, z
+ variant. Similarly, use the x, y variant for two dimensional
+ allocations and x for the mono dimensional allocations.
+
+ For efficiency, this function does not validate the inputs. Trying to
+ wrap the X index, exceeding the size of the allocation, or using indexes
+ incompatible with the dimensionality of the allocation yiels undefined results.
+
+ See also @rsAllocationVLoadX().
+test: none
+end:
+
+function: rsAllocationVStoreX_#2#1
+version: 22
+w: 2, 3, 4
+t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
+ret: void
+arg: rs_allocation a
+arg: #2#1 val
+arg: uint32_t x
+arg: uint32_t y, "Y offset in the allocation of the first cell to be copied into."
test: none
end:
@@ -125,19 +196,7 @@
arg: #2#1 val
arg: uint32_t x
arg: uint32_t y
-test: none
-end:
-
-function: rsAllocationVStoreX_#2#1
-version: 22
-w: 2, 3, 4
-t: u8, u16, u32, u64, i8, i16, i32, i64, f32, f64
-ret: void
-arg: rs_allocation a
-arg: #2#1 val
-arg: uint32_t x
-arg: uint32_t y
-arg: uint32_t z
+arg: uint32_t z, "Z offset in the allocation of the first cell to be copied into."
test: none
end:
@@ -145,9 +204,18 @@
ret: const void*
arg: rs_allocation a
arg: uint32_t x
-summary: Get an element
+summary: Return a cell from an allocation
description:
- Extract a single element from an allocation.
+ This function extracts a single cell from an allocation.
+
+ When retrieving from a three dimensional allocations, use the x, y, z
+ variant. Similarly, use the x, y variant for two dimensional
+ allocations and x for the mono dimensional allocations.
+
+ This function has two styles. One returns the address of the value using a
+ void*, the other returns the actual value, e.g. rsGetElementAt() vs.
+ rsGetElementAt_int4(). For primitive types, always use the latter as it is
+ more efficient.
test: none
end:
@@ -246,11 +314,15 @@
arg: rs_allocation a
arg: uint32_t x
arg: uint32_t y
-summary:
+summary: Get the U component of an allocation of YUVs
description:
- Extract a single element from an allocation.
+ Extracts the U component of a single YUV value from a 2D allocation of YUVs.
- Coordinates are in the dimensions of the Y plane
+ Inside an allocation, Y, U, and V components may be stored if different planes
+ and at different resolutions. The x, y coordinates provided here are in the
+ dimensions of the Y plane.
+
+ See @rsGetElementAtYuv_uchar_Y().
test: none
end:
@@ -260,11 +332,15 @@
arg: rs_allocation a
arg: uint32_t x
arg: uint32_t y
-summary:
+summary: Get the V component of an allocation of YUVs
description:
- Extract a single element from an allocation.
+ Extracts the V component of a single YUV value from a 2D allocation of YUVs.
- Coordinates are in the dimensions of the Y plane
+ Inside an allocation, Y, U, and V components may be stored if different planes
+ and at different resolutions. The x, y coordinates provided here are in the
+ dimensions of the Y plane.
+
+ See @rsGetElementAtYuv_uchar_Y().
test: none
end:
@@ -274,24 +350,32 @@
arg: rs_allocation a
arg: uint32_t x
arg: uint32_t y
-summary:
+summary: Get the Y component of an allocation of YUVs
description:
- Extract a single element from an allocation.
+ Extracts the Y component of a single YUV value from a 2D allocation of YUVs.
+
+ Inside an allocation, Y, U, and V components may be stored if different planes
+ and at different resolutions. The x, y coordinates provided here are in the
+ dimensions of the Y plane.
+
+ See @rsGetElementAtYuv_uchar_U() and @rsGetElementAtYuv_uchar_V().
test: none
end:
function: rsSample
version: 16
ret: float4
-arg: rs_allocation a, "allocation to sample from"
-arg: rs_sampler s, "sampler state"
-arg: float location, "location to sample from"
-summary:
+arg: rs_allocation a, "Allocation to sample from."
+arg: rs_sampler s, "Sampler state."
+arg: float location, "Location to sample from."
+summary: Sample a value from a texture allocation
description:
- Fetch allocation in a way described by the sampler
+ Fetches a value from a texture allocation in a way described by the sampler.
- If your allocation is 1D, use the variant with float for location.
- For 2D, use the float2 variant.
+ If your allocation is 1D, use the variant with float for location. For 2D,
+ use the float2 variant.
+
+ See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.Sampler</a> for more details.
test: none
end:
@@ -301,7 +385,7 @@
arg: rs_allocation a
arg: rs_sampler s
arg: float location
-arg: float lod, "mip level to sample from, for fractional values mip levels will be interpolated if RS_SAMPLER_LINEAR_MIP_LINEAR is used"
+arg: float lod, "Mip level to sample from, for fractional values mip levels will be interpolated if RS_SAMPLER_LINEAR_MIP_LINEAR is used."
test: none
end:
@@ -330,9 +414,20 @@
arg: rs_allocation a
arg: void* ptr
arg: uint32_t x
-summary: Set an element
+summary: Set a cell of an allocation
description:
- Set single element of an allocation.
+ This function stores a value into a single cell of an allocation.
+
+ When storing into a three dimensional allocations, use the x, y, z
+ variant. Similarly, use the x, y variant for two dimensional
+ allocations and x for the mono dimensional allocations.
+
+ This function has two styles. One passes the value to be stored using
+ a void*, the other has the actual value as an argument, e.g. rsSetElementAt()
+ vs. rsSetElementAt_int4(). For primitive types, always use the latter as it is
+ more efficient.
+
+ See also @rsGetElementAt().
test: none
end:
diff --git a/api/rs_atomic.spec b/api/rs_atomic.spec
index 8add583..7bee720 100644
--- a/api/rs_atomic.spec
+++ b/api/rs_atomic.spec
@@ -15,13 +15,13 @@
#
header:
-summary: Atomic routines
+summary: Atomic Update Functions
description:
To update values shared between multiple threads, use the functions below.
They ensure that the values are atomically updated, i.e. that the memory
- reads, the updates, and the memory writes are all done in the right order.
+ reads, the updates, and the memory writes are done in the right order.
- These functions are slower than just doing the non-atomic variants, so use
+ These functions are slower than their non-atomic equivalents, so use
them only when synchronization is needed.
Note that in RenderScript, your code is likely to be running in separate
@@ -33,9 +33,9 @@
function: rsAtomicAdd
version: 14
-ret: int32_t, "Old value"
-arg: volatile int32_t* addr, "Address of the value to modify"
-arg: int32_t value, "Amount to add"
+ret: int32_t, "Value of *addr prior to the operation."
+arg: volatile int32_t* addr, "Address of the value to modify."
+arg: int32_t value, "Amount to add."
summary: Thread-safe addition
description:
Atomicly adds a value to the value at addr, i.e. <code>*addr += value</code>.
@@ -52,13 +52,13 @@
function: rsAtomicAnd
version: 14
-ret: int32_t, "Old value"
-arg: volatile int32_t* addr, "Address of the value to modify"
-arg: int32_t value, "Value to and with"
+ret: int32_t, "Value of *addr prior to the operation."
+arg: volatile int32_t* addr, "Address of the value to modify."
+arg: int32_t value, "Value to and with."
summary: Thread-safe bitwise and
description:
Atomicly performs a bitwise and of two values, storing the result back at addr,
- i.e. <code>*addr &= value</code>
+ i.e. <code>*addr &= value</code>.
test: none
end:
@@ -72,17 +72,17 @@
function: rsAtomicCas
version: 14
-ret: int32_t, "Old value"
-arg: volatile int32_t* addr, "The address to compare and replace if the compare passes."
+ret: int32_t, "Value of *addr prior to the operation."
+arg: volatile int32_t* addr, "The address of the value to compare and replace if the test passes."
arg: int32_t compareValue, "The value to test *addr against."
arg: int32_t newValue, "The value to write if the test passes."
summary: Thread-safe compare and set
description:
If the value at addr matches compareValue then the newValue is written at addr,
- i.e. <code>if (*addr == compareValue) { *addr = newValue; }</code>
+ i.e. <code>if (*addr == compareValue) { *addr = newValue; }</code>.
You can check that the value was written by checking that the value returned
- by rsAtomicCas is compareValue.
+ by rsAtomicCas() is compareValue.
test: none
end:
@@ -97,11 +97,11 @@
function: rsAtomicDec
version: 14
-ret: int32_t, "Old value"
-arg: volatile int32_t* addr, "Address of the value to decrement"
+ret: int32_t, "Value of *addr prior to the operation."
+arg: volatile int32_t* addr, "Address of the value to decrement."
summary: Thread-safe decrement
description:
- Atomicly subtracts one from the value at addr. Equal to <code>@rsAtomicSub(addr, 1)</code>
+ Atomicly subtracts one from the value at addr. This is equivalent to <code>@rsAtomicSub(addr, 1)</code>.
test: none
end:
@@ -114,11 +114,11 @@
function: rsAtomicInc
version: 14
-ret: int32_t, "Old value"
-arg: volatile int32_t* addr, "Address of the value to increment"
+ret: int32_t, "Value of *addr prior to the operation."
+arg: volatile int32_t* addr, "Address of the value to increment."
summary: Thread-safe increment
description:
- Atomicly adds one to the value at addr. Equal to <code>@rsAtomicAdd(addr, 1)</code>
+ Atomicly adds one to the value at addr. This is equivalent to <code>@rsAtomicAdd(addr, 1)</code>.
test: none
end:
@@ -131,13 +131,13 @@
function: rsAtomicMax
version: 14
-ret: uint32_t, "Old value"
-arg: volatile uint32_t* addr, "Address of the value to modify"
-arg: uint32_t value, "Comparison value"
+ret: uint32_t, "Value of *addr prior to the operation."
+arg: volatile uint32_t* addr, "Address of the value to modify."
+arg: uint32_t value, "Comparison value."
summary: Thread-safe maximum
description:
- Atomicly sets the value at addr to the maximum of addr and value, i.e.
- <code>*addr = max(*addr, value)</code>
+ Atomicly sets the value at addr to the maximum of *addr and value, i.e.
+ <code>*addr = max(*addr, value)</code>.
test: none
end:
@@ -151,13 +151,13 @@
function: rsAtomicMin
version: 14
-ret: uint32_t, "Old value"
-arg: volatile uint32_t* addr, "Address of the value to modify"
-arg: uint32_t value, "Comparison value"
+ret: uint32_t, "Value of *addr prior to the operation."
+arg: volatile uint32_t* addr, "Address of the value to modify."
+arg: uint32_t value, "Comparison value."
summary: Thread-safe minimum
description:
- Atomicly sets the value at addr to the minimum of addr and value, i.e.
- <code>*addr = min(*addr, value)</code>
+ Atomicly sets the value at addr to the minimum of *addr and value, i.e.
+ <code>*addr = min(*addr, value)</code>.
test: none
end:
@@ -171,13 +171,13 @@
function: rsAtomicOr
version: 14
-ret: int32_t, "Old value"
-arg: volatile int32_t* addr, "Address of the value to modify"
-arg: int32_t value, "Value to or with"
+ret: int32_t, "Value of *addr prior to the operation."
+arg: volatile int32_t* addr, "Address of the value to modify."
+arg: int32_t value, "Value to or with."
summary: Thread-safe bitwise or
description:
Atomicly perform a bitwise or two values, storing the result at addr,
- i.e. <code>*addr |= value</code>
+ i.e. <code>*addr |= value</code>.
test: none
end:
@@ -191,12 +191,12 @@
function: rsAtomicSub
version: 14
-ret: int32_t, "Old value"
-arg: volatile int32_t* addr, "Address of the value to modify"
-arg: int32_t value, "Amount to subtract"
+ret: int32_t, "Value of *addr prior to the operation."
+arg: volatile int32_t* addr, "Address of the value to modify."
+arg: int32_t value, "Amount to subtract."
summary: Thread-safe subtraction
description:
- Atomicly subtracts a value from the value at addr, i.e. <code>*addr -= value</code>
+ Atomicly subtracts a value from the value at addr, i.e. <code>*addr -= value</code>.
test: none
end:
@@ -210,13 +210,13 @@
function: rsAtomicXor
version: 14
-ret: int32_t, "Old value"
-arg: volatile int32_t* addr, "Address of the value to modify"
-arg: int32_t value, "Value to xor with"
+ret: int32_t, "Value of *addr prior to the operation."
+arg: volatile int32_t* addr, "Address of the value to modify."
+arg: int32_t value, "Value to xor with."
summary: Thread-safe bitwise exclusive or
description:
Atomicly performs a bitwise xor of two values, storing the result at addr,
- i.e. <code>*addr ^= value</code>
+ i.e. <code>*addr ^= value</code>.
test: none
end:
diff --git a/api/rs_convert.spec b/api/rs_convert.spec
index 8e38a4a..596e66f 100644
--- a/api/rs_convert.spec
+++ b/api/rs_convert.spec
@@ -1,5 +1,5 @@
#
-# Copyright (C) 2014 The Android Open Source Project
+# Copyright (C) 2015 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.
@@ -15,9 +15,10 @@
#
header:
-summary: Conversion functions
+summary: Conversion Functions
description:
- TODO Add desc.
+ The functions below convert from a numerical vector type to another,
+ of from one color representation to another.
end:
function: convert_#3#1
@@ -28,13 +29,17 @@
t: u8, u16, u32, i8, i16, i32, f32
ret: #3#1
arg: #2#1 v, compatible(#3)
-summary: Converts numerical vectors
+summary: Convert numerical vectors
description:
- Component wise conversion from a numerical type to another.
+ Converts a vector from one numerical type to another. The conversion are
+ done entry per entry.
- Conversions of floating point values to integer will truncate.
+ E.g calling <code>a = convert_short3(b)</code> is equivalent to doing
+ <code>a.x = (short)b.x; a.y = (short)b.y; a.z = (short)b.z;</code>.
- Conversions of numbers too large to fit the destination type yield undefined results.
+ Converting floating point values to integer types truncates.
+
+ Converting numbers too large to fit the destination type yields undefined results.
For example, converting a float that contains 1.0e18 to a short is undefined.
Use @clamp() to avoid this.
end:
@@ -72,15 +77,18 @@
function: rsPackColorTo8888
attrib: const
ret: uchar4
-arg: float r
-arg: float g
-arg: float b
-summary:
+arg: float r, "Red component."
+arg: float g, "Green component."
+arg: float b, "Blue component."
+summary: Create a uchar4 RGBA from floats
description:
- Pack floating point (0-1) RGB values into a uchar4.
+ Packs three or four floating point RGBA values into a uchar4. The RGBA values should
+ be between 0.0 and 1.0 inclusive. Values outside of this range are clamped to
+ this range. However numbers greater than INT_MAX or less than INT_MIN can result
+ in undefined behavior.
- For the float3 variant and the variant that only specifies r, g, b,
- the alpha component is set to 255 (1.0).
+ If the alpha component is not specified, it is assumed to be 1.0, i.e. the
+ result will have an alpha set to 255.
test: none
end:
@@ -90,14 +98,14 @@
arg: float r
arg: float g
arg: float b
-arg: float a
+arg: float a, "Alpha component."
test: none
end:
function: rsPackColorTo8888
attrib: const
ret: uchar4
-arg: float3 color
+arg: float3 color, "Vector of 3 or 4 floats containing the R, G, B, and A values."
test: none
end:
@@ -109,12 +117,16 @@
end:
function: rsUnpackColor8888
+# NOTE: The = below indicates that the generator should not add "overloadable" by default.
+# We're doing this to stay backward compatible with the unusual declaration used when this
+# function was introduced.
attrib: =const
ret: float4
arg: uchar4 c
-summary:
+summary: Create a float4 RGBA from uchar4
description:
- Unpack a uchar4 color to float4. The resulting float range will be (0-1).
+ Unpacks a uchar4 color to float4. The resulting floats will be between 0.0 and
+ 1.0 inclusive.
test: none
end:
@@ -123,11 +135,13 @@
w: 4
t: u8, f32
ret: #2#1
-arg: uchar y
-arg: uchar u
-arg: uchar v
-summary:
+arg: uchar y, "Luminance component"
+arg: uchar u, "U chrominance component"
+arg: uchar v, "V chrominance component"
+summary: Convert a YUV value to RGBA
description:
- Convert from YUV to RGBA.
+ Converts a color from a YUV representation to RGBA.
+
+ We currently don't provide a function to do the reverse conversion.
test: none
end:
diff --git a/api/rs_core.spec b/api/rs_core.spec
index 6177d44..51b5dd7 100644
--- a/api/rs_core.spec
+++ b/api/rs_core.spec
@@ -15,7 +15,7 @@
#
header:
-summary: TODO
+summary: Overview
description:
# TODO move elsewhere?
RenderScript is a high-performance runtime that provides
diff --git a/api/rs_debug.spec b/api/rs_debug.spec
index b357b33..4f91a68 100644
--- a/api/rs_debug.spec
+++ b/api/rs_debug.spec
@@ -15,11 +15,10 @@
#
header:
-summary: Utility debugging routines
+summary: Debugging Functions
description:
- Routines intended to be used during application developement. These should
- not be used in shipping applications. All print a string and value pair to
- the standard log.
+ The functions below are intended to be used during application developement.
+ They should not be used in shipping applications.
include:
#define RS_DEBUG(a) rsDebug(#a, a)
#define RS_DEBUG_MARKER rsDebug(__FILE__, __LINE__)
@@ -30,9 +29,12 @@
ret: void
arg: const char* message
arg: #1 a
-summary:
+summary: Log a message and values
description:
- Debug function. Prints a string and value to the log.
+ This function prints a message to the standard log, followed by the provided values.
+
+ This function is intended for debugging only and should not be used in shipping
+ applications.
test: none
end:
diff --git a/api/rs_for_each.spec b/api/rs_for_each.spec
index a16da5f..00d2152 100644
--- a/api/rs_for_each.spec
+++ b/api/rs_for_each.spec
@@ -15,66 +15,99 @@
#
header:
-summary: TODO Add documentation
+summary: Kernel Invocation Functions and Types
description:
- TODO Add documentation
+ The @rsForEach() function can be used to invoke the root kernel of a script.
+
+ The other functions are used to get the characteristics of the invocation of
+ an executing kernel, like dimensions and current indexes. These functions take
+ a @rs_kernel_context as argument.
end:
type: rs_for_each_strategy_t
enum: rs_for_each_strategy
-value: RS_FOR_EACH_STRATEGY_SERIAL = 0
-value: RS_FOR_EACH_STRATEGY_DONT_CARE = 1
-value: RS_FOR_EACH_STRATEGY_DST_LINEAR = 2
-value: RS_FOR_EACH_STRATEGY_TILE_SMALL = 3
-value: RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4
-value: RS_FOR_EACH_STRATEGY_TILE_LARGE = 5
-summary: Launch order hint for rsForEach calls
+value: RS_FOR_EACH_STRATEGY_SERIAL = 0, "Prefer contiguous memory regions."
+value: RS_FOR_EACH_STRATEGY_DONT_CARE = 1, "No prefrences."
+#TODO explain this better
+value: RS_FOR_EACH_STRATEGY_DST_LINEAR = 2, "Prefer DST."
+value: RS_FOR_EACH_STRATEGY_TILE_SMALL = 3, "Prefer processing small rectangular regions."
+value: RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4, "Prefer processing medium rectangular regions."
+value: RS_FOR_EACH_STRATEGY_TILE_LARGE = 5, "Prefer processing large rectangular regions."
+summary: Suggested cell processing order
description:
- Launch order hint for rsForEach calls. This provides a hint to the system to
- determine in which order the root function of the target is called with each
- cell of the allocation.
+ This type is used to suggest how the invoked kernel should iterate over the cells of the
+ allocations. This is a hint only. Implementations may not follow the suggestion.
- This is a hint and implementations may not obey the order.
+ This specification can help the caching behavior of the running kernel, e.g. the cache
+ locality when the processing is distributed over multiple cores.
end:
type: rs_kernel_context
version: 23
simple: const struct rs_kernel_context_t *
-summary: Opaque handle to RenderScript kernel invocation context
+summary: Handle to a kernel invocation context
description:
- TODO
+ The kernel context contains common characteristics of the allocations being iterated
+ over, like dimensions, and rarely used indexes, like the Array0 index or the current
+ level of detail.
+
+ A kernel may be executed in parallel over multiple threads. Each thread will have its
+ own context.
+
+ You can access the context by adding a rs_kernel_context argument to your
+ kernel function. See @rsGetDimX() and @rsGetArray0() for examples.
end:
type: rs_script_call_t
struct: rs_script_call
-field: rs_for_each_strategy_t strategy
-field: uint32_t xStart
-field: uint32_t xEnd
-field: uint32_t yStart
-field: uint32_t yEnd
-field: uint32_t zStart
-field: uint32_t zEnd
-field: uint32_t arrayStart
-field: uint32_t arrayEnd
-summary: Provides extra information to a rsForEach call
+field: rs_for_each_strategy_t strategy, "Currently ignored. In the future, will be suggested cell iteration strategy."
+field: uint32_t xStart, "Starting index in the X dimension."
+field: uint32_t xEnd, "Ending index (exclusive) in the X dimension."
+field: uint32_t yStart, "Starting index in the Y dimension."
+field: uint32_t yEnd, "Ending index (exclusive) in the Y dimension."
+field: uint32_t zStart, "Starting index in the Z dimension."
+field: uint32_t zEnd, "Ending index (exclusive) in the Z dimension."
+field: uint32_t arrayStart, "Starting index in the Array0 dimension."
+field: uint32_t arrayEnd, "Ending index (exclusive) in the Array0 dimension."
+summary: Cell iteration information
description:
- Structure to provide extra information to a rsForEach call. Primarly used to
- restrict the call to a subset of cells in the allocation.
+ This structure is used to provide iteration information to a rsForEach call.
+ It is currently used to restrict processing to a subset of cells. In future
+ versions, it will also be used to provide hint on how to best iterate over
+ the cells.
+
+ The Start fields are inclusive and the End fields are exclusive. E.g. to iterate
+ over cells 4, 5, 6, and 7 in the X dimension, set xStart to 4 and xEnd to 8.
end:
function: rsForEach
version: 9 13
ret: void
-arg: rs_script script, "The target script to call"
-arg: rs_allocation input, "The allocation to source data from"
-arg: rs_allocation output, "the allocation to write date into"
-arg: const void* usrData, "The user defined params to pass to the root script. May be NULL."
-arg: const rs_script_call_t* sc, "Extra control infomation used to select a sub-region of the allocation to be processed or suggest a walking strategy. May be NULL."
-summary:
+arg: rs_script script, "Script to call."
+arg: rs_allocation input, "Allocation to source data from."
+arg: rs_allocation output, "Allocation to write date into."
+arg: const void* usrData, "User defined data to pass to the script. May be NULL."
+arg: const rs_script_call_t* sc, "Extra control information used to select a sub-region of the allocation to be processed or suggest a walking strategy. May be NULL."
+summary: Invoke the root kernel of a script
description:
- Make a script to script call to launch work. One of the input or output is
- required to be a valid object. The input and output must be of the same
- dimensions.
+ Invoke the kernel named "root" of the specified script. Like other kernels, this root()
+ function will be invoked repeatedly over the cells of the specificed allocation, filling
+ the output allocation with the results.
+
+ When rsForEach is called, the root script is launched immediately. rsForEach returns
+ only when the script has completed and the output allocation is ready to use.
+
+ The rs_script argument is typically initialized using a global variable set from Java.
+
+ The kernel can be invoked with just an input allocation or just an output allocation.
+ This can be done by defining an rs_allocation variable and not initializing it. E.g.<code><br/>
+ rs_script gCustomScript;<br/>
+ void specializedProcessing(rs_allocation in) {<br/>
+ rs_allocation ignoredOut;<br/>
+ rsForEach(gCustomScript, in, ignoredOut);<br/>
+ }<br/></code>
+
+ If both input and output allocations are specified, they must have the same dimensions.
test: none
end:
@@ -288,6 +321,8 @@
function. E.g.<br/>
<code>int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) {<br/>
uint32_t size = rsGetDimX(context); //...<br/></code>
+
+ To get the dimension of specific allocation, use @rsAllocationGetDimX().
test: none
end:
@@ -301,6 +336,8 @@
See @rsGetDimX() for an explanation of the context.
Returns 0 if the Y dimension is not present.
+
+ To get the dimension of specific allocation, use @rsAllocationGetDimY().
test: none
end:
@@ -314,6 +351,8 @@
See @rsGetDimX() for an explanation of the context.
Returns 0 if the Z dimension is not present.
+
+ To get the dimension of specific allocation, use @rsAllocationGetDimZ().
test: none
end:
@@ -335,7 +374,7 @@
version: 23
ret: uint32_t
arg: rs_kernel_context ctxt
-summary: Index in the Levels of Detail dimension for the specified context.
+summary: Index in the Levels of Detail dimension for the specified context
description:
Returns the index in the Levels of Detail dimension of the cell being
processed, as specified by the supplied context. See @rsGetArray0() for
diff --git a/api/rs_graphics.spec b/api/rs_graphics.spec
index f90a4f4..4f9d971 100644
--- a/api/rs_graphics.spec
+++ b/api/rs_graphics.spec
@@ -15,11 +15,9 @@
#
header:
-summary: RenderScript graphics API
+summary: Graphics Functions and Types
description:
- NOTE: RenderScript Graphics has been deprecated. Do not use.
-
- A set of graphics functions used by RenderScript.
+ The graphics subsystem of RenderScript has been deprecated.
include:
#ifdef __LP64__
// TODO We need to fix some of the builds before enabling this error:
@@ -34,16 +32,17 @@
version: 16
size: 32
enum:
-value: RS_BLEND_SRC_ZERO = 0
-value: RS_BLEND_SRC_ONE = 1
-value: RS_BLEND_SRC_DST_COLOR = 2
-value: RS_BLEND_SRC_ONE_MINUS_DST_COLOR = 3
-value: RS_BLEND_SRC_SRC_ALPHA = 4
-value: RS_BLEND_SRC_ONE_MINUS_SRC_ALPHA = 5
-value: RS_BLEND_SRC_DST_ALPHA = 6
-value: RS_BLEND_SRC_ONE_MINUS_DST_ALPHA = 7
-value: RS_BLEND_SRC_SRC_ALPHA_SATURATE = 8
-value: RS_BLEND_SRC_INVALID = 100
+value: RS_BLEND_SRC_ZERO = 0
+value: RS_BLEND_SRC_ONE = 1
+value: RS_BLEND_SRC_DST_COLOR = 2
+value: RS_BLEND_SRC_ONE_MINUS_DST_COLOR = 3
+value: RS_BLEND_SRC_SRC_ALPHA = 4
+value: RS_BLEND_SRC_ONE_MINUS_SRC_ALPHA = 5
+value: RS_BLEND_SRC_DST_ALPHA = 6
+value: RS_BLEND_SRC_ONE_MINUS_DST_ALPHA = 7
+value: RS_BLEND_SRC_SRC_ALPHA_SATURATE = 8
+value: RS_BLEND_SRC_INVALID = 100
+deprecated:
summary: Blend source function
description:
end:
@@ -52,15 +51,16 @@
version: 16
size: 32
enum:
-value: RS_BLEND_DST_ZERO = 0
-value: RS_BLEND_DST_ONE = 1
-value: RS_BLEND_DST_SRC_COLOR = 2
-value: RS_BLEND_DST_ONE_MINUS_SRC_COLOR = 3
-value: RS_BLEND_DST_SRC_ALPHA = 4
-value: RS_BLEND_DST_ONE_MINUS_SRC_ALPHA = 5
-value: RS_BLEND_DST_DST_ALPHA = 6
-value: RS_BLEND_DST_ONE_MINUS_DST_ALPHA = 7
-value: RS_BLEND_DST_INVALID = 100
+value: RS_BLEND_DST_ZERO = 0
+value: RS_BLEND_DST_ONE = 1
+value: RS_BLEND_DST_SRC_COLOR = 2
+value: RS_BLEND_DST_ONE_MINUS_SRC_COLOR = 3
+value: RS_BLEND_DST_SRC_ALPHA = 4
+value: RS_BLEND_DST_ONE_MINUS_SRC_ALPHA = 5
+value: RS_BLEND_DST_DST_ALPHA = 6
+value: RS_BLEND_DST_ONE_MINUS_DST_ALPHA = 7
+value: RS_BLEND_DST_INVALID = 100
+deprecated:
summary: Blend destination function
description:
end:
@@ -69,10 +69,11 @@
version: 16
size: 32
enum:
-value: RS_CULL_BACK = 0
-value: RS_CULL_FRONT = 1
-value: RS_CULL_NONE = 2
-value: RS_CULL_INVALID = 100
+value: RS_CULL_BACK = 0
+value: RS_CULL_FRONT = 1
+value: RS_CULL_NONE = 2
+value: RS_CULL_INVALID = 100
+deprecated:
summary: Culling mode
description:
end:
@@ -81,14 +82,15 @@
version: 16
size: 32
enum:
-value: RS_DEPTH_FUNC_ALWAYS = 0, "Always drawn"
-value: RS_DEPTH_FUNC_LESS = 1, "Drawn if the incoming depth value is less than that in the depth buffer"
-value: RS_DEPTH_FUNC_LEQUAL = 2, "Drawn if the incoming depth value is less or equal to that in the depth buffer"
-value: RS_DEPTH_FUNC_GREATER = 3, "Drawn if the incoming depth value is greater than that in the depth buffer"
-value: RS_DEPTH_FUNC_GEQUAL = 4, "Drawn if the incoming depth value is greater or equal to that in the depth buffer"
-value: RS_DEPTH_FUNC_EQUAL = 5, "Drawn if the incoming depth value is equal to that in the depth buffer"
-value: RS_DEPTH_FUNC_NOTEQUAL = 6, "Drawn if the incoming depth value is not equal to that in the depth buffer"
-value: RS_DEPTH_FUNC_INVALID = 100, "Invalid depth function"
+value: RS_DEPTH_FUNC_ALWAYS = 0, "Always drawn"
+value: RS_DEPTH_FUNC_LESS = 1, "Drawn if the incoming depth value is less than that in the depth buffer"
+value: RS_DEPTH_FUNC_LEQUAL = 2, "Drawn if the incoming depth value is less or equal to that in the depth buffer"
+value: RS_DEPTH_FUNC_GREATER = 3, "Drawn if the incoming depth value is greater than that in the depth buffer"
+value: RS_DEPTH_FUNC_GEQUAL = 4, "Drawn if the incoming depth value is greater or equal to that in the depth buffer"
+value: RS_DEPTH_FUNC_EQUAL = 5, "Drawn if the incoming depth value is equal to that in the depth buffer"
+value: RS_DEPTH_FUNC_NOTEQUAL = 6, "Drawn if the incoming depth value is not equal to that in the depth buffer"
+value: RS_DEPTH_FUNC_INVALID = 100, "Invalid depth function"
+deprecated:
summary: Depth function
description:
Specifies conditional drawing depending on the comparison of the incoming
@@ -106,6 +108,7 @@
value: RS_PRIMITIVE_TRIANGLE_STRIP = 4, "Vertices will be rendered as a connected triangle strip defined by the first three vertices with each additional triangle defined by a new vertex"
value: RS_PRIMITIVE_TRIANGLE_FAN = 5, "Vertices will be rendered as a sequence of triangles that all share first vertex as the origin"
value: RS_PRIMITIVE_INVALID = 100, "Invalid primitive"
+deprecated:
summary: How to intepret mesh vertex data
description:
Describes the way mesh vertex data is interpreted when rendering
@@ -114,6 +117,7 @@
type: rs_font
size: 32
simple: _RS_HANDLE
+deprecated:
summary: Handle to a Font
description:
Opaque handle to a RenderScript font object.
@@ -124,6 +128,7 @@
type: rs_mesh
size: 32
simple: _RS_HANDLE
+deprecated:
summary: Handle to a Mesh
description:
Opaque handle to a RenderScript mesh object.
@@ -133,6 +138,7 @@
type: rs_program_fragment
size: 32
simple: _RS_HANDLE
+deprecated:
summary: Handle to a ProgramFragment
description:
Opaque handle to a RenderScript ProgramFragment object.
@@ -142,6 +148,7 @@
type: rs_program_vertex
size: 32
simple: _RS_HANDLE
+deprecated:
summary: Handle to a ProgramVertex
description:
Opaque handle to a RenderScript ProgramVertex object.
@@ -151,6 +158,7 @@
type: rs_program_raster
size: 32
simple: _RS_HANDLE
+deprecated:
summary: Handle to a ProgramRaster
description:
Opaque handle to a RenderScript ProgramRaster object.
@@ -160,6 +168,7 @@
type: rs_program_store
size: 32
simple: _RS_HANDLE
+deprecated:
summary: Handle to a ProgramStore
description:
Opaque handle to a RenderScript ProgramStore object.
@@ -195,7 +204,8 @@
size: 32
ret: void
arg: rs_allocation alloc
-summary:
+deprecated:
+summary: Sync the contents of an allocation
description:
Sync the contents of an allocation.
@@ -221,7 +231,8 @@
ret: void
arg: rs_allocation colorTarget
arg: uint slot
-summary:
+deprecated:
+summary: Set the color target
description:
Set the color target used for all subsequent rendering calls
test: none
@@ -233,7 +244,8 @@
arg: rs_program_fragment ps, "program fragment object"
arg: uint slot, "index of the constant buffer on the program"
arg: rs_allocation c, "constants to bind"
-summary:
+deprecated:
+summary: Bind a constant allocation
description:
Bind a new Allocation object to a ProgramFragment or ProgramVertex.
The Allocation must be a valid constant input for the Program.
@@ -254,7 +266,8 @@
size: 32
ret: void
arg: rs_allocation depthTarget
-summary:
+deprecated:
+summary: Set the depth target
description:
Set the depth target used for all subsequent rendering calls
test: none
@@ -264,7 +277,8 @@
size: 32
ret: void
arg: rs_font font, "object to bind"
-summary:
+deprecated:
+summary: Bind a font object
description:
Binds the font object to be used for all subsequent font rendering calls
test: none
@@ -274,7 +288,8 @@
size: 32
ret: void
arg: rs_program_fragment pf
-summary:
+deprecated:
+summary: Bind a ProgramFragment
description:
Bind a new ProgramFragment to the rendering context.
test: none
@@ -284,7 +299,8 @@
size: 32
ret: void
arg: rs_program_raster pr
-summary:
+deprecated:
+summary: Bind a ProgramRaster
description:
Bind a new ProgramRaster to the rendering context.
test: none
@@ -294,7 +310,8 @@
size: 32
ret: void
arg: rs_program_store ps
-summary:
+deprecated:
+summary: Bind a ProgramStore
description:
Bind a new ProgramStore to the rendering context.
test: none
@@ -304,7 +321,8 @@
size: 32
ret: void
arg: rs_program_vertex pv
-summary:
+deprecated:
+summary: Bind a ProgramVertex
description:
Bind a new ProgramVertex to the rendering context.
test: none
@@ -316,7 +334,8 @@
arg: rs_program_fragment fragment
arg: uint slot
arg: rs_sampler sampler
-summary:
+deprecated:
+summary: Bind a sampler
description:
Bind a new Sampler object to a ProgramFragment. The sampler will
operate on the texture bound at the matching slot.
@@ -329,7 +348,8 @@
arg: rs_program_fragment v
arg: uint slot
arg: rs_allocation alloc
-summary:
+deprecated:
+summary: Bind a texture allocation
description:
Bind a new Allocation object to a ProgramFragment. The
Allocation must be a valid texture for the Program. The sampling
@@ -342,7 +362,8 @@
version: 14
size: 32
ret: void
-summary:
+deprecated:
+summary: Clear all color and depth targets
description:
Clear all color and depth targets and resume rendering into
the framebuffer
@@ -356,7 +377,8 @@
arg: float g
arg: float b
arg: float a
-summary:
+deprecated:
+summary: Clear the specified color from the surface
description:
Clears the rendering surface to the specified color.
test: none
@@ -367,7 +389,8 @@
size: 32
ret: void
arg: uint slot
-summary:
+deprecated:
+summary: Clear the color target
description:
Clear the previously set color target
test: none
@@ -377,7 +400,8 @@
size: 32
ret: void
arg: float value
-summary:
+deprecated:
+summary: Clear the depth surface
description:
Clears the depth suface to the specified value.
test: none
@@ -387,7 +411,8 @@
version: 14
size: 32
ret: void
-summary:
+deprecated:
+summary: Clear the depth target
description:
Clear the previously set depth target
test: none
@@ -397,7 +422,8 @@
size: 32
ret: void
arg: rs_mesh ism, "mesh object to render"
-summary:
+deprecated:
+summary: Draw a mesh
description:
Draw a mesh using the current context state.
@@ -442,7 +468,8 @@
arg: float x4
arg: float y4
arg: float z4
-summary:
+deprecated:
+summary: Draw a quad
description:
Low performance utility function for drawing a simple quad. Not intended for
drawing large quantities of geometry.
@@ -472,7 +499,8 @@
arg: float z4
arg: float u4
arg: float v4
-summary:
+deprecated:
+summary: Draw a textured quad
description:
Low performance utility function for drawing a textured quad. Not intended
for drawing large quantities of geometry.
@@ -487,7 +515,8 @@
arg: float x2
arg: float y2
arg: float z
-summary:
+deprecated:
+summary: Draw a rectangle
description:
Low performance utility function for drawing a simple rectangle. Not
intended for drawing large quantities of geometry.
@@ -502,7 +531,8 @@
arg: float z
arg: float w
arg: float h
-summary:
+deprecated:
+summary: Draw rectangles in screenspace
description:
Low performance function for drawing rectangles in screenspace. This
function uses the default passthough ProgramVertex. Any bound ProgramVertex
@@ -517,7 +547,8 @@
arg: const char* text
arg: int x
arg: int y
-summary:
+deprecated:
+summary: Draw a text string
description:
Draws text given a string and location
test: none
@@ -536,7 +567,8 @@
version: 14
size: 32
ret: uint
-summary:
+deprecated:
+summary: End rendering commands
description:
Force RenderScript to finish all rendering commands
test: none
@@ -549,7 +581,8 @@
arg: float g, "green component"
arg: float b, "blue component"
arg: float a, "alpha component"
-summary:
+deprecated:
+summary: Set the font color
description:
Sets the font color for all subsequent rendering calls
test: none
@@ -558,7 +591,8 @@
function: rsgGetHeight
size: 32
ret: uint
-summary:
+deprecated:
+summary: Get the surface height
description:
Get the height of the current rendering surface.
test: none
@@ -567,7 +601,8 @@
function: rsgGetWidth
size: 32
ret: uint
-summary:
+deprecated:
+summary: Get the surface width
description:
Get the width of the current rendering surface.
test: none
@@ -581,7 +616,8 @@
arg: int* right
arg: int* top
arg: int* bottom
-summary:
+deprecated:
+summary: Get the bounding box for a text string
description:
Returns the bounding box of the text relative to (0, 0)
Any of left, right, top, bottom could be NULL
@@ -609,7 +645,8 @@
arg: float* maxX
arg: float* maxY
arg: float* maxZ
-summary:
+deprecated:
+summary: Compute a bounding box
description:
Computes an axis aligned bounding box of a mesh object
test: none
@@ -640,7 +677,8 @@
ret: rs_allocation, "allocation containing index data"
arg: rs_mesh m, "mesh to get data from"
arg: uint32_t index, "index of the index allocation"
-summary:
+deprecated:
+summary: Return an allocation containing index data
description:
Returns an allocation containing index data or a null
allocation if only the primitive is specified
@@ -653,7 +691,8 @@
ret: rs_primitive, "primitive describing how the mesh is rendered"
arg: rs_mesh m, "mesh to get data from"
arg: uint32_t index, "index of the primitive"
-summary:
+deprecated:
+summary: Return the primitive
description:
Returns the primitive describing how a part of the mesh is
rendered
@@ -665,7 +704,8 @@
size: 32
ret: uint32_t, "number of primitive groups in the mesh. This would include simple primitives as well as allocations containing index data"
arg: rs_mesh m, "mesh to get data from"
-summary:
+deprecated:
+summary: Return the number of index sets
description:
Meshes could have multiple index sets, this function returns
the number.
@@ -678,7 +718,8 @@
ret: rs_allocation, "allocation containing vertex data"
arg: rs_mesh m, "mesh to get data from"
arg: uint32_t index, "index of the vertex allocation"
-summary:
+deprecated:
+summary: Return a vertex allocation
description:
Returns an allocation that is part of the mesh and contains
vertex data, e.g. positions, normals, texcoords
@@ -690,7 +731,8 @@
size: 32
ret: uint32_t, "number of allocations in the mesh that contain vertex data"
arg: rs_mesh m, "mesh to get data from"
-summary:
+deprecated:
+summary: Return the number of vertex allocations
description:
Returns the number of allocations in the mesh that contain
vertex data
@@ -705,7 +747,8 @@
arg: float g
arg: float b
arg: float a
-summary:
+deprecated:
+summary: Set the constant color for a fixed function emulation program
description:
Set the constant color for a fixed function emulation program.
test: none
@@ -715,7 +758,8 @@
size: 32
ret: void
arg: rs_matrix4x4* proj, "matrix to store the current projection matrix into"
-summary:
+deprecated:
+summary: Get the projection matrix for a fixed function vertex program
description:
Get the projection matrix for a currently bound fixed function
vertex program. Calling this function with a custom vertex shader
@@ -727,7 +771,8 @@
size: 32
ret: void
arg: const rs_matrix4x4* model, "model matrix"
-summary:
+deprecated:
+summary: Load the model matrix for a bound fixed function vertex program
description:
Load the model matrix for a currently bound fixed function
vertex program. Calling this function with a custom vertex shader
@@ -739,7 +784,8 @@
size: 32
ret: void
arg: const rs_matrix4x4* proj, "projection matrix"
-summary:
+deprecated:
+summary: Load the projection matrix for a bound fixed function vertex program
description:
Load the projection matrix for a currently bound fixed function
vertex program. Calling this function with a custom vertex shader
@@ -751,7 +797,8 @@
size: 32
ret: void
arg: const rs_matrix4x4* tex, "texture matrix"
-summary:
+deprecated:
+summary: Load the texture matrix for a bound fixed function vertex program
description:
Load the texture matrix for a currently bound fixed function
vertex program. Calling this function with a custom vertex shader
@@ -764,7 +811,8 @@
size: 32
ret: rs_cull_mode
arg: rs_program_raster pr, "program raster to query"
-summary:
+deprecated:
+summary: Get program raster cull mode
description:
Get program raster cull mode
test: none
@@ -775,7 +823,8 @@
size: 32
ret: bool
arg: rs_program_raster pr, "program raster to query"
-summary:
+deprecated:
+summary: Get program raster point sprite state
description:
Get program raster point sprite state
test: none
@@ -786,7 +835,8 @@
size: 32
ret: rs_blend_dst_func
arg: rs_program_store ps, "program store to query"
-summary:
+deprecated:
+summary: Get program store blend destination function
description:
Get program store blend destination function
test: none
@@ -797,7 +847,8 @@
size: 32
ret: rs_blend_src_func
arg: rs_program_store ps, "program store to query"
-summary:
+deprecated:
+summary: Get program store blend source function
description:
Get program store blend source function
test: none
@@ -808,7 +859,8 @@
size: 32
ret: rs_depth_func
arg: rs_program_store ps, "program store to query"
-summary:
+deprecated:
+summary: Get program store depth function
description:
Get program store depth function
test: none
@@ -819,7 +871,8 @@
size: 32
ret: bool
arg: rs_program_store ps, "program store to query"
-summary:
+deprecated:
+summary: Get program store alpha component color mask
description:
Get program store alpha component color mask
test: none
@@ -830,7 +883,8 @@
size: 32
ret: bool
arg: rs_program_store ps, "program store to query"
-summary:
+deprecated:
+summary: Get program store blur component color mask
description:
Get program store blur component color mask
test: none
@@ -841,7 +895,8 @@
size: 32
ret: bool
arg: rs_program_store ps, "program store to query"
-summary:
+deprecated:
+summary: Get program store green component color mask
description:
Get program store green component color mask
test: none
@@ -852,7 +907,8 @@
size: 32
ret: bool
arg: rs_program_store ps, "program store to query"
-summary:
+deprecated:
+summary: Get program store red component color mask
description:
Get program store red component color mask
test: none
@@ -863,7 +919,8 @@
size: 32
ret: bool
arg: rs_program_store ps, "program store to query"
-summary:
+deprecated:
+summary: Get program store depth mask
description:
Get program store depth mask
test: none
@@ -874,7 +931,8 @@
size: 32
ret: bool
arg: rs_program_store ps, "program store to query"
-summary:
+deprecated:
+summary: Get program store dither state
description:
Get program store dither state
test: none
diff --git a/api/rs_io.spec b/api/rs_io.spec
index 05722b7..eca2259 100644
--- a/api/rs_io.spec
+++ b/api/rs_io.spec
@@ -15,64 +15,79 @@
#
header:
-summary: Input/output functions
+summary: Input/Output Functions
description:
- TODO Add documentation
+ These functions are used to:<ul>
+ <li>Send information to the Java client, and</li>
+#TODO We need better documentation for:
+ <li>Send the processed allocation or receive the next allocation to process.</li></ul>
end:
function: rsAllocationIoReceive
version: 16
ret: void
-arg: rs_allocation a, "allocation to work on"
+arg: rs_allocation a, "Allocation to work on."
summary: Receive new content from the queue
description:
Receive a new set of contents from the queue.
+#TODO We need better documentation.
test: none
end:
function: rsAllocationIoSend
version: 16
ret: void
-arg: rs_allocation a, "allocation to work on"
+arg: rs_allocation a, "Allocation to work on."
summary: Send new content to the queue
description:
Send the contents of the Allocation to the queue.
+#TODO We need better documentation.
test: none
end:
function: rsSendToClient
ret: bool
arg: int cmdID
-summary:
+summary: Send a message to the client, non-blocking
description:
- Send a message back to the client. Will not block and returns true
- if the message was sendable and false if the fifo was full.
- A message ID is required. Data payload is optional.
+ Sends a message back to the client. This call does not block.
+ It returns true if the message was sent and false if the
+ message queue is full.
+
+ A message ID is required. The data payload is optional.
+
+ See <a href='http://developer.android.com/reference/android/renderscript/RenderScript.RSMessageHandler.html'>RenderScript.RSMessageHandler</a>.
test: none
end:
function: rsSendToClient
ret: bool
arg: int cmdID
-arg: const void* data
-arg: uint len
+arg: const void* data, "Application specific data."
+arg: uint len, "Length of the data, in bytes."
test: none
end:
function: rsSendToClientBlocking
ret: void
arg: int cmdID
-summary:
+summary: Send a message to the client, blocking
description:
- Send a message back to the client, blocking until the message is queued.
- A message ID is required. Data payload is optional.
+ Sends a message back to the client. This function will block
+ until there is room on the message queue for this message.
+ This function may return before the message was delivered and
+ processed by the client.
+
+ A message ID is required. The data payload is optional.
+
+ See <a href='http://developer.android.com/reference/android/renderscript/RenderScript.RSMessageHandler.html'>RenderScript.RSMessageHandler</a>.
test: none
end:
function: rsSendToClientBlocking
ret: void
arg: int cmdID
-arg: const void* data
-arg: uint len
+arg: const void* data, "Application specific data."
+arg: uint len, "Length of the data, in bytes."
test: none
end:
diff --git a/api/rs_math.spec b/api/rs_math.spec
index 01bc563..a175e82 100644
--- a/api/rs_math.spec
+++ b/api/rs_math.spec
@@ -15,9 +15,9 @@
#
header:
-summary: Mathematical functions
+summary: Mathematical Constants and Functions
description:
- Most mathematical functions can be applied to scalars and vectors.
+ The mathematical functions below can be applied to scalars and vectors.
When applied to vectors, a vector of the function applied to each entry
of the input is returned.
@@ -31,9 +31,8 @@
a = sin(b);<br/>
</code>
-# TODO Adjust documentation
- A few functions like @distance() and @length() interpret instead the input
- as a single vector in n-dimensional space.
+ See <a href='rs_vector_math.html'>"Vector math functions"</a> for functions like @distance() and @length()
+ that interpret instead the input as a single vector in n-dimensional space.
The precision of the mathematical operations is affected by the pragmas
# TODO Create an anchor for the section of http://developer.android.com/guide/topics/renderscript/compute.html that details rs_fp_* and link them here.
@@ -64,8 +63,10 @@
constant: M_2_PIl
value: 0.636619772367581343075535053490057448f
hidden:
-summary: Deprecated. Use M_2_PI instead.
+deprecated: Use M_2_PI instead.
+summary: 2 / pi, as a 32 bit float
description:
+ 2 divided by pi, as a 32 bit float.
end:
constant: M_2_SQRTPI
@@ -2165,11 +2166,10 @@
arg: #1 amount, "The value to clamp"
arg: #1 low, "Lower bound"
arg: #1 high, "Upper bound"
+deprecated: Use @clamp() instead.
summary: Restrain a value to a range
description:
Clamp a value between low and high.
-
- Deprecated. Use @clamp() instead.
test: none
end:
@@ -2177,7 +2177,8 @@
attrib: const
ret: float
arg: float v
-summary:
+deprecated: Use @fract() instead.
+summary: Returns the fractional part of a float
description:
Returns the fractional part of a float
test: none
@@ -2186,7 +2187,7 @@
function: rsRand
ret: int
arg: int max_value
-summary:
+summary: Pseudo-random number
description:
Return a random value between 0 (or min_value) and max_malue.
test: none
diff --git a/api/rs_matrix.spec b/api/rs_matrix.spec
index d69ad1a..830dbec 100644
--- a/api/rs_matrix.spec
+++ b/api/rs_matrix.spec
@@ -15,7 +15,7 @@
#
header:
-summary: Matrix functions
+summary: Matrix Functions
description:
These functions let you manipulate square matrices of rank 2x2, 3x3, and 4x4.
They are particularly useful for graphical transformations and are
@@ -56,7 +56,7 @@
arg: float4* bottom, "bottom plane"
arg: float4* near, "near plane"
arg: float4* far, "far plane"
-summary:
+summary: Compute frustum planes
description:
Computes 6 frustum planes from the view projection matrix
inline:
@@ -116,9 +116,9 @@
arg: float4* bottom, "bottom plane"
arg: float4* near, "near plane"
arg: float4* far, "far plane"
-summary:
+summary: Checks if a sphere is within the frustum planes
description:
- Checks if a sphere is withing the 6 frustum planes
+ Returns true if the sphere is within the 6 frustum planes.
inline:
float distToCenter = dot(left->xyz, sphere->xyz) + left->w;
if (distToCenter < -sphere->w) {
@@ -171,7 +171,6 @@
test: none
end:
-
function: rsMatrixInverseTranspose
ret: bool
arg: rs_matrix4x4* m, "The matrix to modify."
@@ -182,7 +181,6 @@
test: none
end:
-
function: rsMatrixLoad
t: rs_matrix4x4, rs_matrix3x3, rs_matrix2x2
ret: void
diff --git a/api/rs_object_info.spec b/api/rs_object_info.spec
index de700ac..fb77875 100644
--- a/api/rs_object_info.spec
+++ b/api/rs_object_info.spec
@@ -15,15 +15,16 @@
#
header:
-summary: Element functions
+summary: Object Characteristics Functions
description:
- The term "element" is used a bit ambiguously in RenderScript, as both
- the type of an item of an allocation and the instantiation of that type:
- <ul>
- <li>@rs_element is a handle to a type specification, and</li>
+ The functions below can be used to query the characteristics of an allocation,
+ element, or sampler object. These objects are created from Java.
+ The term "element" is used a bit ambiguously in RenderScript, as both
+ the type of an item of an allocation and the instantiation of that type:<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. an item of an allocation.</li></ul>
+ of the type, i.e. an item of an allocation.</li></ul>
The functions below let you query the characteristics of the type specificiation.
@@ -43,17 +44,22 @@
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.
+ 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 details
+summary: Presence of levels of detail
description:
- Query an allocation for the presence of more than one Level Of Details. This is useful for mipmaps.
+ 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:
@@ -63,6 +69,8 @@
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:
@@ -73,6 +81,8 @@
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:
@@ -83,6 +93,8 @@
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:
@@ -99,9 +111,14 @@
t: rs_element, rs_type, rs_allocation, rs_sampler, rs_script
ret: void
arg: #1* dst
-hidden:
-summary: For internal use.
+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:
@@ -109,9 +126,16 @@
t: rs_element, rs_type, rs_allocation, rs_sampler, rs_script
ret: bool
arg: #1 v
-hidden:
-summary: For internal use.
+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:
@@ -247,14 +271,12 @@
function: rsGetAllocation
ret: rs_allocation
arg: const void* p
+deprecated: This function is deprecated and will be removed from the SDK in a future release.
summary: Returns 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.
-
- This function is deprecated and will be removed from the SDK in a future
- release.
test: none
end:
diff --git a/api/rs_object_types.spec b/api/rs_object_types.spec
index 3d912fb..db41287 100644
--- a/api/rs_object_types.spec
+++ b/api/rs_object_types.spec
@@ -15,9 +15,11 @@
#
header:
-summary: Standard RenderScript types
+summary: Object Types
description:
- TODO desc.
+ The types below are used to manipulate RenderScript objects like allocations,
+ samplers, elements, and scripts. Most of these object are created using the Java
+ RenderScript APIs.
include:
#define NULL ((void *)0)
@@ -78,40 +80,6 @@
See: android.renderscript.ScriptC
end:
-type: rs_matrix4x4
-struct:
-field: float m[16]
-summary: 4x4 matrix of 32 bit floats
-description:
- Native holder for RS matrix. Elements are stored in the array at the
- location [row*4 + col]
-end:
-
-type: rs_matrix3x3
-struct:
-field: float m[9]
-summary: 3x3 matrix of 32 bit floats
-description:
- Native holder for RS matrix. Elements are stored in the array at the
- location [row*3 + col]
-end:
-
-type: rs_matrix2x2
-struct:
-field: float m[4]
-summary: 2x2 matrix of 32 bit floats
-description:
- Native holder for RS matrix. Elements are stored in the array at the
- location [row*2 + col]
-end:
-
-type: rs_quaternion
-simple: float4
-summary: Quarternion
-description:
- Quaternion type for use with the quaternion functions
-end:
-
type: rs_allocation_cubemap_face
version: 14
enum:
@@ -142,36 +110,36 @@
type: rs_data_type
version: 16
enum:
-value: RS_TYPE_NONE = 0
-value: RS_TYPE_FLOAT_32 = 2
-value: RS_TYPE_FLOAT_64 = 3
-value: RS_TYPE_SIGNED_8 = 4
-value: RS_TYPE_SIGNED_16 = 5
-value: RS_TYPE_SIGNED_32 = 6
-value: RS_TYPE_SIGNED_64 = 7
-value: RS_TYPE_UNSIGNED_8 = 8
-value: RS_TYPE_UNSIGNED_16 = 9
-value: RS_TYPE_UNSIGNED_32 = 10
-value: RS_TYPE_UNSIGNED_64 = 11
-value: RS_TYPE_BOOLEAN = 12
-value: RS_TYPE_UNSIGNED_5_6_5 = 13
+value: RS_TYPE_NONE = 0
+value: RS_TYPE_FLOAT_32 = 2
+value: RS_TYPE_FLOAT_64 = 3
+value: RS_TYPE_SIGNED_8 = 4
+value: RS_TYPE_SIGNED_16 = 5
+value: RS_TYPE_SIGNED_32 = 6
+value: RS_TYPE_SIGNED_64 = 7
+value: RS_TYPE_UNSIGNED_8 = 8
+value: RS_TYPE_UNSIGNED_16 = 9
+value: RS_TYPE_UNSIGNED_32 = 10
+value: RS_TYPE_UNSIGNED_64 = 11
+value: RS_TYPE_BOOLEAN = 12
+value: RS_TYPE_UNSIGNED_5_6_5 = 13
value: RS_TYPE_UNSIGNED_5_5_5_1 = 14
value: RS_TYPE_UNSIGNED_4_4_4_4 = 15
-value: RS_TYPE_MATRIX_4X4 = 16
-value: RS_TYPE_MATRIX_3X3 = 17
-value: RS_TYPE_MATRIX_2X2 = 18
-value: RS_TYPE_ELEMENT = 1000
-value: RS_TYPE_TYPE = 1001
-value: RS_TYPE_ALLOCATION = 1002
-value: RS_TYPE_SAMPLER = 1003
-value: RS_TYPE_SCRIPT = 1004
-value: RS_TYPE_MESH = 1005
+value: RS_TYPE_MATRIX_4X4 = 16
+value: RS_TYPE_MATRIX_3X3 = 17
+value: RS_TYPE_MATRIX_2X2 = 18
+value: RS_TYPE_ELEMENT = 1000
+value: RS_TYPE_TYPE = 1001
+value: RS_TYPE_ALLOCATION = 1002
+value: RS_TYPE_SAMPLER = 1003
+value: RS_TYPE_SCRIPT = 1004
+value: RS_TYPE_MESH = 1005
value: RS_TYPE_PROGRAM_FRAGMENT = 1006
-value: RS_TYPE_PROGRAM_VERTEX = 1007
-value: RS_TYPE_PROGRAM_RASTER = 1008
-value: RS_TYPE_PROGRAM_STORE = 1009
-value: RS_TYPE_FONT = 1010
-value: RS_TYPE_INVALID = 10000
+value: RS_TYPE_PROGRAM_VERTEX = 1007
+value: RS_TYPE_PROGRAM_RASTER = 1008
+value: RS_TYPE_PROGRAM_STORE = 1009
+value: RS_TYPE_FONT = 1010
+value: RS_TYPE_INVALID = 10000
summary: Element data types
description:
DataType represents the basic type information for a basic element. The
@@ -213,14 +181,14 @@
type: rs_sampler_value
version: 16
enum:
-value: RS_SAMPLER_NEAREST = 0
-value: RS_SAMPLER_LINEAR = 1
-value: RS_SAMPLER_LINEAR_MIP_LINEAR = 2
-value: RS_SAMPLER_WRAP = 3
-value: RS_SAMPLER_CLAMP = 4
-value: RS_SAMPLER_LINEAR_MIP_NEAREST = 5
-value: RS_SAMPLER_MIRRORED_REPEAT = 6
-value: RS_SAMPLER_INVALID = 100
+value: RS_SAMPLER_NEAREST = 0
+value: RS_SAMPLER_LINEAR = 1
+value: RS_SAMPLER_LINEAR_MIP_LINEAR = 2
+value: RS_SAMPLER_WRAP = 3
+value: RS_SAMPLER_CLAMP = 4
+value: RS_SAMPLER_LINEAR_MIP_NEAREST = 5
+value: RS_SAMPLER_MIRRORED_REPEAT = 6
+value: RS_SAMPLER_INVALID = 100
summary: Sampler wrap T value
description:
end:
diff --git a/api/rs_quaternion.spec b/api/rs_quaternion.spec
index 07051a9..6cb280d 100644
--- a/api/rs_quaternion.spec
+++ b/api/rs_quaternion.spec
@@ -15,17 +15,17 @@
#
header:
-summary: Quaternion routines
+summary: Quaternion Functions
description:
end:
function: rsQuaternionAdd
ret: void
-arg: rs_quaternion* q, "destination quaternion to add to"
-arg: const rs_quaternion* rhs, "right hand side quaternion to add"
-summary:
+arg: rs_quaternion* q, "Destination quaternion to add to."
+arg: const rs_quaternion* rhs, "Quaternion to add."
+summary: Add two quaternions
description:
- Add two quaternions
+ Adds two quaternions, i.e. <code>*q += *rhs;</code>
inline:
q->w *= rhs->w;
q->x *= rhs->x;
@@ -36,10 +36,10 @@
function: rsQuaternionConjugate
ret: void
-arg: rs_quaternion* q, "quaternion to conjugate"
-summary:
+arg: rs_quaternion* q, "Quaternion to modify."
+summary: Conjugate a quaternion
description:
- Conjugates the quaternion
+ Conjugates the quaternion.
inline:
q->x = -q->x;
q->y = -q->y;
@@ -48,12 +48,12 @@
end:
function: rsQuaternionDot
-ret: float, "dot product between q0 and q1"
-arg: const rs_quaternion* q0, "first quaternion"
-arg: const rs_quaternion* q1, "second quaternion"
-summary:
+ret: float
+arg: const rs_quaternion* q0, "First quaternion."
+arg: const rs_quaternion* q1, "Second quaternion."
+summary: Dot product of two quaternions
description:
- Dot product of two quaternions
+ Returns the dot product of two quaternions.
inline:
return q0->w*q1->w + q0->x*q1->x + q0->y*q1->y + q0->z*q1->z;
test: none
@@ -61,11 +61,11 @@
function: rsQuaternionGetMatrixUnit
ret: void
-arg: rs_matrix4x4* m, "resulting matrix"
-arg: const rs_quaternion* q, "normalized quaternion"
-summary:
+arg: rs_matrix4x4* m, "Resulting matrix."
+arg: const rs_quaternion* q, "Normalized quaternion."
+summary: Get a rotation matrix from a quaternion
description:
- Computes rotation matrix from the normalized quaternion
+ Computes a rotation matrix from the normalized quaternion.
inline:
float xx = q->x * q->x;
float xy = q->x * q->y;
@@ -93,14 +93,14 @@
function: rsQuaternionLoadRotateUnit
ret: void
-arg: rs_quaternion* q, "quaternion to set"
-arg: float rot, "rot angle to rotate by"
-arg: float x, "component of a vector"
-arg: float y, "component of a vector"
-arg: float z, "component of a vector"
-summary:
+arg: rs_quaternion* q, "Destination quaternion."
+arg: float rot, "Angle to rotate by, in radians."
+arg: float x, "X component of the vector."
+arg: float y, "Y component of the vector."
+arg: float z, "Z component of the vector."
+summary: Quaternion that represents a rotation about an arbitrary unit vector
description:
- Loads a quaternion that represents a rotation about an arbitrary unit vector
+ Loads a quaternion that represents a rotation about an arbitrary unit vector.
inline:
rot *= (float)(M_PI / 180.0f) * 0.5f;
float c = cos(rot);
@@ -115,14 +115,14 @@
function: rsQuaternionSet
ret: void
-arg: rs_quaternion* q, "destination quaternion"
-arg: float w, "component"
-arg: float x, "component"
-arg: float y, "component"
-arg: float z, "component"
-summary:
+arg: rs_quaternion* q, "Destination quaternion."
+arg: float w, "W component."
+arg: float x, "X component."
+arg: float y, "Y component."
+arg: float z, "Z component."
+summary: Create a quarternion
description:
- Set the quaternion from components or from another quaternion.
+ Creates a quaternion from its four components or from another quaternion.
inline:
q->w = w;
q->x = x;
@@ -134,7 +134,7 @@
function: rsQuaternionSet
ret: void
arg: rs_quaternion* q
-arg: const rs_quaternion* rhs, "source quaternion"
+arg: const rs_quaternion* rhs, "Source quaternion."
inline:
q->w = rhs->w;
q->x = rhs->x;
@@ -148,12 +148,12 @@
function: rsQuaternionLoadRotate
ret: void
-arg: rs_quaternion* q, "quaternion to set"
-arg: float rot, "angle to rotate by"
-arg: float x, "component of a vector"
-arg: float y, "component of a vector"
-arg: float z, "component of a vector"
-summary:
+arg: rs_quaternion* q, "Destination quaternion."
+arg: float rot, "Angle to rotate by."
+arg: float x, "X component of a vector."
+arg: float y, "Y component of a vector."
+arg: float z, "Z component of a vector."
+summary: Create a rotation quaternion
description:
Loads a quaternion that represents a rotation about an arbitrary vector
(doesn't have to be unit)
@@ -171,10 +171,10 @@
function: rsQuaternionNormalize
ret: void
-arg: rs_quaternion* q, "quaternion to normalize"
-summary:
+arg: rs_quaternion* q, "Quaternion to normalize."
+summary: Normalize a quaternion
description:
- Normalizes the quaternion
+ Normalizes the quaternion.
inline:
const float len = rsQuaternionDot(q, q);
if (len != 1) {
@@ -189,23 +189,24 @@
function: rsQuaternionMultiply
ret: void
-arg: rs_quaternion* q, "destination quaternion"
-arg: float s, "scalar"
-summary:
+arg: rs_quaternion* q, "Destination quaternion."
+arg: float scalar, "Scalar to multiply the quarternion by."
+summary: Multiply a quaternion by a scalar or another quaternion
description:
- Multiply quaternion by a scalar or another quaternion
+ Multiplies a quaternion by a scalar or by another quaternion, e.g
+ <code>*q = *q * scalar;</code> or <code>*q = *q * *rhs;</code>.
inline:
- q->w *= s;
- q->x *= s;
- q->y *= s;
- q->z *= s;
+ q->w *= scalar;
+ q->x *= scalar;
+ q->y *= scalar;
+ q->z *= scalar;
test: none
end:
function: rsQuaternionMultiply
ret: void
arg: rs_quaternion* q
-arg: const rs_quaternion* rhs, "right hand side quaternion to multiply by"
+arg: const rs_quaternion* rhs, "Quarternion to multiply the destination quaternion by."
inline:
rs_quaternion qtmp;
rsQuaternionSet(&qtmp, q);
@@ -220,13 +221,13 @@
function: rsQuaternionSlerp
ret: void
-arg: rs_quaternion* q, "result quaternion from interpolation"
-arg: const rs_quaternion* q0, "first param"
-arg: const rs_quaternion* q1, "second param"
-arg: float t, "how much to interpolate by"
-summary:
+arg: rs_quaternion* q, "Result quaternion from the interpolation."
+arg: const rs_quaternion* q0, "First input quaternion."
+arg: const rs_quaternion* q1, "Second input quaternion."
+arg: float t, "How much to interpolate by."
+summary: Spherical linear interpolation between two quaternions
description:
- Performs spherical linear interpolation between two quaternions
+ Performs spherical linear interpolation between two quaternions.
inline:
if (t <= 0.0f) {
rsQuaternionSet(q, q0);
diff --git a/api/rs_time.spec b/api/rs_time.spec
index 8011393..208cced 100644
--- a/api/rs_time.spec
+++ b/api/rs_time.spec
@@ -15,9 +15,11 @@
#
header:
-summary: RenderScript time routines
+summary: Time Functions and Types
description:
- This file contains RenderScript functions relating to time and date manipulation.
+ The functions below can be used to tell the current clock time and the
+ current system up time. It's not recommended to call these functions
+ inside of a kernel.
end:
type: rs_time_t
@@ -52,7 +54,7 @@
function: rsGetDt
ret: float, "Time in seconds."
-summary:
+summary: Elapsed time since last call
description:
Returns the time in seconds since this function was last called in this
script.
@@ -60,31 +62,35 @@
end:
function: rsLocaltime
-ret: rs_tm*, "Pointer to broken-down time (same as input p local)."
-arg: rs_tm* local, "Broken-down time."
-arg: const rs_time_t* timer, "Input time as calendar time."
-summary:
+ret: rs_tm*, "Pointer to the output local time, i.e. the same value as the parameter local."
+arg: rs_tm* local, "Pointer to time structure where the local time will be stored."
+arg: const rs_time_t* timer, "Input time as a number of seconds since January 1, 1970."
+summary: Convert to local time
description:
- Converts the time specified by p timer into broken-down time and stores it
- in p local. This function also returns a pointer to p local. If p local
- is NULL, this function does nothing and returns NULL.
+ Converts the time specified by timer into a @rs_tm structure that provides year, month, hour, etc.
+ This value is stored at *local.
+
+ This functions returns the same pointer that is passed as first argument.
+ If the local parameter is NULL, this function does nothing and returns NULL.
test: none
end:
function: rsTime
-ret: rs_time_t, "Seconds since the Epoch."
+ret: rs_time_t, "Seconds since the Epoch, -1 if there's an error."
arg: rs_time_t* timer, "Location to also store the returned calendar time."
-summary:
+summary: Seconds since January 1, 1970
description:
Returns the number of seconds since the Epoch (00:00:00 UTC, January 1,
- 1970). If p timer is non-NULL, the result is also stored in the memory
- pointed to by this variable. If an error occurs, a value of -1 is returned.
+ 1970).
+
+ If timer is non-NULL, the result is also stored in the memory pointed to by
+ this variable.
test: none
end:
function: rsUptimeMillis
ret: int64_t, "Uptime in milliseconds."
-summary:
+summary: System uptime in milliseconds
description:
Returns the current system clock (uptime) in milliseconds.
test: none
@@ -92,8 +98,11 @@
function: rsUptimeNanos
ret: int64_t, "Uptime in nanoseconds."
-summary:
+summary: System uptime in nanoseconds
description:
Returns the current system clock (uptime) in nanoseconds.
+
+ The granularity of the values return by this call may be much
+ larger than a nanosecond.
test: none
end:
diff --git a/api/rs_value_types.spec b/api/rs_value_types.spec
index 1e6eeed..a9ffa1e 100644
--- a/api/rs_value_types.spec
+++ b/api/rs_value_types.spec
@@ -15,46 +15,104 @@
#
header:
-summary: Standard RenderScript types
+summary: Numerical Types
description:
- Integers:<ul>
- <li>8 bit: char, int8_t</li>
- <li>16 bit: short, int16_t</li>
- <li>32 bit: int, in32_t</li>
- <li>64 bit: long, long long, int64_t</li></ul>
+ <h5>Scalars:</h5>
- Unsigned integers:<ul>
- <li>8 bit: uchar, uint8_t</li>
- <li>16 bit: ushort, uint16_t</li>
- <li>32 bit: uint, uint32_t</li>
- <li>64 bit: ulong, uint64_t</li></ul>
+ RenderScript supports the following scalar numerical types:
- Floating point:<ul>
- <li>32 bit: float</li>
- <li>64 bit: double</li></ul>
+ Integers:<ul>
+ <li>8 bit: char, @int8_t</li>
+ <li>16 bit: short, @int16_t</li>
+ <li>32 bit: int, @int32_t</li>
+ <li>64 bit: long, long long, @int64_t</li></ul>
- Vectors of length 2, 3, and 4 are supported for all the types above.
+ Unsigned integers:<ul>
+ <li>8 bit: uchar, @uint8_t</li>
+ <li>16 bit: ushort, @uint16_t</li>
+ <li>32 bit: uint, @uint32_t</li>
+ <li>64 bit: ulong, @uint64_t</li></ul>
+
+ Floating point:<ul>
+ <li>32 bit: float</li>
+ <li>64 bit: double</li></ul>
+
+ <h5>Vectors:</h5>
+
+ RenderScript supports fixed size vectors of length 2, 3, and 4.
+ Vectors are declared using the common type name followed by a 2, 3, or 4.
+ E.g. @float4, @int3, @double2, @ulong4.
+
+ To create vector literals, use the vector type followed by the values enclosed
+ between parentheses, e.g. <code>(float3)(1.0f, 2.0f, 3.0f)</code>.
+
+ Entries of a vector can be accessed using different naming styles.
+
+ Single entries can be accessed by following the variable name with a dot and:<ul>
+ <li>The letters x, y, z, and w,</li>
+ <li>The letters r, g, b, and a,</li>
+ <li>The letter s or S, followed by a zero based index.</li></ul>
+
+ For example, with <code>int4 myVar;</code> the following are equivalent:<code><br/>
+ myVar.x == myVar.r == myVar.s0 == myVar.S0<br/>
+ myVar.y == myVar.g == myVar.s1 == myVar.S1<br/>
+ myVar.z == myVar.b == myVar.s2 == myVar.S2<br/>
+ myVar.w == myVar.a == myVar.s3 == myVar.S3</code>
+
+ Multiple entries of a vector can be accessed at once by using an identifier
+ that is the concatenation of multiple letters or indices. The resulting vector
+ has a size equal to the number of entries named.
+
+ With the example above, the middle two entries can be accessed using
+ <code>myVar.yz</code>, <code>myVar.gb</code>, <code>myVar.s12</code>, and <code>myVar.S12</code>.
+
+ The entries don't have to be contiguous or in increasing order.
+ Entries can even be repeated, as long as we're not trying to assign
+ to it. You also can't mix the naming styles.
+
+ Here are examples of what can or can't be done: <code><br/>
+ float4 v4;<br/>
+ float3 v3;<br/>
+ float2 v2;<br/>
+ v2 = v4.xx; // Valid<br/>
+ v3 = v4.zxw; // Valid<br/>
+ v3 = v4.bba; // Valid<br/>
+ v3 = v4.s034; // Valid<br/>
+ v3.s120 = v4.S233; // Valid<br/>
+ v4.yz = v3.rg; // Valid<br/>
+ v4.yzx = v3.rg; // Invalid: mismatched sizes<br/>
+ v4.yzz = v3; // Invalid: z appears twice in an assignment<br/>
+ v3 = v3.xas0; // Invalid: can't mix xyzw with rgba nor s0...<br/>
+ </code>
+
+ <h5>Matrices and Quaternions:</h5>
+
+ RenderScript supports fixed size square matrices of floats of size 2x2, 3x3, and 4x4.
+ The types are named @rs_matrix2x2, @rs_matrix3x3, and @rs_matrix4x4. See
+ <a href='rs_matrix.html'>Matrix Functions</a> for the list of operations.
+
+ Quaternions are also supported via @rs_quaternion. See <a href='rs_quaternion.html'>Quaterion Functions</a>. for the list of operations.
end:
type: int8_t
simple: char
summary: 8 bit signed integer
description:
- 8 bit integer type
+ 8 bit signed integer type.
end:
type: int16_t
simple: short
summary: 16 bit signed integer
description:
- 16 bit integer type
+ A 16 bit signed integer type.
end:
type: int32_t
simple: int
summary: 32 bit signed integer
description:
- 32 bit integer type
+ A 32 bit signed integer type.
end:
type: int64_t
@@ -62,7 +120,7 @@
simple: long long
summary: 64 bit signed integer
description:
- 64 bit integer type
+ A 64 bit signed integer type.
end:
type: int64_t
@@ -74,21 +132,21 @@
simple: unsigned char
summary: 8 bit unsigned integer
description:
- 8 bit unsigned integer type
+ 8 bit unsigned integer type.
end:
type: uint16_t
simple: unsigned short
summary: 16 bit unsigned integer
description:
- 16 bit unsigned integer type
+ A 16 bit unsigned integer type.
end:
type: uint32_t
simple: unsigned int
summary: 32 bit unsigned integer
description:
- 32 bit unsigned integer type
+ A 32 bit unsigned integer type.
end:
type: uint64_t
@@ -96,7 +154,7 @@
simple: unsigned long long
summary: 64 bit unsigned integer
description:
- 64 bit unsigned integer type
+ A 64 bit unsigned integer type.
end:
type: uint64_t
@@ -108,28 +166,28 @@
simple: uint8_t
summary: 8 bit unsigned integer
description:
- 8 bit unsigned integer type
+ 8 bit unsigned integer type.
end:
type: ushort
simple: uint16_t
summary: 16 bit unsigned integer
description:
- 16 bit unsigned integer type
+ A 16 bit unsigned integer type.
end:
type: uint
simple: uint32_t
summary: 32 bit unsigned integer
description:
- 32 bit unsigned integer type
+ A 32 bit unsigned integer type.
end:
type: ulong
simple: uint64_t
summary: 64 bit unsigned integer
description:
- Typedef for unsigned long (use for 64-bit unsigned integers)
+ A 64 bit unsigned integer type.
end:
type: size_t
@@ -137,7 +195,7 @@
simple: uint64_t
summary: Unsigned size type
description:
- Typedef for size_t
+ Unsigned size type. The number of bits depend on the compilation flags.
end:
type: size_t
@@ -150,7 +208,7 @@
simple: int64_t
summary: Signed size type
description:
- Typedef for ssize_t
+ Signed size type. The number of bits depend on the compilation flags.
end:
type: ssize_t
@@ -332,6 +390,7 @@
a single 32 bit field with 32 bit alignment.
end:
+
type: short2
simple: short __attribute__((ext_vector_type(2)))
summary: Two 16 bit signed integers
@@ -405,3 +464,47 @@
Vector version of the basic long type. Provides four long fields packed into
a single 256 bit field with 256 bit alignment.
end:
+
+
+type: rs_matrix2x2
+struct:
+field: float m[4]
+summary: 2x2 matrix of 32 bit floats
+description:
+ A square 2x2 matrix of floats. The entries are stored in the array at the
+ location [row*2 + col].
+
+ See <a href='rs_matrix.html'>Matrix Functions</a>.
+end:
+
+type: rs_matrix3x3
+struct:
+field: float m[9]
+summary: 3x3 matrix of 32 bit floats
+description:
+ A square 3x3 matrix of floats. The entries are stored in the array at the
+ location [row*3 + col].
+
+ See <a href='rs_matrix.html'>Matrix Functions</a>.
+end:
+
+type: rs_matrix4x4
+struct:
+field: float m[16]
+summary: 4x4 matrix of 32 bit floats
+description:
+ A square 4x4 matrix of floats. The entries are stored in the array at the
+ location [row*4 + col].
+
+ See <a href='rs_matrix.html'>Matrix Functions</a>.
+end:
+
+
+type: rs_quaternion
+simple: float4
+summary: Quaternion
+description:
+ A square 4x4 matrix of floats that represents a quaternion.
+
+ See <a href='rs_quaternion.html'>Quaternion Functions</a>.
+end:
diff --git a/api/rs_vector_math.spec b/api/rs_vector_math.spec
index d25bb17..176489a 100644
--- a/api/rs_vector_math.spec
+++ b/api/rs_vector_math.spec
@@ -1,5 +1,5 @@
#
-# Copyright (C) 2014 The Android Open Source Project
+# Copyright (C) 2015 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.
@@ -15,9 +15,20 @@
#
header:
-summary: TODO Add documentation
+summary: Vector Math Functions
description:
- TODO Add documentation
+ These functions interpret the input arguments as representation of vectors in n-dimensional space.
+
+ The precision of the mathematical operations is affected by the pragmas
+# TODO Create an anchor for the section of http://developer.android.com/guide/topics/renderscript/compute.html that details rs_fp_* and link them here.
+ rs_fp_relaxed and rs_fp_full.
+
+ Different precision/speed tradeoffs can be achieved by using three variants
+ of common math functions. Functions with a name starting with<ul>
+ <li>native_ may have custom hardware implementations with weaker precision,</li>
+ <li>half_ may perform internal computations using 16 bit floats, and</li>
+ <li>fast_ are n-dimensional space computations that may use 16 bit floats.
+ </ul>
end:
function: cross
diff --git a/scriptc/rs_allocation_data.rsh b/scriptc/rs_allocation_data.rsh
index 12d62a0..928b649 100644
--- a/scriptc/rs_allocation_data.rsh
+++ b/scriptc/rs_allocation_data.rsh
@@ -17,33 +17,47 @@
// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
/*
- * rs_allocation_data.rsh: Allocation routines
+ * rs_allocation_data.rsh: Allocation Data Access Functions
*
- * TODO Adjust documentation.
+ * The functions below can be used to get and set the cells that comprise
+ * an allocation.
*
- * Functions that can be used to query the characteristics of an allocation,
- * to set and get elements of the allocation.
+ * - Individual cells are accessed using the rsGetElementAt* and
+ * rsSetElementAt functions.
+ * - Multiple cells can be copied using the rsAllocationCopy* and
+ * rsAllocationV* functions.
+ * - For getting values through a sampler, use rsSample.
+ *
+ * The rsGetElementAt and rsSetElement* functions are somewhat misnamed.
+ * They don't get or set elements, which are akin to data types; they get
+ * or set cells. Think of them as rsGetCellAt and and rsSetCellAt.
*/
#ifndef RENDERSCRIPT_RS_ALLOCATION_DATA_RSH
#define RENDERSCRIPT_RS_ALLOCATION_DATA_RSH
/*
- * rsAllocationCopy1DRange: Copy consecutive values between allocations
+ * rsAllocationCopy1DRange: Copy consecutive cells between allocations
*
- * Copies part of an allocation into another allocation.
+ * Copies the specified number of cells from one allocation to another.
*
* The two allocations must be different. Using this function to copy whithin
* the same allocation yields undefined results.
*
+ * The function does not validate whether the offset plus count exceeds the size
+ * of either allocation. Be careful!
+ *
+ * This function should only be called between 1D allocations. Calling it
+ * on other allocations is undefined.
+ *
* Parameters:
- * dstAlloc: Allocation to copy data into.
- * dstOff: The offset of the first element to be copied in the destination allocation.
- * dstMip: Mip level in the destination allocation.
- * count: The number of elements to be copied.
- * srcAlloc: The source data allocation.
- * srcOff: The offset of the first element in data to be copied in the source allocation.
- * srcMip: Mip level in the source allocation.
+ * dstAlloc: Allocation to copy cells into.
+ * dstOff: Offset in the destination of the first cell to be copied into.
+ * dstMip: Mip level in the destination allocation. 0 if mip mapping is not used.
+ * count: Number of cells to be copied.
+ * srcAlloc: Source allocation.
+ * srcOff: Offset in the source of the first cell to be copied.
+ * srcMip: Mip level in the source allocation. 0 if mip mapping is not used.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern void __attribute__((overloadable))
@@ -52,26 +66,33 @@
#endif
/*
- * rsAllocationCopy2DRange: Copy a rectangular region between allocations
+ * rsAllocationCopy2DRange: Copy a rectangular region of cells between allocations
*
- * Copy a rectangular region into the allocation from another allocation.
+ * Copies a rectangular region of cells from one allocation to another.
+ * (width * heigth) cells are copied.
*
* The two allocations must be different. Using this function to copy whithin
* the same allocation yields undefined results.
*
+ * The function does not validate whether the the source or destination region
+ * exceeds the size of its respective allocation. Be careful!
+ *
+ * This function should only be called between 2D allocations. Calling it
+ * on other allocations is undefined.
+ *
* Parameters:
- * dstAlloc: Allocation to copy data into.
- * dstXoff: X offset of the region to update in the destination allocation.
- * dstYoff: Y offset of the region to update in the destination allocation.
- * dstMip: Mip level in the destination allocation.
- * dstFace: Cubemap face of the destination allocation, ignored for allocations that aren't cubemaps.
+ * dstAlloc: Allocation to copy cells into.
+ * dstXoff: X offset in the destination of the region to be set.
+ * dstYoff: Y offset in the destination of the region to be set.
+ * dstMip: Mip level in the destination allocation. 0 if mip mapping is not used.
+ * dstFace: Cubemap face of the destination allocation. Ignored for allocations that aren't cubemaps.
* width: Width of the incoming region to update.
* height: Height of the incoming region to update.
- * srcAlloc: The source data allocation.
- * srcXoff: X offset in data of the source allocation.
- * srcYoff: Y offset in data of the source allocation.
- * srcMip: Mip level in the source allocation.
- * srcFace: Cubemap face of the source allocation, ignored for allocations that aren't cubemaps.
+ * srcAlloc: Source allocation.
+ * srcXoff: X offset in the source.
+ * srcYoff: Y offset in the source.
+ * srcMip: Mip level in the source allocation. 0 if mip mapping is not used.
+ * srcFace: Cubemap face of the source allocation. Ignored for allocations that aren't cubemaps.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern void __attribute__((overloadable))
@@ -82,7 +103,34 @@
#endif
/*
- * Get a single element from an allocation.
+ * rsAllocationVLoadX: Get a vector from an allocation of scalars
+ *
+ * This function returns a vector composed of successive cells of the allocation.
+ * It assumes that the allocation contains scalars.
+ *
+ * The "X" in the name indicates that successive values are extracted by
+ * increasing the X index. There are currently no functions to get successive
+ * values incrementing other dimensions. Use multiple calls to rsGetElementAt()
+ * instead.
+ *
+ * For example, when calling rsAllocationVLoadX_int4(a, 20, 30),
+ * an int4 composed of a[20, 30], a[21, 30], a[22, 30], and a[23, 30] is returned.
+ *
+ * When retrieving from a three dimensional allocations, use the x, y, z
+ * variant. Similarly, use the x, y variant for two dimensional
+ * allocations and x for the mono dimensional allocations.
+ *
+ * For efficiency, this function does not validate the inputs. Trying to
+ * wrap the X index, exceeding the size of the allocation, or using indexes
+ * incompatible with the dimensionality of the allocation yields undefined results.
+ *
+ * See also rsAllocationVStoreX().
+ *
+ * Parameters:
+ * a: Allocation to get the data from.
+ * x: X offset in the allocation of the first cell to be copied from.
+ * y: Y offset in the allocation of the first cell to be copied from.
+ * z: Z offset in the allocation of the first cell to be copied from.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 22))
extern float2 __attribute__((overloadable))
@@ -535,7 +583,35 @@
#endif
/*
- * Set a single element of an allocation.
+ * rsAllocationVStoreX: Store a vector into an allocation of scalars
+ *
+ * This function stores the entries of a vector into successive cells of an
+ * allocation. It assumes that the allocation contains scalars.
+ *
+ * The "X" in the name indicates that successive values are stored by
+ * increasing the X index. There are currently no functions to store successive
+ * values incrementing other dimensions. Use multiple calls to rsSetElementAt()
+ * instead.
+ *
+ * For example, when calling rsAllocationVStoreX_int3(a, v, 20, 30),
+ * v.x is stored at a[20, 30], v.y at a[21, 30], and v.z at a[22, 30].
+ *
+ * When storing into a three dimensional allocations, use the x, y, z
+ * variant. Similarly, use the x, y variant for two dimensional
+ * allocations and x for the mono dimensional allocations.
+ *
+ * For efficiency, this function does not validate the inputs. Trying to
+ * wrap the X index, exceeding the size of the allocation, or using indexes
+ * incompatible with the dimensionality of the allocation yiels undefined results.
+ *
+ * See also rsAllocationVLoadX().
+ *
+ * Parameters:
+ * a: Allocation to store the data into.
+ * val: Value to be stored.
+ * x: X offset in the allocation of the first cell to be copied into.
+ * y: Y offset in the allocation of the first cell to be copied into.
+ * z: Z offset in the allocation of the first cell to be copied into.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 22))
extern void __attribute__((overloadable))
@@ -988,9 +1064,18 @@
#endif
/*
- * rsGetElementAt: Get an element
+ * rsGetElementAt: Return a cell from an allocation
*
- * Extract a single element from an allocation.
+ * This function extracts a single cell from an allocation.
+ *
+ * When retrieving from a three dimensional allocations, use the x, y, z
+ * variant. Similarly, use the x, y variant for two dimensional
+ * allocations and x for the mono dimensional allocations.
+ *
+ * This function has two styles. One returns the address of the value using a
+ * void*, the other returns the actual value, e.g. rsGetElementAt() vs.
+ * rsGetElementAt_int4(). For primitive types, always use the latter as it is
+ * more efficient.
*/
extern const void* __attribute__((overloadable))
rsGetElementAt(rs_allocation a, uint32_t x);
@@ -2442,9 +2527,15 @@
#endif
/*
- * Extract a single element from an allocation.
+ * rsGetElementAtYuv_uchar_U: Get the U component of an allocation of YUVs
*
- * Coordinates are in the dimensions of the Y plane
+ * Extracts the U component of a single YUV value from a 2D allocation of YUVs.
+ *
+ * Inside an allocation, Y, U, and V components may be stored if different planes
+ * and at different resolutions. The x, y coordinates provided here are in the
+ * dimensions of the Y plane.
+ *
+ * See rsGetElementAtYuv_uchar_Y().
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 18))
extern uchar __attribute__((overloadable))
@@ -2452,9 +2543,15 @@
#endif
/*
- * Extract a single element from an allocation.
+ * rsGetElementAtYuv_uchar_V: Get the V component of an allocation of YUVs
*
- * Coordinates are in the dimensions of the Y plane
+ * Extracts the V component of a single YUV value from a 2D allocation of YUVs.
+ *
+ * Inside an allocation, Y, U, and V components may be stored if different planes
+ * and at different resolutions. The x, y coordinates provided here are in the
+ * dimensions of the Y plane.
+ *
+ * See rsGetElementAtYuv_uchar_Y().
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 18))
extern uchar __attribute__((overloadable))
@@ -2462,7 +2559,15 @@
#endif
/*
- * Extract a single element from an allocation.
+ * rsGetElementAtYuv_uchar_Y: Get the Y component of an allocation of YUVs
+ *
+ * Extracts the Y component of a single YUV value from a 2D allocation of YUVs.
+ *
+ * Inside an allocation, Y, U, and V components may be stored if different planes
+ * and at different resolutions. The x, y coordinates provided here are in the
+ * dimensions of the Y plane.
+ *
+ * See rsGetElementAtYuv_uchar_U() and rsGetElementAtYuv_uchar_V().
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 18))
extern uchar __attribute__((overloadable))
@@ -2470,16 +2575,20 @@
#endif
/*
- * Fetch allocation in a way described by the sampler
+ * rsSample: Sample a value from a texture allocation
*
- * If your allocation is 1D, use the variant with float for location.
- * For 2D, use the float2 variant.
+ * Fetches a value from a texture allocation in a way described by the sampler.
+ *
+ * If your allocation is 1D, use the variant with float for location. For 2D,
+ * use the float2 variant.
+ *
+ * See android.renderscript.Sampler for more details.
*
* Parameters:
- * a: allocation to sample from
- * s: sampler state
- * location: location to sample from
- * lod: mip level to sample from, for fractional values mip levels will be interpolated if RS_SAMPLER_LINEAR_MIP_LINEAR is used
+ * a: Allocation to sample from.
+ * s: Sampler state.
+ * location: Location to sample from.
+ * lod: Mip level to sample from, for fractional values mip levels will be interpolated if RS_SAMPLER_LINEAR_MIP_LINEAR is used.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern float4 __attribute__((overloadable))
@@ -2502,9 +2611,20 @@
#endif
/*
- * rsSetElementAt: Set an element
+ * rsSetElementAt: Set a cell of an allocation
*
- * Set single element of an allocation.
+ * This function stores a value into a single cell of an allocation.
+ *
+ * When storing into a three dimensional allocations, use the x, y, z
+ * variant. Similarly, use the x, y variant for two dimensional
+ * allocations and x for the mono dimensional allocations.
+ *
+ * This function has two styles. One passes the value to be stored using
+ * a void*, the other has the actual value as an argument, e.g. rsSetElementAt()
+ * vs. rsSetElementAt_int4(). For primitive types, always use the latter as it is
+ * more efficient.
+ *
+ * See also rsGetElementAt().
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 18))
extern void __attribute__((overloadable))
diff --git a/scriptc/rs_atomic.rsh b/scriptc/rs_atomic.rsh
index 58ce130..cc2b8d5 100644
--- a/scriptc/rs_atomic.rsh
+++ b/scriptc/rs_atomic.rsh
@@ -17,13 +17,13 @@
// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
/*
- * rs_atomic.rsh: Atomic routines
+ * rs_atomic.rsh: Atomic Update Functions
*
* To update values shared between multiple threads, use the functions below.
* They ensure that the values are atomically updated, i.e. that the memory
- * reads, the updates, and the memory writes are all done in the right order.
+ * reads, the updates, and the memory writes are done in the right order.
*
- * These functions are slower than just doing the non-atomic variants, so use
+ * These functions are slower than their non-atomic equivalents, so use
* them only when synchronization is needed.
*
* Note that in RenderScript, your code is likely to be running in separate
@@ -42,10 +42,10 @@
* Atomicly adds a value to the value at addr, i.e. *addr += value.
*
* Parameters:
- * addr: Address of the value to modify
- * value: Amount to add
+ * addr: Address of the value to modify.
+ * value: Amount to add.
*
- * Returns: Old value
+ * Returns: Value of *addr prior to the operation.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern int32_t __attribute__((overloadable))
@@ -61,13 +61,13 @@
* rsAtomicAnd: Thread-safe bitwise and
*
* Atomicly performs a bitwise and of two values, storing the result back at addr,
- * i.e. *addr &= value
+ * i.e. *addr &= value.
*
* Parameters:
- * addr: Address of the value to modify
- * value: Value to and with
+ * addr: Address of the value to modify.
+ * value: Value to and with.
*
- * Returns: Old value
+ * Returns: Value of *addr prior to the operation.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern int32_t __attribute__((overloadable))
@@ -83,17 +83,17 @@
* rsAtomicCas: Thread-safe compare and set
*
* If the value at addr matches compareValue then the newValue is written at addr,
- * i.e. if (*addr == compareValue) { *addr = newValue; }
+ * i.e. if (*addr == compareValue) { *addr = newValue; }.
*
* You can check that the value was written by checking that the value returned
- * by rsAtomicCas is compareValue.
+ * by rsAtomicCas() is compareValue.
*
* Parameters:
- * addr: The address to compare and replace if the compare passes.
+ * addr: The address of the value to compare and replace if the test passes.
* compareValue: The value to test *addr against.
* newValue: The value to write if the test passes.
*
- * Returns: Old value
+ * Returns: Value of *addr prior to the operation.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern int32_t __attribute__((overloadable))
@@ -108,12 +108,12 @@
/*
* rsAtomicDec: Thread-safe decrement
*
- * Atomicly subtracts one from the value at addr. Equal to rsAtomicSub(addr, 1)
+ * Atomicly subtracts one from the value at addr. This is equivalent to rsAtomicSub(addr, 1).
*
* Parameters:
- * addr: Address of the value to decrement
+ * addr: Address of the value to decrement.
*
- * Returns: Old value
+ * Returns: Value of *addr prior to the operation.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern int32_t __attribute__((overloadable))
@@ -128,12 +128,12 @@
/*
* rsAtomicInc: Thread-safe increment
*
- * Atomicly adds one to the value at addr. Equal to rsAtomicAdd(addr, 1)
+ * Atomicly adds one to the value at addr. This is equivalent to rsAtomicAdd(addr, 1).
*
* Parameters:
- * addr: Address of the value to increment
+ * addr: Address of the value to increment.
*
- * Returns: Old value
+ * Returns: Value of *addr prior to the operation.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern int32_t __attribute__((overloadable))
@@ -148,14 +148,14 @@
/*
* rsAtomicMax: Thread-safe maximum
*
- * Atomicly sets the value at addr to the maximum of addr and value, i.e.
- * *addr = max(*addr, value)
+ * Atomicly sets the value at addr to the maximum of *addr and value, i.e.
+ * *addr = max(*addr, value).
*
* Parameters:
- * addr: Address of the value to modify
- * value: Comparison value
+ * addr: Address of the value to modify.
+ * value: Comparison value.
*
- * Returns: Old value
+ * Returns: Value of *addr prior to the operation.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern uint32_t __attribute__((overloadable))
@@ -170,14 +170,14 @@
/*
* rsAtomicMin: Thread-safe minimum
*
- * Atomicly sets the value at addr to the minimum of addr and value, i.e.
- * *addr = min(*addr, value)
+ * Atomicly sets the value at addr to the minimum of *addr and value, i.e.
+ * *addr = min(*addr, value).
*
* Parameters:
- * addr: Address of the value to modify
- * value: Comparison value
+ * addr: Address of the value to modify.
+ * value: Comparison value.
*
- * Returns: Old value
+ * Returns: Value of *addr prior to the operation.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern uint32_t __attribute__((overloadable))
@@ -193,13 +193,13 @@
* rsAtomicOr: Thread-safe bitwise or
*
* Atomicly perform a bitwise or two values, storing the result at addr,
- * i.e. *addr |= value
+ * i.e. *addr |= value.
*
* Parameters:
- * addr: Address of the value to modify
- * value: Value to or with
+ * addr: Address of the value to modify.
+ * value: Value to or with.
*
- * Returns: Old value
+ * Returns: Value of *addr prior to the operation.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern int32_t __attribute__((overloadable))
@@ -214,13 +214,13 @@
/*
* rsAtomicSub: Thread-safe subtraction
*
- * Atomicly subtracts a value from the value at addr, i.e. *addr -= value
+ * Atomicly subtracts a value from the value at addr, i.e. *addr -= value.
*
* Parameters:
- * addr: Address of the value to modify
- * value: Amount to subtract
+ * addr: Address of the value to modify.
+ * value: Amount to subtract.
*
- * Returns: Old value
+ * Returns: Value of *addr prior to the operation.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern int32_t __attribute__((overloadable))
@@ -236,13 +236,13 @@
* rsAtomicXor: Thread-safe bitwise exclusive or
*
* Atomicly performs a bitwise xor of two values, storing the result at addr,
- * i.e. *addr ^= value
+ * i.e. *addr ^= value.
*
* Parameters:
- * addr: Address of the value to modify
- * value: Value to xor with
+ * addr: Address of the value to modify.
+ * value: Value to xor with.
*
- * Returns: Old value
+ * Returns: Value of *addr prior to the operation.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern int32_t __attribute__((overloadable))
diff --git a/scriptc/rs_convert.rsh b/scriptc/rs_convert.rsh
index eaa6c1a..7abd557 100644
--- a/scriptc/rs_convert.rsh
+++ b/scriptc/rs_convert.rsh
@@ -17,22 +17,27 @@
// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
/*
- * rs_convert.rsh: Conversion functions
+ * rs_convert.rsh: Conversion Functions
*
- * TODO Add desc.
+ * The functions below convert from a numerical vector type to another,
+ * of from one color representation to another.
*/
#ifndef RENDERSCRIPT_RS_CONVERT_RSH
#define RENDERSCRIPT_RS_CONVERT_RSH
/*
- * convert: Converts numerical vectors
+ * convert: Convert numerical vectors
*
- * Component wise conversion from a numerical type to another.
+ * Converts a vector from one numerical type to another. The conversion are
+ * done entry per entry.
*
- * Conversions of floating point values to integer will truncate.
+ * E.g calling a = convert_short3(b) is equivalent to doing
+ * a.x = (short)b.x; a.y = (short)b.y; a.z = (short)b.z;.
*
- * Conversions of numbers too large to fit the destination type yield undefined results.
+ * Converting floating point values to integer types truncates.
+ *
+ * Converting numbers too large to fit the destination type yields undefined results.
* For example, converting a float that contains 1.0e18 to a short is undefined.
* Use clamp() to avoid this.
*/
@@ -1243,10 +1248,22 @@
#endif
/*
- * Pack floating point (0-1) RGB values into a uchar4.
+ * rsPackColorTo8888: Create a uchar4 RGBA from floats
*
- * For the float3 variant and the variant that only specifies r, g, b,
- * the alpha component is set to 255 (1.0).
+ * Packs three or four floating point RGBA values into a uchar4. The RGBA values should
+ * be between 0.0 and 1.0 inclusive. Values outside of this range are clamped to
+ * this range. However numbers greater than INT_MAX or less than INT_MIN can result
+ * in undefined behavior.
+ *
+ * If the alpha component is not specified, it is assumed to be 1.0, i.e. the
+ * result will have an alpha set to 255.
+ *
+ * Parameters:
+ * r: Red component.
+ * g: Green component.
+ * b: Blue component.
+ * a: Alpha component.
+ * color: Vector of 3 or 4 floats containing the R, G, B, and A values.
*/
extern uchar4 __attribute__((const, overloadable))
rsPackColorTo8888(float r, float g, float b);
@@ -1261,13 +1278,25 @@
rsPackColorTo8888(float4 color);
/*
- * Unpack a uchar4 color to float4. The resulting float range will be (0-1).
+ * rsUnpackColor8888: Create a float4 RGBA from uchar4
+ *
+ * Unpacks a uchar4 color to float4. The resulting floats will be between 0.0 and
+ * 1.0 inclusive.
*/
extern float4 __attribute__((const))
rsUnpackColor8888(uchar4 c);
/*
- * Convert from YUV to RGBA.
+ * rsYuvToRGBA: Convert a YUV value to RGBA
+ *
+ * Converts a color from a YUV representation to RGBA.
+ *
+ * We currently don't provide a function to do the reverse conversion.
+ *
+ * Parameters:
+ * y: Luminance component
+ * u: U chrominance component
+ * v: V chrominance component
*/
extern float4 __attribute__((const, overloadable))
rsYuvToRGBA_float4(uchar y, uchar u, uchar v);
diff --git a/scriptc/rs_core.rsh b/scriptc/rs_core.rsh
index 029667a..be9f7fa 100644
--- a/scriptc/rs_core.rsh
+++ b/scriptc/rs_core.rsh
@@ -17,7 +17,7 @@
// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
/*
- * rs_core.rsh: TODO
+ * rs_core.rsh: Overview
*
* RenderScript is a high-performance runtime that provides
* compute operations at the native level. RenderScript code is compiled on devices
diff --git a/scriptc/rs_debug.rsh b/scriptc/rs_debug.rsh
index d52590e..348c598 100644
--- a/scriptc/rs_debug.rsh
+++ b/scriptc/rs_debug.rsh
@@ -17,11 +17,10 @@
// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
/*
- * rs_debug.rsh: Utility debugging routines
+ * rs_debug.rsh: Debugging Functions
*
- * Routines intended to be used during application developement. These should
- * not be used in shipping applications. All print a string and value pair to
- * the standard log.
+ * The functions below are intended to be used during application developement.
+ * They should not be used in shipping applications.
*/
#ifndef RENDERSCRIPT_RS_DEBUG_RSH
@@ -31,7 +30,12 @@
#define RS_DEBUG_MARKER rsDebug(__FILE__, __LINE__)
/*
- * Debug function. Prints a string and value to the log.
+ * rsDebug: Log a message and values
+ *
+ * This function prints a message to the standard log, followed by the provided values.
+ *
+ * This function is intended for debugging only and should not be used in shipping
+ * applications.
*/
extern void __attribute__((overloadable))
rsDebug(const char* message, double a);
diff --git a/scriptc/rs_for_each.rsh b/scriptc/rs_for_each.rsh
index 640b530..f08a4e3 100644
--- a/scriptc/rs_for_each.rsh
+++ b/scriptc/rs_for_each.rsh
@@ -17,70 +17,104 @@
// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
/*
- * rs_for_each.rsh: TODO Add documentation
+ * rs_for_each.rsh: Kernel Invocation Functions and Types
*
- * TODO Add documentation
+ * The rsForEach() function can be used to invoke the root kernel of a script.
+ *
+ * The other functions are used to get the characteristics of the invocation of
+ * an executing kernel, like dimensions and current indexes. These functions take
+ * a rs_kernel_context as argument.
*/
#ifndef RENDERSCRIPT_RS_FOR_EACH_RSH
#define RENDERSCRIPT_RS_FOR_EACH_RSH
/*
- * rs_for_each_strategy_t: Launch order hint for rsForEach calls
+ * rs_for_each_strategy_t: Suggested cell processing order
*
- * Launch order hint for rsForEach calls. This provides a hint to the system to
- * determine in which order the root function of the target is called with each
- * cell of the allocation.
+ * This type is used to suggest how the invoked kernel should iterate over the cells of the
+ * allocations. This is a hint only. Implementations may not follow the suggestion.
*
- * This is a hint and implementations may not obey the order.
+ * This specification can help the caching behavior of the running kernel, e.g. the cache
+ * locality when the processing is distributed over multiple cores.
*/
typedef enum rs_for_each_strategy {
- RS_FOR_EACH_STRATEGY_SERIAL = 0,
- RS_FOR_EACH_STRATEGY_DONT_CARE = 1,
- RS_FOR_EACH_STRATEGY_DST_LINEAR = 2,
- RS_FOR_EACH_STRATEGY_TILE_SMALL = 3,
- RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4,
- RS_FOR_EACH_STRATEGY_TILE_LARGE = 5
+ RS_FOR_EACH_STRATEGY_SERIAL = 0, // Prefer contiguous memory regions.
+ RS_FOR_EACH_STRATEGY_DONT_CARE = 1, // No prefrences.
+ RS_FOR_EACH_STRATEGY_DST_LINEAR = 2, // Prefer DST.
+ RS_FOR_EACH_STRATEGY_TILE_SMALL = 3, // Prefer processing small rectangular regions.
+ RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4, // Prefer processing medium rectangular regions.
+ RS_FOR_EACH_STRATEGY_TILE_LARGE = 5 // Prefer processing large rectangular regions.
} rs_for_each_strategy_t;
/*
- * rs_kernel_context: Opaque handle to RenderScript kernel invocation context
+ * rs_kernel_context: Handle to a kernel invocation context
*
- * TODO
+ * The kernel context contains common characteristics of the allocations being iterated
+ * over, like dimensions, and rarely used indexes, like the Array0 index or the current
+ * level of detail.
+ *
+ * A kernel may be executed in parallel over multiple threads. Each thread will have its
+ * own context.
+ *
+ * You can access the context by adding a rs_kernel_context argument to your
+ * kernel function. See rsGetDimX() and rsGetArray0() for examples.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
typedef const struct rs_kernel_context_t * rs_kernel_context;
#endif
/*
- * rs_script_call_t: Provides extra information to a rsForEach call
+ * rs_script_call_t: Cell iteration information
*
- * Structure to provide extra information to a rsForEach call. Primarly used to
- * restrict the call to a subset of cells in the allocation.
+ * This structure is used to provide iteration information to a rsForEach call.
+ * It is currently used to restrict processing to a subset of cells. In future
+ * versions, it will also be used to provide hint on how to best iterate over
+ * the cells.
+ *
+ * The Start fields are inclusive and the End fields are exclusive. E.g. to iterate
+ * over cells 4, 5, 6, and 7 in the X dimension, set xStart to 4 and xEnd to 8.
*/
typedef struct rs_script_call {
- rs_for_each_strategy_t strategy;
- uint32_t xStart;
- uint32_t xEnd;
- uint32_t yStart;
- uint32_t yEnd;
- uint32_t zStart;
- uint32_t zEnd;
- uint32_t arrayStart;
- uint32_t arrayEnd;
+ rs_for_each_strategy_t strategy; // Currently ignored. In the future, will be suggested cell iteration strategy.
+ uint32_t xStart; // Starting index in the X dimension.
+ uint32_t xEnd; // Ending index (exclusive) in the X dimension.
+ uint32_t yStart; // Starting index in the Y dimension.
+ uint32_t yEnd; // Ending index (exclusive) in the Y dimension.
+ uint32_t zStart; // Starting index in the Z dimension.
+ uint32_t zEnd; // Ending index (exclusive) in the Z dimension.
+ uint32_t arrayStart; // Starting index in the Array0 dimension.
+ uint32_t arrayEnd; // Ending index (exclusive) in the Array0 dimension.
} rs_script_call_t;
/*
- * Make a script to script call to launch work. One of the input or output is
- * required to be a valid object. The input and output must be of the same
- * dimensions.
+ * rsForEach: Invoke the root kernel of a script
+ *
+ * Invoke the kernel named "root" of the specified script. Like other kernels, this root()
+ * function will be invoked repeatedly over the cells of the specificed allocation, filling
+ * the output allocation with the results.
+ *
+ * When rsForEach is called, the root script is launched immediately. rsForEach returns
+ * only when the script has completed and the output allocation is ready to use.
+ *
+ * The rs_script argument is typically initialized using a global variable set from Java.
+ *
+ * The kernel can be invoked with just an input allocation or just an output allocation.
+ * This can be done by defining an rs_allocation variable and not initializing it. E.g.
+ * rs_script gCustomScript;
+ * void specializedProcessing(rs_allocation in) {
+ * rs_allocation ignoredOut;
+ * rsForEach(gCustomScript, in, ignoredOut);
+ * }
+ *
+ * If both input and output allocations are specified, they must have the same dimensions.
*
* Parameters:
- * script: The target script to call
- * input: The allocation to source data from
- * output: the allocation to write date into
- * usrData: The user defined params to pass to the root script. May be NULL.
- * sc: Extra control infomation used to select a sub-region of the allocation to be processed or suggest a walking strategy. May be NULL.
+ * script: Script to call.
+ * input: Allocation to source data from.
+ * output: Allocation to write date into.
+ * usrData: User defined data to pass to the script. May be NULL.
+ * sc: Extra control information used to select a sub-region of the allocation to be processed or suggest a walking strategy. May be NULL.
* usrDataLen: The size of the userData structure. This will be used to perform a shallow copy of the data if necessary.
*/
#if !defined(RS_VERSION) || (RS_VERSION <= 13)
@@ -276,6 +310,8 @@
* function. E.g.
* int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) {
* uint32_t size = rsGetDimX(context); //...
+ *
+ * To get the dimension of specific allocation, use rsAllocationGetDimX().
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
extern uint32_t __attribute__((overloadable))
@@ -289,6 +325,8 @@
* See rsGetDimX() for an explanation of the context.
*
* Returns 0 if the Y dimension is not present.
+ *
+ * To get the dimension of specific allocation, use rsAllocationGetDimY().
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
extern uint32_t __attribute__((overloadable))
@@ -302,6 +340,8 @@
* See rsGetDimX() for an explanation of the context.
*
* Returns 0 if the Z dimension is not present.
+ *
+ * To get the dimension of specific allocation, use rsAllocationGetDimZ().
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 23))
extern uint32_t __attribute__((overloadable))
@@ -323,7 +363,7 @@
#endif
/*
- * rsGetLod: Index in the Levels of Detail dimension for the specified context.
+ * rsGetLod: Index in the Levels of Detail dimension for the specified context
*
* Returns the index in the Levels of Detail dimension of the cell being
* processed, as specified by the supplied context. See rsGetArray0() for
diff --git a/scriptc/rs_graphics.rsh b/scriptc/rs_graphics.rsh
index 190ec4d..c133aad 100644
--- a/scriptc/rs_graphics.rsh
+++ b/scriptc/rs_graphics.rsh
@@ -17,11 +17,9 @@
// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
/*
- * rs_graphics.rsh: RenderScript graphics API
+ * rs_graphics.rsh: Graphics Functions and Types
*
- * NOTE: RenderScript Graphics has been deprecated. Do not use.
- *
- * A set of graphics functions used by RenderScript.
+ * The graphics subsystem of RenderScript has been deprecated.
*/
#ifndef RENDERSCRIPT_RS_GRAPHICS_RSH
@@ -38,20 +36,22 @@
/*
* rs_blend_src_func: Blend source function
*
+ * DEPRECATED. Do not use.
+ *
*/
#ifndef __LP64__
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
typedef enum {
- RS_BLEND_SRC_ZERO = 0,
- RS_BLEND_SRC_ONE = 1,
- RS_BLEND_SRC_DST_COLOR = 2,
- RS_BLEND_SRC_ONE_MINUS_DST_COLOR = 3,
- RS_BLEND_SRC_SRC_ALPHA = 4,
- RS_BLEND_SRC_ONE_MINUS_SRC_ALPHA = 5,
- RS_BLEND_SRC_DST_ALPHA = 6,
- RS_BLEND_SRC_ONE_MINUS_DST_ALPHA = 7,
- RS_BLEND_SRC_SRC_ALPHA_SATURATE = 8,
- RS_BLEND_SRC_INVALID = 100
+ RS_BLEND_SRC_ZERO = 0,
+ RS_BLEND_SRC_ONE = 1,
+ RS_BLEND_SRC_DST_COLOR = 2,
+ RS_BLEND_SRC_ONE_MINUS_DST_COLOR = 3,
+ RS_BLEND_SRC_SRC_ALPHA = 4,
+ RS_BLEND_SRC_ONE_MINUS_SRC_ALPHA = 5,
+ RS_BLEND_SRC_DST_ALPHA = 6,
+ RS_BLEND_SRC_ONE_MINUS_DST_ALPHA = 7,
+ RS_BLEND_SRC_SRC_ALPHA_SATURATE = 8,
+ RS_BLEND_SRC_INVALID = 100
} rs_blend_src_func;
#endif
#endif
@@ -59,19 +59,21 @@
/*
* rs_blend_dst_func: Blend destination function
*
+ * DEPRECATED. Do not use.
+ *
*/
#ifndef __LP64__
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
typedef enum {
- RS_BLEND_DST_ZERO = 0,
- RS_BLEND_DST_ONE = 1,
- RS_BLEND_DST_SRC_COLOR = 2,
- RS_BLEND_DST_ONE_MINUS_SRC_COLOR = 3,
- RS_BLEND_DST_SRC_ALPHA = 4,
- RS_BLEND_DST_ONE_MINUS_SRC_ALPHA = 5,
- RS_BLEND_DST_DST_ALPHA = 6,
- RS_BLEND_DST_ONE_MINUS_DST_ALPHA = 7,
- RS_BLEND_DST_INVALID = 100
+ RS_BLEND_DST_ZERO = 0,
+ RS_BLEND_DST_ONE = 1,
+ RS_BLEND_DST_SRC_COLOR = 2,
+ RS_BLEND_DST_ONE_MINUS_SRC_COLOR = 3,
+ RS_BLEND_DST_SRC_ALPHA = 4,
+ RS_BLEND_DST_ONE_MINUS_SRC_ALPHA = 5,
+ RS_BLEND_DST_DST_ALPHA = 6,
+ RS_BLEND_DST_ONE_MINUS_DST_ALPHA = 7,
+ RS_BLEND_DST_INVALID = 100
} rs_blend_dst_func;
#endif
#endif
@@ -79,14 +81,16 @@
/*
* rs_cull_mode: Culling mode
*
+ * DEPRECATED. Do not use.
+ *
*/
#ifndef __LP64__
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
typedef enum {
- RS_CULL_BACK = 0,
- RS_CULL_FRONT = 1,
- RS_CULL_NONE = 2,
- RS_CULL_INVALID = 100
+ RS_CULL_BACK = 0,
+ RS_CULL_FRONT = 1,
+ RS_CULL_NONE = 2,
+ RS_CULL_INVALID = 100
} rs_cull_mode;
#endif
#endif
@@ -94,20 +98,22 @@
/*
* rs_depth_func: Depth function
*
+ * DEPRECATED. Do not use.
+ *
* Specifies conditional drawing depending on the comparison of the incoming
* depth to that found in the depth buffer.
*/
#ifndef __LP64__
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
typedef enum {
- RS_DEPTH_FUNC_ALWAYS = 0, // Always drawn
- RS_DEPTH_FUNC_LESS = 1, // Drawn if the incoming depth value is less than that in the depth buffer
- RS_DEPTH_FUNC_LEQUAL = 2, // Drawn if the incoming depth value is less or equal to that in the depth buffer
- RS_DEPTH_FUNC_GREATER = 3, // Drawn if the incoming depth value is greater than that in the depth buffer
- RS_DEPTH_FUNC_GEQUAL = 4, // Drawn if the incoming depth value is greater or equal to that in the depth buffer
- RS_DEPTH_FUNC_EQUAL = 5, // Drawn if the incoming depth value is equal to that in the depth buffer
- RS_DEPTH_FUNC_NOTEQUAL = 6, // Drawn if the incoming depth value is not equal to that in the depth buffer
- RS_DEPTH_FUNC_INVALID = 100 // Invalid depth function
+ RS_DEPTH_FUNC_ALWAYS = 0, // Always drawn
+ RS_DEPTH_FUNC_LESS = 1, // Drawn if the incoming depth value is less than that in the depth buffer
+ RS_DEPTH_FUNC_LEQUAL = 2, // Drawn if the incoming depth value is less or equal to that in the depth buffer
+ RS_DEPTH_FUNC_GREATER = 3, // Drawn if the incoming depth value is greater than that in the depth buffer
+ RS_DEPTH_FUNC_GEQUAL = 4, // Drawn if the incoming depth value is greater or equal to that in the depth buffer
+ RS_DEPTH_FUNC_EQUAL = 5, // Drawn if the incoming depth value is equal to that in the depth buffer
+ RS_DEPTH_FUNC_NOTEQUAL = 6, // Drawn if the incoming depth value is not equal to that in the depth buffer
+ RS_DEPTH_FUNC_INVALID = 100 // Invalid depth function
} rs_depth_func;
#endif
#endif
@@ -115,6 +121,8 @@
/*
* rs_primitive: How to intepret mesh vertex data
*
+ * DEPRECATED. Do not use.
+ *
* Describes the way mesh vertex data is interpreted when rendering
*/
#ifndef __LP64__
@@ -134,6 +142,8 @@
/*
* rs_font: Handle to a Font
*
+ * DEPRECATED. Do not use.
+ *
* Opaque handle to a RenderScript font object.
* See: android.renderscript.Font
*/
@@ -144,6 +154,8 @@
/*
* rs_mesh: Handle to a Mesh
*
+ * DEPRECATED. Do not use.
+ *
* Opaque handle to a RenderScript mesh object.
* See: android.renderscript.Mesh
*/
@@ -154,6 +166,8 @@
/*
* rs_program_fragment: Handle to a ProgramFragment
*
+ * DEPRECATED. Do not use.
+ *
* Opaque handle to a RenderScript ProgramFragment object.
* See: android.renderscript.ProgramFragment
*/
@@ -164,6 +178,8 @@
/*
* rs_program_vertex: Handle to a ProgramVertex
*
+ * DEPRECATED. Do not use.
+ *
* Opaque handle to a RenderScript ProgramVertex object.
* See: android.renderscript.ProgramVertex
*/
@@ -174,6 +190,8 @@
/*
* rs_program_raster: Handle to a ProgramRaster
*
+ * DEPRECATED. Do not use.
+ *
* Opaque handle to a RenderScript ProgramRaster object.
* See: android.renderscript.ProgramRaster
*/
@@ -184,6 +202,8 @@
/*
* rs_program_store: Handle to a ProgramStore
*
+ * DEPRECATED. Do not use.
+ *
* Opaque handle to a RenderScript ProgramStore object.
* See: android.renderscript.ProgramStore
*/
@@ -192,8 +212,14 @@
#endif
/*
- * rsClearObject: For internal use.
+ * rsClearObject: Release an object
*
+ * 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().
*/
#ifndef __LP64__
extern void __attribute__((overloadable))
@@ -226,8 +252,16 @@
#endif
/*
- * rsIsObject: For internal use.
+ * rsIsObject: Check for an empty handle
*
+ * 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.
*/
#ifndef __LP64__
extern bool __attribute__((overloadable))
@@ -294,6 +328,10 @@
#endif
/*
+ * rsgAllocationSyncAll: Sync the contents of an allocation
+ *
+ * DEPRECATED. Do not use.
+ *
* Sync the contents of an allocation.
*
* If the source is specified, sync from memory space specified by source.
@@ -314,6 +352,10 @@
#endif
/*
+ * rsgBindColorTarget: Set the color target
+ *
+ * DEPRECATED. Do not use.
+ *
* Set the color target used for all subsequent rendering calls
*/
#ifndef __LP64__
@@ -324,6 +366,10 @@
#endif
/*
+ * rsgBindConstant: Bind a constant allocation
+ *
+ * DEPRECATED. Do not use.
+ *
* Bind a new Allocation object to a ProgramFragment or ProgramVertex.
* The Allocation must be a valid constant input for the Program.
*
@@ -344,6 +390,10 @@
#endif
/*
+ * rsgBindDepthTarget: Set the depth target
+ *
+ * DEPRECATED. Do not use.
+ *
* Set the depth target used for all subsequent rendering calls
*/
#ifndef __LP64__
@@ -354,6 +404,10 @@
#endif
/*
+ * rsgBindFont: Bind a font object
+ *
+ * DEPRECATED. Do not use.
+ *
* Binds the font object to be used for all subsequent font rendering calls
*
* Parameters:
@@ -365,6 +419,10 @@
#endif
/*
+ * rsgBindProgramFragment: Bind a ProgramFragment
+ *
+ * DEPRECATED. Do not use.
+ *
* Bind a new ProgramFragment to the rendering context.
*/
#ifndef __LP64__
@@ -373,6 +431,10 @@
#endif
/*
+ * rsgBindProgramRaster: Bind a ProgramRaster
+ *
+ * DEPRECATED. Do not use.
+ *
* Bind a new ProgramRaster to the rendering context.
*/
#ifndef __LP64__
@@ -381,6 +443,10 @@
#endif
/*
+ * rsgBindProgramStore: Bind a ProgramStore
+ *
+ * DEPRECATED. Do not use.
+ *
* Bind a new ProgramStore to the rendering context.
*/
#ifndef __LP64__
@@ -389,6 +455,10 @@
#endif
/*
+ * rsgBindProgramVertex: Bind a ProgramVertex
+ *
+ * DEPRECATED. Do not use.
+ *
* Bind a new ProgramVertex to the rendering context.
*/
#ifndef __LP64__
@@ -397,6 +467,10 @@
#endif
/*
+ * rsgBindSampler: Bind a sampler
+ *
+ * DEPRECATED. Do not use.
+ *
* Bind a new Sampler object to a ProgramFragment. The sampler will
* operate on the texture bound at the matching slot.
*/
@@ -406,6 +480,10 @@
#endif
/*
+ * rsgBindTexture: Bind a texture allocation
+ *
+ * DEPRECATED. Do not use.
+ *
* Bind a new Allocation object to a ProgramFragment. The
* Allocation must be a valid texture for the Program. The sampling
* of the texture will be controled by the Sampler bound at the
@@ -417,6 +495,10 @@
#endif
/*
+ * rsgClearAllRenderTargets: Clear all color and depth targets
+ *
+ * DEPRECATED. Do not use.
+ *
* Clear all color and depth targets and resume rendering into
* the framebuffer
*/
@@ -428,6 +510,10 @@
#endif
/*
+ * rsgClearColor: Clear the specified color from the surface
+ *
+ * DEPRECATED. Do not use.
+ *
* Clears the rendering surface to the specified color.
*/
#ifndef __LP64__
@@ -436,6 +522,10 @@
#endif
/*
+ * rsgClearColorTarget: Clear the color target
+ *
+ * DEPRECATED. Do not use.
+ *
* Clear the previously set color target
*/
#ifndef __LP64__
@@ -446,6 +536,10 @@
#endif
/*
+ * rsgClearDepth: Clear the depth surface
+ *
+ * DEPRECATED. Do not use.
+ *
* Clears the depth suface to the specified value.
*/
#ifndef __LP64__
@@ -454,6 +548,10 @@
#endif
/*
+ * rsgClearDepthTarget: Clear the depth target
+ *
+ * DEPRECATED. Do not use.
+ *
* Clear the previously set depth target
*/
#ifndef __LP64__
@@ -464,6 +562,10 @@
#endif
/*
+ * rsgDrawMesh: Draw a mesh
+ *
+ * DEPRECATED. Do not use.
+ *
* Draw a mesh using the current context state.
*
* If primitiveIndex is specified, draw part of a mesh using the current context state.
@@ -494,6 +596,10 @@
#endif
/*
+ * rsgDrawQuad: Draw a quad
+ *
+ * DEPRECATED. Do not use.
+ *
* Low performance utility function for drawing a simple quad. Not intended for
* drawing large quantities of geometry.
*/
@@ -504,6 +610,10 @@
#endif
/*
+ * rsgDrawQuadTexCoords: Draw a textured quad
+ *
+ * DEPRECATED. Do not use.
+ *
* Low performance utility function for drawing a textured quad. Not intended
* for drawing large quantities of geometry.
*/
@@ -515,6 +625,10 @@
#endif
/*
+ * rsgDrawRect: Draw a rectangle
+ *
+ * DEPRECATED. Do not use.
+ *
* Low performance utility function for drawing a simple rectangle. Not
* intended for drawing large quantities of geometry.
*/
@@ -524,6 +638,10 @@
#endif
/*
+ * rsgDrawSpriteScreenspace: Draw rectangles in screenspace
+ *
+ * DEPRECATED. Do not use.
+ *
* Low performance function for drawing rectangles in screenspace. This
* function uses the default passthough ProgramVertex. Any bound ProgramVertex
* is ignored. This function has considerable overhead and should not be used
@@ -535,6 +653,10 @@
#endif
/*
+ * rsgDrawText: Draw a text string
+ *
+ * DEPRECATED. Do not use.
+ *
* Draws text given a string and location
*/
#ifndef __LP64__
@@ -548,6 +670,10 @@
#endif
/*
+ * rsgFinish: End rendering commands
+ *
+ * DEPRECATED. Do not use.
+ *
* Force RenderScript to finish all rendering commands
*/
#ifndef __LP64__
@@ -558,6 +684,10 @@
#endif
/*
+ * rsgFontColor: Set the font color
+ *
+ * DEPRECATED. Do not use.
+ *
* Sets the font color for all subsequent rendering calls
*
* Parameters:
@@ -572,6 +702,10 @@
#endif
/*
+ * rsgGetHeight: Get the surface height
+ *
+ * DEPRECATED. Do not use.
+ *
* Get the height of the current rendering surface.
*/
#ifndef __LP64__
@@ -580,6 +714,10 @@
#endif
/*
+ * rsgGetWidth: Get the surface width
+ *
+ * DEPRECATED. Do not use.
+ *
* Get the width of the current rendering surface.
*/
#ifndef __LP64__
@@ -588,6 +726,10 @@
#endif
/*
+ * rsgMeasureText: Get the bounding box for a text string
+ *
+ * DEPRECATED. Do not use.
+ *
* Returns the bounding box of the text relative to (0, 0)
* Any of left, right, top, bottom could be NULL
*/
@@ -602,6 +744,10 @@
#endif
/*
+ * rsgMeshComputeBoundingBox: Compute a bounding box
+ *
+ * DEPRECATED. Do not use.
+ *
* Computes an axis aligned bounding box of a mesh object
*/
#ifndef __LP64__
@@ -625,6 +771,10 @@
#endif
/*
+ * rsgMeshGetIndexAllocation: Return an allocation containing index data
+ *
+ * DEPRECATED. Do not use.
+ *
* Returns an allocation containing index data or a null
* allocation if only the primitive is specified
*
@@ -642,6 +792,10 @@
#endif
/*
+ * rsgMeshGetPrimitive: Return the primitive
+ *
+ * DEPRECATED. Do not use.
+ *
* Returns the primitive describing how a part of the mesh is
* rendered
*
@@ -659,6 +813,10 @@
#endif
/*
+ * rsgMeshGetPrimitiveCount: Return the number of index sets
+ *
+ * DEPRECATED. Do not use.
+ *
* Meshes could have multiple index sets, this function returns
* the number.
*
@@ -675,6 +833,10 @@
#endif
/*
+ * rsgMeshGetVertexAllocation: Return a vertex allocation
+ *
+ * DEPRECATED. Do not use.
+ *
* Returns an allocation that is part of the mesh and contains
* vertex data, e.g. positions, normals, texcoords
*
@@ -692,6 +854,10 @@
#endif
/*
+ * rsgMeshGetVertexAllocationCount: Return the number of vertex allocations
+ *
+ * DEPRECATED. Do not use.
+ *
* Returns the number of allocations in the mesh that contain
* vertex data
*
@@ -708,6 +874,10 @@
#endif
/*
+ * rsgProgramFragmentConstantColor: Set the constant color for a fixed function emulation program
+ *
+ * DEPRECATED. Do not use.
+ *
* Set the constant color for a fixed function emulation program.
*/
#ifndef __LP64__
@@ -716,6 +886,10 @@
#endif
/*
+ * rsgProgramVertexGetProjectionMatrix: Get the projection matrix for a fixed function vertex program
+ *
+ * DEPRECATED. Do not use.
+ *
* Get the projection matrix for a currently bound fixed function
* vertex program. Calling this function with a custom vertex shader
* would result in an error.
@@ -729,6 +903,10 @@
#endif
/*
+ * rsgProgramVertexLoadModelMatrix: Load the model matrix for a bound fixed function vertex program
+ *
+ * DEPRECATED. Do not use.
+ *
* Load the model matrix for a currently bound fixed function
* vertex program. Calling this function with a custom vertex shader
* would result in an error.
@@ -742,6 +920,10 @@
#endif
/*
+ * rsgProgramVertexLoadProjectionMatrix: Load the projection matrix for a bound fixed function vertex program
+ *
+ * DEPRECATED. Do not use.
+ *
* Load the projection matrix for a currently bound fixed function
* vertex program. Calling this function with a custom vertex shader
* would result in an error.
@@ -755,6 +937,10 @@
#endif
/*
+ * rsgProgramVertexLoadTextureMatrix: Load the texture matrix for a bound fixed function vertex program
+ *
+ * DEPRECATED. Do not use.
+ *
* Load the texture matrix for a currently bound fixed function
* vertex program. Calling this function with a custom vertex shader
* would result in an error.
@@ -768,6 +954,10 @@
#endif
/*
+ * rsgProgramRasterGetCullMode: Get program raster cull mode
+ *
+ * DEPRECATED. Do not use.
+ *
* Get program raster cull mode
*
* Parameters:
@@ -781,6 +971,10 @@
#endif
/*
+ * rsgProgramRasterIsPointSpriteEnabled: Get program raster point sprite state
+ *
+ * DEPRECATED. Do not use.
+ *
* Get program raster point sprite state
*
* Parameters:
@@ -794,6 +988,10 @@
#endif
/*
+ * rsgProgramStoreGetBlendDstFunc: Get program store blend destination function
+ *
+ * DEPRECATED. Do not use.
+ *
* Get program store blend destination function
*
* Parameters:
@@ -807,6 +1005,10 @@
#endif
/*
+ * rsgProgramStoreGetBlendSrcFunc: Get program store blend source function
+ *
+ * DEPRECATED. Do not use.
+ *
* Get program store blend source function
*
* Parameters:
@@ -820,6 +1022,10 @@
#endif
/*
+ * rsgProgramStoreGetDepthFunc: Get program store depth function
+ *
+ * DEPRECATED. Do not use.
+ *
* Get program store depth function
*
* Parameters:
@@ -833,6 +1039,10 @@
#endif
/*
+ * rsgProgramStoreIsColorMaskAlphaEnabled: Get program store alpha component color mask
+ *
+ * DEPRECATED. Do not use.
+ *
* Get program store alpha component color mask
*
* Parameters:
@@ -846,6 +1056,10 @@
#endif
/*
+ * rsgProgramStoreIsColorMaskBlueEnabled: Get program store blur component color mask
+ *
+ * DEPRECATED. Do not use.
+ *
* Get program store blur component color mask
*
* Parameters:
@@ -859,6 +1073,10 @@
#endif
/*
+ * rsgProgramStoreIsColorMaskGreenEnabled: Get program store green component color mask
+ *
+ * DEPRECATED. Do not use.
+ *
* Get program store green component color mask
*
* Parameters:
@@ -872,6 +1090,10 @@
#endif
/*
+ * rsgProgramStoreIsColorMaskRedEnabled: Get program store red component color mask
+ *
+ * DEPRECATED. Do not use.
+ *
* Get program store red component color mask
*
* Parameters:
@@ -885,6 +1107,10 @@
#endif
/*
+ * rsgProgramStoreIsDepthMaskEnabled: Get program store depth mask
+ *
+ * DEPRECATED. Do not use.
+ *
* Get program store depth mask
*
* Parameters:
@@ -898,6 +1124,10 @@
#endif
/*
+ * rsgProgramStoreIsDitherEnabled: Get program store dither state
+ *
+ * DEPRECATED. Do not use.
+ *
* Get program store dither state
*
* Parameters:
diff --git a/scriptc/rs_io.rsh b/scriptc/rs_io.rsh
index 7bb7a49..d14af11 100644
--- a/scriptc/rs_io.rsh
+++ b/scriptc/rs_io.rsh
@@ -17,9 +17,11 @@
// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
/*
- * rs_io.rsh: Input/output functions
+ * rs_io.rsh: Input/Output Functions
*
- * TODO Add documentation
+ * These functions are used to:
+ * - Send information to the Java client, and
+ * - Send the processed allocation or receive the next allocation to process.
*/
#ifndef RENDERSCRIPT_RS_IO_RSH
@@ -31,7 +33,7 @@
* Receive a new set of contents from the queue.
*
* Parameters:
- * a: allocation to work on
+ * a: Allocation to work on.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern void __attribute__((overloadable))
@@ -44,7 +46,7 @@
* Send the contents of the Allocation to the queue.
*
* Parameters:
- * a: allocation to work on
+ * a: Allocation to work on.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern void __attribute__((overloadable))
@@ -52,9 +54,19 @@
#endif
/*
- * Send a message back to the client. Will not block and returns true
- * if the message was sendable and false if the fifo was full.
- * A message ID is required. Data payload is optional.
+ * rsSendToClient: Send a message to the client, non-blocking
+ *
+ * Sends a message back to the client. This call does not block.
+ * It returns true if the message was sent and false if the
+ * message queue is full.
+ *
+ * A message ID is required. The data payload is optional.
+ *
+ * See RenderScript.RSMessageHandler.
+ *
+ * Parameters:
+ * data: Application specific data.
+ * len: Length of the data, in bytes.
*/
extern bool __attribute__((overloadable))
rsSendToClient(int cmdID);
@@ -63,8 +75,20 @@
rsSendToClient(int cmdID, const void* data, uint len);
/*
- * Send a message back to the client, blocking until the message is queued.
- * A message ID is required. Data payload is optional.
+ * rsSendToClientBlocking: Send a message to the client, blocking
+ *
+ * Sends a message back to the client. This function will block
+ * until there is room on the message queue for this message.
+ * This function may return before the message was delivered and
+ * processed by the client.
+ *
+ * A message ID is required. The data payload is optional.
+ *
+ * See RenderScript.RSMessageHandler.
+ *
+ * Parameters:
+ * data: Application specific data.
+ * len: Length of the data, in bytes.
*/
extern void __attribute__((overloadable))
rsSendToClientBlocking(int cmdID);
diff --git a/scriptc/rs_math.rsh b/scriptc/rs_math.rsh
index f78a0e1..0f094f6 100644
--- a/scriptc/rs_math.rsh
+++ b/scriptc/rs_math.rsh
@@ -17,9 +17,9 @@
// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
/*
- * rs_math.rsh: Mathematical functions
+ * rs_math.rsh: Mathematical Constants and Functions
*
- * Most mathematical functions can be applied to scalars and vectors.
+ * The mathematical functions below can be applied to scalars and vectors.
* When applied to vectors, a vector of the function applied to each entry
* of the input is returned.
*
@@ -33,8 +33,8 @@
* a = sin(b);
*
*
- * A few functions like distance() and length() interpret instead the input
- * as a single vector in n-dimensional space.
+ * See "Vector math functions" for functions like distance() and length()
+ * that interpret instead the input as a single vector in n-dimensional space.
*
* The precision of the mathematical operations is affected by the pragmas
* rs_fp_relaxed and rs_fp_full.
@@ -65,8 +65,11 @@
#define M_2_PI 0.636619772367581343075535053490057448f
/*
- * M_2_PIl: Deprecated. Use M_2_PI instead.
+ * M_2_PIl: 2 / pi, as a 32 bit float
*
+ * DEPRECATED. Do not use.
+ *
+ * 2 divided by pi, as a 32 bit float.
*/
#define M_2_PIl 0.636619772367581343075535053490057448f
@@ -4057,9 +4060,9 @@
/*
* rsClamp: Restrain a value to a range
*
- * Clamp a value between low and high.
+ * DEPRECATED. Do not use.
*
- * Deprecated. Use clamp() instead.
+ * Clamp a value between low and high.
*
* Parameters:
* amount: The value to clamp
@@ -4085,12 +4088,18 @@
rsClamp(uint amount, uint low, uint high);
/*
+ * rsFrac: Returns the fractional part of a float
+ *
+ * DEPRECATED. Do not use.
+ *
* Returns the fractional part of a float
*/
extern float __attribute__((const, overloadable))
rsFrac(float v);
/*
+ * rsRand: Pseudo-random number
+ *
* Return a random value between 0 (or min_value) and max_malue.
*/
extern int __attribute__((overloadable))
diff --git a/scriptc/rs_matrix.rsh b/scriptc/rs_matrix.rsh
index 169d2b2..bb7c6e8 100644
--- a/scriptc/rs_matrix.rsh
+++ b/scriptc/rs_matrix.rsh
@@ -17,7 +17,7 @@
// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
/*
- * rs_matrix.rsh: Matrix functions
+ * rs_matrix.rsh: Matrix Functions
*
* These functions let you manipulate square matrices of rank 2x2, 3x3, and 4x4.
* They are particularly useful for graphical transformations and are
@@ -51,6 +51,8 @@
#include "rs_vector_math.rsh"
/*
+ * rsExtractFrustumPlanes: Compute frustum planes
+ *
* Computes 6 frustum planes from the view projection matrix
*
* Parameters:
@@ -111,7 +113,9 @@
}
/*
- * Checks if a sphere is withing the 6 frustum planes
+ * rsIsSphereInFrustum: Checks if a sphere is within the frustum planes
+ *
+ * Returns true if the sphere is within the 6 frustum planes.
*
* Parameters:
* sphere: float4 representing the sphere
diff --git a/scriptc/rs_object_info.rsh b/scriptc/rs_object_info.rsh
index 16828a3..6ea7ed6 100644
--- a/scriptc/rs_object_info.rsh
+++ b/scriptc/rs_object_info.rsh
@@ -17,15 +17,16 @@
// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
/*
- * rs_object_info.rsh: Element functions
+ * rs_object_info.rsh: Object Characteristics Functions
+ *
+ * The functions below can be used to query the characteristics of an allocation,
+ * element, or sampler object. These objects are created from Java.
*
* The term "element" is used a bit ambiguously in RenderScript, as both
* the type of an item of an allocation and the instantiation of that type:
- *
* - rs_element is a handle to a type specification, and
- *
* - In functions like rsGetElementAt(), "element" means the instantiation
- * of the type, i.e. an item of an allocation.
+ * of the type, i.e. an item of an allocation.
*
* The functions below let you query the characteristics of the type specificiation.
*
@@ -46,8 +47,10 @@
/*
* rsAllocationGetDimFaces: Presence of more than one face
*
- * 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.
+ * 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.
*
* Returns: Returns 1 if more than one face is present, 0 otherwise.
*/
@@ -55,9 +58,12 @@
rsAllocationGetDimFaces(rs_allocation a);
/*
- * rsAllocationGetDimLOD: Presence of levels of details
+ * rsAllocationGetDimLOD: Presence of levels of detail
*
- * Query an allocation for the presence of more than one Level Of Details. This is useful for mipmaps.
+ * 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.
*
* Returns: Returns 1 if more than one LOD is present, 0 otherwise.
*/
@@ -69,6 +75,8 @@
*
* Returns the size of the X dimension of the allocation.
*
+ * Use rsGetDimX() to get the dimension of a currently running kernel.
+ *
* Returns: The X dimension of the allocation.
*/
extern uint32_t __attribute__((overloadable))
@@ -80,6 +88,8 @@
* 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.
+ *
* Returns: The Y dimension of the allocation.
*/
extern uint32_t __attribute__((overloadable))
@@ -91,6 +101,8 @@
* 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.
+ *
* Returns: The Z dimension of the allocation.
*/
extern uint32_t __attribute__((overloadable))
@@ -108,8 +120,14 @@
rsAllocationGetElement(rs_allocation a);
/*
- * rsClearObject: For internal use.
+ * rsClearObject: Release an object
*
+ * 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().
*/
extern void __attribute__((overloadable))
rsClearObject(rs_element* dst);
@@ -127,8 +145,16 @@
rsClearObject(rs_script* dst);
/*
- * rsIsObject: For internal use.
+ * rsIsObject: Check for an empty handle
*
+ * 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.
*/
extern bool __attribute__((overloadable))
rsIsObject(rs_element v);
@@ -308,12 +334,11 @@
/*
* rsGetAllocation: Returns the Allocation for a given pointer
*
+ * DEPRECATED. Do not use.
+ *
* 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.
- *
- * This function is deprecated and will be removed from the SDK in a future
- * release.
*/
extern rs_allocation __attribute__((overloadable))
rsGetAllocation(const void* p);
diff --git a/scriptc/rs_object_types.rsh b/scriptc/rs_object_types.rsh
index 7df0561..bc1dcb1 100644
--- a/scriptc/rs_object_types.rsh
+++ b/scriptc/rs_object_types.rsh
@@ -17,9 +17,11 @@
// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
/*
- * rs_object_types.rsh: Standard RenderScript types
+ * rs_object_types.rsh: Object Types
*
- * TODO desc.
+ * The types below are used to manipulate RenderScript objects like allocations,
+ * samplers, elements, and scripts. Most of these object are created using the Java
+ * RenderScript APIs.
*/
#ifndef RENDERSCRIPT_RS_OBJECT_TYPES_RSH
@@ -84,43 +86,6 @@
typedef _RS_HANDLE rs_script;
/*
- * rs_matrix4x4: 4x4 matrix of 32 bit floats
- *
- * Native holder for RS matrix. Elements are stored in the array at the
- * location [row*4 + col]
- */
-typedef struct {
- float m[16];
-} rs_matrix4x4;
-
-/*
- * rs_matrix3x3: 3x3 matrix of 32 bit floats
- *
- * Native holder for RS matrix. Elements are stored in the array at the
- * location [row*3 + col]
- */
-typedef struct {
- float m[9];
-} rs_matrix3x3;
-
-/*
- * rs_matrix2x2: 2x2 matrix of 32 bit floats
- *
- * Native holder for RS matrix. Elements are stored in the array at the
- * location [row*2 + col]
- */
-typedef struct {
- float m[4];
-} rs_matrix2x2;
-
-/*
- * rs_quaternion: Quarternion
- *
- * Quaternion type for use with the quaternion functions
- */
-typedef float4 rs_quaternion;
-
-/*
* rs_allocation_cubemap_face: Enum for selecting cube map faces
*
*/
@@ -171,36 +136,36 @@
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
typedef enum {
- RS_TYPE_NONE = 0,
- RS_TYPE_FLOAT_32 = 2,
- RS_TYPE_FLOAT_64 = 3,
- RS_TYPE_SIGNED_8 = 4,
- RS_TYPE_SIGNED_16 = 5,
- RS_TYPE_SIGNED_32 = 6,
- RS_TYPE_SIGNED_64 = 7,
- RS_TYPE_UNSIGNED_8 = 8,
- RS_TYPE_UNSIGNED_16 = 9,
- RS_TYPE_UNSIGNED_32 = 10,
- RS_TYPE_UNSIGNED_64 = 11,
- RS_TYPE_BOOLEAN = 12,
- RS_TYPE_UNSIGNED_5_6_5 = 13,
+ RS_TYPE_NONE = 0,
+ RS_TYPE_FLOAT_32 = 2,
+ RS_TYPE_FLOAT_64 = 3,
+ RS_TYPE_SIGNED_8 = 4,
+ RS_TYPE_SIGNED_16 = 5,
+ RS_TYPE_SIGNED_32 = 6,
+ RS_TYPE_SIGNED_64 = 7,
+ RS_TYPE_UNSIGNED_8 = 8,
+ RS_TYPE_UNSIGNED_16 = 9,
+ RS_TYPE_UNSIGNED_32 = 10,
+ RS_TYPE_UNSIGNED_64 = 11,
+ RS_TYPE_BOOLEAN = 12,
+ RS_TYPE_UNSIGNED_5_6_5 = 13,
RS_TYPE_UNSIGNED_5_5_5_1 = 14,
RS_TYPE_UNSIGNED_4_4_4_4 = 15,
- RS_TYPE_MATRIX_4X4 = 16,
- RS_TYPE_MATRIX_3X3 = 17,
- RS_TYPE_MATRIX_2X2 = 18,
- RS_TYPE_ELEMENT = 1000,
- RS_TYPE_TYPE = 1001,
- RS_TYPE_ALLOCATION = 1002,
- RS_TYPE_SAMPLER = 1003,
- RS_TYPE_SCRIPT = 1004,
- RS_TYPE_MESH = 1005,
+ RS_TYPE_MATRIX_4X4 = 16,
+ RS_TYPE_MATRIX_3X3 = 17,
+ RS_TYPE_MATRIX_2X2 = 18,
+ RS_TYPE_ELEMENT = 1000,
+ RS_TYPE_TYPE = 1001,
+ RS_TYPE_ALLOCATION = 1002,
+ RS_TYPE_SAMPLER = 1003,
+ RS_TYPE_SCRIPT = 1004,
+ RS_TYPE_MESH = 1005,
RS_TYPE_PROGRAM_FRAGMENT = 1006,
- RS_TYPE_PROGRAM_VERTEX = 1007,
- RS_TYPE_PROGRAM_RASTER = 1008,
- RS_TYPE_PROGRAM_STORE = 1009,
- RS_TYPE_FONT = 1010,
- RS_TYPE_INVALID = 10000
+ RS_TYPE_PROGRAM_VERTEX = 1007,
+ RS_TYPE_PROGRAM_RASTER = 1008,
+ RS_TYPE_PROGRAM_STORE = 1009,
+ RS_TYPE_FONT = 1010,
+ RS_TYPE_INVALID = 10000
} rs_data_type;
#endif
@@ -232,14 +197,14 @@
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
typedef enum {
- RS_SAMPLER_NEAREST = 0,
- RS_SAMPLER_LINEAR = 1,
- RS_SAMPLER_LINEAR_MIP_LINEAR = 2,
- RS_SAMPLER_WRAP = 3,
- RS_SAMPLER_CLAMP = 4,
- RS_SAMPLER_LINEAR_MIP_NEAREST = 5,
- RS_SAMPLER_MIRRORED_REPEAT = 6,
- RS_SAMPLER_INVALID = 100
+ RS_SAMPLER_NEAREST = 0,
+ RS_SAMPLER_LINEAR = 1,
+ RS_SAMPLER_LINEAR_MIP_LINEAR = 2,
+ RS_SAMPLER_WRAP = 3,
+ RS_SAMPLER_CLAMP = 4,
+ RS_SAMPLER_LINEAR_MIP_NEAREST = 5,
+ RS_SAMPLER_MIRRORED_REPEAT = 6,
+ RS_SAMPLER_INVALID = 100
} rs_sampler_value;
#endif
diff --git a/scriptc/rs_quaternion.rsh b/scriptc/rs_quaternion.rsh
index a9321c9..041bdf5 100644
--- a/scriptc/rs_quaternion.rsh
+++ b/scriptc/rs_quaternion.rsh
@@ -17,7 +17,7 @@
// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
/*
- * rs_quaternion.rsh: Quaternion routines
+ * rs_quaternion.rsh: Quaternion Functions
*
*/
@@ -25,11 +25,13 @@
#define RENDERSCRIPT_RS_QUATERNION_RSH
/*
- * Add two quaternions
+ * rsQuaternionAdd: Add two quaternions
+ *
+ * Adds two quaternions, i.e. *q += *rhs;
*
* Parameters:
- * q: destination quaternion to add to
- * rhs: right hand side quaternion to add
+ * q: Destination quaternion to add to.
+ * rhs: Quaternion to add.
*/
static inline void __attribute__((overloadable))
rsQuaternionAdd(rs_quaternion* q, const rs_quaternion* rhs) {
@@ -40,10 +42,12 @@
}
/*
- * Conjugates the quaternion
+ * rsQuaternionConjugate: Conjugate a quaternion
+ *
+ * Conjugates the quaternion.
*
* Parameters:
- * q: quaternion to conjugate
+ * q: Quaternion to modify.
*/
static inline void __attribute__((overloadable))
rsQuaternionConjugate(rs_quaternion* q) {
@@ -53,13 +57,13 @@
}
/*
- * Dot product of two quaternions
+ * rsQuaternionDot: Dot product of two quaternions
+ *
+ * Returns the dot product of two quaternions.
*
* Parameters:
- * q0: first quaternion
- * q1: second quaternion
- *
- * Returns: dot product between q0 and q1
+ * q0: First quaternion.
+ * q1: Second quaternion.
*/
static inline float __attribute__((overloadable))
rsQuaternionDot(const rs_quaternion* q0, const rs_quaternion* q1) {
@@ -67,11 +71,13 @@
}
/*
- * Computes rotation matrix from the normalized quaternion
+ * rsQuaternionGetMatrixUnit: Get a rotation matrix from a quaternion
+ *
+ * Computes a rotation matrix from the normalized quaternion.
*
* Parameters:
- * m: resulting matrix
- * q: normalized quaternion
+ * m: Resulting matrix.
+ * q: Normalized quaternion.
*/
static inline void __attribute__((overloadable))
rsQuaternionGetMatrixUnit(rs_matrix4x4* m, const rs_quaternion* q) {
@@ -99,14 +105,16 @@
}
/*
- * Loads a quaternion that represents a rotation about an arbitrary unit vector
+ * rsQuaternionLoadRotateUnit: Quaternion that represents a rotation about an arbitrary unit vector
+ *
+ * Loads a quaternion that represents a rotation about an arbitrary unit vector.
*
* Parameters:
- * q: quaternion to set
- * rot: rot angle to rotate by
- * x: component of a vector
- * y: component of a vector
- * z: component of a vector
+ * q: Destination quaternion.
+ * rot: Angle to rotate by, in radians.
+ * x: X component of the vector.
+ * y: Y component of the vector.
+ * z: Z component of the vector.
*/
static inline void __attribute__((overloadable))
rsQuaternionLoadRotateUnit(rs_quaternion* q, float rot, float x, float y, float z) {
@@ -121,15 +129,17 @@
}
/*
- * Set the quaternion from components or from another quaternion.
+ * rsQuaternionSet: Create a quarternion
+ *
+ * Creates a quaternion from its four components or from another quaternion.
*
* Parameters:
- * q: destination quaternion
- * w: component
- * x: component
- * y: component
- * z: component
- * rhs: source quaternion
+ * q: Destination quaternion.
+ * w: W component.
+ * x: X component.
+ * y: Y component.
+ * z: Z component.
+ * rhs: Source quaternion.
*/
static inline void __attribute__((overloadable))
rsQuaternionSet(rs_quaternion* q, float w, float x, float y, float z) {
@@ -148,15 +158,17 @@
}
/*
+ * rsQuaternionLoadRotate: Create a rotation quaternion
+ *
* Loads a quaternion that represents a rotation about an arbitrary vector
* (doesn't have to be unit)
*
* Parameters:
- * q: quaternion to set
- * rot: angle to rotate by
- * x: component of a vector
- * y: component of a vector
- * z: component of a vector
+ * q: Destination quaternion.
+ * rot: Angle to rotate by.
+ * x: X component of a vector.
+ * y: Y component of a vector.
+ * z: Z component of a vector.
*/
static inline void __attribute__((overloadable))
rsQuaternionLoadRotate(rs_quaternion* q, float rot, float x, float y, float z) {
@@ -171,10 +183,12 @@
}
/*
- * Normalizes the quaternion
+ * rsQuaternionNormalize: Normalize a quaternion
+ *
+ * Normalizes the quaternion.
*
* Parameters:
- * q: quaternion to normalize
+ * q: Quaternion to normalize.
*/
static inline void __attribute__((overloadable))
rsQuaternionNormalize(rs_quaternion* q) {
@@ -189,19 +203,22 @@
}
/*
- * Multiply quaternion by a scalar or another quaternion
+ * rsQuaternionMultiply: Multiply a quaternion by a scalar or another quaternion
+ *
+ * Multiplies a quaternion by a scalar or by another quaternion, e.g
+ * *q = *q * scalar; or *q = *q * *rhs;.
*
* Parameters:
- * q: destination quaternion
- * s: scalar
- * rhs: right hand side quaternion to multiply by
+ * q: Destination quaternion.
+ * scalar: Scalar to multiply the quarternion by.
+ * rhs: Quarternion to multiply the destination quaternion by.
*/
static inline void __attribute__((overloadable))
- rsQuaternionMultiply(rs_quaternion* q, float s) {
- q->w *= s;
- q->x *= s;
- q->y *= s;
- q->z *= s;
+ rsQuaternionMultiply(rs_quaternion* q, float scalar) {
+ q->w *= scalar;
+ q->x *= scalar;
+ q->y *= scalar;
+ q->z *= scalar;
}
static inline void __attribute__((overloadable))
@@ -217,13 +234,15 @@
}
/*
- * Performs spherical linear interpolation between two quaternions
+ * rsQuaternionSlerp: Spherical linear interpolation between two quaternions
+ *
+ * Performs spherical linear interpolation between two quaternions.
*
* Parameters:
- * q: result quaternion from interpolation
- * q0: first param
- * q1: second param
- * t: how much to interpolate by
+ * q: Result quaternion from the interpolation.
+ * q0: First input quaternion.
+ * q1: Second input quaternion.
+ * t: How much to interpolate by.
*/
static inline void __attribute__((overloadable))
rsQuaternionSlerp(rs_quaternion* q, const rs_quaternion* q0, const rs_quaternion* q1, float t) {
diff --git a/scriptc/rs_time.rsh b/scriptc/rs_time.rsh
index 5f8721a..8ce120f 100644
--- a/scriptc/rs_time.rsh
+++ b/scriptc/rs_time.rsh
@@ -17,9 +17,11 @@
// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
/*
- * rs_time.rsh: RenderScript time routines
+ * rs_time.rsh: Time Functions and Types
*
- * This file contains RenderScript functions relating to time and date manipulation.
+ * The functions below can be used to tell the current clock time and the
+ * current system up time. It's not recommended to call these functions
+ * inside of a kernel.
*/
#ifndef RENDERSCRIPT_RS_TIME_RSH
@@ -57,6 +59,8 @@
} rs_tm;
/*
+ * rsGetDt: Elapsed time since last call
+ *
* Returns the time in seconds since this function was last called in this
* script.
*
@@ -66,33 +70,43 @@
rsGetDt(void);
/*
- * Converts the time specified by p timer into broken-down time and stores it
- * in p local. This function also returns a pointer to p local. If p local
- * is NULL, this function does nothing and returns NULL.
+ * rsLocaltime: Convert to local time
+ *
+ * Converts the time specified by timer into a rs_tm structure that provides year, month, hour, etc.
+ * This value is stored at *local.
+ *
+ * This functions returns the same pointer that is passed as first argument.
+ * If the local parameter is NULL, this function does nothing and returns NULL.
*
* Parameters:
- * local: Broken-down time.
- * timer: Input time as calendar time.
+ * local: Pointer to time structure where the local time will be stored.
+ * timer: Input time as a number of seconds since January 1, 1970.
*
- * Returns: Pointer to broken-down time (same as input p local).
+ * Returns: Pointer to the output local time, i.e. the same value as the parameter local.
*/
extern rs_tm* __attribute__((overloadable))
rsLocaltime(rs_tm* local, const rs_time_t* timer);
/*
+ * rsTime: Seconds since January 1, 1970
+ *
* Returns the number of seconds since the Epoch (00:00:00 UTC, January 1,
- * 1970). If p timer is non-NULL, the result is also stored in the memory
- * pointed to by this variable. If an error occurs, a value of -1 is returned.
+ * 1970).
+ *
+ * If timer is non-NULL, the result is also stored in the memory pointed to by
+ * this variable.
*
* Parameters:
* timer: Location to also store the returned calendar time.
*
- * Returns: Seconds since the Epoch.
+ * Returns: Seconds since the Epoch, -1 if there's an error.
*/
extern rs_time_t __attribute__((overloadable))
rsTime(rs_time_t* timer);
/*
+ * rsUptimeMillis: System uptime in milliseconds
+ *
* Returns the current system clock (uptime) in milliseconds.
*
* Returns: Uptime in milliseconds.
@@ -101,8 +115,13 @@
rsUptimeMillis(void);
/*
+ * rsUptimeNanos: System uptime in nanoseconds
+ *
* Returns the current system clock (uptime) in nanoseconds.
*
+ * The granularity of the values return by this call may be much
+ * larger than a nanosecond.
+ *
* Returns: Uptime in nanoseconds.
*/
extern int64_t __attribute__((overloadable))
diff --git a/scriptc/rs_value_types.rsh b/scriptc/rs_value_types.rsh
index b64d7d7..13c0500 100644
--- a/scriptc/rs_value_types.rsh
+++ b/scriptc/rs_value_types.rsh
@@ -17,25 +17,83 @@
// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
/*
- * rs_value_types.rsh: Standard RenderScript types
+ * rs_value_types.rsh: Numerical Types
*
- * Integers:
- * - 8 bit: char, int8_t
- * - 16 bit: short, int16_t
- * - 32 bit: int, in32_t
- * - 64 bit: long, long long, int64_t
+ * Scalars:
*
- * Unsigned integers:
- * - 8 bit: uchar, uint8_t
- * - 16 bit: ushort, uint16_t
- * - 32 bit: uint, uint32_t
- * - 64 bit: ulong, uint64_t
+ * RenderScript supports the following scalar numerical types:
*
- * Floating point:
- * - 32 bit: float
- * - 64 bit: double
+ * Integers:
+ * - 8 bit: char, int8_t
+ * - 16 bit: short, int16_t
+ * - 32 bit: int, int32_t
+ * - 64 bit: long, long long, int64_t
*
- * Vectors of length 2, 3, and 4 are supported for all the types above.
+ * Unsigned integers:
+ * - 8 bit: uchar, uint8_t
+ * - 16 bit: ushort, uint16_t
+ * - 32 bit: uint, uint32_t
+ * - 64 bit: ulong, uint64_t
+ *
+ * Floating point:
+ * - 32 bit: float
+ * - 64 bit: double
+ *
+ * Vectors:
+ *
+ * RenderScript supports fixed size vectors of length 2, 3, and 4.
+ * Vectors are declared using the common type name followed by a 2, 3, or 4.
+ * E.g. float4, int3, double2, ulong4.
+ *
+ * To create vector literals, use the vector type followed by the values enclosed
+ * between parentheses, e.g. (float3)(1.0f, 2.0f, 3.0f).
+ *
+ * Entries of a vector can be accessed using different naming styles.
+ *
+ * Single entries can be accessed by following the variable name with a dot and:
+ * - The letters x, y, z, and w,
+ * - The letters r, g, b, and a,
+ * - The letter s or S, followed by a zero based index.
+ *
+ * For example, with int4 myVar; the following are equivalent:
+ * myVar.x == myVar.r == myVar.s0 == myVar.S0
+ * myVar.y == myVar.g == myVar.s1 == myVar.S1
+ * myVar.z == myVar.b == myVar.s2 == myVar.S2
+ * myVar.w == myVar.a == myVar.s3 == myVar.S3
+ *
+ * Multiple entries of a vector can be accessed at once by using an identifier
+ * that is the concatenation of multiple letters or indices. The resulting vector
+ * has a size equal to the number of entries named.
+ *
+ * With the example above, the middle two entries can be accessed using
+ * myVar.yz, myVar.gb, myVar.s12, and myVar.S12.
+ *
+ * The entries don't have to be contiguous or in increasing order.
+ * Entries can even be repeated, as long as we're not trying to assign
+ * to it. You also can't mix the naming styles.
+ *
+ * Here are examples of what can or can't be done:
+ * float4 v4;
+ * float3 v3;
+ * float2 v2;
+ * v2 = v4.xx; // Valid
+ * v3 = v4.zxw; // Valid
+ * v3 = v4.bba; // Valid
+ * v3 = v4.s034; // Valid
+ * v3.s120 = v4.S233; // Valid
+ * v4.yz = v3.rg; // Valid
+ * v4.yzx = v3.rg; // Invalid: mismatched sizes
+ * v4.yzz = v3; // Invalid: z appears twice in an assignment
+ * v3 = v3.xas0; // Invalid: can't mix xyzw with rgba nor s0...
+ *
+ *
+ * Matrices and Quaternions:
+ *
+ * RenderScript supports fixed size square matrices of floats of size 2x2, 3x3, and 4x4.
+ * The types are named rs_matrix2x2, rs_matrix3x3, and rs_matrix4x4. See
+ * Matrix Functions for the list of operations.
+ *
+ * Quaternions are also supported via rs_quaternion. See Quaterion Functions. for the list of operations.
*/
#ifndef RENDERSCRIPT_RS_VALUE_TYPES_RSH
@@ -44,28 +102,28 @@
/*
* int8_t: 8 bit signed integer
*
- * 8 bit integer type
+ * 8 bit signed integer type.
*/
typedef char int8_t;
/*
* int16_t: 16 bit signed integer
*
- * 16 bit integer type
+ * A 16 bit signed integer type.
*/
typedef short int16_t;
/*
* int32_t: 32 bit signed integer
*
- * 32 bit integer type
+ * A 32 bit signed integer type.
*/
typedef int int32_t;
/*
* int64_t: 64 bit signed integer
*
- * 64 bit integer type
+ * A 64 bit signed integer type.
*/
#if !defined(RS_VERSION) || (RS_VERSION <= 20)
typedef long long int64_t;
@@ -78,28 +136,28 @@
/*
* uint8_t: 8 bit unsigned integer
*
- * 8 bit unsigned integer type
+ * 8 bit unsigned integer type.
*/
typedef unsigned char uint8_t;
/*
* uint16_t: 16 bit unsigned integer
*
- * 16 bit unsigned integer type
+ * A 16 bit unsigned integer type.
*/
typedef unsigned short uint16_t;
/*
* uint32_t: 32 bit unsigned integer
*
- * 32 bit unsigned integer type
+ * A 32 bit unsigned integer type.
*/
typedef unsigned int uint32_t;
/*
* uint64_t: 64 bit unsigned integer
*
- * 64 bit unsigned integer type
+ * A 64 bit unsigned integer type.
*/
#if !defined(RS_VERSION) || (RS_VERSION <= 20)
typedef unsigned long long uint64_t;
@@ -112,35 +170,35 @@
/*
* uchar: 8 bit unsigned integer
*
- * 8 bit unsigned integer type
+ * 8 bit unsigned integer type.
*/
typedef uint8_t uchar;
/*
* ushort: 16 bit unsigned integer
*
- * 16 bit unsigned integer type
+ * A 16 bit unsigned integer type.
*/
typedef uint16_t ushort;
/*
* uint: 32 bit unsigned integer
*
- * 32 bit unsigned integer type
+ * A 32 bit unsigned integer type.
*/
typedef uint32_t uint;
/*
* ulong: 64 bit unsigned integer
*
- * Typedef for unsigned long (use for 64-bit unsigned integers)
+ * A 64 bit unsigned integer type.
*/
typedef uint64_t ulong;
/*
* size_t: Unsigned size type
*
- * Typedef for size_t
+ * Unsigned size type. The number of bits depend on the compilation flags.
*/
#ifdef __LP64__
typedef uint64_t size_t;
@@ -153,7 +211,7 @@
/*
* ssize_t: Signed size type
*
- * Typedef for ssize_t
+ * Signed size type. The number of bits depend on the compilation flags.
*/
#ifdef __LP64__
typedef int64_t ssize_t;
@@ -403,4 +461,49 @@
*/
typedef long __attribute__((ext_vector_type(4))) long4;
+/*
+ * rs_matrix2x2: 2x2 matrix of 32 bit floats
+ *
+ * A square 2x2 matrix of floats. The entries are stored in the array at the
+ * location [row*2 + col].
+ *
+ * See Matrix Functions.
+ */
+typedef struct {
+ float m[4];
+} rs_matrix2x2;
+
+/*
+ * rs_matrix3x3: 3x3 matrix of 32 bit floats
+ *
+ * A square 3x3 matrix of floats. The entries are stored in the array at the
+ * location [row*3 + col].
+ *
+ * See Matrix Functions.
+ */
+typedef struct {
+ float m[9];
+} rs_matrix3x3;
+
+/*
+ * rs_matrix4x4: 4x4 matrix of 32 bit floats
+ *
+ * A square 4x4 matrix of floats. The entries are stored in the array at the
+ * location [row*4 + col].
+ *
+ * See Matrix Functions.
+ */
+typedef struct {
+ float m[16];
+} rs_matrix4x4;
+
+/*
+ * rs_quaternion: Quaternion
+ *
+ * A square 4x4 matrix of floats that represents a quaternion.
+ *
+ * See Quaternion Functions.
+ */
+typedef float4 rs_quaternion;
+
#endif // RENDERSCRIPT_RS_VALUE_TYPES_RSH
diff --git a/scriptc/rs_vector_math.rsh b/scriptc/rs_vector_math.rsh
index d6c35b9..8ad2cbf 100644
--- a/scriptc/rs_vector_math.rsh
+++ b/scriptc/rs_vector_math.rsh
@@ -17,9 +17,19 @@
// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
/*
- * rs_vector_math.rsh: TODO Add documentation
+ * rs_vector_math.rsh: Vector Math Functions
*
- * TODO Add documentation
+ * These functions interpret the input arguments as representation of vectors in n-dimensional space.
+ *
+ * The precision of the mathematical operations is affected by the pragmas
+ * rs_fp_relaxed and rs_fp_full.
+ *
+ * Different precision/speed tradeoffs can be achieved by using three variants
+ * of common math functions. Functions with a name starting with
+ * - native_ may have custom hardware implementations with weaker precision,
+ * - half_ may perform internal computations using 16 bit floats, and
+ * - fast_ are n-dimensional space computations that may use 16 bit floats.
+ *
*/
#ifndef RENDERSCRIPT_RS_VECTOR_MATH_RSH