API Runtime Reference documentation tweaks.
Many small changes. Among them:
- Cleaned up the boiler plate HTML used for -H option to the minimal possible.
- Cleaned line break of the comments to make them more consistent in the
.rsh files.
- Added missing summaries.
- Make the style of argument comments more consistent.
- Fixed missing HTML escaping.
- Fixed generation of the snippets for the .cs file.
- Improved the documentation about the math precision.
- Reworked the documentation of object types.
Change-Id: I8b229720134aac6d46a0a2679e8b58f15be5ed7e
diff --git a/api/GenerateDocumentation.cpp b/api/GenerateDocumentation.cpp
index eab1889..e5f238a 100644
--- a/api/GenerateDocumentation.cpp
+++ b/api/GenerateDocumentation.cpp
@@ -37,55 +37,18 @@
if (forVerification) {
*file << "<!DOCTYPE html>\n";
*file << "<!-- " << AUTO_GENERATED_WARNING << "-->\n";
-
- *file << "<html><head><meta http-equiv='Content-Type' content='text/html; charset=UTF-8'>\n"
- "<meta name='viewport' content='width=device-width'>\n"
- "<link rel='shortcut icon' type='image/x-icon' "
- "href='http://developer.android.com/favicon.ico'>\n"
- "<title>android.renderscript | Android Developers</title>\n"
- "<!-- STYLESHEETS -->\n"
+ *file << "<html><head>\n"
+ "<title>RenderScript Reference</title>\n"
+ "<meta http-equiv='Content-Type' content='text/html; charset=UTF-8'>\n"
"<link rel='stylesheet' "
"href='http://fonts.googleapis.com/css?family=Roboto+Condensed'>\n"
"<link rel='stylesheet' href='http://fonts.googleapis.com/"
"css?family=Roboto:light,regular,medium,thin,italic,mediumitalic,bold' "
"title='roboto'>\n"
- "<link href='./test_files/default.css' rel='stylesheet' type='text/css'>\n"
- "<!-- FULLSCREEN STYLESHEET -->\n"
- "<link href='./test_files/fullscreen.css' rel='stylesheet' class='fullscreen' "
+ "<link href='default.css' rel='stylesheet' type='text/css'>\n"
+ "<link href='fullscreen.css' rel='stylesheet' class='fullscreen' "
"type='text/css'>\n"
- "<!-- JAVASCRIPT -->\n"
- "<script src='./test_files/cb=gapi.loaded_0' async=''></script><script "
- "type='text/javascript' async='' src='./test_files/plusone.js' "
- "gapi_processed='true'></script><script async='' "
- "src='./test_files/analytics.js'></script><script src='./test_files/jsapi' "
- "type='text/javascript'></script>\n"
- "<script src='./test_files/android_3p-bundle.js' "
- "type='text/javascript'></script>\n"
- "<script type='text/javascript'>\n"
- " var toRoot = '/';\n"
- " var metaTags = [];\n"
- " var devsite = false;\n"
- "</script>\n"
- "<script src='./test_files/docs.js' type='text/javascript'></script><script "
- "type='text/javascript' src='./test_files/saved_resource'></script>\n"
- "<script>\n"
- " (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){\n"
- " (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new "
- "Date();a=s.createElement(o),\n"
- " "
- "m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)\n"
- " })(window,document,'script','//www.google-analytics.com/analytics.js','ga');\n"
- " ga('create', 'UA-5831155-1', 'android.com');\n"
- " ga('create', 'UA-49880327-2', 'android.com', {'name': 'universal'}); // New "
- "tracker);\n"
- " ga('send', 'pageview');\n"
- " ga('universal.send', 'pageview'); // Send page view for new tracker.\n"
- "</script>\n"
- "<link type='text/css' href='./test_files/default+en.css' "
- "rel='stylesheet'><script "
- "type='text/javascript' src='./test_files/default+en.I.js'></script></head>\n"
- "<body class='gc-documentation\n"
- " develop reference'>\n\n";
+ "<body class='gc-documentation develop reference'>\n\n";
*file << "<h1>" << title << "</h1>\n";
} else {
*file << "page.title=RenderScript " << title << "\n\n";
@@ -95,7 +58,7 @@
static void writeFooter(GeneratedFile* file, bool forVerification) {
if (forVerification) {
- *file << "<!-- end body-content -->\n</body></html>\n";
+ *file << "</body></html>\n";
}
}
@@ -260,7 +223,7 @@
static void writeSummaryTableStart(GeneratedFile* file, const string& label, bool labelIsHeading) {
if (labelIsHeading) {
- *file << "<h2 style='margin-bottom: 0px;'>" << label << "</h2><hr/>\n";
+ *file << "<h2 style='margin-bottom: 0px;'>" << label << "</h2>\n";
}
*file << "<table class='jd-sumtable'><tbody>\n";
if (!labelIsHeading) {
@@ -452,7 +415,7 @@
}
bool success = true;
- writeHeader(&file, forVerification, "Overview");
+ writeHeader(&file, forVerification, "Runtime API Reference");
for (auto specFile : systemSpecification.getSpecFiles()) {
if (!writeOverviewForFile(&file, *specFile)) {
@@ -566,6 +529,9 @@
}
static bool writeDetailedFunction(GeneratedFile* file, Function* function) {
+ if (function->hidden()) {
+ return true;
+ }
const string& name = function->getName();
*file << "<a id='android_rs:" << name << "'></a>\n";
@@ -712,7 +678,15 @@
file << "<!-- Copy and paste the following lines into the RenderScript section of\n";
file << " platform/frameworks/base/docs/html/guide/guide_toc.cs\n\n";
- generateSnippet(&file, OVERVIEW_HTML_FILE_NAME, "Overview");
+ const char offset[] = " ";
+ file << offset << "<li class=\"nav-section\">\n";
+ file << offset << " <div class=\"nav-section-header\">\n";
+ file << offset << " <a href=\"<?cs var:toroot ?>guide/topics/renderscript/reference/" <<
+ OVERVIEW_HTML_FILE_NAME << "\">\n";
+ file << offset << " <span class=\"en\">Runtime API Reference</span>\n";
+ file << offset << " </a></div>\n";
+ file << offset << " <ul>\n";
+
for (auto specFile : systemSpecification.getSpecFiles()) {
if (specFile->hasSpecifications()) {
const string fileName = stringReplace(specFile->getSpecFileName(), ".spec", ".html");
@@ -720,6 +694,10 @@
}
}
generateSnippet(&file, INDEX_HTML_FILE_NAME, "Index");
+
+ file << offset << " </ul>\n";
+ file << offset << "</li>\n";
+
return true;
}
diff --git a/api/Utilities.cpp b/api/Utilities.cpp
index 6464ae1..311d7c6 100644
--- a/api/Utilities.cpp
+++ b/api/Utilities.cpp
@@ -117,6 +117,7 @@
out = stringReplace(out, ">", ">");
out = stringReplace(out, "<", "<");
out = stringReplace(out, " ", " ");
+ out = stringReplace(out, "&", "&");
return out;
}
diff --git a/api/rs_allocation_data.spec b/api/rs_allocation_data.spec
index 27fad2e..31fa58d 100644
--- a/api/rs_allocation_data.spec
+++ b/api/rs_allocation_data.spec
@@ -104,16 +104,16 @@
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.
+ 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.
+ 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.
+ For efficiency, this function does not validate the inputs. Trying to wrap
+ the X index, exceeding the size of the allocation, or using indices incompatible
+ with the dimensionality of the allocation yields undefined results.
See also @rsAllocationVStoreX().
test: none
@@ -152,24 +152,23 @@
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:
- This function stores the entries of a vector into successive cells of an
- allocation. It assumes that the allocation contains 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.
+ 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].
+ 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.
+ 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.
+ 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
@@ -208,14 +207,13 @@
description:
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.
+ 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.
+ 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:
@@ -418,13 +416,13 @@
description:
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.
+ 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
+ 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().
diff --git a/api/rs_atomic.spec b/api/rs_atomic.spec
index 7bee720..07713c2 100644
--- a/api/rs_atomic.spec
+++ b/api/rs_atomic.spec
@@ -58,7 +58,7 @@
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:
@@ -73,9 +73,9 @@
function: rsAtomicCas
version: 14
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."
+arg: volatile int32_t* addr, "Address of the value to compare and replace if the test passes."
+arg: int32_t compareValue, "Value to test *addr against."
+arg: int32_t newValue, "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,
diff --git a/api/rs_convert.spec b/api/rs_convert.spec
index 596e66f..ed53199 100644
--- a/api/rs_convert.spec
+++ b/api/rs_convert.spec
@@ -17,8 +17,8 @@
header:
summary: Conversion Functions
description:
- The functions below convert from a numerical vector type to another,
- of from one color representation to another.
+ The functions below convert from a numerical vector type to another, of from one color
+ representation to another.
end:
function: convert_#3#1
@@ -31,10 +31,9 @@
arg: #2#1 v, compatible(#3)
summary: Convert numerical vectors
description:
- Converts a vector from one numerical type to another. The conversion are
- done entry per entry.
+ Converts a vector from one numerical type to another. The conversion are done entry per entry.
- E.g calling <code>a = convert_short3(b)</code> is equivalent to doing
+ 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>.
Converting floating point values to integer types truncates.
@@ -82,13 +81,12 @@
arg: float b, "Blue component."
summary: Create a uchar4 RGBA from floats
description:
- 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.
+ 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.
+ 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:
@@ -125,8 +123,7 @@
arg: uchar4 c
summary: Create a float4 RGBA from uchar4
description:
- Unpacks a uchar4 color to float4. The resulting floats will be between 0.0 and
- 1.0 inclusive.
+ Unpacks a uchar4 color to float4. The resulting floats will be between 0.0 and 1.0 inclusive.
test: none
end:
@@ -135,9 +132,9 @@
w: 4
t: u8, f32
ret: #2#1
-arg: uchar y, "Luminance component"
-arg: uchar u, "U chrominance component"
-arg: uchar v, "V chrominance component"
+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:
Converts a color from a YUV representation to RGBA.
diff --git a/api/rs_core.spec b/api/rs_core.spec
index 1643c45..b4d083a 100644
--- a/api/rs_core.spec
+++ b/api/rs_core.spec
@@ -24,14 +24,12 @@
to write RenderScript code in C99. The RenderScript compute header files are automatically
included for you.
- To use RenderScript, you need to utilize the RenderScript runtime APIs documented here
- as well as the Android framework APIs for RenderScript.
+ To use RenderScript, you need to utilize the RenderScript runtime APIs documented here as well
+ as the Android framework APIs for RenderScript. For documentation on the Android framework
+ APIs, see the <a target="_parent" href="http://developer.android.com/reference/android/renderscript/package-summary.html">android.renderscript</a> package reference.
- For documentation on the Android framework APIs, see the <a target="_parent" href="http://developer.android.com/reference/android/renderscript/package-summary.html">android.renderscript</a> package reference.
-
- For more information on how to develop with RenderScript and how the runtime and
- Android framework APIs interact, see the <a target="_parent" href="http://developer.android.com/guide/topics/renderscript/index.html">RenderScript developer guide</a>
- and the <a target="_parent" href="http://developer.android.com/resources/samples/RenderScript/index.html">RenderScript samples</a>.
+ For more information on how to develop with RenderScript and how the runtime and Android
+ framework APIs interact, see the <a target="_parent" href="http://developer.android.com/guide/topics/renderscript/index.html">RenderScript developer guide</a> and the <a target="_parent" href="http://developer.android.com/resources/samples/RenderScript/index.html">RenderScript samples</a>.
include:
#define RS_KERNEL __attribute__((kernel))
diff --git a/api/rs_for_each.spec b/api/rs_for_each.spec
index 3e4eeb2..5d51316 100644
--- a/api/rs_for_each.spec
+++ b/api/rs_for_each.spec
@@ -54,8 +54,8 @@
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.
+ 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
@@ -134,7 +134,7 @@
arg: rs_allocation input
arg: rs_allocation output
arg: const void* usrData
-arg: size_t usrDataLen, "The size of the userData structure. This will be used to perform a shallow copy of the data if necessary."
+arg: size_t usrDataLen, "Size of the userData structure. This will be used to perform a shallow copy of the data if necessary."
arg: const rs_script_call_t* sc
test: none
end:
@@ -165,15 +165,15 @@
arg: rs_kernel_context ctxt
summary: Index in the Array0 dimension for the specified context
description:
- Returns the index in the Array0 dimension of the cell being processed,
- as specified by the supplied context.
+ Returns the index in the Array0 dimension of the cell being processed, as specified
+ by the supplied context.
- This context is created when a kernel is launched and updated at each
- iteration. It contains common characteristics of the allocations being
- iterated over and rarely used indexes, like the Array0 index.
+ This context is created when a kernel is launched and updated at each iteration.
+ It contains common characteristics of the allocations being iterated over and rarely
+ used indexes, like the Array0 index.
- You can access the context by adding a rs_kernel_context argument to your
- kernel function. E.g.<br/>
+ You can access the context by adding a rs_kernel_context argument to your kernel
+ function. E.g.<br/>
<code>short RS_KERNEL myKernel(short value, uint32_t x, rs_kernel_context context) {<br/>
// The current index in the common x, y, z, w dimensions are accessed by<br/>
// adding these variables as arguments. For the more rarely used indexes<br/>
@@ -192,9 +192,8 @@
arg: rs_kernel_context ctxt
summary: Index in the Array1 dimension for the specified context
description:
- Returns the index in the Array1 dimension of the cell being processed,
- as specified by the supplied context. See @rsGetArray0() for an explanation
- of the context.
+ Returns the index in the Array1 dimension of the cell being processed, as specified
+ by the supplied context. See @rsGetArray0() for an explanation of the context.
Returns 0 if the Array1 dimension is not present.
test: none
@@ -220,9 +219,8 @@
arg: rs_kernel_context ctxt
summary: Index in the Array3 dimension for the specified context
description:
- Returns the index in the Array3 dimension of the cell being processed,
- as specified by the supplied context. See @rsGetArray0() for an explanation
- of the context.
+ Returns the index in the Array3 dimension of the cell being processed, as specified
+ by the supplied context. See @rsGetArray0() for an explanation of the context.
Returns 0 if the Array3 dimension is not present.
test: none
@@ -288,9 +286,9 @@
arg: rs_kernel_context ctxt
summary: Presence of more than one face for the specified context
description:
- If the context refers to a cubemap, this function returns true if there's
- more than one face present. In all other cases, it returns false.
- See @rsGetDimX() for an explanation of the context.
+ If the context refers to a cubemap, this function returns true if there's more than
+ one face present. In all other cases, it returns false. See @rsGetDimX() for an
+ explanation of the context.
@rsAllocationGetDimFaces() is similar but returns 0 or 1 instead of a bool.
test: none
@@ -302,8 +300,9 @@
arg: rs_kernel_context ctxt
summary: Number of levels of detail for the specified context
description:
- Returns the number of levels of detail for the specified context.
- This is useful for mipmaps. See @rsGetDimX() for an explanation of the context.
+ Returns the number of levels of detail for the specified context. This is useful
+ for mipmaps. See @rsGetDimX() for an explanation of the context.
+
Returns 0 if Level of Detail is not used.
@rsAllocationGetDimLOD() is similar but returns 0 or 1 instead the actual
@@ -368,8 +367,8 @@
arg: rs_kernel_context ctxt
summary: Coordinate of the Face for the specified context
description:
- Returns the face on which the cell being processed is found, as specified
- by the supplied context. See @rsGetArray0() for an explanation of the context.
+ Returns the face on which the cell being processed is found, as specified by the
+ supplied context. See @rsGetArray0() for an explanation of the context.
Returns RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X if the face dimension is not
present.
@@ -382,9 +381,9 @@
arg: rs_kernel_context ctxt
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
- an explanation of the context.
+ Returns the index in the Levels of Detail dimension of the cell being processed,
+ as specified by the supplied context. See @rsGetArray0() for an explanation of
+ the context.
Returns 0 if the Levels of Detail dimension is not present.
test: none
diff --git a/api/rs_math.spec b/api/rs_math.spec
index a175e82..cdd7123 100644
--- a/api/rs_math.spec
+++ b/api/rs_math.spec
@@ -17,12 +17,10 @@
header:
summary: Mathematical Constants and Functions
description:
- 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.
+ The mathematical functions below can be applied to scalars and vectors. When applied
+ to vectors, the returned value is a vector of the function applied to each entry of the input.
- For example:<br/>
- <code>
+ For example:<code><br/>
float3 a, b;<br/>
// The following call sets<br/>
// a.x to sin(b.x),<br/>
@@ -31,18 +29,22 @@
a = sin(b);<br/>
</code>
- 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.
+ 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.
- rs_fp_relaxed and rs_fp_full.
+ The precision of the mathematical operations on 32 bit floats is affected by the pragmas
+ rs_fp_relaxed and rs_fp_full. Under rs_fp_relaxed, subnormal values may be flushed to zero and
+ rounding may be done towards zero. In comparison, rs_fp_full requires correct handling of
+ subnormal values, i.e. smaller than 1.17549435e-38f. rs_fp_rull also requires round to nearest
+ with ties to even.
- 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.
+ Different precision/speed tradeoffs can be achieved by using variants of the common math
+ functions. Functions with a name starting with<ul>
+ <li>native_: May have custom hardware implementations with weaker precision. Additionally,
+ subnormal values may be flushed to zero, rounding towards zero may be used, and NaN and
+ infinity input may not be handled correctly.</li>
+ <li>half_: May perform internal computations using 16 bit floats. Additionally, subnormal
+ values may be flushed to zero, and rounding towards zero may be used.</li>
</ul>
end:
@@ -268,8 +270,8 @@
w: 1, 2, 3, 4
t: f32
ret: #2#1
-arg: #2#1 numerator, "The numerator"
-arg: #2#1 denominator, "The denominator. Can be 0."
+arg: #2#1 numerator, "Numerator."
+arg: #2#1 denominator, "Denominator. Can be 0."
summary: Inverse tangent of a ratio
description:
Returns the inverse tangent of <code>(numerator / denominator)</code>, in radians.
@@ -283,8 +285,8 @@
w: 1, 2, 3, 4
t: f32
ret: #2#1
-arg: #2#1 numerator, "The numerator"
-arg: #2#1 denominator, "The denominator. Can be 0."
+arg: #2#1 numerator, "Numerator."
+arg: #2#1 denominator, "Denominator. Can be 0."
summary: Inverse tangent of a ratio, divided by pi
description:
Returns the inverse tangent of <code>(numerator / denominator)</code>, in radians, divided by pi.
@@ -632,10 +634,9 @@
description:
Multiply and add. Returns <code>(multiplicand1 * multiplicand2) + offset</code>.
- This function is similar to @mad(). fma() retains full precision of the
- multiplied result and rounds only after the addition. @mad() rounds after the
- multiplication and the addition. This extra precision is not guaranteed in
- rs_fp_relaxed mode.
+ This function is similar to @mad(). fma() retains full precision of the multiplied result
+ and rounds only after the addition. @mad() rounds after the multiplication and the addition.
+ This extra precision is not guaranteed in rs_fp_relaxed mode.
end:
function: fmax
@@ -716,8 +717,8 @@
description:
Returns the positive fractional part of v, i.e. <code>v - floor(v)</code>.
- For example, <code>fract(1.3f, &val)</code> returns 0.3f and sets val to 1.f.
- <code>fract(-1.3f, &val)</code> returns 0.7f and sets val to -2.f.
+ For example, <code>fract(1.3f, &val)</code> returns 0.3f and sets val to 1.f.
+ <code>fract(-1.3f, &val)</code> returns 0.7f and sets val to -2.f.
end:
function: fract
@@ -825,8 +826,7 @@
For example, <code>ilogb(8.5f)</code> returns 3.
- Because of the difference in mantissa, this number is one less than
- is returned by @frexp().
+ Because of the difference in mantissa, this number is one less than is returned by @frexp().
@logb() is similar but returns a float.
test: custom
@@ -837,8 +837,8 @@
attrib: const
w: 1, 2, 3, 4
ret: float#1
-arg: float#1 mantissa, "The mantissa"
-arg: int#1 exponent, "The exponent, a single component or matching vector."
+arg: float#1 mantissa, "Mantissa."
+arg: int#1 exponent, "Exponent, a single component or matching vector."
summary: Creates a floating point from mantissa and exponent
description:
Returns the floating point created from the mantissa and exponent,
@@ -952,8 +952,7 @@
For example, <code>logb(8.5f)</code> returns 3.f.
- Because of the difference in mantissa, this number is one less than
- is returned by frexp().
+ Because of the difference in mantissa, this number is one less than is returned by frexp().
@ilogb() is similar but returns an integer.
end:
@@ -971,10 +970,9 @@
description:
Multiply and add. Returns <code>(multiplicand1 * multiplicand2) + offset</code>.
- This function is similar to @fma(). @fma() retains full precision of the
- multiplied result and rounds only after the addition. mad() rounds after the
- multiplication and the addition. In rs_fp_relaxed mode, mad() may not do the
- rounding after multiplicaiton.
+ This function is similar to @fma(). @fma() retains full precision of the multiplied result
+ and rounds only after the addition. mad() rounds after the multiplication and the addition.
+ In rs_fp_relaxed mode, mad() may not do the rounding after multiplicaiton.
end:
function: max
@@ -1156,7 +1154,8 @@
description:
Returns start + ((stop - start) * fraction).
- This can be useful for mixing two values. For example, to create a new color that is 40% color1 and 60% color2, use <code>mix(color1, color2, 0.6f)</code>.
+ This can be useful for mixing two values. For example, to create a new color that is
+ 40% color1 and 60% color2, use <code>mix(color1, color2, 0.6f)</code>.
end:
function: mix
@@ -1174,14 +1173,15 @@
version: 9
w: 1, 2, 3, 4
t: f32
-ret: #2#1, "The floating point portion of the value."
-arg: #2#1 v, "Source value"
+ret: #2#1, "Floating point portion of the value."
+arg: #2#1 v, "Source value."
arg: #2#1* integral_part, "*integral_part will be set to the integral portion of the number."
summary: Integral and fractional components
description:
Returns the integral and fractional components of a number.
- Both components will have the same sign as x. For example, for an input of -3.72f, iret will be set to -3.f and .72f will be returned.
+ Both components will have the same sign as x. For example, for an input of -3.72f,
+ iret will be set to -3.f and .72f will be returned.
end:
function: nan
@@ -1209,8 +1209,7 @@
description:
Returns the approximate inverse cosine, in radians.
- This function yields undefined results from input values less than -1 or greater
- than 1.
+ This function yields undefined results from input values less than -1 or greater than 1.
See also @acos().
# TODO Temporary
@@ -1246,8 +1245,7 @@
To get an inverse cosine measured in degrees, use <code>acospi(a) * 180.f</code>.
- This function yields undefined results from input values less than -1 or greater
- than 1.
+ This function yields undefined results from input values less than -1 or greater than 1.
See also @acospi().
# TODO Temporary
@@ -1265,8 +1263,7 @@
description:
Returns the approximate inverse sine, in radians.
- This function yields undefined results from input values less than -1 or greater
- than 1.
+ This function yields undefined results from input values less than -1 or greater than 1.
See also @asin().
# TODO Temporary
@@ -1302,8 +1299,7 @@
To get an inverse sine measured in degrees, use <code>asinpi(a) * 180.f</code>.
- This function yields undefined results from input values less than -1 or greater
- than 1.
+ This function yields undefined results from input values less than -1 or greater than 1.
See also @asinpi().
# TODO Temporary
@@ -1332,8 +1328,8 @@
w: 1, 2, 3, 4
t: f32
ret: #2#1
-arg: #2#1 numerator, "The numerator"
-arg: #2#1 denominator, "The denominator. Can be 0."
+arg: #2#1 numerator, "Numerator."
+arg: #2#1 denominator, "Denominator. Can be 0."
summary: Approximate inverse tangent of a ratio
description:
Returns the approximate inverse tangent of <code>(numerator / denominator)</code>, in radians.
@@ -1349,11 +1345,12 @@
w: 1, 2, 3, 4
t: f32
ret: #2#1
-arg: #2#1 numerator, "The numerator"
-arg: #2#1 denominator, "The denominator. Can be 0."
+arg: #2#1 numerator, "Numerator."
+arg: #2#1 denominator, "Denominator. Can be 0."
summary: Approximate inverse tangent of a ratio, divided by pi
description:
- Returns the approximate inverse tangent of <code>(numerator / denominator)</code>, in radians, divided by pi.
+ Returns the approximate inverse tangent of <code>(numerator / denominator)</code>,
+ in radians, divided by pi.
To get an inverse tangent measured in degrees, use <code>atan2pi(n, d) * 180.f</code>.
@@ -1478,7 +1475,8 @@
description:
Fast approximate exp.
- It is valid for inputs from -86.f to 86.f. The precision is no worse than what would be expected from using 16 bit floating point values.
+ It is valid for inputs from -86.f to 86.f. The precision is no worse than what would be
+ expected from using 16 bit floating point values.
See also @exp().
test: limited
@@ -1495,7 +1493,8 @@
description:
Fast approximate exp10.
- It is valid for inputs from -37.f to 37.f. The precision is no worse than what would be expected from using 16 bit floating point values.
+ It is valid for inputs from -37.f to 37.f. The precision is no worse than what would be
+ expected from using 16 bit floating point values.
See also @exp10().
test: limited
@@ -1512,7 +1511,8 @@
description:
Fast approximate exp2.
- It is valid for inputs from -125.f to 125.f. The precision is no worse than what would be expected from using 16 bit floating point values.
+ It is valid for inputs from -125.f to 125.f. The precision is no worse than what would be
+ expected from using 16 bit floating point values.
See also @exp2().
test: limited
@@ -1689,8 +1689,8 @@
version: 21
w: 1, 2, 3, 4
t: f32
-ret: #2#1, "sine"
-arg: #2#1 v, "The incoming value in radians."
+ret: #2#1, "Sine."
+arg: #2#1 v, "Incoming value in radians."
arg: #2#1* cos, "*cos will be set to the cosine value."
summary: Approximate sine and cosine
description:
@@ -1799,9 +1799,8 @@
description:
Returns the next representable floating point number from v towards target.
- In rs_fp_relaxed mode, a denormalized input value may not yield the next
- denormalized value, as support of denormalized values is optional in
- relaxed mode.
+ In rs_fp_relaxed mode, a denormalized input value may not yield the next denormalized
+ value, as support of denormalized values is optional in relaxed mode.
end:
function: pow
@@ -1816,7 +1815,8 @@
description:
Returns base raised to the power exponent, i.e. base ^ exponent.
- @pown() and @powr() are similar. @pown() takes an integer exponent. @powr() assumes the base to be non-negative.
+ @pown() and @powr() are similar. @pown() takes an integer exponent. @powr() assumes the
+ base to be non-negative.
end:
function: pown
@@ -1831,7 +1831,8 @@
description:
Returns base raised to the power exponent, i.e. base ^ exponent.
- @pow() and @powr() are similar. The both take a float exponent. @powr() also assumes the base to be non-negative.
+ @pow() and @powr() are similar. The both take a float exponent. @powr() also assumes the
+ base to be non-negative.
end:
function: powr
@@ -1846,7 +1847,8 @@
description:
Returns base raised to the power exponent, i.e. base ^ exponent. base must be >= 0.
- @pow() and @pown() are similar. They both make no assumptions about the base. @pow() takes a float exponent while @pown() take an integer.
+ @pow() and @pown() are similar. They both make no assumptions about the base.
+ @pow() takes a float exponent while @pown() take an integer.
See also @native_powr().
end:
@@ -1873,7 +1875,8 @@
arg: #2#1 denominator
summary: Remainder of a division
description:
- Returns the remainder of (numerator / denominator), where the quotient is rounded towards the nearest integer.
+ Returns the remainder of (numerator / denominator), where the quotient is rounded towards
+ the nearest integer.
The function @fmod() is similar but rounds toward the closest interger.
For example, <code>@fmod(-3.8f, 2.f)</code> returns -1.8f (-3.8f - -1.f * 2.f)
@@ -1884,9 +1887,9 @@
version: 9
w: 1, 2, 3, 4
t: f32
-ret: #2#1, "The remainder, precise only for the low three bits."
-arg: #2#1 numerator, "The numerator."
-arg: #2#1 denominator, "The denominator."
+ret: #2#1, "Remainder, precise only for the low three bits."
+arg: #2#1 numerator, "Numerator."
+arg: #2#1 denominator, "Denominator."
arg: int#1* quotient, "*quotient will be set to the integer quotient."
summary: Remainder and quotient of a division
description:
@@ -1894,9 +1897,13 @@
Only the sign and lowest three bits of the quotient are guaranteed to be accurate.
- This function is useful for implementing periodic functions. The low three bits of the quotient gives the quadrant and the remainder the distance within the quadrant. For example, an implementation of @sin(x) could call <code>remquo(x, PI / 2.f, &quadrant)</code> to reduce very large value of x to something within a limited range.
+ This function is useful for implementing periodic functions. The low three bits of the
+ quotient gives the quadrant and the remainder the distance within the quadrant.
+ For example, an implementation of @sin(x) could call <code>remquo(x, PI / 2.f, &quadrant)</code>
+ to reduce very large value of x to something within a limited range.
- Example: <code>remquo(-23.5f, 8.f, ")</code> sets the lowest three bits of quot to 3 and the sign negative. It returns 0.5f.
+ Example: <code>remquo(-23.5f, 8.f, &quot)</code> sets the lowest three bits of quot to 3
+ and the sign negative. It returns 0.5f.
test: custom
end:
@@ -1911,7 +1918,9 @@
description:
Rounds to the nearest integral value.
- rint() rounds half values to even. For example, <code>rint(0.5f)</code> returns 0.f and <code>rint(1.5f)</code> returns 2.f. Similarly, <code>rint(-0.5f)</code> returns -0.f and <code>rint(-1.5f)</code> returns -2.f.
+ rint() rounds half values to even. For example, <code>rint(0.5f)</code> returns 0.f and
+ <code>rint(1.5f)</code> returns 2.f. Similarly, <code>rint(-0.5f)</code> returns -0.f and
+ <code>rint(-1.5f)</code> returns -2.f.
@round() is similar but rounds away from zero. @trunc() truncates the decimal fraction.
end:
@@ -1942,7 +1951,9 @@
description:
Round to the nearest integral value.
- round() rounds half values away from zero. For example, <code>round(0.5f)</code> returns 1.f and <code>round(1.5f)</code> returns 2.f. Similarly, <code>round(-0.5f)</code> returns -1.f and <code>round(-1.5f)</code> returns -2.f.
+ round() rounds half values away from zero. For example, <code>round(0.5f)</code> returns 1.f
+ and <code>round(1.5f)</code> returns 2.f. Similarly, <code>round(-0.5f)</code> returns -1.f
+ and <code>round(-1.5f)</code> returns -2.f.
@rint() is similar but rounds half values toward even. @trunc() truncates the decimal fraction.
end:
@@ -1995,8 +2006,8 @@
version: 9
w: 1, 2, 3, 4
t: f32
-ret: #2#1, "sine of v"
-arg: #2#1 v, "The incoming value in radians"
+ret: #2#1, "Sine of v."
+arg: #2#1 v, "Incoming value in radians."
arg: #2#1* cos, "*cos will be set to the cosine value."
summary: Sine and cosine
description:
@@ -2061,7 +2072,9 @@
description:
Returns 0.f if v < edge, 1.f otherwise.
- This can be useful to create conditional computations without using loops and branching instructions. For example, instead of computing <code>(a[i] < b[i]) ? 0.f : @atan2(a[i], b[i])</code> for the corresponding elements of a vector, you could instead use <code>step(a, b) * @atan2(a, b)</code>.
+ This can be useful to create conditional computations without using loops and branching
+ instructions. For example, instead of computing <code>(a[i] < b[i]) ? 0.f : @atan2(a[i], b[i])</code>
+ for the corresponding elements of a vector, you could instead use <code>step(a, b) * @atan2(a, b)</code>.
end:
function: step
@@ -2163,9 +2176,9 @@
attrib: const, always_inline
t: i8, i16, i32, u8, u16, u32
ret: #1
-arg: #1 amount, "The value to clamp"
-arg: #1 low, "Lower bound"
-arg: #1 high, "Upper bound"
+arg: #1 amount, "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:
diff --git a/api/rs_matrix.spec b/api/rs_matrix.spec
index 830dbec..d66e9d9 100644
--- a/api/rs_matrix.spec
+++ b/api/rs_matrix.spec
@@ -18,29 +18,29 @@
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
- compatible with OpenGL.
+ They are particularly useful for graphical transformations and are compatible
+ with OpenGL.
- We use a zero-based index for rows and columns. E.g. the last element of
- a @rs_matrix4x4 is found at (3, 3).
+ We use a zero-based index for rows and columns. E.g. the last element of a
+ @rs_matrix4x4 is found at (3, 3).
- RenderScript uses column-major matrices and column-based vectors.
- Transforming a vector is done by postmultiplying the vector,
- e.g. <code>(matrix * vector)</code>, as provided by @rsMatrixMultiply().
+ RenderScript uses column-major matrices and column-based vectors. Transforming
+ a vector is done by postmultiplying the vector, e.g. <code>(matrix * vector)</code>,
+ as provided by @rsMatrixMultiply().
- To create a transformation matrix that performs two transformations at
- once, multiply the two source matrices, with the first transformation as the
- right argument. E.g. to create a transformation matrix that applies the
- transformation s1 followed by s2, call <code>rsMatrixLoadMultiply(&combined, &s2, &s1)</code>.
+ To create a transformation matrix that performs two transformations at once,
+ multiply the two source matrices, with the first transformation as the right
+ argument. E.g. to create a transformation matrix that applies the
+ transformation s1 followed by s2, call <code>rsMatrixLoadMultiply(&combined, &s2, &s1)</code>.
This derives from <code>s2 * (s1 * v)</code>, which is <code>(s2 * s1) * v</code>.
We have two style of functions to create transformation matrices:
- rsMatrixLoad<i>Transformation</i> and rsMatrix<i>Transformation</i>. The
- former style simply stores the transformation matrix in the first argument.
- The latter modifies a pre-existing transformation matrix so that the new
- transformation happens first. E.g. if you call @rsMatrixTranslate()
- on a matrix that already does a scaling, the resulting matrix when applied
- to a vector will first do the translation then the scaling.
+ rsMatrixLoad<i>Transformation</i> and rsMatrix<i>Transformation</i>. The former
+ style simply stores the transformation matrix in the first argument. The latter
+ modifies a pre-existing transformation matrix so that the new transformation
+ happens first. E.g. if you call @rsMatrixTranslate() on a matrix that already
+ does a scaling, the resulting matrix when applied to a vector will first do the
+ translation then the scaling.
include:
#include "rs_vector_math.rsh"
end:
@@ -49,13 +49,13 @@
# TODO Why always_inline?
attrib: always_inline
ret: void
-arg: const rs_matrix4x4* viewProj, "matrix to extract planes from"
-arg: float4* left, "left plane"
-arg: float4* right, "right plane"
-arg: float4* top, "top plane"
-arg: float4* bottom, "bottom plane"
-arg: float4* near, "near plane"
-arg: float4* far, "far plane"
+arg: const rs_matrix4x4* viewProj, "Matrix to extract planes from."
+arg: float4* left, "Left plane."
+arg: float4* right, "Right plane."
+arg: float4* top, "Top plane."
+arg: float4* bottom, "Bottom plane."
+arg: float4* near, "Near plane."
+arg: float4* far, "Far plane."
summary: Compute frustum planes
description:
Computes 6 frustum planes from the view projection matrix
@@ -109,13 +109,13 @@
function: rsIsSphereInFrustum
attrib: always_inline
ret: bool
-arg: float4* sphere, "float4 representing the sphere"
-arg: float4* left, "left plane"
-arg: float4* right, "right plane"
-arg: float4* top, "top plane"
-arg: float4* bottom, "bottom plane"
-arg: float4* near, "near plane"
-arg: float4* far, "far plane"
+arg: float4* sphere, "float4 representing the sphere."
+arg: float4* left, "Left plane."
+arg: float4* right, "Right plane."
+arg: float4* top, "Top plane."
+arg: float4* bottom, "Bottom plane."
+arg: float4* near, "Near plane."
+arg: float4* far, "Far plane."
summary: Checks if a sphere is within the frustum planes
description:
Returns true if the sphere is within the 6 frustum planes.
@@ -151,9 +151,9 @@
function: rsMatrixGet
t: rs_matrix4x4, rs_matrix3x3, rs_matrix2x2
ret: float
-arg: const #1* m, "The matrix to extract the element from."
-arg: uint32_t col, "The zero-based column of the element to be extracted."
-arg: uint32_t row, "The zero-based row of the element to extracted."
+arg: const #1* m, "Matrix to extract the element from."
+arg: uint32_t col, "Zero-based column of the element to be extracted."
+arg: uint32_t row, "Zero-based row of the element to extracted."
summary: Get one element
description:
Returns one element of a matrix.
@@ -164,7 +164,7 @@
function: rsMatrixInverse
ret: bool
-arg: rs_matrix4x4* m, "The matrix to invert."
+arg: rs_matrix4x4* m, "Matrix to invert."
summary: Inverts a matrix in place
description:
Returns true if the matrix was successfully inverted.
@@ -173,19 +173,19 @@
function: rsMatrixInverseTranspose
ret: bool
-arg: rs_matrix4x4* m, "The matrix to modify."
+arg: rs_matrix4x4* m, "Matrix to modify."
summary: Inverts and transpose a matrix in place
description:
- The matrix is first inverted then transposed.
- Returns true if the matrix was successfully inverted.
+ The matrix is first inverted then transposed. Returns true if the matrix was
+ successfully inverted.
test: none
end:
function: rsMatrixLoad
t: rs_matrix4x4, rs_matrix3x3, rs_matrix2x2
ret: void
-arg: #1* destination, "The matrix to set."
-arg: const float* array, "The array of values to set the matrix to. These arrays should be 4, 9, or 16 floats long, depending on the matrix size."
+arg: #1* destination, "Matrix to set."
+arg: const float* array, "Array of values to set the matrix to. These arrays should be 4, 9, or 16 floats long, depending on the matrix size."
summary: Load or copy a matrix
description:
Set the elements of a matrix from an array of floats or from another matrix.
@@ -194,8 +194,8 @@
<code>row 0, column 0</code> should be first, followed by the element at
<code>row 0, column 1</code>, etc.
- If loading from a matrix and the source is smaller than the destination, the rest of the
- destination is filled with elements of the identity matrix. E.g.
+ If loading from a matrix and the source is smaller than the destination, the rest
+ of the destination is filled with elements of the identity matrix. E.g.
loading a rs_matrix2x2 into a rs_matrix4x4 will give:
<table style="max-width:300px">
<tr><td>m00</td> <td>m01</td> <td>0.0</td> <td>0.0</td></tr>
@@ -210,7 +210,7 @@
t: rs_matrix4x4, rs_matrix3x3, rs_matrix2x2
ret: void
arg: #1* destination
-arg: const #1* source, "The source matrix."
+arg: const #1* source, "Source matrix."
test: none
end:
@@ -224,7 +224,7 @@
function: rsMatrixLoadFrustum
ret: void
-arg: rs_matrix4x4* m, "The matrix to set."
+arg: rs_matrix4x4* m, "Matrix to set."
arg: float left
arg: float right
arg: float bottom
@@ -233,19 +233,18 @@
arg: float far
summary: Load a frustum projection matrix
description:
- Constructs a frustum projection matrix, transforming the box
- identified by the six clipping planes <code>left, right, bottom, top,
- near, far</code>.
+ Constructs a frustum projection matrix, transforming the box identified by
+ the six clipping planes <code>left, right, bottom, top, near, far</code>.
- To apply this projection to a vector, multiply the vector by the
- created matrix using @rsMatrixMultiply().
+ To apply this projection to a vector, multiply the vector by the created
+ matrix using @rsMatrixMultiply().
test: none
end:
function: rsMatrixLoadIdentity
t: rs_matrix4x4, rs_matrix3x3, rs_matrix2x2
ret: void
-arg: #1* m, "The matrix to set."
+arg: #1* m, "Matrix to set."
summary: Load identity matrix
description:
Set the elements of a matrix to the identity matrix.
@@ -255,28 +254,27 @@
function: rsMatrixLoadMultiply
t: rs_matrix4x4, rs_matrix3x3, rs_matrix2x2
ret: void
-arg: #1* m, "The matrix to set."
-arg: const #1* lhs, "The left matrix of the product."
-arg: const #1* rhs, "The right matrix of the product."
+arg: #1* m, "Matrix to set."
+arg: const #1* lhs, "Left matrix of the product."
+arg: const #1* rhs, "Right matrix of the product."
summary: Multiply two matrices
description:
Sets m to the matrix product of <code>lhs * rhs</code>.
To combine two 4x4 transformaton matrices, multiply the second transformation matrix
by the first transformation matrix. E.g. to create a transformation matrix that applies
- the transformation s1 followed by s2, call
- <code>rsMatrixLoadMultiply(&combined, &s2, &s1)</code>.
+ the transformation s1 followed by s2, call <code>rsMatrixLoadMultiply(&combined, &s2, &s1)</code>.
<b>Warning:</b> Prior to version 21, storing the result back into right matrix is not supported and
will result in undefined behavior. Use rsMatrixMulitply instead. E.g. instead of doing
- rsMatrixLoadMultiply (&m2r, &m2r, &m2l), use rsMatrixMultiply (&m2r, &m2l).
- rsMatrixLoadMultiply (&m2l, &m2r, &m2l) works as expected.
+ rsMatrixLoadMultiply (&m2r, &m2r, &m2l), use rsMatrixMultiply (&m2r, &m2l).
+ rsMatrixLoadMultiply (&m2l, &m2r, &m2l) works as expected.
test: none
end:
function: rsMatrixLoadOrtho
ret: void
-arg: rs_matrix4x4* m, "The matrix to set."
+arg: rs_matrix4x4* m, "Matrix to set."
arg: float left
arg: float right
arg: float bottom
@@ -285,13 +283,12 @@
arg: float far
summary: Load an orthographic projection matrix
description:
- Constructs an orthographic projection matrix, transforming the box
- identified by the six clipping planes <code>left, right, bottom, top,
- near, far</code> into a unit cube with a corner at
- <code>(-1, -1, -1)</code> and the opposite at <code>(1, 1, 1)</code>.
+ Constructs an orthographic projection matrix, transforming the box identified by the
+ six clipping planes <code>left, right, bottom, top, near, far</code> into a unit cube
+ with a corner at <code>(-1, -1, -1)</code> and the opposite at <code>(1, 1, 1)</code>.
- To apply this projection to a vector, multiply the vector by the
- created matrix using @rsMatrixMultiply().
+ To apply this projection to a vector, multiply the vector by the created matrix
+ using @rsMatrixMultiply().
See https://en.wikipedia.org/wiki/Orthographic_projection .
test: none
@@ -299,34 +296,32 @@
function: rsMatrixLoadPerspective
ret: void
-arg: rs_matrix4x4* m, "The matrix to set."
+arg: rs_matrix4x4* m, "Matrix to set."
arg: float fovy, "Field of view, in degrees along the Y axis."
arg: float aspect, "Ratio of x / y."
-arg: float near, "The near clipping plane."
-arg: float far, "The far clipping plane."
+arg: float near, "Near clipping plane."
+arg: float far, "Far clipping plane."
summary: Load a perspective projection matrix
description:
Constructs a perspective projection matrix, assuming a symmetrical field of view.
- To apply this projection to a vector, multiply the vector by the
- created matrix using @rsMatrixMultiply().
+ To apply this projection to a vector, multiply the vector by the created matrix
+ using @rsMatrixMultiply().
test: none
end:
function: rsMatrixLoadRotate
ret: void
-arg: rs_matrix4x4* m, "The matrix to set."
+arg: rs_matrix4x4* m, "Matrix to set."
arg: float rot, "How much rotation to do, in degrees."
-arg: float x, "The x component of the vector that is the axis of rotation."
-arg: float y, "The y component of the vector that is the axis of rotation."
-arg: float z, "The z component of the vector that is the axis of rotation."
+arg: float x, "X component of the vector that is the axis of rotation."
+arg: float y, "Y component of the vector that is the axis of rotation."
+arg: float z, "Z component of the vector that is the axis of rotation."
summary: Load a rotation matrix
description:
- This function creates a rotation matrix. The axis of rotation is the
- <code>(x, y, z)</code> vector.
+ This function creates a rotation matrix. The axis of rotation is the <code>(x, y, z)</code> vector.
- To rotate a vector, multiply the vector by the created matrix
- using @rsMatrixMultiply().
+ To rotate a vector, multiply the vector by the created matrix using @rsMatrixMultiply().
See http://en.wikipedia.org/wiki/Rotation_matrix .
test: none
@@ -334,41 +329,40 @@
function: rsMatrixLoadScale
ret: void
-arg: rs_matrix4x4* m, "The matrix to set."
-arg: float x, "The multiple to scale the x components by."
-arg: float y, "The multiple to scale the y components by."
-arg: float z, "The multiple to scale the z components by."
+arg: rs_matrix4x4* m, "Matrix to set."
+arg: float x, "Multiple to scale the x components by."
+arg: float y, "Multiple to scale the y components by."
+arg: float z, "Multiple to scale the z components by."
summary: Load a scaling matrix
description:
- This function creates a scaling matrix, where each component of a
- vector is multiplied by a number. This number can be negative.
+ This function creates a scaling matrix, where each component of a vector is multiplied
+ by a number. This number can be negative.
- To scale a vector, multiply the vector by the created matrix
- using @rsMatrixMultiply().
+ To scale a vector, multiply the vector by the created matrix using @rsMatrixMultiply().
test: none
end:
function: rsMatrixLoadTranslate
ret: void
-arg: rs_matrix4x4* m, "The matrix to set."
-arg: float x, "The number to add to each x component."
-arg: float y, "The number to add to each y component."
-arg: float z, "The number to add to each z component."
+arg: rs_matrix4x4* m, "Matrix to set."
+arg: float x, "Number to add to each x component."
+arg: float y, "Number to add to each y component."
+arg: float z, "Number to add to each z component."
summary: Load a translation matrix
description:
- This function creates a translation matrix, where a
- number is added to each element of a vector.
+ This function creates a translation matrix, where a number is added to each element of
+ a vector.
- To translate a vector, multiply the vector by the created matrix
- using @rsMatrixMultiply().
+ To translate a vector, multiply the vector by the created matrix using
+ @rsMatrixMultiply().
test: none
end:
function: rsMatrixMultiply
t: rs_matrix4x4, rs_matrix3x3, rs_matrix2x2
ret: void
-arg: #1* m, "The left matrix of the product and the matrix to be set."
-arg: const #1* rhs, "The right matrix of the product."
+arg: #1* m, "Left matrix of the product and the matrix to be set."
+arg: const #1* rhs, "Right matrix of the product."
summary: Multiply a matrix by a vector or another matrix
description:
For the matrix by matrix variant, sets m to the matrix product <code>m * rhs</code>.
@@ -488,49 +482,48 @@
function: rsMatrixRotate
ret: void
-arg: rs_matrix4x4* m, "The matrix to modify."
+arg: rs_matrix4x4* m, "Matrix to modify."
arg: float rot, "How much rotation to do, in degrees."
-arg: float x, "The x component of the vector that is the axis of rotation."
-arg: float y, "The y component of the vector that is the axis of rotation."
-arg: float z, "The z component of the vector that is the axis of rotation."
+arg: float x, "X component of the vector that is the axis of rotation."
+arg: float y, "Y component of the vector that is the axis of rotation."
+arg: float z, "Z component of the vector that is the axis of rotation."
summary: Apply a rotation to a transformation matrix
description:
Multiply the matrix m with a rotation matrix.
- This function modifies a transformation matrix to first do a rotation.
- The axis of rotation is the <code>(x, y, z)</code> vector.
+ This function modifies a transformation matrix to first do a rotation. The axis of
+ rotation is the <code>(x, y, z)</code> vector.
- To apply this combined transformation to a vector, multiply
- the vector by the created matrix using @rsMatrixMultiply().
+ To apply this combined transformation to a vector, multiply the vector by the created
+ matrix using @rsMatrixMultiply().
test: none
end:
function: rsMatrixScale
ret: void
-arg: rs_matrix4x4* m, "The matrix to modify."
-arg: float x, "The multiple to scale the x components by."
-arg: float y, "The multiple to scale the y components by."
-arg: float z, "The multiple to scale the z components by."
+arg: rs_matrix4x4* m, "Matrix to modify."
+arg: float x, "Multiple to scale the x components by."
+arg: float y, "Multiple to scale the y components by."
+arg: float z, "Multiple to scale the z components by."
summary: Apply a scaling to a transformation matrix
description:
Multiply the matrix m with a scaling matrix.
- This function modifies a transformation matrix to first do a scaling.
- When scaling, each component of a vector is multiplied by a number.
- This number can be negative.
+ This function modifies a transformation matrix to first do a scaling. When scaling,
+ each component of a vector is multiplied by a number. This number can be negative.
- To apply this combined transformation to a vector, multiply
- the vector by the created matrix using @rsMatrixMultiply().
+ To apply this combined transformation to a vector, multiply the vector by the created
+ matrix using @rsMatrixMultiply().
test: none
end:
function: rsMatrixSet
t: rs_matrix4x4, rs_matrix3x3, rs_matrix2x2
ret: void
-arg: #1* m, "The matrix that will be modified."
-arg: uint32_t col, "The zero-based column of the element to be set."
-arg: uint32_t row, "The zero-based row of the element to be set."
-arg: float v, "The value to set."
+arg: #1* m, "Matrix that will be modified."
+arg: uint32_t col, "Zero-based column of the element to be set."
+arg: uint32_t row, "Zero-based row of the element to be set."
+arg: float v, "Value to set."
summary: Set one element
description:
Set an element of a matrix.
@@ -541,27 +534,26 @@
function: rsMatrixTranslate
ret: void
-arg: rs_matrix4x4* m, "The matrix to modify."
-arg: float x, "The number to add to each x component."
-arg: float y, "The number to add to each y component."
-arg: float z, "The number to add to each z component."
+arg: rs_matrix4x4* m, "Matrix to modify."
+arg: float x, "Number to add to each x component."
+arg: float y, "Number to add to each y component."
+arg: float z, "Number to add to each z component."
summary: Apply a translation to a transformation matrix
description:
Multiply the matrix m with a translation matrix.
- This function modifies a transformation matrix to first
- do a translation. When translating, a number is added
- to each component of a vector.
+ This function modifies a transformation matrix to first do a translation. When
+ translating, a number is added to each component of a vector.
- To apply this combined transformation to a vector, multiply
- the vector by the created matrix using @rsMatrixMultiply().
+ To apply this combined transformation to a vector, multiply the vector by the
+ created matrix using @rsMatrixMultiply().
test: none
end:
function: rsMatrixTranspose
t: rs_matrix4x4*, rs_matrix3x3*, rs_matrix2x2*
ret: void
-arg: #1 m, "The matrix to transpose."
+arg: #1 m, "Matrix to transpose."
summary: Transpose a matrix place
description:
Transpose the matrix m in place.
diff --git a/api/rs_object_info.spec b/api/rs_object_info.spec
index fb77875..cf9b56b 100644
--- a/api/rs_object_info.spec
+++ b/api/rs_object_info.spec
@@ -17,26 +17,52 @@
header:
summary: Object Characteristics Functions
description:
- The functions below can be used to query the characteristics of an allocation,
- element, or sampler object. These objects are created from Java.
+ The functions below can be used to query the characteristics of an Allocation, Element,
+ or Sampler object. These objects are created from Java. You can't create them from a
+ script.
- 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>
+ <h5>Allocations:</h5>
+
+ Allocations are the primary method used to pass data to and from RenderScript kernels.
+
+ They are a structured collection of cells that can be used to store bitmaps, textures,
+ arbitrary data points, etc.
+
+ This collection of cells may have many dimensions (X, Y, Z, Array0, Array1, Array2, Array3),
+ faces (for cubemaps), and level of details (for mipmapping).
+
+ See the <a href='http://developer.android.com/reference/android/renderscript/Allocation.html'>android.renderscript.Allocation</a> for details on to create Allocations.
+
+ <h5>Elements:</h5>
+
+ The term "element" is used a bit ambiguously in RenderScript, as both type information
+ for the cells of an Allocation and the instantiation of that type. For example:<ul>
<li>@rs_element is a handle to a type specification, and</li>
- <li>In functions like @rsGetElementAt(), "element" means the instantiation
- of the type, i.e. an item of an allocation.</li></ul>
+ <li>In functions like @rsGetElementAt(), "element" means the instantiation of the type,
+ i.e. a cell of an Allocation.</li></ul>
The functions below let you query the characteristics of the type specificiation.
- To create complex elements, use the <a href='http://developer.android.com/reference/android/renderscript/Element.Builder.html'>Element.Builder</a> Java class.
- For common elements, in Java you can simply use one of the many predefined elements
- like <a href='http://developer.android.com/reference/android/renderscript/Element.html#F32_2(android.renderscript.RenderScript)'>F32_2</a>. You can't create elements from a script.
+ An Element can specify a simple data types as found in C, e.g. an integer, float, or
+ boolean. It can also specify a handle to a RenderScript object. See @rs_data_type for
+ a list of basic types.
- An element can be a simple data type as found in C/C++, a handle type,
- a structure, or a fixed size vector (of size 2, 3, or 4) of sub-elements.
+ Elements can specify fixed size vector (of size 2, 3, or 4) versions of the basic types.
+ Elements can be grouped together into complex Elements, creating the equivalent of
+ C structure definitions.
- Elements can also have a kind, which is semantic information used mostly to
- interpret pixel data.
+ Elements can also have a kind, which is semantic information used to interpret pixel
+ data. See @rs_data_kind.
+
+ When creating Allocations of common elements, you can simply use one of the many predefined
+ Elements like <a href='http://developer.android.com/reference/android/renderscript/Element.html#F32_2(android.renderscript.RenderScript)'>F32_2</a>.
+
+ To create complex Elements, use the <a href='http://developer.android.com/reference/android/renderscript/Element.Builder.html'>Element.Builder</a> Java class.
+
+ <h5>Samplers:</h5>
+
+ Samplers objects define how Allocations can be read as structure within a kernel.
+ See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.S</a>.
end:
function: rsAllocationGetDimFaces
@@ -44,8 +70,8 @@
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
@@ -56,54 +82,55 @@
arg: rs_allocation a
summary: Presence of levels of detail
description:
- Query an allocation for the presence of more than one Level Of Detail.
- This is useful for mipmaps.
+ Query an Allocation for the presence of more than one Level Of Detail. This is useful
+ for mipmaps.
Use @rsGetDimLod() to get the dimension of a currently running kernel.
test: none
end:
function: rsAllocationGetDimX
-ret: uint32_t, "The X dimension of the allocation."
+ret: uint32_t, "X dimension of the Allocation."
arg: rs_allocation a
summary: Size of the X dimension
description:
- Returns the size of the X dimension of the allocation.
+ Returns the size of the X dimension of the Allocation.
Use @rsGetDimX() to get the dimension of a currently running kernel.
test: none
end:
function: rsAllocationGetDimY
-ret: uint32_t, "The Y dimension of the allocation."
+ret: uint32_t, "Y dimension of the Allocation."
arg: rs_allocation a
summary: Size of the Y dimension
description:
- Returns the size of the Y dimension of the allocation.
- If the allocation has less than two dimensions, returns 0.
+ Returns the size of the Y dimension of the Allocation. If the Allocation has less
+ than two dimensions, returns 0.
Use @rsGetDimY() to get the dimension of a currently running kernel.
test: none
end:
function: rsAllocationGetDimZ
-ret: uint32_t, "The Z dimension of the allocation."
+ret: uint32_t, "Z dimension of the Allocation."
arg: rs_allocation a
summary: Size of the Z dimension
description:
- Returns the size of the Z dimension of the allocation.
- If the allocation has less than three dimensions, returns 0.
+ Returns the size of the Z dimension of the Allocation. If the Allocation has less
+ than three dimensions, returns 0.
Use @rsGetDimZ() to get the dimension of a currently running kernel.
test: none
end:
function: rsAllocationGetElement
-ret: rs_element, "element describing allocation layout"
-arg: rs_allocation a, "allocation to get data from"
-summary:
+ret: rs_element, "Element describing Allocation layout."
+arg: rs_allocation a, "Allocation to get data from."
+summary: Get the object that describes the cell of an Allocation
description:
- Get the element object describing the allocation's layout
+ Get the Element object describing the type, kind, and other characteristics of a cell
+ of an Allocation. See the rsElement* functions below.
test: none
end:
@@ -113,12 +140,10 @@
arg: #1* dst
summary: Release an object
description:
- Tells the run time that this handle will no longer be used to access the
- the related object. If this was the last handle to that object, resource
- recovery may happen.
+ 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().
+ After calling this function, *dst will be set to an empty handle. See @rsIsObject().
test: none
end:
@@ -133,9 +158,8 @@
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.
+ 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:
@@ -143,9 +167,9 @@
version: 16
ret: uint32_t
arg: rs_element e
-summary: Return the size of an element
+summary: Size of an Element
description:
- Returns the size in bytes that an instantiation of this element will occupy.
+ Returns the size in bytes that an instantiation of this Element will occupy.
test: none
end:
@@ -153,9 +177,9 @@
version: 16
ret: rs_data_kind
arg: rs_element e
-summary: Return the kind of an element
+summary: Kind of an Element
description:
- Returns the element's data kind. This is used to interpret pixel data.
+ Returns the Element's data kind. This is used to interpret pixel data.
See @rs_data_kind.
test: none
@@ -165,106 +189,110 @@
version: 16
ret: rs_data_type
arg: rs_element e
-summary: Return the data type of an element
+summary: Data type of an Element
description:
- Returns the element's base data type. This can be a type similar to C/C++ (e.g. RS_TYPE_UNSIGNED_8),
- a handle (e.g. RS_TYPE_ALLOCATION and RS_TYPE_ELEMENT), or a more complex numerical type
- (e.g.RS_TYPE_UNSIGNED_5_6_5 and RS_TYPE_MATRIX_4X4).
-
- If the element describes a vector, this function returns the data type of one of its items.
-
- If the element describes a structure, RS_TYPE_NONE is returned.
-
+ Returns the Element's base data type. This can be a type similar to C/C++ (e.g.
+ RS_TYPE_UNSIGNED_8), a handle (e.g. RS_TYPE_ALLOCATION and RS_TYPE_ELEMENT), or a
+ more complex numerical type (e.g. RS_TYPE_UNSIGNED_5_6_5 and RS_TYPE_MATRIX_4X4).
See @rs_data_type.
+
+ If the Element describes a vector, this function returns the data type of one of its items.
+ Use @rsElementGetVectorSize to get the size of the vector.
+
+ If the Element describes a structure, RS_TYPE_NONE is returned. Use the rsElementGetSub*
+ functions to explore this complex Element.
test: none
end:
function: rsElementGetSubElement
version: 16
-ret: rs_element, "Sub-element at the given index"
-arg: rs_element e, "Element to query"
-arg: uint32_t index, "Index of the sub-element to return"
-summary: Return a sub element of a complex element
+ret: rs_element, "Sub-element at the given index."
+arg: rs_element e, "Element to query."
+arg: uint32_t index, "Index of the sub-element to return."
+summary: Sub-element of a complex Element
description:
- For the element represents a structure, this function returns the sub-element at
- the specified index.
+ For Elements that represents a structure, this function returns the sub-element at the
+ specified index.
- If the element is not a structure or the index is greater or equal to the number
- of sub-elements, an invalid handle is returned.
+ If the Element is not a structure or the index is greater or equal to the number of
+ sub-elements, an invalid handle is returned.
test: none
end:
function: rsElementGetSubElementArraySize
version: 16
-ret: uint32_t, "Array size of the sub-element at the given index"
-arg: rs_element e, "Element to query"
-arg: uint32_t index, "Index of the sub-element"
-summary: Return the array size of a sub element of a complex element
+ret: uint32_t, "Array size of the sub-element."
+arg: rs_element e, "Element to query."
+arg: uint32_t index, "Index of the sub-element."
+summary: Array size of a sub-element of a complex Element
description:
- For complex elements, some sub-elements could be statically
- sized arrays. This function returns the array size of the
- sub-element at the index.
+ For complex Elements, sub-elements can be statically sized arrays. This function
+ returns the array size of the sub-element at the index. This sub-element repetition
+ is different than fixed size vectors.
test: none
end:
function: rsElementGetSubElementCount
version: 16
-ret: uint32_t, "Number of sub-elements in this element"
-arg: rs_element e, "Element to get data from"
-summary: Return the number of sub-elements
+ret: uint32_t, "Number of sub-elements."
+arg: rs_element e, "Element to get data from."
+summary: Number of sub-elements
description:
- Elements could be simple, such as an int or a float, or a
- structure with multiple sub-elements, such as a collection of
- floats, float2, float4. This function returns zero for simple
- elements or the number of sub-elements otherwise.
+ Elements can be simple, such as an int or a float, or a structure with multiple
+ sub-elements. This function returns zero for simple Elements and the number of
+ sub-elements for complex Elements.
test: none
end:
function: rsElementGetSubElementName
version: 16
-ret: uint32_t, "Number of characters actually written, excluding the null terminator"
-arg: rs_element e, "Element to get data from"
-arg: uint32_t index, "Index of the sub-element"
-arg: char* name, "Array to store the name into"
-arg: uint32_t nameLength, "Length of the provided name array"
-summary: Return the name of a sub-element
+ret: uint32_t, "Number of characters copied, excluding the null terminator."
+arg: rs_element e, "Element to get data from."
+arg: uint32_t index, "Index of the sub-element."
+arg: char* name, "Address of the array to store the name into."
+arg: uint32_t nameLength, "Length of the provided name array."
+summary: Name of a sub-element
description:
- For complex elements, this function returns the name of the sub-element
- at the specified index.
+ For complex Elements, this function returns the name of the sub-element at the
+ specified index.
test: none
end:
function: rsElementGetSubElementNameLength
version: 16
-ret: uint32_t, "Length of the sub-element name including the null terminator (size of buffer needed to write the name)"
-arg: rs_element e, "Element to get data from"
-arg: uint32_t index, "Index of the sub-element to return"
-summary: Return the length of the name of a sub-element
+ret: uint32_t, "Length of the sub-element name including the null terminator."
+arg: rs_element e, "Element to get data from."
+arg: uint32_t index, "Index of the sub-element."
+summary: Length of the name of a sub-element
description:
- For complex elements, this function will return the length of
- sub-element name at index
+ For complex Elements, this function returns the length of the name of the sub-element
+ at the specified index.
test: none
end:
function: rsElementGetSubElementOffsetBytes
version: 16
-ret: uint32_t, "Offset in bytes of sub-element in this element at given index"
-arg: rs_element e, "Element to get data from"
-arg: uint32_t index, "Index of the sub-element"
-summary:
+ret: uint32_t, "Offset in bytes."
+arg: rs_element e, "Element to get data from."
+arg: uint32_t index, "Index of the sub-element."
+summary: Offset of the instantiated sub-element
description:
- This function specifies the location of a sub-element within
- the element
+ This function returns the relative position of the instantiation of the specified
+ sub-element within the instantiation of the Element.
+
+ For example, if the Element describes a 32 bit float followed by a 32 bit integer,
+ the offset return for the first will be 0 and the second 4.
test: none
end:
function: rsElementGetVectorSize
version: 16
-ret: uint32_t, "Length of the element vector (for float2, float3, etc.)"
-arg: rs_element e, "Element to get data from"
-summary:
+ret: uint32_t, "Length of the element vector."
+arg: rs_element e, "Element to get data from."
+summary: Vector size of the Element
description:
- Returns the element's vector size
+ Returns the Element's vector size. If the Element does not represent a vector,
+ 1 is returned.
test: none
end:
@@ -272,61 +300,70 @@
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
+summary: Return the Allocation for a given pointer
description:
- Returns the Allocation for a given pointer. The pointer should point within
- a valid allocation. The results are undefined if the pointer is not from a
- valid allocation.
+ Returns the Allocation for a given pointer. The pointer should point within a valid
+ allocation. The results are undefined if the pointer is not from a valid Allocation.
test: none
end:
function: rsSamplerGetAnisotropy
version: 16
-ret: float, "anisotropy"
-arg: rs_sampler s, "sampler to query"
-summary:
+ret: float
+arg: rs_sampler s
+summary: Anisotropy of the Sampler
description:
- Get sampler anisotropy
+ Get the Sampler's anisotropy.
+
+ See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.S</a>.
test: none
end:
function: rsSamplerGetMagnification
version: 16
-ret: rs_sampler_value, "magnification value"
-arg: rs_sampler s, "sampler to query"
-summary:
+ret: rs_sampler_value
+arg: rs_sampler s
+summary: Sampler magnification value
description:
- Get sampler magnification value
+ Get the Sampler's magnification value.
+
+ See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.S</a>.
test: none
end:
function: rsSamplerGetMinification
version: 16
-ret: rs_sampler_value, "minification value"
-arg: rs_sampler s, "sampler to query"
-summary:
+ret: rs_sampler_value
+arg: rs_sampler s
+summary: Sampler minification value
description:
- Get sampler minification value
+ Get the Sampler's minification value.
+
+ See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.S</a>.
test: none
end:
function: rsSamplerGetWrapS
version: 16
-ret: rs_sampler_value, "wrap S value"
-arg: rs_sampler s, "sampler to query"
-summary:
+ret: rs_sampler_value
+arg: rs_sampler s
+summary: Sampler wrap S value
description:
- Get sampler wrap S value
+ Get the Sampler's wrap S value.
+
+ See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.S</a>.
test: none
end:
function: rsSamplerGetWrapT
version: 16
-ret: rs_sampler_value, "wrap T value"
-arg: rs_sampler s, "sampler to query"
-summary:
+ret: rs_sampler_value
+arg: rs_sampler s
+summary: Sampler wrap T value
description:
- Get sampler wrap T value
+ Get the sampler's wrap T value.
+
+ See <a href='http://developer.android.com/reference/android/renderscript/Sampler.html'>android.renderscript.S</a>.
test: none
end:
diff --git a/api/rs_object_types.spec b/api/rs_object_types.spec
index e58cd04..092ef99 100644
--- a/api/rs_object_types.spec
+++ b/api/rs_object_types.spec
@@ -17,9 +17,8 @@
header:
summary: Object Types
description:
- 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.
+ 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)
@@ -44,7 +43,7 @@
simple: _RS_HANDLE
summary: Handle to an element
description:
- Opaque handle to a RenderScript element.
+ An opaque handle to a RenderScript element.
See <a href="http://developer.android.com/reference/android/renderscript/Element.html">android.renderscript.Element</a>.
end:
@@ -53,7 +52,7 @@
simple: _RS_HANDLE
summary: Handle to a Type
description:
- Opaque handle to a RenderScript type.
+ An opaque handle to a RenderScript type.
See <a href="http://developer.android.com/reference/android/renderscript/Type.html">android.renderscript.Type</a>.
end:
@@ -62,7 +61,7 @@
simple: _RS_HANDLE
summary: Handle to an allocation
description:
- Opaque handle to a RenderScript allocation.
+ An opaque handle to a RenderScript allocation.
See <a href="http://developer.android.com/reference/android/renderscript/Allocation.html">android.renderscript.Allocation</a>.
end:
@@ -71,7 +70,7 @@
simple: _RS_HANDLE
summary: Handle to a Sampler
description:
- Opaque handle to a RenderScript sampler object.
+ An opaque handle to a RenderScript sampler object.
See <a href="http://developer.android.com/reference/android/renderscript/Sampler.html">android.renderscript.Sampler</a>.
end:
@@ -80,7 +79,7 @@
simple: _RS_HANDLE
summary: Handle to a Script
description:
- Opaque handle to a RenderScript script object.
+ An opaque handle to a RenderScript script object.
See <a href="http://developer.android.com/reference/android/renderscript/ScriptC.html">android.renderscript.ScriptC</a>.
end:
@@ -96,6 +95,7 @@
value: RS_ALLOCATION_CUBEMAP_FACE_NEGATIVE_Z = 5
summary: Enum for selecting cube map faces
description:
+ An enum used to specify one the six faces of a cubemap.
end:
type: rs_allocation_usage_type
@@ -109,7 +109,7 @@
value: RS_ALLOCATION_USAGE_IO_INPUT = 0x0020, "Allocation is used as a Surface consumer."
value: RS_ALLOCATION_USAGE_IO_OUTPUT = 0x0040, "Allocation is used as a Surface producer."
value: RS_ALLOCATION_USAGE_SHARED = 0x0080, "Allocation's backing store is shared with another object (usually a Bitmap). Copying to or from the original source Bitmap will cause a synchronization rather than a full copy."
-summary: Bitfield to specify the usage types for an allocation
+summary: Bitfield to specify how an allocation is used
description:
These values are ORed together to specify which usages or memory spaces are
relevant to an allocation or an operation on an allocation.
@@ -118,72 +118,68 @@
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_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_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_NONE = 0, "Element is a complex type, i.e. a struct."
+value: RS_TYPE_FLOAT_32 = 2, "A 32 bit float point value."
+value: RS_TYPE_FLOAT_64 = 3, "A 64 bit floating point value."
+value: RS_TYPE_SIGNED_8 = 4, "An 8 bit signed integer."
+value: RS_TYPE_SIGNED_16 = 5, "A 16 bit signed integer."
+value: RS_TYPE_SIGNED_32 = 6, "A 32 bit signed integer."
+value: RS_TYPE_SIGNED_64 = 7, "A 64 bit signed integer."
+value: RS_TYPE_UNSIGNED_8 = 8, "An 8 bit unsigned integer."
+value: RS_TYPE_UNSIGNED_16 = 9, "A 16 bit unsigned integer."
+value: RS_TYPE_UNSIGNED_32 = 10, "A 32 bit unsigned integer."
+value: RS_TYPE_UNSIGNED_64 = 11, "A 64 bit unsigned integer."
+value: RS_TYPE_BOOLEAN = 12, "0 or 1 (false or true) stored in an 8 bit container."
+value: RS_TYPE_UNSIGNED_5_6_5 = 13, "A 16 bit unsigned integer packing graphical data in 5, 6, and 5 bit sections."
+value: RS_TYPE_UNSIGNED_5_5_5_1 = 14, "A 16 bit unsigned integer packing graphical data in 5, 5, 5, and 1 bit sections."
+value: RS_TYPE_UNSIGNED_4_4_4_4 = 15, "A 16 bit unsigned integer packing graphical data in 4, 4, 4, and 4 bit sections."
+value: RS_TYPE_MATRIX_4X4 = 16, "A 4x4 matrix of 32 bit floats, aligned on a 32 bit boundary."
+value: RS_TYPE_MATRIX_3X3 = 17, "A 3x3 matrix of 32 bit floats, aligned on a 32 bit boundary."
+value: RS_TYPE_MATRIX_2X2 = 18, "A 2x2 matrix of 32 bit floats, aligned on a 32 bit boundary."
+value: RS_TYPE_ELEMENT = 1000, "A handle to an Element."
+value: RS_TYPE_TYPE = 1001, "A handle to a Type."
+value: RS_TYPE_ALLOCATION = 1002, "A handle to an Allocation."
+value: RS_TYPE_SAMPLER = 1003, "A handle to a Sampler."
+value: RS_TYPE_SCRIPT = 1004, "A handle to a Script."
+value: RS_TYPE_MESH = 1005, "Deprecated."
+value: RS_TYPE_PROGRAM_FRAGMENT = 1006, "Deprecated."
+value: RS_TYPE_PROGRAM_VERTEX = 1007, "Deprecated."
+value: RS_TYPE_PROGRAM_RASTER = 1008, "Deprecated."
+value: RS_TYPE_PROGRAM_STORE = 1009, "Deprecated."
+value: RS_TYPE_FONT = 1010, "Deprecated."
value: RS_TYPE_INVALID = 10000
-summary: Element data types
+summary: Element basic data type
description:
- DataType represents the basic type information for a basic element. The
- naming convention follows. For numeric types it is FLOAT,
- SIGNED, or UNSIGNED followed by the _BITS where BITS is the
- size of the data. BOOLEAN is a true / false (1,0)
- represented in an 8 bit container. The UNSIGNED variants
- with multiple bit definitions are for packed graphical data
- formats and represent vectors with per vector member sizes
- which are treated as a single unit for packing and alignment
- purposes.
+ rs_data_type is used to encode the type information of a basic element.
- MATRIX the three matrix types contain FLOAT_32 elements and are treated
- as 32 bits for alignment purposes.
-
- RS_* objects. 32 bit opaque handles.
+ RS_TYPE_UNSIGNED_5_6_5, RS_TYPE_UNSIGNED_5_5_5_1, RS_TYPE_UNSIGNED_4_4_4_4 are for packed
+ graphical data formats and represent vectors with per vector member sizes which are treated
+ as a single unit for packing and alignment purposes.
end:
type: rs_data_kind
version: 16
enum:
-value: RS_KIND_USER = 0
-value: RS_KIND_PIXEL_L = 7
-value: RS_KIND_PIXEL_A = 8
-value: RS_KIND_PIXEL_LA = 9
-value: RS_KIND_PIXEL_RGB = 10
-value: RS_KIND_PIXEL_RGBA = 11
-value: RS_KIND_PIXEL_DEPTH = 12
-value: RS_KIND_PIXEL_YUV = 13
+value: RS_KIND_USER = 0, "No special interpretation."
+value: RS_KIND_PIXEL_L = 7, "Luminance."
+value: RS_KIND_PIXEL_A = 8, "Alpha."
+value: RS_KIND_PIXEL_LA = 9, "Luminance and Alpha."
+value: RS_KIND_PIXEL_RGB = 10, "Red, Green, Blue."
+value: RS_KIND_PIXEL_RGBA = 11, "Red, Green, Blue, and Alpha."
+value: RS_KIND_PIXEL_DEPTH = 12, "Depth for a depth texture."
+value: RS_KIND_PIXEL_YUV = 13, "Luminance and chrominance."
value: RS_KIND_INVALID = 100
summary: Element data kind
description:
- The special interpretation of the data if required. This is primarly
- useful for graphical data. USER indicates no special interpretation is
- expected. PIXEL is used in conjunction with the standard data types for
- representing texture formats.
+ This enumeration is primarly useful for graphical data. It provides additional information to
+ help interpret the rs_data_type.
+
+ RS_KIND_USER indicates no special interpretation is expected.
+
+ The RS_KIND_PIXEL_* values are used in conjunction with the standard data types for representing
+ texture formats.
+
+ See the <a href='http://developer.android.com/reference/android/renderscript/Element.html#createPixel(android.renderscript.RenderScript,%20android.renderscript.Element.DataType, android.renderscript.Element.DataKind)'>Element.createPixel()</a> method.
end:
type: rs_sampler_value
diff --git a/api/rs_quaternion.spec b/api/rs_quaternion.spec
index 6cb280d..fa37b38 100644
--- a/api/rs_quaternion.spec
+++ b/api/rs_quaternion.spec
@@ -17,6 +17,7 @@
header:
summary: Quaternion Functions
description:
+ The following functions manipulate quaternions.
end:
function: rsQuaternionAdd
@@ -120,7 +121,7 @@
arg: float x, "X component."
arg: float y, "Y component."
arg: float z, "Z component."
-summary: Create a quarternion
+summary: Create a quaternion
description:
Creates a quaternion from its four components or from another quaternion.
inline:
@@ -190,7 +191,7 @@
function: rsQuaternionMultiply
ret: void
arg: rs_quaternion* q, "Destination quaternion."
-arg: float scalar, "Scalar to multiply the quarternion by."
+arg: float scalar, "Scalar to multiply the quaternion by."
summary: Multiply a quaternion by a scalar or another quaternion
description:
Multiplies a quaternion by a scalar or by another quaternion, e.g
@@ -206,7 +207,7 @@
function: rsQuaternionMultiply
ret: void
arg: rs_quaternion* q
-arg: const rs_quaternion* rhs, "Quarternion to multiply the destination quaternion by."
+arg: const rs_quaternion* rhs, "Quaternion to multiply the destination quaternion by."
inline:
rs_quaternion qtmp;
rsQuaternionSet(&qtmp, q);
diff --git a/api/rs_time.spec b/api/rs_time.spec
index 208cced..bd31e09 100644
--- a/api/rs_time.spec
+++ b/api/rs_time.spec
@@ -17,9 +17,8 @@
header:
summary: Time Functions and Types
description:
- 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.
+ The functions below can be used to tell the current clock time and the current
+ system up time. It is not recommended to call these functions inside of a kernel.
end:
type: rs_time_t
@@ -56,8 +55,7 @@
ret: float, "Time in seconds."
summary: Elapsed time since last call
description:
- Returns the time in seconds since this function was last called in this
- script.
+ Returns the time in seconds since this function was last called in this script.
test: none
end:
@@ -67,11 +65,11 @@
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 timer into a @rs_tm structure that provides year, month, hour, etc.
- This value is stored at *local.
+ 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.
+ 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:
@@ -80,8 +78,7 @@
arg: rs_time_t* timer, "Location to also store the returned calendar time."
summary: Seconds since January 1, 1970
description:
- Returns the number of seconds since the Epoch (00:00:00 UTC, January 1,
- 1970).
+ Returns the number of seconds since the Epoch (00:00:00 UTC, January 1, 1970).
If timer is non-NULL, the result is also stored in the memory pointed to by
this variable.
@@ -102,7 +99,6 @@
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.
+ 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 a9ffa1e..a4f303a 100644
--- a/api/rs_value_types.spec
+++ b/api/rs_value_types.spec
@@ -20,22 +20,12 @@
<h5>Scalars:</h5>
RenderScript supports the following scalar numerical types:
-
- 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>
-
- 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>
+ <table>
+ <tr><td> </td> <td>8 bits </td> <td>16 bits </td> <td>32 bits </td> <td>64 bits</td></tr>
+ <tr><td>Integer: </td> <td>char, @int8_t </td> <td>short, @int16_t </td> <td>@int32_t </td> <td>long, long long, @int64_t</td></tr>
+ <tr><td>Unsigned integer:</td> <td>uchar, @uint8_t</td> <td>ushort, @uint16_t</td> <td>uint, @uint32_t</td> <td>ulong, @uint64_t</td></tr>
+ <tr><td>Floating point: </td> <td> </td> <td> </td> <td>float </td> <td>double</td></tr>
+ </table>
<h5>Vectors:</h5>
@@ -59,30 +49,31 @@
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.
+ 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.
+ 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/>
+ 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 = v4.s032; // 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/>
+ v3 = v4.s034; // Invalid: the digit can only be 0, 1, 2, or 3<br/>
</code>
<h5>Matrices and Quaternions:</h5>
@@ -91,7 +82,8 @@
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.
+ 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
@@ -220,24 +212,27 @@
simple: float __attribute__((ext_vector_type(2)))
summary: Two 32 bit floats
description:
- Vector version of the basic float type.
- Provides two float fields packed into a single 64 bit field with 64 bit alignment.
+ A vector of two floats. These two floats are packed into a single 64 bit field
+ with a 64 bit alignment.
+
+ A vector of two floats. These two floats are packed into a single 64 bit field
+ with a 64 bit alignment.
end:
type: float3
simple: float __attribute__((ext_vector_type(3)))
summary: Three 32 bit floats
description:
- Vector version of the basic float type.
- Provides three float fields packed into a single 128 bit field with 128 bit alignment.
+ A vector of three floats. These three floats are packed into a single 128 bit field
+ with a 128 bit alignment.
end:
type: float4
simple: float __attribute__((ext_vector_type(4)))
summary: Four 32 bit floats
description:
- Vector version of the basic float type.
- Provides four float fields packed into a single 128 bit field with 128 bit alignment.
+ A vector of four floats type. These four floats are packed into a single 128 bit field
+ with a 128 bit alignment.
end:
@@ -245,24 +240,24 @@
simple: double __attribute__((ext_vector_type(2)))
summary: Two 64 bit floats
description:
- Vector version of the basic double type. Provides two double fields packed
- into a single 128 bit field with 128 bit alignment.
+ A vector of two doubles. These two double fields packed into a single 128 bit field
+ with a 128 bit alignment.
end:
type: double3
simple: double __attribute__((ext_vector_type(3)))
summary: Three 64 bit floats
description:
- Vector version of the basic double type. Provides three double fields packed
- into a single 256 bit field with 256 bit alignment.
+ A vector of three doubles. These three double fields packed into a single 256 bit field
+ with a 256 bit alignment.
end:
type: double4
simple: double __attribute__((ext_vector_type(4)))
summary: Four 64 bit floats
description:
- Vector version of the basic double type. Provides four double fields packed
- into a single 256 bit field with 256 bit alignment.
+ A vector of four doubles. These four double fields packed into a single 256 bit field
+ with a 256 bit alignment.
end:
@@ -270,24 +265,24 @@
simple: uchar __attribute__((ext_vector_type(2)))
summary: Two 8 bit unsigned integers
description:
- Vector version of the basic uchar type. Provides two uchar fields packed
- into a single 16 bit field with 16 bit alignment.
+ A vector of two uchars. These two uchar fields packed into a single 16 bit field
+ with a 16 bit alignment.
end:
type: uchar3
simple: uchar __attribute__((ext_vector_type(3)))
summary: Three 8 bit unsigned integers
description:
- Vector version of the basic uchar type. Provides three uchar fields packed
- into a single 32 bit field with 32 bit alignment.
+ A vector of three uchars. These three uchar fields packed into a single 32 bit field
+ with a 32 bit alignment.
end:
type: uchar4
simple: uchar __attribute__((ext_vector_type(4)))
summary: Four 8 bit unsigned integers
description:
- Vector version of the basic uchar type. Provides four uchar fields packed
- into a single 32 bit field with 32 bit alignment.
+ A vector of four uchars. These four uchar fields packed into a single 32 bit field
+ with a 32 bit alignment.
end:
@@ -295,24 +290,24 @@
simple: ushort __attribute__((ext_vector_type(2)))
summary: Two 16 bit unsigned integers
description:
- Vector version of the basic ushort type. Provides two ushort fields packed
- into a single 32 bit field with 32 bit alignment.
+ A vector of two ushorts. These two ushort fields packed into a single 32 bit field
+ with a 32 bit alignment.
end:
type: ushort3
simple: ushort __attribute__((ext_vector_type(3)))
summary: Three 16 bit unsigned integers
description:
- Vector version of the basic ushort type. Provides three ushort fields packed
- into a single 64 bit field with 64 bit alignment.
+ A vector of three ushorts. These three ushort fields packed into a single 64 bit field
+ with a 64 bit alignment.
end:
type: ushort4
simple: ushort __attribute__((ext_vector_type(4)))
summary: Four 16 bit unsigned integers
description:
- Vector version of the basic ushort type. Provides four ushort fields packed
- into a single 64 bit field with 64 bit alignment.
+ A vector of four ushorts. These four ushort fields packed into a single 64 bit field
+ with a 64 bit alignment.
end:
@@ -320,24 +315,24 @@
simple: uint __attribute__((ext_vector_type(2)))
summary: Two 32 bit unsigned integers
description:
- Vector version of the basic uint type. Provides two uint fields packed into a
- single 64 bit field with 64 bit alignment.
+ A vector of two uints. These two uints are packed into a single 64 bit field
+ with a 64 bit alignment.
end:
type: uint3
simple: uint __attribute__((ext_vector_type(3)))
summary: Three 32 bit unsigned integers
description:
- Vector version of the basic uint type. Provides three uint fields packed into
- a single 128 bit field with 128 bit alignment.
+ A vector of three uints. These three uints are packed into a single 128 bit field
+ with a 128 bit alignment.
end:
type: uint4
simple: uint __attribute__((ext_vector_type(4)))
summary: Four 32 bit unsigned integers
description:
- Vector version of the basic uint type. Provides four uint fields packed into
- a single 128 bit field with 128 bit alignment.
+ A vector of four uints. These four uints are packed into a single 128 bit field
+ with a 128 bit alignment.
end:
@@ -345,24 +340,24 @@
simple: ulong __attribute__((ext_vector_type(2)))
summary: Two 64 bit unsigned integers
description:
- Vector version of the basic ulong type. Provides two ulong fields packed into
- a single 128 bit field with 128 bit alignment.
+ A vector of two ulongs. These two ulongs are packed into a single 128 bit field
+ with a 128 bit alignment.
end:
type: ulong3
simple: ulong __attribute__((ext_vector_type(3)))
summary: Three 64 bit unsigned integers
description:
- Vector version of the basic ulong type. Provides three ulong fields packed
- into a single 256 bit field with 256 bit alignment.
+ A vector of three ulongs. These three ulong fields packed into a single 256 bit field
+ with a 256 bit alignment.
end:
type: ulong4
simple: ulong __attribute__((ext_vector_type(4)))
summary: Four 64 bit unsigned integers
description:
- Vector version of the basic ulong type. Provides four ulong fields packed
- into a single 256 bit field with 256 bit alignment.
+ A vector of four ulongs. These four ulong fields packed into a single 256 bit field
+ with a 256 bit alignment.
end:
@@ -370,24 +365,24 @@
simple: char __attribute__((ext_vector_type(2)))
summary: Two 8 bit signed integers
description:
- Vector version of the basic char type. Provides two char fields packed into a
- single 16 bit field with 16 bit alignment.
+ A vector of two chars. These two chars are packed into a single 16 bit field
+ with a 16 bit alignment.
end:
type: char3
simple: char __attribute__((ext_vector_type(3)))
summary: Three 8 bit signed integers
description:
- Vector version of the basic char type. Provides three char fields packed into
- a single 32 bit field with 32 bit alignment.
+ A vector of three chars. These three chars are packed into a single 32 bit field
+ with a 32 bit alignment.
end:
type: char4
simple: char __attribute__((ext_vector_type(4)))
summary: Four 8 bit signed integers
description:
- Vector version of the basic char type. Provides four char fields packed into
- a single 32 bit field with 32 bit alignment.
+ A vector of four chars. These four chars are packed into a single 32 bit field
+ with a 32 bit alignment.
end:
@@ -395,24 +390,24 @@
simple: short __attribute__((ext_vector_type(2)))
summary: Two 16 bit signed integers
description:
- Vector version of the basic short type. Provides two short fields packed into
- a single 32 bit field with 32 bit alignment.
+ A vector of two shorts. These two shorts are packed into a single 32 bit field
+ with a 32 bit alignment.
end:
type: short3
simple: short __attribute__((ext_vector_type(3)))
summary: Three 16 bit signed integers
description:
- Vector version of the basic short type. Provides three short fields packed
- into a single 64 bit field with 64 bit alignment.
+ A vector of three shorts. These three short fields packed into a single 64 bit field
+ with a 64 bit alignment.
end:
type: short4
simple: short __attribute__((ext_vector_type(4)))
summary: Four 16 bit signed integers
description:
- Vector version of the basic short type. Provides four short fields packed
- into a single 64 bit field with 64 bit alignment.
+ A vector of four shorts. These four short fields packed into a single 64 bit field
+ with a 64 bit alignment.
end:
@@ -420,24 +415,24 @@
simple: int __attribute__((ext_vector_type(2)))
summary: Two 32 bit signed integers
description:
- Vector version of the basic int type. Provides two int fields packed into a
- single 64 bit field with 64 bit alignment.
+ A vector of two ints. These two ints are packed into a single 64 bit field
+ with a 64 bit alignment.
end:
type: int3
simple: int __attribute__((ext_vector_type(3)))
summary: Three 32 bit signed integers
description:
- Vector version of the basic int type. Provides three int fields packed into a
- single 128 bit field with 128 bit alignment.
+ A vector of three ints. These three ints are packed into a single 128 bit field
+ with a 128 bit alignment.
end:
type: int4
simple: int __attribute__((ext_vector_type(4)))
summary: Four 32 bit signed integers
description:
- Vector version of the basic int type. Provides two four fields packed into a
- single 128 bit field with 128 bit alignment.
+ A vector of four ints. These two fours are packed into a single 128 bit field
+ with a 128 bit alignment.
end:
@@ -445,24 +440,24 @@
simple: long __attribute__((ext_vector_type(2)))
summary: Two 64 bit signed integers
description:
- Vector version of the basic long type. Provides two long fields packed into a
- single 128 bit field with 128 bit alignment.
+ A vector of two longs. These two longs are packed into a single 128 bit field
+ with a 128 bit alignment.
end:
type: long3
simple: long __attribute__((ext_vector_type(3)))
summary: Three 64 bit signed integers
description:
- Vector version of the basic long type. Provides three long fields packed into
- a single 256 bit field with 256 bit alignment.
+ A vector of three longs. These three longs are packed into a single 256 bit field
+ with a 256 bit alignment.
end:
type: long4
simple: long __attribute__((ext_vector_type(4)))
summary: Four 64 bit signed integers
description:
- Vector version of the basic long type. Provides four long fields packed into
- a single 256 bit field with 256 bit alignment.
+ A vector of four longs. These four longs are packed into a single 256 bit field
+ with a 256 bit alignment.
end:
diff --git a/api/rs_vector_math.spec b/api/rs_vector_math.spec
index 176489a..a699d33 100644
--- a/api/rs_vector_math.spec
+++ b/api/rs_vector_math.spec
@@ -17,17 +17,20 @@
header:
summary: Vector Math Functions
description:
- These functions interpret the input arguments as representation of vectors in n-dimensional space.
+ 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
+ The precision of the mathematical operations on 32 bit floats 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.
+ rs_fp_relaxed and rs_fp_full. See <a href='rs_math.html'>Mathematical Constants and Functions</a> for details.
- 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.
+ Different precision/speed tradeoffs can be achieved by using variants of the common math
+ functions. Functions with a name starting with<ul>
+ <li>native_: May have custom hardware implementations with weaker precision. Additionally,
+ subnormal values may be flushed to zero, rounding towards zero may be used, and NaN and
+ infinity input may not be handled correctly.</li>
+ <li>fast_: May perform internal computations using 16 bit floats. Additionally, subnormal
+ values may be flushed to zero, and rounding towards zero may be used.</li>
</ul>
end:
@@ -87,7 +90,8 @@
description:
Computes the approximate distance between two points.
- The precision is what would be expected from doing the computation using 16 bit floating point values.
+ The precision is what would be expected from doing the computation using 16 bit floating
+ point values.
See also @distance(), @native_distance().
test: vector
@@ -104,7 +108,8 @@
description:
Computes the approximate length of a vector.
- The precision is what would be expected from doing the computation using 16 bit floating point values.
+ The precision is what would be expected from doing the computation using 16 bit floating
+ point values.
See also @length(), @native_length().
test: vector
@@ -121,9 +126,11 @@
description:
Approximately normalizes a vector.
- For vectors of size 1, returns -1.f for negative values, 0.f for null values, and 1.f for positive values.
+ For vectors of size 1, returns -1.f for negative values, 0.f for null values, and 1.f for
+ positive values.
- The precision is what would be expected from doing the computation using 16 bit floating point values.
+ The precision is what would be expected from doing the computation using 16 bit floating
+ point values.
See also @normalize(), @native_normalize().
test: vector
@@ -201,7 +208,8 @@
description:
Normalize a vector.
- For vectors of size 1, returns -1.f for negative values, 0.f for null values, and 1.f for positive values.
+ For vectors of size 1, returns -1.f for negative values, 0.f for null values, and 1.f for
+ positive values.
See also @fast_normalize(), @native_normalize().
test: vector
diff --git a/scriptc/rs_allocation_data.rsh b/scriptc/rs_allocation_data.rsh
index 928b649..d8785a2 100644
--- a/scriptc/rs_allocation_data.rsh
+++ b/scriptc/rs_allocation_data.rsh
@@ -113,16 +113,16 @@
* 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.
+ * 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.
+ * 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.
+ * For efficiency, this function does not validate the inputs. Trying to wrap
+ * the X index, exceeding the size of the allocation, or using indices incompatible
+ * with the dimensionality of the allocation yields undefined results.
*
* See also rsAllocationVStoreX().
*
@@ -585,24 +585,23 @@
/*
* 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.
+ * 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.
+ * 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].
+ * 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.
+ * 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.
+ * 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().
*
@@ -1068,14 +1067,13 @@
*
* 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.
+ * 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.
+ * 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);
@@ -2615,13 +2613,13 @@
*
* 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.
+ * 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
+ * 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().
diff --git a/scriptc/rs_atomic.rsh b/scriptc/rs_atomic.rsh
index cc2b8d5..0ab26ca 100644
--- a/scriptc/rs_atomic.rsh
+++ b/scriptc/rs_atomic.rsh
@@ -89,9 +89,9 @@
* by rsAtomicCas() is compareValue.
*
* Parameters:
- * 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.
+ * addr: Address of the value to compare and replace if the test passes.
+ * compareValue: Value to test *addr against.
+ * newValue: Value to write if the test passes.
*
* Returns: Value of *addr prior to the operation.
*/
diff --git a/scriptc/rs_convert.rsh b/scriptc/rs_convert.rsh
index 7abd557..7cf6c50 100644
--- a/scriptc/rs_convert.rsh
+++ b/scriptc/rs_convert.rsh
@@ -19,8 +19,8 @@
/*
* rs_convert.rsh: Conversion Functions
*
- * The functions below convert from a numerical vector type to another,
- * of from one color representation to another.
+ * The functions below convert from a numerical vector type to another, of from one color
+ * representation to another.
*/
#ifndef RENDERSCRIPT_RS_CONVERT_RSH
@@ -29,10 +29,9 @@
/*
* convert: Convert numerical vectors
*
- * Converts a vector from one numerical type to another. The conversion are
- * done entry per entry.
+ * Converts a vector from one numerical type to another. The conversion are done entry per entry.
*
- * E.g calling a = convert_short3(b) is equivalent to doing
+ * 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;.
*
* Converting floating point values to integer types truncates.
@@ -1250,13 +1249,12 @@
/*
* rsPackColorTo8888: Create a uchar4 RGBA from floats
*
- * 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.
+ * 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.
+ * 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.
@@ -1280,8 +1278,7 @@
/*
* 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.
+ * 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);
@@ -1294,9 +1291,9 @@
* We currently don't provide a function to do the reverse conversion.
*
* Parameters:
- * y: Luminance component
- * u: U chrominance component
- * v: V chrominance component
+ * 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 f242890..128c689 100644
--- a/scriptc/rs_core.rsh
+++ b/scriptc/rs_core.rsh
@@ -26,14 +26,12 @@
* to write RenderScript code in C99. The RenderScript compute header files are automatically
* included for you.
*
- * To use RenderScript, you need to utilize the RenderScript runtime APIs documented here
- * as well as the Android framework APIs for RenderScript.
+ * To use RenderScript, you need to utilize the RenderScript runtime APIs documented here as well
+ * as the Android framework APIs for RenderScript. For documentation on the Android framework
+ * APIs, see the android.renderscript package reference.
*
- * For documentation on the Android framework APIs, see the android.renderscript package reference.
- *
- * For more information on how to develop with RenderScript and how the runtime and
- * Android framework APIs interact, see the RenderScript developer guide
- * and the RenderScript samples.
+ * For more information on how to develop with RenderScript and how the runtime and Android
+ * framework APIs interact, see the RenderScript developer guide and the RenderScript samples.
*/
#ifndef RENDERSCRIPT_RS_CORE_RSH
diff --git a/scriptc/rs_for_each.rsh b/scriptc/rs_for_each.rsh
index 758edbe..1bbcf9f 100644
--- a/scriptc/rs_for_each.rsh
+++ b/scriptc/rs_for_each.rsh
@@ -57,8 +57,8 @@
* 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.
+ * 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;
@@ -121,7 +121,7 @@
* 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.
+ * usrDataLen: 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)
extern void __attribute__((overloadable))
@@ -154,15 +154,15 @@
/*
* rsGetArray0: Index in the Array0 dimension for the specified context
*
- * Returns the index in the Array0 dimension of the cell being processed,
- * as specified by the supplied context.
+ * Returns the index in the Array0 dimension of the cell being processed, as specified
+ * by the supplied context.
*
- * This context is created when a kernel is launched and updated at each
- * iteration. It contains common characteristics of the allocations being
- * iterated over and rarely used indexes, like the Array0 index.
+ * This context is created when a kernel is launched and updated at each iteration.
+ * It contains common characteristics of the allocations being iterated over and rarely
+ * used indexes, like the Array0 index.
*
- * You can access the context by adding a rs_kernel_context argument to your
- * kernel function. E.g.
+ * You can access the context by adding a rs_kernel_context argument to your kernel
+ * function. E.g.
* short RS_KERNEL myKernel(short value, uint32_t x, rs_kernel_context context) {
* // The current index in the common x, y, z, w dimensions are accessed by
* // adding these variables as arguments. For the more rarely used indexes
@@ -181,9 +181,8 @@
/*
* rsGetArray1: Index in the Array1 dimension for the specified context
*
- * Returns the index in the Array1 dimension of the cell being processed,
- * as specified by the supplied context. See rsGetArray0() for an explanation
- * of the context.
+ * Returns the index in the Array1 dimension of the cell being processed, as specified
+ * by the supplied context. See rsGetArray0() for an explanation of the context.
*
* Returns 0 if the Array1 dimension is not present.
*/
@@ -209,9 +208,8 @@
/*
* rsGetArray3: Index in the Array3 dimension for the specified context
*
- * Returns the index in the Array3 dimension of the cell being processed,
- * as specified by the supplied context. See rsGetArray0() for an explanation
- * of the context.
+ * Returns the index in the Array3 dimension of the cell being processed, as specified
+ * by the supplied context. See rsGetArray0() for an explanation of the context.
*
* Returns 0 if the Array3 dimension is not present.
*/
@@ -275,9 +273,9 @@
/*
* rsGetDimHasFaces: Presence of more than one face for the specified context
*
- * If the context refers to a cubemap, this function returns true if there's
- * more than one face present. In all other cases, it returns false.
- * See rsGetDimX() for an explanation of the context.
+ * If the context refers to a cubemap, this function returns true if there's more than
+ * one face present. In all other cases, it returns false. See rsGetDimX() for an
+ * explanation of the context.
*
* rsAllocationGetDimFaces() is similar but returns 0 or 1 instead of a bool.
*
@@ -291,8 +289,9 @@
/*
* rsGetDimLod: Number of levels of detail for the specified context
*
- * Returns the number of levels of detail for the specified context.
- * This is useful for mipmaps. See rsGetDimX() for an explanation of the context.
+ * Returns the number of levels of detail for the specified context. This is useful
+ * for mipmaps. See rsGetDimX() for an explanation of the context.
+ *
* Returns 0 if Level of Detail is not used.
*
* rsAllocationGetDimLOD() is similar but returns 0 or 1 instead the actual
@@ -357,8 +356,8 @@
/*
* rsGetFace: Coordinate of the Face for the specified context
*
- * Returns the face on which the cell being processed is found, as specified
- * by the supplied context. See rsGetArray0() for an explanation of the context.
+ * Returns the face on which the cell being processed is found, as specified by the
+ * supplied context. See rsGetArray0() for an explanation of the context.
*
* Returns RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X if the face dimension is not
* present.
@@ -371,9 +370,9 @@
/*
* 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
- * an explanation of the context.
+ * Returns the index in the Levels of Detail dimension of the cell being processed,
+ * as specified by the supplied context. See rsGetArray0() for an explanation of
+ * the context.
*
* Returns 0 if the Levels of Detail dimension is not present.
*/
diff --git a/scriptc/rs_graphics.rsh b/scriptc/rs_graphics.rsh
index c133aad..5439f06 100644
--- a/scriptc/rs_graphics.rsh
+++ b/scriptc/rs_graphics.rsh
@@ -214,12 +214,10 @@
/*
* 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.
+ * 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().
+ * After calling this function, *dst will be set to an empty handle. See rsIsObject().
*/
#ifndef __LP64__
extern void __attribute__((overloadable))
@@ -259,9 +257,8 @@
* 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.
+ * 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))
diff --git a/scriptc/rs_math.rsh b/scriptc/rs_math.rsh
index 0f094f6..7ab6975 100644
--- a/scriptc/rs_math.rsh
+++ b/scriptc/rs_math.rsh
@@ -19,12 +19,10 @@
/*
* rs_math.rsh: Mathematical Constants and Functions
*
- * 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.
+ * The mathematical functions below can be applied to scalars and vectors. When applied
+ * to vectors, the returned value is a vector of the function applied to each entry of the input.
*
* For example:
- *
* float3 a, b;
* // The following call sets
* // a.x to sin(b.x),
@@ -33,17 +31,22 @@
* a = sin(b);
*
*
- * See "Vector math functions" for functions like distance() and length()
- * that 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.
+ * The precision of the mathematical operations on 32 bit floats is affected by the pragmas
+ * rs_fp_relaxed and rs_fp_full. Under rs_fp_relaxed, subnormal values may be flushed to zero and
+ * rounding may be done towards zero. In comparison, rs_fp_full requires correct handling of
+ * subnormal values, i.e. smaller than 1.17549435e-38f. rs_fp_rull also requires round to nearest
+ * with ties to even.
*
- * 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.
+ * Different precision/speed tradeoffs can be achieved by using variants of the common math
+ * functions. Functions with a name starting with
+ * - native_: May have custom hardware implementations with weaker precision. Additionally,
+ * subnormal values may be flushed to zero, rounding towards zero may be used, and NaN and
+ * infinity input may not be handled correctly.
+ * - half_: May perform internal computations using 16 bit floats. Additionally, subnormal
+ * values may be flushed to zero, and rounding towards zero may be used.
*
*/
@@ -338,8 +341,8 @@
* See also native_atan2().
*
* Parameters:
- * numerator: The numerator
- * denominator: The denominator. Can be 0.
+ * numerator: Numerator.
+ * denominator: Denominator. Can be 0.
*/
extern float __attribute__((const, overloadable))
atan2(float numerator, float denominator);
@@ -363,8 +366,8 @@
* See also native_atan2pi().
*
* Parameters:
- * numerator: The numerator
- * denominator: The denominator. Can be 0.
+ * numerator: Numerator.
+ * denominator: Denominator. Can be 0.
*/
extern float __attribute__((const, overloadable))
atan2pi(float numerator, float denominator);
@@ -1125,10 +1128,9 @@
*
* Multiply and add. Returns (multiplicand1 * multiplicand2) + offset.
*
- * This function is similar to mad(). fma() retains full precision of the
- * multiplied result and rounds only after the addition. mad() rounds after the
- * multiplication and the addition. This extra precision is not guaranteed in
- * rs_fp_relaxed mode.
+ * This function is similar to mad(). fma() retains full precision of the multiplied result
+ * and rounds only after the addition. mad() rounds after the multiplication and the addition.
+ * This extra precision is not guaranteed in rs_fp_relaxed mode.
*/
extern float __attribute__((const, overloadable))
fma(float multiplicand1, float multiplicand2, float offset);
@@ -1406,8 +1408,7 @@
*
* For example, ilogb(8.5f) returns 3.
*
- * Because of the difference in mantissa, this number is one less than
- * is returned by frexp().
+ * Because of the difference in mantissa, this number is one less than is returned by frexp().
*
* logb() is similar but returns a float.
*/
@@ -1432,8 +1433,8 @@
* See frexp() for the reverse operation.
*
* Parameters:
- * mantissa: The mantissa
- * exponent: The exponent, a single component or matching vector.
+ * mantissa: Mantissa.
+ * exponent: Exponent, a single component or matching vector.
*/
extern float __attribute__((const, overloadable))
ldexp(float mantissa, int exponent);
@@ -1575,8 +1576,7 @@
*
* For example, logb(8.5f) returns 3.f.
*
- * Because of the difference in mantissa, this number is one less than
- * is returned by frexp().
+ * Because of the difference in mantissa, this number is one less than is returned by frexp().
*
* ilogb() is similar but returns an integer.
*/
@@ -1597,10 +1597,9 @@
*
* Multiply and add. Returns (multiplicand1 * multiplicand2) + offset.
*
- * This function is similar to fma(). fma() retains full precision of the
- * multiplied result and rounds only after the addition. mad() rounds after the
- * multiplication and the addition. In rs_fp_relaxed mode, mad() may not do the
- * rounding after multiplicaiton.
+ * This function is similar to fma(). fma() retains full precision of the multiplied result
+ * and rounds only after the addition. mad() rounds after the multiplication and the addition.
+ * In rs_fp_relaxed mode, mad() may not do the rounding after multiplicaiton.
*/
extern float __attribute__((const, overloadable))
mad(float multiplicand1, float multiplicand2, float offset);
@@ -2453,7 +2452,8 @@
*
* Returns start + ((stop - start) * fraction).
*
- * This can be useful for mixing two values. For example, to create a new color that is 40% color1 and 60% color2, use mix(color1, color2, 0.6f).
+ * This can be useful for mixing two values. For example, to create a new color that is
+ * 40% color1 and 60% color2, use mix(color1, color2, 0.6f).
*/
extern float __attribute__((const, overloadable))
mix(float start, float stop, float fraction);
@@ -2481,13 +2481,14 @@
*
* Returns the integral and fractional components of a number.
*
- * Both components will have the same sign as x. For example, for an input of -3.72f, iret will be set to -3.f and .72f will be returned.
+ * Both components will have the same sign as x. For example, for an input of -3.72f,
+ * iret will be set to -3.f and .72f will be returned.
*
* Parameters:
- * v: Source value
+ * v: Source value.
* integral_part: *integral_part will be set to the integral portion of the number.
*
- * Returns: The floating point portion of the value.
+ * Returns: Floating point portion of the value.
*/
extern float __attribute__((overloadable))
modf(float v, float* integral_part);
@@ -2517,8 +2518,7 @@
*
* Returns the approximate inverse cosine, in radians.
*
- * This function yields undefined results from input values less than -1 or greater
- * than 1.
+ * This function yields undefined results from input values less than -1 or greater than 1.
*
* See also acos().
*/
@@ -2576,8 +2576,7 @@
*
* To get an inverse cosine measured in degrees, use acospi(a) * 180.f.
*
- * This function yields undefined results from input values less than -1 or greater
- * than 1.
+ * This function yields undefined results from input values less than -1 or greater than 1.
*
* See also acospi().
*/
@@ -2606,8 +2605,7 @@
*
* Returns the approximate inverse sine, in radians.
*
- * This function yields undefined results from input values less than -1 or greater
- * than 1.
+ * This function yields undefined results from input values less than -1 or greater than 1.
*
* See also asin().
*/
@@ -2665,8 +2663,7 @@
*
* To get an inverse sine measured in degrees, use asinpi(a) * 180.f.
*
- * This function yields undefined results from input values less than -1 or greater
- * than 1.
+ * This function yields undefined results from input values less than -1 or greater than 1.
*
* See also asinpi().
*/
@@ -2725,8 +2722,8 @@
* See also atan2().
*
* Parameters:
- * numerator: The numerator
- * denominator: The denominator. Can be 0.
+ * numerator: Numerator.
+ * denominator: Denominator. Can be 0.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 21))
extern float __attribute__((const, overloadable))
@@ -2751,15 +2748,16 @@
/*
* native_atan2pi: Approximate inverse tangent of a ratio, divided by pi
*
- * Returns the approximate inverse tangent of (numerator / denominator), in radians, divided by pi.
+ * Returns the approximate inverse tangent of (numerator / denominator),
+ * in radians, divided by pi.
*
* To get an inverse tangent measured in degrees, use atan2pi(n, d) * 180.f.
*
* See also atan2pi().
*
* Parameters:
- * numerator: The numerator
- * denominator: The denominator. Can be 0.
+ * numerator: Numerator.
+ * denominator: Denominator. Can be 0.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 21))
extern float __attribute__((const, overloadable))
@@ -2977,7 +2975,8 @@
*
* Fast approximate exp.
*
- * It is valid for inputs from -86.f to 86.f. The precision is no worse than what would be expected from using 16 bit floating point values.
+ * It is valid for inputs from -86.f to 86.f. The precision is no worse than what would be
+ * expected from using 16 bit floating point values.
*
* See also exp().
*/
@@ -3006,7 +3005,8 @@
*
* Fast approximate exp10.
*
- * It is valid for inputs from -37.f to 37.f. The precision is no worse than what would be expected from using 16 bit floating point values.
+ * It is valid for inputs from -37.f to 37.f. The precision is no worse than what would be
+ * expected from using 16 bit floating point values.
*
* See also exp10().
*/
@@ -3035,7 +3035,8 @@
*
* Fast approximate exp2.
*
- * It is valid for inputs from -125.f to 125.f. The precision is no worse than what would be expected from using 16 bit floating point values.
+ * It is valid for inputs from -125.f to 125.f. The precision is no worse than what would be
+ * expected from using 16 bit floating point values.
*
* See also exp2().
*/
@@ -3374,10 +3375,10 @@
* See also sincos().
*
* Parameters:
- * v: The incoming value in radians.
+ * v: Incoming value in radians.
* cos: *cos will be set to the cosine value.
*
- * Returns: sine
+ * Returns: Sine.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 21))
extern float __attribute__((overloadable))
@@ -3568,9 +3569,8 @@
*
* Returns the next representable floating point number from v towards target.
*
- * In rs_fp_relaxed mode, a denormalized input value may not yield the next
- * denormalized value, as support of denormalized values is optional in
- * relaxed mode.
+ * In rs_fp_relaxed mode, a denormalized input value may not yield the next denormalized
+ * value, as support of denormalized values is optional in relaxed mode.
*/
extern float __attribute__((const, overloadable))
nextafter(float v, float target);
@@ -3589,7 +3589,8 @@
*
* Returns base raised to the power exponent, i.e. base ^ exponent.
*
- * pown() and powr() are similar. pown() takes an integer exponent. powr() assumes the base to be non-negative.
+ * pown() and powr() are similar. pown() takes an integer exponent. powr() assumes the
+ * base to be non-negative.
*/
extern float __attribute__((const, overloadable))
pow(float base, float exponent);
@@ -3608,7 +3609,8 @@
*
* Returns base raised to the power exponent, i.e. base ^ exponent.
*
- * pow() and powr() are similar. The both take a float exponent. powr() also assumes the base to be non-negative.
+ * pow() and powr() are similar. The both take a float exponent. powr() also assumes the
+ * base to be non-negative.
*/
extern float __attribute__((const, overloadable))
pown(float base, int exponent);
@@ -3627,7 +3629,8 @@
*
* Returns base raised to the power exponent, i.e. base ^ exponent. base must be >= 0.
*
- * pow() and pown() are similar. They both make no assumptions about the base. pow() takes a float exponent while pown() take an integer.
+ * pow() and pown() are similar. They both make no assumptions about the base.
+ * pow() takes a float exponent while pown() take an integer.
*
* See also native_powr().
*/
@@ -3663,7 +3666,8 @@
/*
* remainder: Remainder of a division
*
- * Returns the remainder of (numerator / denominator), where the quotient is rounded towards the nearest integer.
+ * Returns the remainder of (numerator / denominator), where the quotient is rounded towards
+ * the nearest integer.
*
* The function fmod() is similar but rounds toward the closest interger.
* For example, fmod(-3.8f, 2.f) returns -1.8f (-3.8f - -1.f * 2.f)
@@ -3688,16 +3692,20 @@
*
* Only the sign and lowest three bits of the quotient are guaranteed to be accurate.
*
- * This function is useful for implementing periodic functions. The low three bits of the quotient gives the quadrant and the remainder the distance within the quadrant. For example, an implementation of sin(x) could call remquo(x, PI / 2.f, &quadrant) to reduce very large value of x to something within a limited range.
+ * This function is useful for implementing periodic functions. The low three bits of the
+ * quotient gives the quadrant and the remainder the distance within the quadrant.
+ * For example, an implementation of sin(x) could call remquo(x, PI / 2.f, &quadrant)
+ * to reduce very large value of x to something within a limited range.
*
- * Example: remquo(-23.5f, 8.f, ") sets the lowest three bits of quot to 3 and the sign negative. It returns 0.5f.
+ * Example: remquo(-23.5f, 8.f, ") sets the lowest three bits of quot to 3
+ * and the sign negative. It returns 0.5f.
*
* Parameters:
- * numerator: The numerator.
- * denominator: The denominator.
+ * numerator: Numerator.
+ * denominator: Denominator.
* quotient: *quotient will be set to the integer quotient.
*
- * Returns: The remainder, precise only for the low three bits.
+ * Returns: Remainder, precise only for the low three bits.
*/
extern float __attribute__((overloadable))
remquo(float numerator, float denominator, int* quotient);
@@ -3716,7 +3724,9 @@
*
* Rounds to the nearest integral value.
*
- * rint() rounds half values to even. For example, rint(0.5f) returns 0.f and rint(1.5f) returns 2.f. Similarly, rint(-0.5f) returns -0.f and rint(-1.5f) returns -2.f.
+ * rint() rounds half values to even. For example, rint(0.5f) returns 0.f and
+ * rint(1.5f) returns 2.f. Similarly, rint(-0.5f) returns -0.f and
+ * rint(-1.5f) returns -2.f.
*
* round() is similar but rounds away from zero. trunc() truncates the decimal fraction.
*/
@@ -3756,7 +3766,9 @@
*
* Round to the nearest integral value.
*
- * round() rounds half values away from zero. For example, round(0.5f) returns 1.f and round(1.5f) returns 2.f. Similarly, round(-0.5f) returns -1.f and round(-1.5f) returns -2.f.
+ * round() rounds half values away from zero. For example, round(0.5f) returns 1.f
+ * and round(1.5f) returns 2.f. Similarly, round(-0.5f) returns -1.f
+ * and round(-1.5f) returns -2.f.
*
* rint() is similar but rounds half values toward even. trunc() truncates the decimal fraction.
*/
@@ -3839,10 +3851,10 @@
* See also native_sincos().
*
* Parameters:
- * v: The incoming value in radians
+ * v: Incoming value in radians.
* cos: *cos will be set to the cosine value.
*
- * Returns: sine of v
+ * Returns: Sine of v.
*/
extern float __attribute__((overloadable))
sincos(float v, float* cos);
@@ -3920,7 +3932,9 @@
*
* Returns 0.f if v < edge, 1.f otherwise.
*
- * This can be useful to create conditional computations without using loops and branching instructions. For example, instead of computing (a[i] < b[i]) ? 0.f : atan2(a[i], b[i]) for the corresponding elements of a vector, you could instead use step(a, b) * atan2(a, b).
+ * This can be useful to create conditional computations without using loops and branching
+ * instructions. For example, instead of computing (a[i] < b[i]) ? 0.f : atan2(a[i], b[i])
+ * for the corresponding elements of a vector, you could instead use step(a, b) * atan2(a, b).
*/
extern float __attribute__((const, overloadable))
step(float edge, float v);
@@ -4065,9 +4079,9 @@
* Clamp a value between low and high.
*
* Parameters:
- * amount: The value to clamp
- * low: Lower bound
- * high: Upper bound
+ * amount: Value to clamp.
+ * low: Lower bound.
+ * high: Upper bound.
*/
extern char __attribute__((const, always_inline, overloadable))
rsClamp(char amount, char low, char high);
diff --git a/scriptc/rs_matrix.rsh b/scriptc/rs_matrix.rsh
index bb7c6e8..aafc864 100644
--- a/scriptc/rs_matrix.rsh
+++ b/scriptc/rs_matrix.rsh
@@ -20,29 +20,29 @@
* 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
- * compatible with OpenGL.
+ * They are particularly useful for graphical transformations and are compatible
+ * with OpenGL.
*
- * We use a zero-based index for rows and columns. E.g. the last element of
- * a rs_matrix4x4 is found at (3, 3).
+ * We use a zero-based index for rows and columns. E.g. the last element of a
+ * rs_matrix4x4 is found at (3, 3).
*
- * RenderScript uses column-major matrices and column-based vectors.
- * Transforming a vector is done by postmultiplying the vector,
- * e.g. (matrix * vector), as provided by rsMatrixMultiply().
+ * RenderScript uses column-major matrices and column-based vectors. Transforming
+ * a vector is done by postmultiplying the vector, e.g. (matrix * vector),
+ * as provided by rsMatrixMultiply().
*
- * To create a transformation matrix that performs two transformations at
- * once, multiply the two source matrices, with the first transformation as the
- * right argument. E.g. to create a transformation matrix that applies the
+ * To create a transformation matrix that performs two transformations at once,
+ * multiply the two source matrices, with the first transformation as the right
+ * argument. E.g. to create a transformation matrix that applies the
* transformation s1 followed by s2, call rsMatrixLoadMultiply(&combined, &s2, &s1).
* This derives from s2 * (s1 * v), which is (s2 * s1) * v.
*
* We have two style of functions to create transformation matrices:
- * rsMatrixLoadTransformation and rsMatrixTransformation. The
- * former style simply stores the transformation matrix in the first argument.
- * The latter modifies a pre-existing transformation matrix so that the new
- * transformation happens first. E.g. if you call rsMatrixTranslate()
- * on a matrix that already does a scaling, the resulting matrix when applied
- * to a vector will first do the translation then the scaling.
+ * rsMatrixLoadTransformation and rsMatrixTransformation. The former
+ * style simply stores the transformation matrix in the first argument. The latter
+ * modifies a pre-existing transformation matrix so that the new transformation
+ * happens first. E.g. if you call rsMatrixTranslate() on a matrix that already
+ * does a scaling, the resulting matrix when applied to a vector will first do the
+ * translation then the scaling.
*/
#ifndef RENDERSCRIPT_RS_MATRIX_RSH
@@ -56,13 +56,13 @@
* Computes 6 frustum planes from the view projection matrix
*
* Parameters:
- * viewProj: matrix to extract planes from
- * left: left plane
- * right: right plane
- * top: top plane
- * bottom: bottom plane
- * near: near plane
- * far: far plane
+ * viewProj: Matrix to extract planes from.
+ * left: Left plane.
+ * right: Right plane.
+ * top: Top plane.
+ * bottom: Bottom plane.
+ * near: Near plane.
+ * far: Far plane.
*/
static inline void __attribute__((always_inline, overloadable))
rsExtractFrustumPlanes(const rs_matrix4x4* viewProj, float4* left, float4* right, float4* top,
@@ -118,13 +118,13 @@
* Returns true if the sphere is within the 6 frustum planes.
*
* Parameters:
- * sphere: float4 representing the sphere
- * left: left plane
- * right: right plane
- * top: top plane
- * bottom: bottom plane
- * near: near plane
- * far: far plane
+ * sphere: float4 representing the sphere.
+ * left: Left plane.
+ * right: Right plane.
+ * top: Top plane.
+ * bottom: Bottom plane.
+ * near: Near plane.
+ * far: Far plane.
*/
static inline bool __attribute__((always_inline, overloadable))
rsIsSphereInFrustum(float4* sphere, float4* left, float4* right, float4* top, float4* bottom,
@@ -164,9 +164,9 @@
* Warning: The order of the column and row parameters may be unexpected.
*
* Parameters:
- * m: The matrix to extract the element from.
- * col: The zero-based column of the element to be extracted.
- * row: The zero-based row of the element to extracted.
+ * m: Matrix to extract the element from.
+ * col: Zero-based column of the element to be extracted.
+ * row: Zero-based row of the element to extracted.
*/
extern float __attribute__((overloadable))
rsMatrixGet(const rs_matrix4x4* m, uint32_t col, uint32_t row);
@@ -183,7 +183,7 @@
* Returns true if the matrix was successfully inverted.
*
* Parameters:
- * m: The matrix to invert.
+ * m: Matrix to invert.
*/
extern bool __attribute__((overloadable))
rsMatrixInverse(rs_matrix4x4* m);
@@ -191,11 +191,11 @@
/*
* rsMatrixInverseTranspose: Inverts and transpose a matrix in place
*
- * The matrix is first inverted then transposed.
- * Returns true if the matrix was successfully inverted.
+ * The matrix is first inverted then transposed. Returns true if the matrix was
+ * successfully inverted.
*
* Parameters:
- * m: The matrix to modify.
+ * m: Matrix to modify.
*/
extern bool __attribute__((overloadable))
rsMatrixInverseTranspose(rs_matrix4x4* m);
@@ -209,8 +209,8 @@
* row 0, column 0 should be first, followed by the element at
* row 0, column 1, etc.
*
- * If loading from a matrix and the source is smaller than the destination, the rest of the
- * destination is filled with elements of the identity matrix. E.g.
+ * If loading from a matrix and the source is smaller than the destination, the rest
+ * of the destination is filled with elements of the identity matrix. E.g.
* loading a rs_matrix2x2 into a rs_matrix4x4 will give:
*
* m00 m01 0.0 0.0
@@ -220,9 +220,9 @@
*
*
* Parameters:
- * destination: The matrix to set.
- * array: The array of values to set the matrix to. These arrays should be 4, 9, or 16 floats long, depending on the matrix size.
- * source: The source matrix.
+ * destination: Matrix to set.
+ * array: Array of values to set the matrix to. These arrays should be 4, 9, or 16 floats long, depending on the matrix size.
+ * source: Source matrix.
*/
extern void __attribute__((overloadable))
rsMatrixLoad(rs_matrix4x4* destination, const float* array);
@@ -251,15 +251,14 @@
/*
* rsMatrixLoadFrustum: Load a frustum projection matrix
*
- * Constructs a frustum projection matrix, transforming the box
- * identified by the six clipping planes left, right, bottom, top,
- * near, far.
+ * Constructs a frustum projection matrix, transforming the box identified by
+ * the six clipping planes left, right, bottom, top, near, far.
*
- * To apply this projection to a vector, multiply the vector by the
- * created matrix using rsMatrixMultiply().
+ * To apply this projection to a vector, multiply the vector by the created
+ * matrix using rsMatrixMultiply().
*
* Parameters:
- * m: The matrix to set.
+ * m: Matrix to set.
*/
extern void __attribute__((overloadable))
rsMatrixLoadFrustum(rs_matrix4x4* m, float left, float right, float bottom, float top,
@@ -271,7 +270,7 @@
* Set the elements of a matrix to the identity matrix.
*
* Parameters:
- * m: The matrix to set.
+ * m: Matrix to set.
*/
extern void __attribute__((overloadable))
rsMatrixLoadIdentity(rs_matrix4x4* m);
@@ -289,8 +288,7 @@
*
* To combine two 4x4 transformaton matrices, multiply the second transformation matrix
* by the first transformation matrix. E.g. to create a transformation matrix that applies
- * the transformation s1 followed by s2, call
- * rsMatrixLoadMultiply(&combined, &s2, &s1).
+ * the transformation s1 followed by s2, call rsMatrixLoadMultiply(&combined, &s2, &s1).
*
* Warning: Prior to version 21, storing the result back into right matrix is not supported and
* will result in undefined behavior. Use rsMatrixMulitply instead. E.g. instead of doing
@@ -298,9 +296,9 @@
* rsMatrixLoadMultiply (&m2l, &m2r, &m2l) works as expected.
*
* Parameters:
- * m: The matrix to set.
- * lhs: The left matrix of the product.
- * rhs: The right matrix of the product.
+ * m: Matrix to set.
+ * lhs: Left matrix of the product.
+ * rhs: Right matrix of the product.
*/
extern void __attribute__((overloadable))
rsMatrixLoadMultiply(rs_matrix4x4* m, const rs_matrix4x4* lhs, const rs_matrix4x4* rhs);
@@ -314,18 +312,17 @@
/*
* rsMatrixLoadOrtho: Load an orthographic projection matrix
*
- * Constructs an orthographic projection matrix, transforming the box
- * identified by the six clipping planes left, right, bottom, top,
- * near, far into a unit cube with a corner at
- * (-1, -1, -1) and the opposite at (1, 1, 1).
+ * Constructs an orthographic projection matrix, transforming the box identified by the
+ * six clipping planes left, right, bottom, top, near, far into a unit cube
+ * with a corner at (-1, -1, -1) and the opposite at (1, 1, 1).
*
- * To apply this projection to a vector, multiply the vector by the
- * created matrix using rsMatrixMultiply().
+ * To apply this projection to a vector, multiply the vector by the created matrix
+ * using rsMatrixMultiply().
*
* See https://en.wikipedia.org/wiki/Orthographic_projection .
*
* Parameters:
- * m: The matrix to set.
+ * m: Matrix to set.
*/
extern void __attribute__((overloadable))
rsMatrixLoadOrtho(rs_matrix4x4* m, float left, float right, float bottom, float top, float near,
@@ -336,15 +333,15 @@
*
* Constructs a perspective projection matrix, assuming a symmetrical field of view.
*
- * To apply this projection to a vector, multiply the vector by the
- * created matrix using rsMatrixMultiply().
+ * To apply this projection to a vector, multiply the vector by the created matrix
+ * using rsMatrixMultiply().
*
* Parameters:
- * m: The matrix to set.
+ * m: Matrix to set.
* fovy: Field of view, in degrees along the Y axis.
* aspect: Ratio of x / y.
- * near: The near clipping plane.
- * far: The far clipping plane.
+ * near: Near clipping plane.
+ * far: Far clipping plane.
*/
extern void __attribute__((overloadable))
rsMatrixLoadPerspective(rs_matrix4x4* m, float fovy, float aspect, float near, float far);
@@ -352,20 +349,18 @@
/*
* rsMatrixLoadRotate: Load a rotation matrix
*
- * This function creates a rotation matrix. The axis of rotation is the
- * (x, y, z) vector.
+ * This function creates a rotation matrix. The axis of rotation is the (x, y, z) vector.
*
- * To rotate a vector, multiply the vector by the created matrix
- * using rsMatrixMultiply().
+ * To rotate a vector, multiply the vector by the created matrix using rsMatrixMultiply().
*
* See http://en.wikipedia.org/wiki/Rotation_matrix .
*
* Parameters:
- * m: The matrix to set.
+ * m: Matrix to set.
* rot: How much rotation to do, in degrees.
- * x: The x component of the vector that is the axis of rotation.
- * y: The y component of the vector that is the axis of rotation.
- * z: The z component of the vector that is the axis of rotation.
+ * x: X component of the vector that is the axis of rotation.
+ * y: Y component of the vector that is the axis of rotation.
+ * z: Z component of the vector that is the axis of rotation.
*/
extern void __attribute__((overloadable))
rsMatrixLoadRotate(rs_matrix4x4* m, float rot, float x, float y, float z);
@@ -373,17 +368,16 @@
/*
* rsMatrixLoadScale: Load a scaling matrix
*
- * This function creates a scaling matrix, where each component of a
- * vector is multiplied by a number. This number can be negative.
+ * This function creates a scaling matrix, where each component of a vector is multiplied
+ * by a number. This number can be negative.
*
- * To scale a vector, multiply the vector by the created matrix
- * using rsMatrixMultiply().
+ * To scale a vector, multiply the vector by the created matrix using rsMatrixMultiply().
*
* Parameters:
- * m: The matrix to set.
- * x: The multiple to scale the x components by.
- * y: The multiple to scale the y components by.
- * z: The multiple to scale the z components by.
+ * m: Matrix to set.
+ * x: Multiple to scale the x components by.
+ * y: Multiple to scale the y components by.
+ * z: Multiple to scale the z components by.
*/
extern void __attribute__((overloadable))
rsMatrixLoadScale(rs_matrix4x4* m, float x, float y, float z);
@@ -391,17 +385,17 @@
/*
* rsMatrixLoadTranslate: Load a translation matrix
*
- * This function creates a translation matrix, where a
- * number is added to each element of a vector.
+ * This function creates a translation matrix, where a number is added to each element of
+ * a vector.
*
- * To translate a vector, multiply the vector by the created matrix
- * using rsMatrixMultiply().
+ * To translate a vector, multiply the vector by the created matrix using
+ * rsMatrixMultiply().
*
* Parameters:
- * m: The matrix to set.
- * x: The number to add to each x component.
- * y: The number to add to each y component.
- * z: The number to add to each z component.
+ * m: Matrix to set.
+ * x: Number to add to each x component.
+ * y: Number to add to each y component.
+ * z: Number to add to each z component.
*/
extern void __attribute__((overloadable))
rsMatrixLoadTranslate(rs_matrix4x4* m, float x, float y, float z);
@@ -427,8 +421,8 @@
* Starting with API 14, this function takes a const matrix as the first argument.
*
* Parameters:
- * m: The left matrix of the product and the matrix to be set.
- * rhs: The right matrix of the product.
+ * m: Left matrix of the product and the matrix to be set.
+ * rhs: Right matrix of the product.
*/
extern void __attribute__((overloadable))
rsMatrixMultiply(rs_matrix4x4* m, const rs_matrix4x4* rhs);
@@ -504,18 +498,18 @@
*
* Multiply the matrix m with a rotation matrix.
*
- * This function modifies a transformation matrix to first do a rotation.
- * The axis of rotation is the (x, y, z) vector.
+ * This function modifies a transformation matrix to first do a rotation. The axis of
+ * rotation is the (x, y, z) vector.
*
- * To apply this combined transformation to a vector, multiply
- * the vector by the created matrix using rsMatrixMultiply().
+ * To apply this combined transformation to a vector, multiply the vector by the created
+ * matrix using rsMatrixMultiply().
*
* Parameters:
- * m: The matrix to modify.
+ * m: Matrix to modify.
* rot: How much rotation to do, in degrees.
- * x: The x component of the vector that is the axis of rotation.
- * y: The y component of the vector that is the axis of rotation.
- * z: The z component of the vector that is the axis of rotation.
+ * x: X component of the vector that is the axis of rotation.
+ * y: Y component of the vector that is the axis of rotation.
+ * z: Z component of the vector that is the axis of rotation.
*/
extern void __attribute__((overloadable))
rsMatrixRotate(rs_matrix4x4* m, float rot, float x, float y, float z);
@@ -525,18 +519,17 @@
*
* Multiply the matrix m with a scaling matrix.
*
- * This function modifies a transformation matrix to first do a scaling.
- * When scaling, each component of a vector is multiplied by a number.
- * This number can be negative.
+ * This function modifies a transformation matrix to first do a scaling. When scaling,
+ * each component of a vector is multiplied by a number. This number can be negative.
*
- * To apply this combined transformation to a vector, multiply
- * the vector by the created matrix using rsMatrixMultiply().
+ * To apply this combined transformation to a vector, multiply the vector by the created
+ * matrix using rsMatrixMultiply().
*
* Parameters:
- * m: The matrix to modify.
- * x: The multiple to scale the x components by.
- * y: The multiple to scale the y components by.
- * z: The multiple to scale the z components by.
+ * m: Matrix to modify.
+ * x: Multiple to scale the x components by.
+ * y: Multiple to scale the y components by.
+ * z: Multiple to scale the z components by.
*/
extern void __attribute__((overloadable))
rsMatrixScale(rs_matrix4x4* m, float x, float y, float z);
@@ -549,10 +542,10 @@
* Warning: The order of the column and row parameters may be unexpected.
*
* Parameters:
- * m: The matrix that will be modified.
- * col: The zero-based column of the element to be set.
- * row: The zero-based row of the element to be set.
- * v: The value to set.
+ * m: Matrix that will be modified.
+ * col: Zero-based column of the element to be set.
+ * row: Zero-based row of the element to be set.
+ * v: Value to set.
*/
extern void __attribute__((overloadable))
rsMatrixSet(rs_matrix4x4* m, uint32_t col, uint32_t row, float v);
@@ -568,18 +561,17 @@
*
* Multiply the matrix m with a translation matrix.
*
- * This function modifies a transformation matrix to first
- * do a translation. When translating, a number is added
- * to each component of a vector.
+ * This function modifies a transformation matrix to first do a translation. When
+ * translating, a number is added to each component of a vector.
*
- * To apply this combined transformation to a vector, multiply
- * the vector by the created matrix using rsMatrixMultiply().
+ * To apply this combined transformation to a vector, multiply the vector by the
+ * created matrix using rsMatrixMultiply().
*
* Parameters:
- * m: The matrix to modify.
- * x: The number to add to each x component.
- * y: The number to add to each y component.
- * z: The number to add to each z component.
+ * m: Matrix to modify.
+ * x: Number to add to each x component.
+ * y: Number to add to each y component.
+ * z: Number to add to each z component.
*/
extern void __attribute__((overloadable))
rsMatrixTranslate(rs_matrix4x4* m, float x, float y, float z);
@@ -590,7 +582,7 @@
* Transpose the matrix m in place.
*
* Parameters:
- * m: The matrix to transpose.
+ * m: Matrix to transpose.
*/
extern void __attribute__((overloadable))
rsMatrixTranspose(rs_matrix4x4* m);
diff --git a/scriptc/rs_object_info.rsh b/scriptc/rs_object_info.rsh
index 6ea7ed6..4305f2a 100644
--- a/scriptc/rs_object_info.rsh
+++ b/scriptc/rs_object_info.rsh
@@ -19,26 +19,52 @@
/*
* 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 functions below can be used to query the characteristics of an Allocation, Element,
+ * or Sampler object. These objects are created from Java. You can't create them from a
+ * script.
*
- * 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:
+ * Allocations:
+ *
+ * Allocations are the primary method used to pass data to and from RenderScript kernels.
+ *
+ * They are a structured collection of cells that can be used to store bitmaps, textures,
+ * arbitrary data points, etc.
+ *
+ * This collection of cells may have many dimensions (X, Y, Z, Array0, Array1, Array2, Array3),
+ * faces (for cubemaps), and level of details (for mipmapping).
+ *
+ * See the android.renderscript.Allocation for details on to create Allocations.
+ *
+ * Elements:
+ *
+ * The term "element" is used a bit ambiguously in RenderScript, as both type information
+ * for the cells of an Allocation and the instantiation of that type. For example:
* - 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.
+ * - In functions like rsGetElementAt(), "element" means the instantiation of the type,
+ * i.e. a cell of an Allocation.
*
* The functions below let you query the characteristics of the type specificiation.
*
- * To create complex elements, use the Element.Builder Java class.
- * For common elements, in Java you can simply use one of the many predefined elements
- * like F32_2. You can't create elements from a script.
+ * An Element can specify a simple data types as found in C, e.g. an integer, float, or
+ * boolean. It can also specify a handle to a RenderScript object. See rs_data_type for
+ * a list of basic types.
*
- * An element can be a simple data type as found in C/C++, a handle type,
- * a structure, or a fixed size vector (of size 2, 3, or 4) of sub-elements.
+ * Elements can specify fixed size vector (of size 2, 3, or 4) versions of the basic types.
+ * Elements can be grouped together into complex Elements, creating the equivalent of
+ * C structure definitions.
*
- * Elements can also have a kind, which is semantic information used mostly to
- * interpret pixel data.
+ * Elements can also have a kind, which is semantic information used to interpret pixel
+ * data. See rs_data_kind.
+ *
+ * When creating Allocations of common elements, you can simply use one of the many predefined
+ * Elements like F32_2.
+ *
+ * To create complex Elements, use the Element.Builder Java class.
+ *
+ * Samplers:
+ *
+ * Samplers objects define how Allocations can be read as structure within a kernel.
+ * See android.renderscript.S.
*/
#ifndef RENDERSCRIPT_RS_OBJECT_INFO_RSH
@@ -47,8 +73,8 @@
/*
* 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.
*
@@ -60,8 +86,8 @@
/*
* rsAllocationGetDimLOD: Presence of levels of detail
*
- * Query an allocation for the presence of more than one Level Of Detail.
- * 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.
*
@@ -73,11 +99,11 @@
/*
* rsAllocationGetDimX: Size of the X dimension
*
- * Returns the size of the X dimension of the allocation.
+ * 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.
+ * Returns: X dimension of the Allocation.
*/
extern uint32_t __attribute__((overloadable))
rsAllocationGetDimX(rs_allocation a);
@@ -85,12 +111,12 @@
/*
* rsAllocationGetDimY: Size of the Y dimension
*
- * Returns the size of the Y dimension of the allocation.
- * If the allocation has less than two dimensions, returns 0.
+ * 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.
+ * Returns: Y dimension of the Allocation.
*/
extern uint32_t __attribute__((overloadable))
rsAllocationGetDimY(rs_allocation a);
@@ -98,23 +124,26 @@
/*
* rsAllocationGetDimZ: Size of the Z dimension
*
- * Returns the size of the Z dimension of the allocation.
- * If the allocation has less than three dimensions, returns 0.
+ * 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.
+ * Returns: Z dimension of the Allocation.
*/
extern uint32_t __attribute__((overloadable))
rsAllocationGetDimZ(rs_allocation a);
/*
- * Get the element object describing the allocation's layout
+ * rsAllocationGetElement: Get the object that describes the cell of an Allocation
+ *
+ * Get the Element object describing the type, kind, and other characteristics of a cell
+ * of an Allocation. See the rsElement* functions below.
*
* Parameters:
- * a: allocation to get data from
+ * a: Allocation to get data from.
*
- * Returns: element describing allocation layout
+ * Returns: Element describing Allocation layout.
*/
extern rs_element __attribute__((overloadable))
rsAllocationGetElement(rs_allocation a);
@@ -122,12 +151,10 @@
/*
* 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.
+ * 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().
+ * After calling this function, *dst will be set to an empty handle. See rsIsObject().
*/
extern void __attribute__((overloadable))
rsClearObject(rs_element* dst);
@@ -152,9 +179,8 @@
* 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.
+ * 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);
@@ -172,9 +198,9 @@
rsIsObject(rs_script v);
/*
- * rsElementGetBytesSize: Return the size of an element
+ * rsElementGetBytesSize: Size of an Element
*
- * Returns the size in bytes that an instantiation of this element will occupy.
+ * Returns the size in bytes that an instantiation of this Element will occupy.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern uint32_t __attribute__((overloadable))
@@ -182,9 +208,9 @@
#endif
/*
- * rsElementGetDataKind: Return the kind of an element
+ * rsElementGetDataKind: Kind of an Element
*
- * Returns the element's data kind. This is used to interpret pixel data.
+ * Returns the Element's data kind. This is used to interpret pixel data.
*
* See rs_data_kind.
*/
@@ -194,17 +220,18 @@
#endif
/*
- * rsElementGetDataType: Return the data type of an element
+ * rsElementGetDataType: Data type of an Element
*
- * Returns the element's base data type. This can be a type similar to C/C++ (e.g. RS_TYPE_UNSIGNED_8),
- * a handle (e.g. RS_TYPE_ALLOCATION and RS_TYPE_ELEMENT), or a more complex numerical type
- * (e.g.RS_TYPE_UNSIGNED_5_6_5 and RS_TYPE_MATRIX_4X4).
- *
- * If the element describes a vector, this function returns the data type of one of its items.
- *
- * If the element describes a structure, RS_TYPE_NONE is returned.
- *
+ * Returns the Element's base data type. This can be a type similar to C/C++ (e.g.
+ * RS_TYPE_UNSIGNED_8), a handle (e.g. RS_TYPE_ALLOCATION and RS_TYPE_ELEMENT), or a
+ * more complex numerical type (e.g. RS_TYPE_UNSIGNED_5_6_5 and RS_TYPE_MATRIX_4X4).
* See rs_data_type.
+ *
+ * If the Element describes a vector, this function returns the data type of one of its items.
+ * Use rsElementGetVectorSize to get the size of the vector.
+ *
+ * If the Element describes a structure, RS_TYPE_NONE is returned. Use the rsElementGetSub*
+ * functions to explore this complex Element.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern rs_data_type __attribute__((overloadable))
@@ -212,19 +239,19 @@
#endif
/*
- * rsElementGetSubElement: Return a sub element of a complex element
+ * rsElementGetSubElement: Sub-element of a complex Element
*
- * For the element represents a structure, this function returns the sub-element at
- * the specified index.
+ * For Elements that represents a structure, this function returns the sub-element at the
+ * specified index.
*
- * If the element is not a structure or the index is greater or equal to the number
- * of sub-elements, an invalid handle is returned.
+ * If the Element is not a structure or the index is greater or equal to the number of
+ * sub-elements, an invalid handle is returned.
*
* Parameters:
- * e: Element to query
- * index: Index of the sub-element to return
+ * e: Element to query.
+ * index: Index of the sub-element to return.
*
- * Returns: Sub-element at the given index
+ * Returns: Sub-element at the given index.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern rs_element __attribute__((overloadable))
@@ -232,17 +259,17 @@
#endif
/*
- * rsElementGetSubElementArraySize: Return the array size of a sub element of a complex element
+ * rsElementGetSubElementArraySize: Array size of a sub-element of a complex Element
*
- * For complex elements, some sub-elements could be statically
- * sized arrays. This function returns the array size of the
- * sub-element at the index.
+ * For complex Elements, sub-elements can be statically sized arrays. This function
+ * returns the array size of the sub-element at the index. This sub-element repetition
+ * is different than fixed size vectors.
*
* Parameters:
- * e: Element to query
- * index: Index of the sub-element
+ * e: Element to query.
+ * index: Index of the sub-element.
*
- * Returns: Array size of the sub-element at the given index
+ * Returns: Array size of the sub-element.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern uint32_t __attribute__((overloadable))
@@ -250,17 +277,16 @@
#endif
/*
- * rsElementGetSubElementCount: Return the number of sub-elements
+ * rsElementGetSubElementCount: Number of sub-elements
*
- * Elements could be simple, such as an int or a float, or a
- * structure with multiple sub-elements, such as a collection of
- * floats, float2, float4. This function returns zero for simple
- * elements or the number of sub-elements otherwise.
+ * Elements can be simple, such as an int or a float, or a structure with multiple
+ * sub-elements. This function returns zero for simple Elements and the number of
+ * sub-elements for complex Elements.
*
* Parameters:
- * e: Element to get data from
+ * e: Element to get data from.
*
- * Returns: Number of sub-elements in this element
+ * Returns: Number of sub-elements.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern uint32_t __attribute__((overloadable))
@@ -268,18 +294,18 @@
#endif
/*
- * rsElementGetSubElementName: Return the name of a sub-element
+ * rsElementGetSubElementName: Name of a sub-element
*
- * For complex elements, this function returns the name of the sub-element
- * at the specified index.
+ * For complex Elements, this function returns the name of the sub-element at the
+ * specified index.
*
* Parameters:
- * e: Element to get data from
- * index: Index of the sub-element
- * name: Array to store the name into
- * nameLength: Length of the provided name array
+ * e: Element to get data from.
+ * index: Index of the sub-element.
+ * name: Address of the array to store the name into.
+ * nameLength: Length of the provided name array.
*
- * Returns: Number of characters actually written, excluding the null terminator
+ * Returns: Number of characters copied, excluding the null terminator.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern uint32_t __attribute__((overloadable))
@@ -287,16 +313,16 @@
#endif
/*
- * rsElementGetSubElementNameLength: Return the length of the name of a sub-element
+ * rsElementGetSubElementNameLength: Length of the name of a sub-element
*
- * For complex elements, this function will return the length of
- * sub-element name at index
+ * For complex Elements, this function returns the length of the name of the sub-element
+ * at the specified index.
*
* Parameters:
- * e: Element to get data from
- * index: Index of the sub-element to return
+ * e: Element to get data from.
+ * index: Index of the sub-element.
*
- * Returns: Length of the sub-element name including the null terminator (size of buffer needed to write the name)
+ * Returns: Length of the sub-element name including the null terminator.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern uint32_t __attribute__((overloadable))
@@ -304,14 +330,19 @@
#endif
/*
- * This function specifies the location of a sub-element within
- * the element
+ * rsElementGetSubElementOffsetBytes: Offset of the instantiated sub-element
+ *
+ * This function returns the relative position of the instantiation of the specified
+ * sub-element within the instantiation of the Element.
+ *
+ * For example, if the Element describes a 32 bit float followed by a 32 bit integer,
+ * the offset return for the first will be 0 and the second 4.
*
* Parameters:
- * e: Element to get data from
- * index: Index of the sub-element
+ * e: Element to get data from.
+ * index: Index of the sub-element.
*
- * Returns: Offset in bytes of sub-element in this element at given index
+ * Returns: Offset in bytes.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern uint32_t __attribute__((overloadable))
@@ -319,12 +350,15 @@
#endif
/*
- * Returns the element's vector size
+ * rsElementGetVectorSize: Vector size of the Element
+ *
+ * Returns the Element's vector size. If the Element does not represent a vector,
+ * 1 is returned.
*
* Parameters:
- * e: Element to get data from
+ * e: Element to get data from.
*
- * Returns: Length of the element vector (for float2, float3, etc.)
+ * Returns: Length of the element vector.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern uint32_t __attribute__((overloadable))
@@ -332,24 +366,22 @@
#endif
/*
- * rsGetAllocation: Returns the Allocation for a given pointer
+ * rsGetAllocation: Return 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.
+ * 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.
*/
extern rs_allocation __attribute__((overloadable))
rsGetAllocation(const void* p);
/*
- * Get sampler anisotropy
+ * rsSamplerGetAnisotropy: Anisotropy of the Sampler
*
- * Parameters:
- * s: sampler to query
+ * Get the Sampler's anisotropy.
*
- * Returns: anisotropy
+ * See android.renderscript.S.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern float __attribute__((overloadable))
@@ -357,12 +389,11 @@
#endif
/*
- * Get sampler magnification value
+ * rsSamplerGetMagnification: Sampler magnification value
*
- * Parameters:
- * s: sampler to query
+ * Get the Sampler's magnification value.
*
- * Returns: magnification value
+ * See android.renderscript.S.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern rs_sampler_value __attribute__((overloadable))
@@ -370,12 +401,11 @@
#endif
/*
- * Get sampler minification value
+ * rsSamplerGetMinification: Sampler minification value
*
- * Parameters:
- * s: sampler to query
+ * Get the Sampler's minification value.
*
- * Returns: minification value
+ * See android.renderscript.S.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern rs_sampler_value __attribute__((overloadable))
@@ -383,12 +413,11 @@
#endif
/*
- * Get sampler wrap S value
+ * rsSamplerGetWrapS: Sampler wrap S value
*
- * Parameters:
- * s: sampler to query
+ * Get the Sampler's wrap S value.
*
- * Returns: wrap S value
+ * See android.renderscript.S.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern rs_sampler_value __attribute__((overloadable))
@@ -396,12 +425,11 @@
#endif
/*
- * Get sampler wrap T value
+ * rsSamplerGetWrapT: Sampler wrap T value
*
- * Parameters:
- * s: sampler to query
+ * Get the sampler's wrap T value.
*
- * Returns: wrap T value
+ * See android.renderscript.S.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
extern rs_sampler_value __attribute__((overloadable))
diff --git a/scriptc/rs_object_types.rsh b/scriptc/rs_object_types.rsh
index 43c89db..9b11b32 100644
--- a/scriptc/rs_object_types.rsh
+++ b/scriptc/rs_object_types.rsh
@@ -19,9 +19,8 @@
/*
* rs_object_types.rsh: Object Types
*
- * 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.
+ * 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
@@ -48,7 +47,7 @@
/*
* rs_element: Handle to an element
*
- * Opaque handle to a RenderScript element.
+ * An opaque handle to a RenderScript element.
*
* See android.renderscript.Element.
*/
@@ -57,7 +56,7 @@
/*
* rs_type: Handle to a Type
*
- * Opaque handle to a RenderScript type.
+ * An opaque handle to a RenderScript type.
*
* See android.renderscript.Type.
*/
@@ -66,7 +65,7 @@
/*
* rs_allocation: Handle to an allocation
*
- * Opaque handle to a RenderScript allocation.
+ * An opaque handle to a RenderScript allocation.
*
* See android.renderscript.Allocation.
*/
@@ -75,7 +74,7 @@
/*
* rs_sampler: Handle to a Sampler
*
- * Opaque handle to a RenderScript sampler object.
+ * An opaque handle to a RenderScript sampler object.
*
* See android.renderscript.Sampler.
*/
@@ -84,7 +83,7 @@
/*
* rs_script: Handle to a Script
*
- * Opaque handle to a RenderScript script object.
+ * An opaque handle to a RenderScript script object.
*
* See android.renderscript.ScriptC.
*/
@@ -93,6 +92,7 @@
/*
* rs_allocation_cubemap_face: Enum for selecting cube map faces
*
+ * An enum used to specify one the six faces of a cubemap.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 14))
typedef enum {
@@ -106,7 +106,7 @@
#endif
/*
- * rs_allocation_usage_type: Bitfield to specify the usage types for an allocation
+ * rs_allocation_usage_type: Bitfield to specify how an allocation is used
*
* These values are ORed together to specify which usages or memory spaces are
* relevant to an allocation or an operation on an allocation.
@@ -125,54 +125,45 @@
#endif
/*
- * rs_data_type: Element data types
+ * rs_data_type: Element basic data type
*
- * DataType represents the basic type information for a basic element. The
- * naming convention follows. For numeric types it is FLOAT,
- * SIGNED, or UNSIGNED followed by the _BITS where BITS is the
- * size of the data. BOOLEAN is a true / false (1,0)
- * represented in an 8 bit container. The UNSIGNED variants
- * with multiple bit definitions are for packed graphical data
- * formats and represent vectors with per vector member sizes
- * which are treated as a single unit for packing and alignment
- * purposes.
+ * rs_data_type is used to encode the type information of a basic element.
*
- * MATRIX the three matrix types contain FLOAT_32 elements and are treated
- * as 32 bits for alignment purposes.
- *
- * RS_* objects. 32 bit opaque handles.
+ * RS_TYPE_UNSIGNED_5_6_5, RS_TYPE_UNSIGNED_5_5_5_1, RS_TYPE_UNSIGNED_4_4_4_4 are for packed
+ * graphical data formats and represent vectors with per vector member sizes which are treated
+ * as a single unit for packing and alignment purposes.
*/
#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_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_PROGRAM_FRAGMENT = 1006,
- RS_TYPE_PROGRAM_VERTEX = 1007,
- RS_TYPE_PROGRAM_RASTER = 1008,
- RS_TYPE_PROGRAM_STORE = 1009,
- RS_TYPE_FONT = 1010,
+ RS_TYPE_NONE = 0, // Element is a complex type, i.e. a struct.
+ RS_TYPE_FLOAT_32 = 2, // A 32 bit float point value.
+ RS_TYPE_FLOAT_64 = 3, // A 64 bit floating point value.
+ RS_TYPE_SIGNED_8 = 4, // An 8 bit signed integer.
+ RS_TYPE_SIGNED_16 = 5, // A 16 bit signed integer.
+ RS_TYPE_SIGNED_32 = 6, // A 32 bit signed integer.
+ RS_TYPE_SIGNED_64 = 7, // A 64 bit signed integer.
+ RS_TYPE_UNSIGNED_8 = 8, // An 8 bit unsigned integer.
+ RS_TYPE_UNSIGNED_16 = 9, // A 16 bit unsigned integer.
+ RS_TYPE_UNSIGNED_32 = 10, // A 32 bit unsigned integer.
+ RS_TYPE_UNSIGNED_64 = 11, // A 64 bit unsigned integer.
+ RS_TYPE_BOOLEAN = 12, // 0 or 1 (false or true) stored in an 8 bit container.
+ RS_TYPE_UNSIGNED_5_6_5 = 13, // A 16 bit unsigned integer packing graphical data in 5, 6, and 5 bit sections.
+ RS_TYPE_UNSIGNED_5_5_5_1 = 14, // A 16 bit unsigned integer packing graphical data in 5, 5, 5, and 1 bit sections.
+ RS_TYPE_UNSIGNED_4_4_4_4 = 15, // A 16 bit unsigned integer packing graphical data in 4, 4, 4, and 4 bit sections.
+ RS_TYPE_MATRIX_4X4 = 16, // A 4x4 matrix of 32 bit floats, aligned on a 32 bit boundary.
+ RS_TYPE_MATRIX_3X3 = 17, // A 3x3 matrix of 32 bit floats, aligned on a 32 bit boundary.
+ RS_TYPE_MATRIX_2X2 = 18, // A 2x2 matrix of 32 bit floats, aligned on a 32 bit boundary.
+ RS_TYPE_ELEMENT = 1000, // A handle to an Element.
+ RS_TYPE_TYPE = 1001, // A handle to a Type.
+ RS_TYPE_ALLOCATION = 1002, // A handle to an Allocation.
+ RS_TYPE_SAMPLER = 1003, // A handle to a Sampler.
+ RS_TYPE_SCRIPT = 1004, // A handle to a Script.
+ RS_TYPE_MESH = 1005, // Deprecated.
+ RS_TYPE_PROGRAM_FRAGMENT = 1006, // Deprecated.
+ RS_TYPE_PROGRAM_VERTEX = 1007, // Deprecated.
+ RS_TYPE_PROGRAM_RASTER = 1008, // Deprecated.
+ RS_TYPE_PROGRAM_STORE = 1009, // Deprecated.
+ RS_TYPE_FONT = 1010, // Deprecated.
RS_TYPE_INVALID = 10000
} rs_data_type;
#endif
@@ -180,21 +171,26 @@
/*
* rs_data_kind: Element data kind
*
- * The special interpretation of the data if required. This is primarly
- * useful for graphical data. USER indicates no special interpretation is
- * expected. PIXEL is used in conjunction with the standard data types for
- * representing texture formats.
+ * This enumeration is primarly useful for graphical data. It provides additional information to
+ * help interpret the rs_data_type.
+ *
+ * RS_KIND_USER indicates no special interpretation is expected.
+ *
+ * The RS_KIND_PIXEL_* values are used in conjunction with the standard data types for representing
+ * texture formats.
+ *
+ * See the Element.createPixel() method.
*/
#if (defined(RS_VERSION) && (RS_VERSION >= 16))
typedef enum {
- RS_KIND_USER = 0,
- RS_KIND_PIXEL_L = 7,
- RS_KIND_PIXEL_A = 8,
- RS_KIND_PIXEL_LA = 9,
- RS_KIND_PIXEL_RGB = 10,
- RS_KIND_PIXEL_RGBA = 11,
- RS_KIND_PIXEL_DEPTH = 12,
- RS_KIND_PIXEL_YUV = 13,
+ RS_KIND_USER = 0, // No special interpretation.
+ RS_KIND_PIXEL_L = 7, // Luminance.
+ RS_KIND_PIXEL_A = 8, // Alpha.
+ RS_KIND_PIXEL_LA = 9, // Luminance and Alpha.
+ RS_KIND_PIXEL_RGB = 10, // Red, Green, Blue.
+ RS_KIND_PIXEL_RGBA = 11, // Red, Green, Blue, and Alpha.
+ RS_KIND_PIXEL_DEPTH = 12, // Depth for a depth texture.
+ RS_KIND_PIXEL_YUV = 13, // Luminance and chrominance.
RS_KIND_INVALID = 100
} rs_data_kind;
#endif
diff --git a/scriptc/rs_quaternion.rsh b/scriptc/rs_quaternion.rsh
index 041bdf5..524eeb0 100644
--- a/scriptc/rs_quaternion.rsh
+++ b/scriptc/rs_quaternion.rsh
@@ -19,6 +19,7 @@
/*
* rs_quaternion.rsh: Quaternion Functions
*
+ * The following functions manipulate quaternions.
*/
#ifndef RENDERSCRIPT_RS_QUATERNION_RSH
@@ -129,7 +130,7 @@
}
/*
- * rsQuaternionSet: Create a quarternion
+ * rsQuaternionSet: Create a quaternion
*
* Creates a quaternion from its four components or from another quaternion.
*
@@ -210,8 +211,8 @@
*
* Parameters:
* q: Destination quaternion.
- * scalar: Scalar to multiply the quarternion by.
- * rhs: Quarternion to multiply the destination quaternion by.
+ * scalar: Scalar to multiply the quaternion by.
+ * rhs: Quaternion to multiply the destination quaternion by.
*/
static inline void __attribute__((overloadable))
rsQuaternionMultiply(rs_quaternion* q, float scalar) {
diff --git a/scriptc/rs_time.rsh b/scriptc/rs_time.rsh
index 8ce120f..05987f8 100644
--- a/scriptc/rs_time.rsh
+++ b/scriptc/rs_time.rsh
@@ -19,9 +19,8 @@
/*
* rs_time.rsh: Time Functions and Types
*
- * 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.
+ * The functions below can be used to tell the current clock time and the current
+ * system up time. It is not recommended to call these functions inside of a kernel.
*/
#ifndef RENDERSCRIPT_RS_TIME_RSH
@@ -61,8 +60,7 @@
/*
* rsGetDt: Elapsed time since last call
*
- * Returns the time in seconds since this function was last called in this
- * script.
+ * Returns the time in seconds since this function was last called in this script.
*
* Returns: Time in seconds.
*/
@@ -72,11 +70,11 @@
/*
* 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.
+ * 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.
+ * 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: Pointer to time structure where the local time will be stored.
@@ -90,8 +88,7 @@
/*
* rsTime: Seconds since January 1, 1970
*
- * Returns the number of seconds since the Epoch (00:00:00 UTC, January 1,
- * 1970).
+ * Returns the number of seconds since the Epoch (00:00:00 UTC, January 1, 1970).
*
* If timer is non-NULL, the result is also stored in the memory pointed to by
* this variable.
@@ -119,8 +116,7 @@
*
* Returns the current system clock (uptime) in nanoseconds.
*
- * The granularity of the values return by this call may be much
- * larger than a nanosecond.
+ * The granularity of the values return by this call may be much larger than a nanosecond.
*
* Returns: Uptime in nanoseconds.
*/
diff --git a/scriptc/rs_value_types.rsh b/scriptc/rs_value_types.rsh
index 13c0500..9dc7259 100644
--- a/scriptc/rs_value_types.rsh
+++ b/scriptc/rs_value_types.rsh
@@ -23,21 +23,11 @@
*
* RenderScript supports the following scalar numerical types:
*
- * Integers:
- * - 8 bit: char, int8_t
- * - 16 bit: short, int16_t
- * - 32 bit: int, int32_t
- * - 64 bit: long, long long, int64_t
+ * 8 bits 16 bits 32 bits 64 bits
+ * Integer: char, int8_t short, int16_t int32_t long, long long, int64_t
+ * Unsigned integer: uchar, uint8_t ushort, uint16_t uint, uint32_t ulong, uint64_t
+ * Floating point: float double
*
- * 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:
*
@@ -61,30 +51,31 @@
* 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.
+ * 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.
+ * 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:
+ * 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 = v4.s032; // 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...
+ * v3 = v4.s034; // Invalid: the digit can only be 0, 1, 2, or 3
*
*
* Matrices and Quaternions:
@@ -93,7 +84,8 @@
* 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.
+ * Quaternions are also supported via rs_quaternion. See Quaterion Functions for the list
+ * of operations.
*/
#ifndef RENDERSCRIPT_RS_VALUE_TYPES_RSH
@@ -224,240 +216,243 @@
/*
* float2: Two 32 bit floats
*
- * Vector version of the basic float type.
- * Provides two float fields packed into a single 64 bit field with 64 bit alignment.
+ * A vector of two floats. These two floats are packed into a single 64 bit field
+ * with a 64 bit alignment.
+ *
+ * A vector of two floats. These two floats are packed into a single 64 bit field
+ * with a 64 bit alignment.
*/
typedef float __attribute__((ext_vector_type(2))) float2;
/*
* float3: Three 32 bit floats
*
- * Vector version of the basic float type.
- * Provides three float fields packed into a single 128 bit field with 128 bit alignment.
+ * A vector of three floats. These three floats are packed into a single 128 bit field
+ * with a 128 bit alignment.
*/
typedef float __attribute__((ext_vector_type(3))) float3;
/*
* float4: Four 32 bit floats
*
- * Vector version of the basic float type.
- * Provides four float fields packed into a single 128 bit field with 128 bit alignment.
+ * A vector of four floats type. These four floats are packed into a single 128 bit field
+ * with a 128 bit alignment.
*/
typedef float __attribute__((ext_vector_type(4))) float4;
/*
* double2: Two 64 bit floats
*
- * Vector version of the basic double type. Provides two double fields packed
- * into a single 128 bit field with 128 bit alignment.
+ * A vector of two doubles. These two double fields packed into a single 128 bit field
+ * with a 128 bit alignment.
*/
typedef double __attribute__((ext_vector_type(2))) double2;
/*
* double3: Three 64 bit floats
*
- * Vector version of the basic double type. Provides three double fields packed
- * into a single 256 bit field with 256 bit alignment.
+ * A vector of three doubles. These three double fields packed into a single 256 bit field
+ * with a 256 bit alignment.
*/
typedef double __attribute__((ext_vector_type(3))) double3;
/*
* double4: Four 64 bit floats
*
- * Vector version of the basic double type. Provides four double fields packed
- * into a single 256 bit field with 256 bit alignment.
+ * A vector of four doubles. These four double fields packed into a single 256 bit field
+ * with a 256 bit alignment.
*/
typedef double __attribute__((ext_vector_type(4))) double4;
/*
* uchar2: Two 8 bit unsigned integers
*
- * Vector version of the basic uchar type. Provides two uchar fields packed
- * into a single 16 bit field with 16 bit alignment.
+ * A vector of two uchars. These two uchar fields packed into a single 16 bit field
+ * with a 16 bit alignment.
*/
typedef uchar __attribute__((ext_vector_type(2))) uchar2;
/*
* uchar3: Three 8 bit unsigned integers
*
- * Vector version of the basic uchar type. Provides three uchar fields packed
- * into a single 32 bit field with 32 bit alignment.
+ * A vector of three uchars. These three uchar fields packed into a single 32 bit field
+ * with a 32 bit alignment.
*/
typedef uchar __attribute__((ext_vector_type(3))) uchar3;
/*
* uchar4: Four 8 bit unsigned integers
*
- * Vector version of the basic uchar type. Provides four uchar fields packed
- * into a single 32 bit field with 32 bit alignment.
+ * A vector of four uchars. These four uchar fields packed into a single 32 bit field
+ * with a 32 bit alignment.
*/
typedef uchar __attribute__((ext_vector_type(4))) uchar4;
/*
* ushort2: Two 16 bit unsigned integers
*
- * Vector version of the basic ushort type. Provides two ushort fields packed
- * into a single 32 bit field with 32 bit alignment.
+ * A vector of two ushorts. These two ushort fields packed into a single 32 bit field
+ * with a 32 bit alignment.
*/
typedef ushort __attribute__((ext_vector_type(2))) ushort2;
/*
* ushort3: Three 16 bit unsigned integers
*
- * Vector version of the basic ushort type. Provides three ushort fields packed
- * into a single 64 bit field with 64 bit alignment.
+ * A vector of three ushorts. These three ushort fields packed into a single 64 bit field
+ * with a 64 bit alignment.
*/
typedef ushort __attribute__((ext_vector_type(3))) ushort3;
/*
* ushort4: Four 16 bit unsigned integers
*
- * Vector version of the basic ushort type. Provides four ushort fields packed
- * into a single 64 bit field with 64 bit alignment.
+ * A vector of four ushorts. These four ushort fields packed into a single 64 bit field
+ * with a 64 bit alignment.
*/
typedef ushort __attribute__((ext_vector_type(4))) ushort4;
/*
* uint2: Two 32 bit unsigned integers
*
- * Vector version of the basic uint type. Provides two uint fields packed into a
- * single 64 bit field with 64 bit alignment.
+ * A vector of two uints. These two uints are packed into a single 64 bit field
+ * with a 64 bit alignment.
*/
typedef uint __attribute__((ext_vector_type(2))) uint2;
/*
* uint3: Three 32 bit unsigned integers
*
- * Vector version of the basic uint type. Provides three uint fields packed into
- * a single 128 bit field with 128 bit alignment.
+ * A vector of three uints. These three uints are packed into a single 128 bit field
+ * with a 128 bit alignment.
*/
typedef uint __attribute__((ext_vector_type(3))) uint3;
/*
* uint4: Four 32 bit unsigned integers
*
- * Vector version of the basic uint type. Provides four uint fields packed into
- * a single 128 bit field with 128 bit alignment.
+ * A vector of four uints. These four uints are packed into a single 128 bit field
+ * with a 128 bit alignment.
*/
typedef uint __attribute__((ext_vector_type(4))) uint4;
/*
* ulong2: Two 64 bit unsigned integers
*
- * Vector version of the basic ulong type. Provides two ulong fields packed into
- * a single 128 bit field with 128 bit alignment.
+ * A vector of two ulongs. These two ulongs are packed into a single 128 bit field
+ * with a 128 bit alignment.
*/
typedef ulong __attribute__((ext_vector_type(2))) ulong2;
/*
* ulong3: Three 64 bit unsigned integers
*
- * Vector version of the basic ulong type. Provides three ulong fields packed
- * into a single 256 bit field with 256 bit alignment.
+ * A vector of three ulongs. These three ulong fields packed into a single 256 bit field
+ * with a 256 bit alignment.
*/
typedef ulong __attribute__((ext_vector_type(3))) ulong3;
/*
* ulong4: Four 64 bit unsigned integers
*
- * Vector version of the basic ulong type. Provides four ulong fields packed
- * into a single 256 bit field with 256 bit alignment.
+ * A vector of four ulongs. These four ulong fields packed into a single 256 bit field
+ * with a 256 bit alignment.
*/
typedef ulong __attribute__((ext_vector_type(4))) ulong4;
/*
* char2: Two 8 bit signed integers
*
- * Vector version of the basic char type. Provides two char fields packed into a
- * single 16 bit field with 16 bit alignment.
+ * A vector of two chars. These two chars are packed into a single 16 bit field
+ * with a 16 bit alignment.
*/
typedef char __attribute__((ext_vector_type(2))) char2;
/*
* char3: Three 8 bit signed integers
*
- * Vector version of the basic char type. Provides three char fields packed into
- * a single 32 bit field with 32 bit alignment.
+ * A vector of three chars. These three chars are packed into a single 32 bit field
+ * with a 32 bit alignment.
*/
typedef char __attribute__((ext_vector_type(3))) char3;
/*
* char4: Four 8 bit signed integers
*
- * Vector version of the basic char type. Provides four char fields packed into
- * a single 32 bit field with 32 bit alignment.
+ * A vector of four chars. These four chars are packed into a single 32 bit field
+ * with a 32 bit alignment.
*/
typedef char __attribute__((ext_vector_type(4))) char4;
/*
* short2: Two 16 bit signed integers
*
- * Vector version of the basic short type. Provides two short fields packed into
- * a single 32 bit field with 32 bit alignment.
+ * A vector of two shorts. These two shorts are packed into a single 32 bit field
+ * with a 32 bit alignment.
*/
typedef short __attribute__((ext_vector_type(2))) short2;
/*
* short3: Three 16 bit signed integers
*
- * Vector version of the basic short type. Provides three short fields packed
- * into a single 64 bit field with 64 bit alignment.
+ * A vector of three shorts. These three short fields packed into a single 64 bit field
+ * with a 64 bit alignment.
*/
typedef short __attribute__((ext_vector_type(3))) short3;
/*
* short4: Four 16 bit signed integers
*
- * Vector version of the basic short type. Provides four short fields packed
- * into a single 64 bit field with 64 bit alignment.
+ * A vector of four shorts. These four short fields packed into a single 64 bit field
+ * with a 64 bit alignment.
*/
typedef short __attribute__((ext_vector_type(4))) short4;
/*
* int2: Two 32 bit signed integers
*
- * Vector version of the basic int type. Provides two int fields packed into a
- * single 64 bit field with 64 bit alignment.
+ * A vector of two ints. These two ints are packed into a single 64 bit field
+ * with a 64 bit alignment.
*/
typedef int __attribute__((ext_vector_type(2))) int2;
/*
* int3: Three 32 bit signed integers
*
- * Vector version of the basic int type. Provides three int fields packed into a
- * single 128 bit field with 128 bit alignment.
+ * A vector of three ints. These three ints are packed into a single 128 bit field
+ * with a 128 bit alignment.
*/
typedef int __attribute__((ext_vector_type(3))) int3;
/*
* int4: Four 32 bit signed integers
*
- * Vector version of the basic int type. Provides two four fields packed into a
- * single 128 bit field with 128 bit alignment.
+ * A vector of four ints. These two fours are packed into a single 128 bit field
+ * with a 128 bit alignment.
*/
typedef int __attribute__((ext_vector_type(4))) int4;
/*
* long2: Two 64 bit signed integers
*
- * Vector version of the basic long type. Provides two long fields packed into a
- * single 128 bit field with 128 bit alignment.
+ * A vector of two longs. These two longs are packed into a single 128 bit field
+ * with a 128 bit alignment.
*/
typedef long __attribute__((ext_vector_type(2))) long2;
/*
* long3: Three 64 bit signed integers
*
- * Vector version of the basic long type. Provides three long fields packed into
- * a single 256 bit field with 256 bit alignment.
+ * A vector of three longs. These three longs are packed into a single 256 bit field
+ * with a 256 bit alignment.
*/
typedef long __attribute__((ext_vector_type(3))) long3;
/*
* long4: Four 64 bit signed integers
*
- * Vector version of the basic long type. Provides four long fields packed into
- * a single 256 bit field with 256 bit alignment.
+ * A vector of four longs. These four longs are packed into a single 256 bit field
+ * with a 256 bit alignment.
*/
typedef long __attribute__((ext_vector_type(4))) long4;
diff --git a/scriptc/rs_vector_math.rsh b/scriptc/rs_vector_math.rsh
index 8ad2cbf..a2757e9 100644
--- a/scriptc/rs_vector_math.rsh
+++ b/scriptc/rs_vector_math.rsh
@@ -19,16 +19,19 @@
/*
* rs_vector_math.rsh: Vector Math Functions
*
- * These functions interpret the input arguments as representation of vectors in n-dimensional space.
+ * 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.
+ * The precision of the mathematical operations on 32 bit floats is affected by the pragmas
+ * rs_fp_relaxed and rs_fp_full. See Mathematical Constants and Functions for details.
*
- * 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.
+ * Different precision/speed tradeoffs can be achieved by using variants of the common math
+ * functions. Functions with a name starting with
+ * - native_: May have custom hardware implementations with weaker precision. Additionally,
+ * subnormal values may be flushed to zero, rounding towards zero may be used, and NaN and
+ * infinity input may not be handled correctly.
+ * - fast_: May perform internal computations using 16 bit floats. Additionally, subnormal
+ * values may be flushed to zero, and rounding towards zero may be used.
*
*/
@@ -87,7 +90,8 @@
*
* Computes the approximate distance between two points.
*
- * The precision is what would be expected from doing the computation using 16 bit floating point values.
+ * The precision is what would be expected from doing the computation using 16 bit floating
+ * point values.
*
* See also distance(), native_distance().
*/
@@ -116,7 +120,8 @@
*
* Computes the approximate length of a vector.
*
- * The precision is what would be expected from doing the computation using 16 bit floating point values.
+ * The precision is what would be expected from doing the computation using 16 bit floating
+ * point values.
*
* See also length(), native_length().
*/
@@ -145,9 +150,11 @@
*
* Approximately normalizes a vector.
*
- * For vectors of size 1, returns -1.f for negative values, 0.f for null values, and 1.f for positive values.
+ * For vectors of size 1, returns -1.f for negative values, 0.f for null values, and 1.f for
+ * positive values.
*
- * The precision is what would be expected from doing the computation using 16 bit floating point values.
+ * The precision is what would be expected from doing the computation using 16 bit floating
+ * point values.
*
* See also normalize(), native_normalize().
*/
@@ -276,7 +283,8 @@
*
* Normalize a vector.
*
- * For vectors of size 1, returns -1.f for negative values, 0.f for null values, and 1.f for positive values.
+ * For vectors of size 1, returns -1.f for negative values, 0.f for null values, and 1.f for
+ * positive values.
*
* See also fast_normalize(), native_normalize().
*/
