Obsolete the graphics API in the .rsh files.

Mark the graphics APIs as no longer available starting with version 23.

Modify the generator to change the #ifdef guards around the API to
enable internal code to still access the obsoleted APIs, as we still
neeed to support them at runtime.

Also, include a documentation change in the rs_convert header file that had not
been included previously.

b/19001259

Change-Id: Iaad4833f504da9aa9f5069a977c37b86d1316d3a
(cherry picked from commit 67923a9e829d89522bb5338a6d635d807a7ee59b)

5 files changed, 121 insertions, 46 deletions

diff --git a/api/GenerateDocumentation.cpp b/api/GenerateDocumentation.cpp
index e5f238aa..bb1e8103 100644
--- a/api/GenerateDocumentation.cpp
+++ b/api/GenerateDocumentation.cpp
@@ -320,7 +320,7 @@ static void writeHtmlVersionTag(GeneratedFile* file, VersionInfo info) {
         if (info.minVersion <= 1) {
             // No minimum
             if (info.maxVersion > 0) {
-                stream << "Removed from " << mid << info.maxVersion + 1;
+                stream << "Removed from " << mid << info.maxVersion + 1 << " and beyond";
             }
         } else {
             if (info.maxVersion == 0) {
diff --git a/api/GenerateHeaderFiles.cpp b/api/GenerateHeaderFiles.cpp
index 97ccab61..45cdba94 100644
--- a/api/GenerateHeaderFiles.cpp
+++ b/api/GenerateHeaderFiles.cpp
@@ -38,27 +38,37 @@ static string makeGuardString(const string& filename) {
     return s;
 }
 
-// Write #ifdef's that ensure that the specified version is present
-static void writeVersionGuardStart(GeneratedFile* file, VersionInfo info) {
+/* Write #ifdef's that ensure that the specified version is present.  If we're at the final version,
+ * add a check on a flag that can be set for internal builds.  This enables us to keep supporting
+ * old APIs in the runtime code.
+ */
+static void writeVersionGuardStart(GeneratedFile* file, VersionInfo info, int finalVersion) {
     if (info.intSize == 32) {
         *file << "#ifndef __LP64__\n";
     } else if (info.intSize == 64) {
         *file << "#ifdef __LP64__\n";
     }
 
+    ostringstream checkMaxVersion;
+    if (info.maxVersion > 0) {
+        checkMaxVersion << "(";
+        if (info.maxVersion == finalVersion) {
+            checkMaxVersion << "defined(RS_DECLARE_EXPIRED_APIS) || ";
+        }
+        checkMaxVersion << "RS_VERSION <= " << info.maxVersion << ")";
+    }
+
     if (info.minVersion <= 1) {
         // No minimum
         if (info.maxVersion > 0) {
-            *file << "#if !defined(RS_VERSION) || (RS_VERSION <= " << info.maxVersion << ")\n";
+            *file << "#if !defined(RS_VERSION) || " << checkMaxVersion.str() << "\n";
         }
     } else {
-        if (info.maxVersion == 0) {
-            // No maximum
-            *file << "#if (defined(RS_VERSION) && (RS_VERSION >= " << info.minVersion << "))\n";
-        } else {
-            *file << "#if (defined(RS_VERSION) && (RS_VERSION >= " << info.minVersion
-                  << ") && (RS_VERSION <= " << info.maxVersion << "))\n";
+        *file << "#if (defined(RS_VERSION) && (RS_VERSION >= " << info.minVersion << ")";
+        if (info.maxVersion > 0) {
+            *file << " && " << checkMaxVersion.str();
         }
+        *file << ")\n";
     }
 }
 
@@ -107,16 +117,18 @@ static void writeConstantComment(GeneratedFile* file, const Constant& constant)
 }
 
 static void writeConstantSpecification(GeneratedFile* file, const ConstantSpecification& spec) {
+    const Constant* constant = spec.getConstant();
     VersionInfo info = spec.getVersionInfo();
-    writeVersionGuardStart(file, info);
-    *file << "#define " << spec.getConstant()->getName() << " " << spec.getValue() << "\n\n";
+    writeVersionGuardStart(file, info, constant->getFinalVersion());
+    *file << "#define " << constant->getName() << " " << spec.getValue() << "\n\n";
     writeVersionGuardEnd(file, info);
 }
 
 static void writeTypeSpecification(GeneratedFile* file, const TypeSpecification& spec) {
-    const string& typeName = spec.getType()->getName();
+    const Type* type = spec.getType();
+    const string& typeName = type->getName();
     const VersionInfo info = spec.getVersionInfo();
-    writeVersionGuardStart(file, info);
+    writeVersionGuardStart(file, info, type->getFinalVersion());
     switch (spec.getKind()) {
         case SIMPLE:
             *file << "typedef " << spec.getSimpleType() << " " << typeName << ";\n";
@@ -182,7 +194,8 @@ static void writeTypeComment(GeneratedFile* file, const Type& type) {
 
 static void writeFunctionPermutation(GeneratedFile* file, const FunctionSpecification& spec,
                                      const FunctionPermutation& permutation) {
-    writeVersionGuardStart(file, spec.getVersionInfo());
+    Function* function = spec.getFunction();
+    writeVersionGuardStart(file, spec.getVersionInfo(), function->getFinalVersion());
 
     // Write linkage info.
     const auto inlineCodeLines = permutation.getInline();
diff --git a/api/Specification.cpp b/api/Specification.cpp
index 09a0663d..6b0d09db 100644
--- a/api/Specification.cpp
+++ b/api/Specification.cpp
@@ -224,7 +224,20 @@ bool VersionInfo::scan(Scanner* scanner, int maxApiLevel) {
     return minVersion == 0 || minVersion <= maxApiLevel;
 }
 
-Definition::Definition(const std::string& name) : mName(name), mDeprecated(false), mHidden(false) {
+Definition::Definition(const std::string& name)
+    : mName(name), mDeprecated(false), mHidden(false), mFinalVersion(-1) {
+}
+
+void Definition::updateFinalVersion(const VersionInfo& info) {
+    /* We set it if:
+     * - We have never set mFinalVersion before, or
+     * - The max version is 0, which means we have not expired this API, or
+     * - We have a max that's later than what we currently have.
+     */
+    if (mFinalVersion < 0 || info.maxVersion == 0 ||
+        (mFinalVersion > 0 && info.maxVersion > mFinalVersion)) {
+        mFinalVersion = info.maxVersion;
+    }
 }
 
 void Definition::scanDocumentationTags(Scanner* scanner, bool firstOccurence,
@@ -323,6 +336,7 @@ void ConstantSpecification::scanConstantSpecification(Scanner* scanner, SpecFile
     Constant* constant = systemSpecification.findOrCreateConstant(name, &created);
     ConstantSpecification* spec = new ConstantSpecification(constant);
     constant->addSpecification(spec);
+    constant->updateFinalVersion(info);
     specFile->addConstantSpecification(spec, created);
     spec->mVersionInfo = info;
 
@@ -348,6 +362,7 @@ void TypeSpecification::scanTypeSpecification(Scanner* scanner, SpecFile* specFi
     Type* type = systemSpecification.findOrCreateType(name, &created);
     TypeSpecification* spec = new TypeSpecification(type);
     type->addSpecification(spec);
+    type->updateFinalVersion(info);
     specFile->addTypeSpecification(spec, created);
     spec->mVersionInfo = info;
 
@@ -529,6 +544,7 @@ void FunctionSpecification::scanFunctionSpecification(Scanner* scanner, SpecFile
     Function* function = systemSpecification.findOrCreateFunction(name, &created);
     FunctionSpecification* spec = new FunctionSpecification(function);
     function->addSpecification(spec);
+    function->updateFinalVersion(info);
     specFile->addFunctionSpecification(spec, created);
 
     spec->mUnexpandedName = unexpandedName;
diff --git a/api/Specification.h b/api/Specification.h
index e808e600..97833106 100644
--- a/api/Specification.h
+++ b/api/Specification.h
@@ -147,6 +147,7 @@ protected:
     std::string mSummary;                   // A one-line description
     std::vector<std::string> mDescription;  // The comments to be included in the header
     std::string mUrl;                       // The URL of the detailed documentation
+    int mFinalVersion;  // API level at which this API was removed, 0 if API is still valid
 
 public:
     Definition(const std::string& name);
@@ -158,8 +159,11 @@ public:
     std::string getSummary() const { return mSummary; }
     const std::vector<std::string>& getDescription() const { return mDescription; }
     std::string getUrl() const { return mUrl; }
+    int getFinalVersion() const { return mFinalVersion; }
 
     void scanDocumentationTags(Scanner* scanner, bool firstOccurence, const SpecFile* specFile);
+    // Keep track of the final version of this API, if any.
+    void updateFinalVersion(const VersionInfo& info);
 };
 
 /* Represents a constant, like M_PI.  This is a grouping of the version specific specifications.
@@ -368,7 +372,7 @@ public:
     FunctionSpecification(Function* function) : mFunction(function), mReturn(nullptr) {}
     ~FunctionSpecification();
 
-    Function* getFunction() { return mFunction; }
+    Function* getFunction() const { return mFunction; }
     std::string getAttribute() const { return mAttribute; }
     std::string getTest() const { return mTest; }
     std::string getPrecisionLimit() const { return mPrecisionLimit; }
diff --git a/api/rs_graphics.spec b/api/rs_graphics.spec
index 4f9d9712..a932a53d 100644
--- a/api/rs_graphics.spec
+++ b/api/rs_graphics.spec
@@ -17,7 +17,7 @@
 header:
 summary: Graphics Functions and Types
 description:
- The graphics subsystem of RenderScript has been deprecated.
+ The graphics subsystem of RenderScript was removed at API level 23.
 include:
  #ifdef __LP64__
  // TODO We need to fix some of the builds before enabling this error:
@@ -29,7 +29,7 @@ include:
 end:
 
 type: rs_blend_src_func
-version: 16
+version: 16 22
 size: 32
 enum:
 value: RS_BLEND_SRC_ZERO = 0
@@ -48,7 +48,7 @@ description:
 end:
 
 type: rs_blend_dst_func
-version: 16
+version: 16 22
 size: 32
 enum:
 value: RS_BLEND_DST_ZERO = 0
@@ -66,7 +66,7 @@ description:
 end:
 
 type: rs_cull_mode
-version: 16
+version: 16 22
 size: 32
 enum:
 value: RS_CULL_BACK = 0
@@ -79,7 +79,7 @@ description:
 end:
 
 type: rs_depth_func
-version: 16
+version: 16 22
 size: 32
 enum:
 value: RS_DEPTH_FUNC_ALWAYS = 0, "Always drawn"
@@ -98,7 +98,7 @@ description:
 end:
 
 type: rs_primitive
-version: 16
+version: 16 22
 size: 32
 enum:
 value: RS_PRIMITIVE_POINT = 0, "Vertex data will be rendered as a series of points"
@@ -115,6 +115,7 @@ description:
 end:
 
 type: rs_font
+version: 9 22
 size: 32
 simple: _RS_HANDLE
 deprecated:
@@ -126,6 +127,7 @@ end:
 
 
 type: rs_mesh
+version: 9 22
 size: 32
 simple: _RS_HANDLE
 deprecated:
@@ -136,6 +138,7 @@ description:
 end:
 
 type: rs_program_fragment
+version: 9 22
 size: 32
 simple: _RS_HANDLE
 deprecated:
@@ -146,6 +149,7 @@ description:
 end:
 
 type: rs_program_vertex
+version: 9 22
 size: 32
 simple: _RS_HANDLE
 deprecated:
@@ -156,6 +160,7 @@ description:
 end:
 
 type: rs_program_raster
+version: 9 22
 size: 32
 simple: _RS_HANDLE
 deprecated:
@@ -166,6 +171,7 @@ description:
 end:
 
 type: rs_program_store
+version: 9 22
 size: 32
 simple: _RS_HANDLE
 deprecated:
@@ -176,6 +182,7 @@ description:
 end:
 
 function: rsClearObject
+version: 9 22
 size: 32
 t: rs_mesh, rs_program_fragment, rs_program_vertex, rs_program_raster, rs_program_store, rs_font
 ret: void
@@ -184,6 +191,7 @@ test: none
 end:
 
 function: rsIsObject
+version: 9 22
 size: 32
 t: rs_mesh, rs_program_fragment, rs_program_vertex, rs_program_raster, rs_program_store, rs_font
 ret: bool
@@ -192,6 +200,7 @@ test: none
 end:
 
 function: rsSetObject
+version: 9 22
 size: 32
 t: rs_mesh, rs_program_fragment, rs_program_vertex, rs_program_raster, rs_program_store, rs_font
 ret: void
@@ -201,6 +210,7 @@ test: none
 end:
 
 function: rsgAllocationSyncAll
+version: 9 22
 size: 32
 ret: void
 arg: rs_allocation alloc
@@ -217,7 +227,7 @@ test: none
 end:
 
 function: rsgAllocationSyncAll
-version: 14
+version: 14 22
 size: 32
 ret: void
 arg: rs_allocation alloc
@@ -226,7 +236,7 @@ test: none
 end:
 
 function: rsgBindColorTarget
-version: 14
+version: 14 22
 size: 32
 ret: void
 arg: rs_allocation colorTarget
@@ -239,6 +249,7 @@ test: none
 end:
 
 function: rsgBindConstant
+version: 9 22
 size: 32
 ret: void
 arg: rs_program_fragment ps, "program fragment object"
@@ -253,6 +264,7 @@ test: none
 end:
 
 function: rsgBindConstant
+version: 9 22
 size: 32
 ret: void
 arg: rs_program_vertex pv, "program vertex object"
@@ -262,7 +274,7 @@ test: none
 end:
 
 function: rsgBindDepthTarget
-version: 14
+version: 14 22
 size: 32
 ret: void
 arg: rs_allocation depthTarget
@@ -274,6 +286,7 @@ test: none
 end:
 
 function: rsgBindFont
+version: 9 22
 size: 32
 ret: void
 arg: rs_font font, "object to bind"
@@ -285,6 +298,7 @@ test: none
 end:
 
 function: rsgBindProgramFragment
+version: 9 22
 size: 32
 ret: void
 arg: rs_program_fragment pf
@@ -296,6 +310,7 @@ test: none
 end:
 
 function: rsgBindProgramRaster
+version: 9 22
 size: 32
 ret: void
 arg: rs_program_raster pr
@@ -307,6 +322,7 @@ test: none
 end:
 
 function: rsgBindProgramStore
+version: 9 22
 size: 32
 ret: void
 arg: rs_program_store ps
@@ -318,6 +334,7 @@ test: none
 end:
 
 function: rsgBindProgramVertex
+version: 9 22
 size: 32
 ret: void
 arg: rs_program_vertex pv
@@ -329,6 +346,7 @@ test: none
 end:
 
 function: rsgBindSampler
+version: 9 22
 size: 32
 ret: void
 arg: rs_program_fragment fragment
@@ -343,6 +361,7 @@ test: none
 end:
 
 function: rsgBindTexture
+version: 9 22
 size: 32
 ret: void
 arg: rs_program_fragment v
@@ -359,7 +378,7 @@ test: none
 end:
 
 function: rsgClearAllRenderTargets
-version: 14
+version: 14 22
 size: 32
 ret: void
 deprecated:
@@ -371,6 +390,7 @@ test: none
 end:
 
 function: rsgClearColor
+version: 9 22
 size: 32
 ret: void
 arg: float r
@@ -385,7 +405,7 @@ test: none
 end:
 
 function: rsgClearColorTarget
-version: 14
+version: 14 22
 size: 32
 ret: void
 arg: uint slot
@@ -397,6 +417,7 @@ test: none
 end:
 
 function: rsgClearDepth
+version: 9 22
 size: 32
 ret: void
 arg: float value
@@ -408,7 +429,7 @@ test: none
 end:
 
 function: rsgClearDepthTarget
-version: 14
+version: 14 22
 size: 32
 ret: void
 deprecated:
@@ -419,6 +440,7 @@ test: none
 end:
 
 function: rsgDrawMesh
+version: 9 22
 size: 32
 ret: void
 arg: rs_mesh ism, "mesh object to render"
@@ -436,6 +458,7 @@ test: none
 end:
 
 function: rsgDrawMesh
+version: 9 22
 size: 32
 ret: void
 arg: rs_mesh ism
@@ -444,6 +467,7 @@ test: none
 end:
 
 function: rsgDrawMesh
+version: 9 22
 size: 32
 ret: void
 arg: rs_mesh ism
@@ -454,6 +478,7 @@ test: none
 end:
 
 function: rsgDrawQuad
+version: 9 22
 size: 32
 ret: void
 arg: float x1
@@ -477,6 +502,7 @@ test: none
 end:
 
 function: rsgDrawQuadTexCoords
+version: 9 22
 size: 32
 ret: void
 arg: float x1
@@ -508,6 +534,7 @@ test: none
 end:
 
 function: rsgDrawRect
+version: 9 22
 size: 32
 ret: void
 arg: float x1
@@ -524,6 +551,7 @@ test: none
 end:
 
 function: rsgDrawSpriteScreenspace
+version: 9 22
 size: 32
 ret: void
 arg: float x
@@ -542,6 +570,7 @@ test: none
 end:
 
 function: rsgDrawText
+version: 9 22
 size: 32
 ret: void
 arg: const char* text
@@ -555,6 +584,7 @@ test: none
 end:
 
 function: rsgDrawText
+version: 9 22
 size: 32
 ret: void
 arg: rs_allocation alloc
@@ -564,7 +594,7 @@ test: none
 end:
 
 function: rsgFinish
-version: 14
+version: 14 22
 size: 32
 ret: uint
 deprecated:
@@ -575,6 +605,7 @@ test: none
 end:
 
 function: rsgFontColor
+version: 9 22
 size: 32
 ret: void
 arg: float r, "red component"
@@ -589,6 +620,7 @@ test: none
 end:
 
 function: rsgGetHeight
+version: 9 22
 size: 32
 ret: uint
 deprecated:
@@ -599,6 +631,7 @@ test: none
 end:
 
 function: rsgGetWidth
+version: 9 22
 size: 32
 ret: uint
 deprecated:
@@ -609,6 +642,7 @@ test: none
 end:
 
 function: rsgMeasureText
+version: 9 22
 size: 32
 ret: void
 arg: const char* text
@@ -625,6 +659,7 @@ test: none
 end:
 
 function: rsgMeasureText
+version: 9 22
 size: 32
 ret: void
 arg: rs_allocation alloc
@@ -636,6 +671,7 @@ test: none
 end:
 
 function: rsgMeshComputeBoundingBox
+version: 9 22
 size: 32
 ret: void
 arg: rs_mesh mesh
@@ -653,6 +689,7 @@ test: none
 end:
 
 function: rsgMeshComputeBoundingBox
+version: 9 22
 size: 32
 attrib: always_inline
 ret: void
@@ -672,7 +709,7 @@ test: none
 end:
 
 function: rsgMeshGetIndexAllocation
-version: 16
+version: 16 22
 size: 32
 ret: rs_allocation, "allocation containing index data"
 arg: rs_mesh m, "mesh to get data from"
@@ -686,7 +723,7 @@ test: none
 end:
 
 function: rsgMeshGetPrimitive
-version: 16
+version: 16 22
 size: 32
 ret: rs_primitive, "primitive describing how the mesh is rendered"
 arg: rs_mesh m, "mesh to get data from"
@@ -700,7 +737,7 @@ test: none
 end:
 
 function: rsgMeshGetPrimitiveCount
-version: 16
+version: 16 22
 size: 32
 ret: uint32_t, "number of primitive groups in the mesh. This would include simple primitives as well as allocations containing index data"
 arg: rs_mesh m, "mesh to get data from"
@@ -713,7 +750,7 @@ test: none
 end:
 
 function: rsgMeshGetVertexAllocation
-version: 16
+version: 16 22
 size: 32
 ret: rs_allocation, "allocation containing vertex data"
 arg: rs_mesh m, "mesh to get data from"
@@ -727,7 +764,7 @@ test: none
 end:
 
 function: rsgMeshGetVertexAllocationCount
-version: 16
+version: 16 22
 size: 32
 ret: uint32_t, "number of allocations in the mesh that contain vertex data"
 arg: rs_mesh m, "mesh to get data from"
@@ -740,6 +777,7 @@ test: none
 end:
 
 function: rsgProgramFragmentConstantColor
+version: 9 22
 size: 32
 ret: void
 arg: rs_program_fragment pf
@@ -755,6 +793,7 @@ test: none
 end:
 
 function: rsgProgramVertexGetProjectionMatrix
+version: 9 22
 size: 32
 ret: void
 arg: rs_matrix4x4* proj, "matrix to store the current projection matrix into"
@@ -768,6 +807,7 @@ test: none
 end:
 
 function: rsgProgramVertexLoadModelMatrix
+version: 9 22
 size: 32
 ret: void
 arg: const rs_matrix4x4* model, "model matrix"
@@ -781,6 +821,7 @@ test: none
 end:
 
 function: rsgProgramVertexLoadProjectionMatrix
+version: 9 22
 size: 32
 ret: void
 arg: const rs_matrix4x4* proj, "projection matrix"
@@ -794,6 +835,7 @@ test: none
 end:
 
 function: rsgProgramVertexLoadTextureMatrix
+version: 9 22
 size: 32
 ret: void
 arg: const rs_matrix4x4* tex, "texture matrix"
@@ -807,7 +849,7 @@ test: none
 end:
 
 function: rsgProgramRasterGetCullMode
-version: 16
+version: 16 22
 size: 32
 ret: rs_cull_mode
 arg: rs_program_raster pr, "program raster to query"
@@ -819,7 +861,7 @@ test: none
 end:
 
 function: rsgProgramRasterIsPointSpriteEnabled
-version: 16
+version: 16 22
 size: 32
 ret: bool
 arg: rs_program_raster pr, "program raster to query"
@@ -831,7 +873,7 @@ test: none
 end:
 
 function: rsgProgramStoreGetBlendDstFunc
-version: 16
+version: 16 22
 size: 32
 ret: rs_blend_dst_func
 arg: rs_program_store ps, "program store to query"
@@ -843,7 +885,7 @@ test: none
 end:
 
 function: rsgProgramStoreGetBlendSrcFunc
-version: 16
+version: 16 22
 size: 32
 ret: rs_blend_src_func
 arg: rs_program_store ps, "program store to query"
@@ -855,7 +897,7 @@ test: none
 end:
 
 function: rsgProgramStoreGetDepthFunc
-version: 16
+version: 16 22
 size: 32
 ret: rs_depth_func
 arg: rs_program_store ps, "program store to query"
@@ -867,7 +909,7 @@ test: none
 end:
 
 function: rsgProgramStoreIsColorMaskAlphaEnabled
-version: 16
+version: 16 22
 size: 32
 ret: bool
 arg: rs_program_store ps, "program store to query"
@@ -879,7 +921,7 @@ test: none
 end:
 
 function: rsgProgramStoreIsColorMaskBlueEnabled
-version: 16
+version: 16 22
 size: 32
 ret: bool
 arg: rs_program_store ps, "program store to query"
@@ -891,7 +933,7 @@ test: none
 end:
 
 function: rsgProgramStoreIsColorMaskGreenEnabled
-version: 16
+version: 16 22
 size: 32
 ret: bool
 arg: rs_program_store ps, "program store to query"
@@ -903,7 +945,7 @@ test: none
 end:
 
 function: rsgProgramStoreIsColorMaskRedEnabled
-version: 16
+version: 16 22
 size: 32
 ret: bool
 arg: rs_program_store ps, "program store to query"
@@ -915,7 +957,7 @@ test: none
 end:
 
 function: rsgProgramStoreIsDepthMaskEnabled
-version: 16
+version: 16 22
 size: 32
 ret: bool
 arg: rs_program_store ps, "program store to query"
@@ -927,7 +969,7 @@ test: none
 end:
 
 function: rsgProgramStoreIsDitherEnabled
-version: 16
+version: 16 22
 size: 32
 ret: bool
 arg: rs_program_store ps, "program store to query"