Improve the documentation of the RenderScript API.
Only the explanations should be changing.
Change-Id: I889b366e3be44f5ac7f44a199e4b9a47353665e2
diff --git a/api/rs_convert.spec b/api/rs_convert.spec
index 8e38a4a..596e66f 100644
--- a/api/rs_convert.spec
+++ b/api/rs_convert.spec
@@ -1,5 +1,5 @@
#
-# Copyright (C) 2014 The Android Open Source Project
+# Copyright (C) 2015 The Android Open Source Project
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@@ -15,9 +15,10 @@
#
header:
-summary: Conversion functions
+summary: Conversion Functions
description:
- TODO Add desc.
+ The functions below convert from a numerical vector type to another,
+ of from one color representation to another.
end:
function: convert_#3#1
@@ -28,13 +29,17 @@
t: u8, u16, u32, i8, i16, i32, f32
ret: #3#1
arg: #2#1 v, compatible(#3)
-summary: Converts numerical vectors
+summary: Convert numerical vectors
description:
- Component wise conversion from a numerical type to another.
+ Converts a vector from one numerical type to another. The conversion are
+ done entry per entry.
- Conversions of floating point values to integer will truncate.
+ E.g calling <code>a = convert_short3(b)</code> is equivalent to doing
+ <code>a.x = (short)b.x; a.y = (short)b.y; a.z = (short)b.z;</code>.
- Conversions of numbers too large to fit the destination type yield undefined results.
+ Converting floating point values to integer types truncates.
+
+ Converting numbers too large to fit the destination type yields undefined results.
For example, converting a float that contains 1.0e18 to a short is undefined.
Use @clamp() to avoid this.
end:
@@ -72,15 +77,18 @@
function: rsPackColorTo8888
attrib: const
ret: uchar4
-arg: float r
-arg: float g
-arg: float b
-summary:
+arg: float r, "Red component."
+arg: float g, "Green component."
+arg: float b, "Blue component."
+summary: Create a uchar4 RGBA from floats
description:
- Pack floating point (0-1) RGB values into a uchar4.
+ Packs three or four floating point RGBA values into a uchar4. The RGBA values should
+ be between 0.0 and 1.0 inclusive. Values outside of this range are clamped to
+ this range. However numbers greater than INT_MAX or less than INT_MIN can result
+ in undefined behavior.
- For the float3 variant and the variant that only specifies r, g, b,
- the alpha component is set to 255 (1.0).
+ If the alpha component is not specified, it is assumed to be 1.0, i.e. the
+ result will have an alpha set to 255.
test: none
end:
@@ -90,14 +98,14 @@
arg: float r
arg: float g
arg: float b
-arg: float a
+arg: float a, "Alpha component."
test: none
end:
function: rsPackColorTo8888
attrib: const
ret: uchar4
-arg: float3 color
+arg: float3 color, "Vector of 3 or 4 floats containing the R, G, B, and A values."
test: none
end:
@@ -109,12 +117,16 @@
end:
function: rsUnpackColor8888
+# NOTE: The = below indicates that the generator should not add "overloadable" by default.
+# We're doing this to stay backward compatible with the unusual declaration used when this
+# function was introduced.
attrib: =const
ret: float4
arg: uchar4 c
-summary:
+summary: Create a float4 RGBA from uchar4
description:
- Unpack a uchar4 color to float4. The resulting float range will be (0-1).
+ Unpacks a uchar4 color to float4. The resulting floats will be between 0.0 and
+ 1.0 inclusive.
test: none
end:
@@ -123,11 +135,13 @@
w: 4
t: u8, f32
ret: #2#1
-arg: uchar y
-arg: uchar u
-arg: uchar v
-summary:
+arg: uchar y, "Luminance component"
+arg: uchar u, "U chrominance component"
+arg: uchar v, "V chrominance component"
+summary: Convert a YUV value to RGBA
description:
- Convert from YUV to RGBA.
+ Converts a color from a YUV representation to RGBA.
+
+ We currently don't provide a function to do the reverse conversion.
test: none
end:
