Add "Available since" text to all android/ headers.
Also fix a few missing/incorrect annotations.
Bug: http://b/143470841
Test: treehugger
Change-Id: I1d9ec8350df03df7d80f1cc2334eef45deec30ec
Merged-In: I1d9ec8350df03df7d80f1cc2334eef45deec30ec
diff --git a/include/android/choreographer.h b/include/android/choreographer.h
index 44883cc..346861f 100644
--- a/include/android/choreographer.h
+++ b/include/android/choreographer.h
@@ -59,6 +59,8 @@
/**
* Get the AChoreographer instance for the current thread. This must be called
* on an ALooper thread.
+ *
+ * Available since API level 24.
*/
AChoreographer* AChoreographer_getInstance() __INTRODUCED_IN(24);
@@ -82,6 +84,8 @@
/**
* Power a callback to be run on the next frame. The data pointer provided will
* be passed to the callback function when it's called.
+ *
+ * Available since API level 29.
*/
void AChoreographer_postFrameCallback64(AChoreographer* chroreographer,
AChoreographer_frameCallback64 callback, void* data) __INTRODUCED_IN(29);
@@ -90,6 +94,8 @@
* Post a callback to be run on the frame following the specified delay. The
* data pointer provided will be passed to the callback function when it's
* called.
+ *
+ * Available since API level 29.
*/
void AChoreographer_postFrameCallbackDelayed64(AChoreographer* choreographer,
AChoreographer_frameCallback64 callback, void* data, uint32_t delayMillis) __INTRODUCED_IN(29);
diff --git a/include/android/configuration.h b/include/android/configuration.h
index ef6c5a2..3310722 100644
--- a/include/android/configuration.h
+++ b/include/android/configuration.h
@@ -675,50 +675,52 @@
*/
void AConfiguration_setUiModeNight(AConfiguration* config, int32_t uiModeNight);
-#if __ANDROID_API__ >= 13
/**
* Return the current configuration screen width in dp units, or
* ACONFIGURATION_SCREEN_WIDTH_DP_ANY if not set.
*/
-int32_t AConfiguration_getScreenWidthDp(AConfiguration* config) __INTRODUCED_IN(13);
+int32_t AConfiguration_getScreenWidthDp(AConfiguration* config);
/**
* Set the configuration's current screen width in dp units.
*/
-void AConfiguration_setScreenWidthDp(AConfiguration* config, int32_t value) __INTRODUCED_IN(13);
+void AConfiguration_setScreenWidthDp(AConfiguration* config, int32_t value);
/**
* Return the current configuration screen height in dp units, or
* ACONFIGURATION_SCREEN_HEIGHT_DP_ANY if not set.
*/
-int32_t AConfiguration_getScreenHeightDp(AConfiguration* config) __INTRODUCED_IN(13);
+int32_t AConfiguration_getScreenHeightDp(AConfiguration* config);
/**
* Set the configuration's current screen width in dp units.
*/
-void AConfiguration_setScreenHeightDp(AConfiguration* config, int32_t value) __INTRODUCED_IN(13);
+void AConfiguration_setScreenHeightDp(AConfiguration* config, int32_t value);
/**
* Return the configuration's smallest screen width in dp units, or
* ACONFIGURATION_SMALLEST_SCREEN_WIDTH_DP_ANY if not set.
*/
-int32_t AConfiguration_getSmallestScreenWidthDp(AConfiguration* config) __INTRODUCED_IN(13);
+int32_t AConfiguration_getSmallestScreenWidthDp(AConfiguration* config);
/**
* Set the configuration's smallest screen width in dp units.
*/
-void AConfiguration_setSmallestScreenWidthDp(AConfiguration* config, int32_t value) __INTRODUCED_IN(13);
-#endif /* __ANDROID_API__ >= 13 */
+void AConfiguration_setSmallestScreenWidthDp(AConfiguration* config, int32_t value);
#if __ANDROID_API__ >= 17
/**
* Return the configuration's layout direction, or
* ACONFIGURATION_LAYOUTDIR_ANY if not set.
+ *
+ * Available since API level 17.
*/
int32_t AConfiguration_getLayoutDirection(AConfiguration* config) __INTRODUCED_IN(17);
/**
* Set the configuration's layout direction.
+ *
+ * Available since API level 17.
*/
void AConfiguration_setLayoutDirection(AConfiguration* config, int32_t value) __INTRODUCED_IN(17);
#endif /* __ANDROID_API__ >= 17 */
diff --git a/include/android/font.h b/include/android/font.h
index 8001ee1..1618096 100644
--- a/include/android/font.h
+++ b/include/android/font.h
@@ -96,6 +96,8 @@
/**
* Close an AFont.
*
+ * Available since API level 29.
+ *
* \param font a font returned by ASystemFontIterator_next or AFontMatchert_match.
* Do nothing if NULL is passed.
*/
@@ -116,6 +118,8 @@
* The font file returned is guaranteed to be opend with O_RDONLY.
* Note that the returned pointer is valid until AFont_close() is called for the given font.
*
+ * Available since API level 29.
+ *
* \param font a font object. Passing NULL is not allowed.
* \return a string of the font file path.
*/
@@ -184,6 +188,8 @@
*
* For more information about font weight, read [OpenType usWeightClass](https://docs.microsoft.com/en-us/typography/opentype/spec/os2#usweightclass)
*
+ * Available since API level 29.
+ *
* \param font a font object. Passing NULL is not allowed.
* \return a positive integer less than or equal to {@link ASYSTEM_FONT_MAX_WEIGHT} is returned.
*/
@@ -192,6 +198,8 @@
/**
* Return true if the current font is italic, otherwise returns false.
*
+ * Available since API level 29.
+ *
* \param font a font object. Passing NULL is not allowed.
* \return true if italic, otherwise false.
*/
@@ -204,6 +212,8 @@
*
* Note that the returned pointer is valid until AFont_close() is called.
*
+ * Available since API level 29.
+ *
* \param font a font object. Passing NULL is not allowed.
* \return a IETF BCP47 compliant language tag or nullptr if not available.
*/
@@ -216,6 +226,8 @@
* returns a non-negative value as an font offset in the collection. This
* always returns 0 if the target font file is a regular font.
*
+ * Available since API level 29.
+ *
* \param font a font object. Passing NULL is not allowed.
* \return a font collection index.
*/
@@ -247,6 +259,8 @@
*
* For more information about font variation settings, read [Font Variations Table](https://docs.microsoft.com/en-us/typography/opentype/spec/fvar)
*
+ * Available since API level 29.
+ *
* \param font a font object. Passing NULL is not allowed.
* \return a number of font variation settings.
*/
@@ -258,6 +272,8 @@
*
* See AFont_getAxisCount for more details.
*
+ * Available since API level 29.
+ *
* \param font a font object. Passing NULL is not allowed.
* \param axisIndex an index to the font variation settings. Passing value larger than or
* equal to {@link AFont_getAxisCount} is not allowed.
@@ -271,6 +287,8 @@
*
* See AFont_getAxisCount for more details.
*
+ * Available since API level 29.
+ *
* \param font a font object. Passing NULL is not allowed.
* \param axisIndex an index to the font variation settings. Passing value larger than or
* equal to {@link ASYstemFont_getAxisCount} is not allwed.
diff --git a/include/android/font_matcher.h b/include/android/font_matcher.h
index 0b8f892..d4bd892 100644
--- a/include/android/font_matcher.h
+++ b/include/android/font_matcher.h
@@ -130,13 +130,17 @@
*/
/**
- * Creates a new AFontMatcher object
+ * Creates a new AFontMatcher object.
+ *
+ * Available since API level 29.
*/
AFontMatcher* _Nonnull AFontMatcher_create() __INTRODUCED_IN(29);
/**
* Destroy the matcher object.
*
+ * Available since API level 29.
+ *
* \param matcher a matcher object. Passing NULL is not allowed.
*/
void AFontMatcher_destroy(AFontMatcher* _Nonnull matcher) __INTRODUCED_IN(29);
@@ -147,6 +151,8 @@
* If this function is not called, the matcher performs with {@link ASYSTEM_FONT_WEIGHT_NORMAL}
* with non-italic style.
*
+ * Available since API level 29.
+ *
* \param matcher a matcher object. Passing NULL is not allowed.
* \param weight a font weight value. Only from 0 to 1000 value is valid
* \param italic true if italic, otherwise false.
@@ -161,6 +167,8 @@
*
* If this function is not called, the matcher performs with empty locale list.
*
+ * Available since API level 29.
+ *
* \param matcher a matcher object. Passing NULL is not allowed.
* \param languageTags a null character terminated comma separated IETF BCP47 compliant language
* tags.
@@ -174,6 +182,8 @@
*
* If this function is not called, the matcher performs with {@link AFAMILY_VARIANT_DEFAULT}.
*
+ * Available since API level 29.
+ *
* \param matcher a matcher object. Passing NULL is not allowed.
* \param familyVariant Must be one of {@link AFAMILY_VARIANT_DEFAULT},
* {@link AFAMILY_VARIANT_COMPACT} or {@link AFAMILY_VARIANT_ELEGANT} is valid.
@@ -190,6 +200,8 @@
* Even if no font can render the given text, this function will return a non-null result for
* drawing Tofu character.
*
+ * Available since API level 29.
+ *
* \param matcher a matcher object. Passing NULL is not allowed.
* \param familyName a null character terminated font family name
* \param text a UTF-16 encoded text buffer to be rendered. Do not pass empty string.
diff --git a/include/android/hardware_buffer_jni.h b/include/android/hardware_buffer_jni.h
index aedf369..293e5ac 100644
--- a/include/android/hardware_buffer_jni.h
+++ b/include/android/hardware_buffer_jni.h
@@ -42,6 +42,8 @@
* that is returned. To keep the AHardwareBuffer live after the Java
* HardwareBuffer object got garbage collected, be sure to use AHardwareBuffer_acquire()
* to acquire an additional reference.
+ *
+ * Available since API level 26.
*/
AHardwareBuffer* AHardwareBuffer_fromHardwareBuffer(JNIEnv* env,
jobject hardwareBufferObj) __INTRODUCED_IN(26);
@@ -49,6 +51,8 @@
/**
* Return a new Java HardwareBuffer object that wraps the passed native
* AHardwareBuffer object.
+ *
+ * Available since API level 26.
*/
jobject AHardwareBuffer_toHardwareBuffer(JNIEnv* env,
AHardwareBuffer* hardwareBuffer) __INTRODUCED_IN(26);
diff --git a/include/android/input.h b/include/android/input.h
index cfade6c..ce439c6 100644
--- a/include/android/input.h
+++ b/include/android/input.h
@@ -986,10 +986,8 @@
*/
int32_t AMotionEvent_getMetaState(const AInputEvent* motion_event);
-#if __ANDROID_API__ >= 14
/** Get the button state of all buttons that are pressed. */
-int32_t AMotionEvent_getButtonState(const AInputEvent* motion_event) __INTRODUCED_IN(14);
-#endif
+int32_t AMotionEvent_getButtonState(const AInputEvent* motion_event);
/**
* Get a bitfield indicating which edges, if any, were touched by this motion event.
@@ -1054,14 +1052,12 @@
*/
int32_t AMotionEvent_getPointerId(const AInputEvent* motion_event, size_t pointer_index);
-#if __ANDROID_API__ >= 14
/**
* Get the tool type of a pointer for the given pointer index.
* The tool type indicates the type of tool used to make contact such as a
* finger or stylus, if known.
*/
-int32_t AMotionEvent_getToolType(const AInputEvent* motion_event, size_t pointer_index) __INTRODUCED_IN(14);
-#endif
+int32_t AMotionEvent_getToolType(const AInputEvent* motion_event, size_t pointer_index);
/**
* Get the original raw X coordinate of this event.
@@ -1151,11 +1147,9 @@
*/
float AMotionEvent_getOrientation(const AInputEvent* motion_event, size_t pointer_index);
-#if __ANDROID_API__ >= 13
/** Get the value of the request axis for the given pointer index. */
float AMotionEvent_getAxisValue(const AInputEvent* motion_event,
- int32_t axis, size_t pointer_index) __INTRODUCED_IN(13);
-#endif
+ int32_t axis, size_t pointer_index);
/**
* Get the number of historical points in this event. These are movements that
@@ -1286,14 +1280,12 @@
float AMotionEvent_getHistoricalOrientation(const AInputEvent* motion_event, size_t pointer_index,
size_t history_index);
-#if __ANDROID_API__ >= 13
/**
* Get the historical value of the request axis for the given pointer index
* that occurred between this event and the previous motion event.
*/
float AMotionEvent_getHistoricalAxisValue(const AInputEvent* motion_event,
- int32_t axis, size_t pointer_index, size_t history_index) __INTRODUCED_IN(13);
-#endif
+ int32_t axis, size_t pointer_index, size_t history_index);
struct AInputQueue;
diff --git a/include/android/multinetwork.h b/include/android/multinetwork.h
index d31d1f1..59b1deb 100644
--- a/include/android/multinetwork.h
+++ b/include/android/multinetwork.h
@@ -69,6 +69,7 @@
*
* This is the equivalent of: [android.net.Network#bindSocket()](https://developer.android.com/reference/android/net/Network.html#bindSocket(java.net.Socket))
*
+ * Available since API level 23.
*/
int android_setsocknetwork(net_handle_t network, int fd) __INTRODUCED_IN(23);
@@ -86,6 +87,7 @@
*
* This is the equivalent of: [android.net.ConnectivityManager#setProcessDefaultNetwork()](https://developer.android.com/reference/android/net/ConnectivityManager.html#setProcessDefaultNetwork(android.net.Network))
*
+ * Available since API level 23.
*/
int android_setprocnetwork(net_handle_t network) __INTRODUCED_IN(23);
@@ -103,6 +105,7 @@
*
* This is the equivalent of: [android.net.Network#getAllByName()](https://developer.android.com/reference/android/net/Network.html#getAllByName(java.lang.String))
*
+ * Available since API level 23.
*/
int android_getaddrinfofornetwork(net_handle_t network,
const char *node, const char *service,
@@ -144,6 +147,8 @@
*
* Returns a file descriptor to watch for read events, or a negative
* POSIX error code (see errno.h) if an immediate error occurs.
+ *
+ * Available since API level 29.
*/
int android_res_nquery(net_handle_t network,
const char *dname, int ns_class, int ns_type, uint32_t flags) __INTRODUCED_IN(29);
@@ -155,6 +160,8 @@
*
* Returns a file descriptor to watch for read events, or a negative
* POSIX error code (see errno.h) if an immediate error occurs.
+ *
+ * Available since API level 29.
*/
int android_res_nsend(net_handle_t network,
const uint8_t *msg, size_t msglen, uint32_t flags) __INTRODUCED_IN(29);
@@ -163,6 +170,8 @@
* Read a result for the query associated with the |fd| descriptor.
* Closes |fd| before returning.
*
+ * Available since 29.
+ *
* Returns:
* < 0: negative POSIX error code (see errno.h for possible values). |rcode| is not set.
* >= 0: length of |answer|. |rcode| is the resolver return code (e.g., ns_r_nxdomain)
@@ -173,6 +182,8 @@
/**
* Attempts to cancel the in-progress query associated with the |nsend_fd|
* descriptor.
+ *
+ * Available since API level 29.
*/
void android_res_cancel(int nsend_fd) __INTRODUCED_IN(29);
diff --git a/include/android/native_window_jni.h b/include/android/native_window_jni.h
index 0c196b9..3a77ffe 100644
--- a/include/android/native_window_jni.h
+++ b/include/android/native_window_jni.h
@@ -51,6 +51,8 @@
* the ANativeWindow; maintains it through general Java object's life cycle;
* and will automatically release the reference when the Java object gets garbage
* collected.
+ *
+ * Available since API level 26.
*/
jobject ANativeWindow_toSurface(JNIEnv* env, ANativeWindow* window) __INTRODUCED_IN(26);
#endif
diff --git a/include/android/sensor.h b/include/android/sensor.h
index e9d5c16..3ebe79f 100644
--- a/include/android/sensor.h
+++ b/include/android/sensor.h
@@ -564,6 +564,7 @@
*
* ASensorManager* sensorManager = ASensorManager_getInstanceForPackage("foo.bar.baz");
*
+ * Available since API level 26.
*/
ASensorManager* ASensorManager_getInstanceForPackage(const char* packageName) __INTRODUCED_IN(26);
#endif
@@ -583,6 +584,8 @@
/**
* Returns the default sensor with the given type and wakeUp properties or NULL if no sensor
* of this type and wakeUp properties exists.
+ *
+ * Available since API level 21.
*/
ASensor const* ASensorManager_getDefaultSensorEx(ASensorManager* manager, int type, bool wakeUp) __INTRODUCED_IN(21);
#endif
@@ -609,6 +612,8 @@
* Create a direct channel of {@link ASENSOR_DIRECT_CHANNEL_TYPE_SHARED_MEMORY} to be used
* for configuring sensor direct report.
*
+ * Available since API level 26.
+ *
* \param manager the {@link ASensorManager} instance obtained from
* {@link ASensorManager_getInstanceForPackage}.
* \param fd file descriptor representing a shared memory created by
@@ -627,6 +632,8 @@
* Create a direct channel of {@link ASENSOR_DIRECT_CHANNEL_TYPE_HARDWARE_BUFFER} type to be used
* for configuring sensor direct report.
*
+ * Available since API level 26.
+ *
* \param manager the {@link ASensorManager} instance obtained from
* {@link ASensorManager_getInstanceForPackage}.
* \param buffer {@link AHardwareBuffer} instance created by {@link AHardwareBuffer_allocate}.
@@ -646,6 +653,8 @@
* The buffer used for creating direct channel does not get destroyed with
* {@link ASensorManager_destroy} and has to be close or released separately.
*
+ * Available since API level 26.
+ *
* \param manager the {@link ASensorManager} instance obtained from
* {@link ASensorManager_getInstanceForPackage}.
* \param channelId channel id (a positive integer) returned from
@@ -678,6 +687,8 @@
*
* ASensorManager_configureDirectReport(manager, sensor, channel_id, ASENSOR_DIRECT_RATE_FAST);
*
+ * Available since API level 26.
+ *
* \param manager the {@link ASensorManager} instance obtained from
* {@link ASensorManager_getInstanceForPackage}.
* \param sensor a {@link ASensor} to denote which sensor to be operate. It can be NULL if rate
@@ -780,7 +791,7 @@
*/
ssize_t ASensorEventQueue_getEvents(ASensorEventQueue* queue, ASensorEvent* events, size_t count);
-#if __ANDROID_API__ >= __ANDROID_API_Q__
+#if __ANDROID_API__ >= 29
/**
* Request that {@link ASENSOR_TYPE_ADDITIONAL_INFO} events to be delivered on
* the given {@link ASensorEventQueue}.
@@ -796,13 +807,15 @@
* {@link AAdditionalInfoEvent#type}, as new values may be defined in the future
* and may delivered to the client.
*
+ * Available since API level 29.
+ *
* \param queue {@link ASensorEventQueue} to configure
* \param enable true to request {@link ASENSOR_TYPE_ADDITIONAL_INFO} events,
* false to stop receiving events
* \return 0 on success or a negative error code on failure
*/
-int ASensorEventQueue_requestAdditionalInfoEvents(ASensorEventQueue* queue, bool enable);
-#endif /* __ANDROID_API__ >= __ANDRDOID_API_Q__ */
+int ASensorEventQueue_requestAdditionalInfoEvents(ASensorEventQueue* queue, bool enable) __INTRODUCED_IN(29);
+#endif /* __ANDROID_API__ >= 29 */
/*****************************************************************************/
@@ -837,26 +850,36 @@
/**
* Returns the maximum size of batches for this sensor. Batches will often be
* smaller, as the hardware fifo might be used for other sensors.
+ *
+ * Available since API level 21.
*/
int ASensor_getFifoMaxEventCount(ASensor const* sensor) __INTRODUCED_IN(21);
/**
* Returns the hardware batch fifo size reserved to this sensor.
+ *
+ * Available since API level 21.
*/
int ASensor_getFifoReservedEventCount(ASensor const* sensor) __INTRODUCED_IN(21);
/**
* Returns this sensor's string type.
+ *
+ * Available since API level 21.
*/
const char* ASensor_getStringType(ASensor const* sensor) __INTRODUCED_IN(21);
/**
* Returns the reporting mode for this sensor. One of AREPORTING_MODE_* constants.
+ *
+ * Available since API level 21.
*/
int ASensor_getReportingMode(ASensor const* sensor) __INTRODUCED_IN(21);
/**
* Returns true if this is a wake up sensor, false otherwise.
+ *
+ * Available since API level 21.
*/
bool ASensor_isWakeUpSensor(ASensor const* sensor) __INTRODUCED_IN(21);
#endif /* __ANDROID_API__ >= 21 */
@@ -865,6 +888,8 @@
/**
* Test if sensor supports a certain type of direct channel.
*
+ * Available since API level 26.
+ *
* \param sensor a {@link ASensor} to denote the sensor to be checked.
* \param channelType Channel type constant, either
* {@ASENSOR_DIRECT_CHANNEL_TYPE_SHARED_MEMORY}
@@ -874,7 +899,9 @@
bool ASensor_isDirectChannelTypeSupported(ASensor const* sensor, int channelType) __INTRODUCED_IN(26);
/**
- * Get the highest direct rate level that a sensor support.
+ * Get the highest direct rate level that a sensor supports.
+ *
+ * Available since API level 26.
*
* \param sensor a {@link ASensor} to denote the sensor to be checked.
*
@@ -885,7 +912,7 @@
int ASensor_getHighestDirectReportRateLevel(ASensor const* sensor) __INTRODUCED_IN(26);
#endif /* __ANDROID_API__ >= 26 */
-#if __ANDROID_API__ >= __ANDROID_API_Q__
+#if __ANDROID_API__ >= 29
/**
* Returns the sensor's handle.
*
@@ -899,9 +926,11 @@
* It is important to note that the value returned by {@link ASensor_getHandle} is not the same as
* the value returned by the Java API {@link android.hardware.Sensor#getId} and no mapping exists
* between the values.
+ *
+ * Available since API level 29.
*/
-int ASensor_getHandle(ASensor const* sensor) __INTRODUCED_IN(__ANDROID_API_Q__);
-#endif /* __ANDROID_API__ >= ANDROID_API_Q__ */
+int ASensor_getHandle(ASensor const* sensor) __INTRODUCED_IN(29);
+#endif /* __ANDROID_API__ >= 29 */
#ifdef __cplusplus
};
diff --git a/include/android/surface_control.h b/include/android/surface_control.h
index ef2ad99..90e5653 100644
--- a/include/android/surface_control.h
+++ b/include/android/surface_control.h
@@ -46,7 +46,7 @@
*/
typedef struct ASurfaceControl ASurfaceControl;
-/*
+/**
* Creates an ASurfaceControl with either ANativeWindow or an ASurfaceControl as its parent.
* |debug_name| is a debug name associated with this surface. It can be used to
* identify this surface in the SurfaceFlinger's layer tree. It must not be
@@ -54,10 +54,17 @@
*
* The caller takes ownership of the ASurfaceControl returned and must release it
* using ASurfaceControl_release below.
+ *
+ * Available since API level 29.
*/
ASurfaceControl* ASurfaceControl_createFromWindow(ANativeWindow* parent, const char* debug_name)
__INTRODUCED_IN(29);
+/**
+ * See ASurfaceControl_createFromWindow.
+ *
+ * Available since API level 29.
+ */
ASurfaceControl* ASurfaceControl_create(ASurfaceControl* parent, const char* debug_name)
__INTRODUCED_IN(29);
@@ -65,6 +72,8 @@
* Releases the |surface_control| object. After releasing the ASurfaceControl the caller no longer
* has ownership of the AsurfaceControl. The surface and it's children may remain on display as long
* as their parent remains on display.
+ *
+ * Available since API level 29.
*/
void ASurfaceControl_release(ASurfaceControl* surface_control) __INTRODUCED_IN(29);
@@ -79,11 +88,15 @@
/**
* The caller takes ownership of the transaction and must release it using
* ASurfaceControl_delete below.
+ *
+ * Available since API level 29.
*/
ASurfaceTransaction* ASurfaceTransaction_create() __INTRODUCED_IN(29);
/**
* Destroys the |transaction| object.
+ *
+ * Available since API level 29.
*/
void ASurfaceTransaction_delete(ASurfaceTransaction* transaction) __INTRODUCED_IN(29);
@@ -93,6 +106,8 @@
* Note that the transaction is guaranteed to be applied atomically. The
* transactions which are applied on the same thread are also guaranteed to be
* applied in order.
+ *
+ * Available since API level 29.
*/
void ASurfaceTransaction_apply(ASurfaceTransaction* transaction) __INTRODUCED_IN(29);
@@ -116,6 +131,8 @@
*
* THREADING
* The transaction completed callback can be invoked on any thread.
+ *
+ * Available since API level 29.
*/
typedef void (*ASurfaceTransaction_OnComplete)(void* context, ASurfaceTransactionStats* stats)
__INTRODUCED_IN(29);
@@ -123,6 +140,8 @@
/**
* Returns the timestamp of when the frame was latched by the framework. Once a frame is
* latched by the framework, it is presented at the following hardware vsync.
+ *
+ * Available since API level 29.
*/
int64_t ASurfaceTransactionStats_getLatchTime(ASurfaceTransactionStats* surface_transaction_stats)
__INTRODUCED_IN(29);
@@ -131,6 +150,8 @@
* Returns a sync fence that signals when the transaction has been presented.
* The recipient of the callback takes ownership of the fence and is responsible for closing
* it.
+ *
+ * Available since API level 29.
*/
int ASurfaceTransactionStats_getPresentFenceFd(ASurfaceTransactionStats* surface_transaction_stats)
__INTRODUCED_IN(29);
@@ -141,6 +162,8 @@
* When the client is done using the array, it must release it by calling
* ASurfaceTransactionStats_releaseASurfaceControls.
*
+ * Available since API level 29.
+ *
* |outASurfaceControlsSize| returns the size of the ASurfaceControls array.
*/
void ASurfaceTransactionStats_getASurfaceControls(ASurfaceTransactionStats* surface_transaction_stats,
@@ -150,6 +173,8 @@
/**
* Releases the array of ASurfaceControls that were returned by
* ASurfaceTransactionStats_getASurfaceControls.
+ *
+ * Available since API level 29.
*/
void ASurfaceTransactionStats_releaseASurfaceControls(ASurfaceControl** surface_controls)
__INTRODUCED_IN(29);
@@ -158,6 +183,8 @@
* Returns the timestamp of when the CURRENT buffer was acquired. A buffer is considered
* acquired when its acquire_fence_fd has signaled. A buffer cannot be latched or presented until
* it is acquired. If no acquire_fence_fd was provided, this timestamp will be set to -1.
+ *
+ * Available since API level 29.
*/
int64_t ASurfaceTransactionStats_getAcquireTime(ASurfaceTransactionStats* surface_transaction_stats,
ASurfaceControl* surface_control)
@@ -180,6 +207,8 @@
*
* The client must ensure that all pending refs on a buffer are released before attempting to reuse
* this buffer, otherwise synchronization errors may occur.
+ *
+ * Available since API level 29.
*/
int ASurfaceTransactionStats_getPreviousReleaseFenceFd(
ASurfaceTransactionStats* surface_transaction_stats,
@@ -190,6 +219,8 @@
* Sets the callback that will be invoked when the updates from this transaction
* are presented. For details on the callback semantics and data, see the
* comments on the ASurfaceTransaction_OnComplete declaration above.
+ *
+ * Available since API level 29.
*/
void ASurfaceTransaction_setOnComplete(ASurfaceTransaction* transaction, void* context,
ASurfaceTransaction_OnComplete func) __INTRODUCED_IN(29);
@@ -199,6 +230,8 @@
* Any children of the* reparented |surface_control| will remain children of the |surface_control|.
*
* The |new_parent| can be null. Surface controls with a null parent do not appear on the display.
+ *
+ * Available since API level 29.
*/
void ASurfaceTransaction_reparent(ASurfaceTransaction* transaction,
ASurfaceControl* surface_control, ASurfaceControl* new_parent)
@@ -213,6 +246,8 @@
* Updates the visibility of |surface_control|. If show is set to
* ASURFACE_TRANSACTION_VISIBILITY_HIDE, the |surface_control| and all surfaces in its subtree will
* be hidden.
+ *
+ * Available since API level 29.
*/
void ASurfaceTransaction_setVisibility(ASurfaceTransaction* transaction,
ASurfaceControl* surface_control, int8_t visibility)
@@ -224,6 +259,8 @@
* the same z order is undefined.
*
* Z orders may be from MIN_INT32 to MAX_INT32. A layer's default z order index is 0.
+ *
+ * Available since API level 29.
*/
void ASurfaceTransaction_setZOrder(ASurfaceTransaction* transaction,
ASurfaceControl* surface_control, int32_t z_order)
@@ -236,6 +273,8 @@
*
* The frameworks takes ownership of the |acquire_fence_fd| passed and is responsible
* for closing it.
+ *
+ * Available since API level 29.
*/
void ASurfaceTransaction_setBuffer(ASurfaceTransaction* transaction,
ASurfaceControl* surface_control, AHardwareBuffer* buffer,
@@ -246,6 +285,8 @@
* ASurfaceControl visible in transparent regions of the surface. Colors |r|, |g|,
* and |b| must be within the range that is valid for |dataspace|. |dataspace| and |alpha|
* will be the dataspace and alpha set for the background color layer.
+ *
+ * Available since API level 29.
*/
void ASurfaceTransaction_setColor(ASurfaceTransaction* transaction,
ASurfaceControl* surface_control, float r, float g, float b,
@@ -264,6 +305,8 @@
* |transform| the transform applied after the source rect is applied to the buffer. This parameter
* should be set to 0 for no transform. To specify a transfrom use the NATIVE_WINDOW_TRANSFORM_*
* enum.
+ *
+ * Available since API level 29.
*/
void ASurfaceTransaction_setGeometry(ASurfaceTransaction* transaction,
ASurfaceControl* surface_control, const ARect& source,
@@ -281,6 +324,8 @@
* Updates whether the content for the buffer associated with this surface is
* completely opaque. If true, every pixel of content inside the buffer must be
* opaque or visual errors can occur.
+ *
+ * Available since API level 29.
*/
void ASurfaceTransaction_setBufferTransparency(ASurfaceTransaction* transaction,
ASurfaceControl* surface_control,
@@ -290,6 +335,8 @@
/**
* Updates the region for the content on this surface updated in this
* transaction. If unspecified, the complete surface is assumed to be damaged.
+ *
+ * Available since API level 29.
*/
void ASurfaceTransaction_setDamageRegion(ASurfaceTransaction* transaction,
ASurfaceControl* surface_control, const ARect rects[],
@@ -304,6 +351,8 @@
*
* If an earlier transaction has a desired present time of x, and a later transaction has a desired
* present time that is before x, the later transaction will not preempt the earlier transaction.
+ *
+ * Available since API level 29.
*/
void ASurfaceTransaction_setDesiredPresentTime(ASurfaceTransaction* transaction,
int64_t desiredPresentTime) __INTRODUCED_IN(29);
@@ -312,6 +361,8 @@
* Sets the alpha for the buffer. It uses a premultiplied blending.
*
* The |alpha| must be between 0.0 and 1.0.
+ *
+ * Available since API level 29.
*/
void ASurfaceTransaction_setBufferAlpha(ASurfaceTransaction* transaction,
ASurfaceControl* surface_control, float alpha)
@@ -321,6 +372,8 @@
* Sets the data space of the surface_control's buffers.
*
* If no data space is set, the surface control defaults to ADATASPACE_SRGB.
+ *
+ * Available since API level 29.
*/
void ASurfaceTransaction_setBufferDataSpace(ASurfaceTransaction* transaction,
ASurfaceControl* surface_control, ADataSpace data_space)
@@ -331,6 +384,8 @@
*
* When |metadata| is set to null, the framework does not use any smpte2086 metadata when rendering
* the surface's buffer.
+ *
+ * Available since API level 29.
*/
void ASurfaceTransaction_setHdrMetadata_smpte2086(ASurfaceTransaction* transaction,
ASurfaceControl* surface_control,
@@ -342,6 +397,8 @@
*
* When |metadata| is set to null, the framework does not use any cta861.3 metadata when rendering
* the surface's buffer.
+ *
+ * Available since API level 29.
*/
void ASurfaceTransaction_setHdrMetadata_cta861_3(ASurfaceTransaction* transaction,
ASurfaceControl* surface_control,
diff --git a/include/android/surface_texture.h b/include/android/surface_texture.h
index 540d23a..dde7eaa 100644
--- a/include/android/surface_texture.h
+++ b/include/android/surface_texture.h
@@ -65,6 +65,9 @@
* Release the reference to the native ASurfaceTexture acquired with
* ASurfaceTexture_fromSurfaceTexture().
* Failing to do so will result in leaked memory and graphic resources.
+ *
+ * Available since API level 28.
+ *
* \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
*/
void ASurfaceTexture_release(ASurfaceTexture* st) __INTRODUCED_IN(28);
@@ -73,6 +76,8 @@
* Returns a reference to an ANativeWindow (i.e. the Producer) for this SurfaceTexture.
* This is equivalent to Java's: Surface sur = new Surface(surfaceTexture);
*
+ * Available since API level 28.
+ *
* \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
* @return A reference to an ANativeWindow. This reference MUST BE released when no longer needed
* using ANativeWindow_release(). Failing to do so will result in leaked resources. nullptr is
@@ -90,6 +95,8 @@
* contexts. Note, however, that the image contents are only accessible from one OpenGL ES
* context at a time.
*
+ * Available since API level 28.
+ *
* \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
* \param texName The name of the OpenGL ES texture that will be created. This texture name
* must be unusued in the OpenGL ES context that is current on the calling thread.
@@ -108,6 +115,8 @@
* contexts. Note, however, that the image contents are only accessible from one OpenGL ES
* context at a time.
*
+ * Available since API level 28.
+ *
* \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
* \return 0 on success, negative posix error code otherwise (see <errno.h>)
*/
@@ -118,6 +127,8 @@
* called while the OpenGL ES context that owns the texture is current on the calling thread.
* It will implicitly bind its texture to the GL_TEXTURE_EXTERNAL_OES texture target.
*
+ * Available since API level 28.
+ *
* \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
* \return 0 on success, negative posix error code otherwise (see <errno.h>)
*/
@@ -135,6 +146,8 @@
* The matrix is stored in column-major order so that it may be passed directly to OpenGL ES via
* the glLoadMatrixf or glUniformMatrix4fv functions.
*
+ * Available since API level 28.
+ *
* \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
* \param mtx the array into which the 4x4 matrix will be stored. The array must have exactly
* 16 elements.
@@ -156,6 +169,8 @@
* For EGL/Vulkan producers, this timestamp is the desired present time set with the
* EGL_ANDROID_presentation_time or VK_GOOGLE_display_timing extensions
*
+ * Available since API level 28.
+ *
* \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
*/
int64_t ASurfaceTexture_getTimestamp(ASurfaceTexture* st) __INTRODUCED_IN(28);
diff --git a/include/android/surface_texture_jni.h b/include/android/surface_texture_jni.h
index b0e1edd..2266d54 100644
--- a/include/android/surface_texture_jni.h
+++ b/include/android/surface_texture_jni.h
@@ -32,6 +32,8 @@
__BEGIN_DECLS
+#if __ANDROID_API__ >= 28
+
/**
* Get a reference to the native ASurfaceTexture from the corresponding java object.
*
@@ -40,13 +42,17 @@
* properly once the Java object gets finalized.
* However, this will not result in program termination.
*
+ * Available since API level 28.
+ *
* \param env JNI environment
* \param surfacetexture Instance of Java SurfaceTexture object
* \return native ASurfaceTexture reference or nullptr if the java object is not a SurfaceTexture.
* The returned reference MUST BE released when it's no longer needed using
* ASurfaceTexture_release().
*/
-ASurfaceTexture* ASurfaceTexture_fromSurfaceTexture(JNIEnv* env, jobject surfacetexture);
+ASurfaceTexture* ASurfaceTexture_fromSurfaceTexture(JNIEnv* env, jobject surfacetexture) __INTRODUCED_IN(28);
+
+#endif
__END_DECLS
diff --git a/include/android/system_fonts.h b/include/android/system_fonts.h
index f0485a1..6fd7d2c 100644
--- a/include/android/system_fonts.h
+++ b/include/android/system_fonts.h
@@ -102,6 +102,8 @@
*
* Use ASystemFont_close() to close the iterator.
*
+ * Available since API level 29.
+ *
* \return a pointer for a newly allocated iterator, nullptr on failure.
*/
ASystemFontIterator* _Nullable ASystemFontIterator_open() __INTRODUCED_IN(29);
@@ -109,6 +111,8 @@
/**
* Close an opened system font iterator, freeing any related resources.
*
+ * Available since API level 29.
+ *
* \param iterator a pointer of an iterator for the system fonts. Do nothing if NULL is passed.
*/
void ASystemFontIterator_close(ASystemFontIterator* _Nullable iterator) __INTRODUCED_IN(29);
@@ -116,6 +120,8 @@
/**
* Move to the next system font.
*
+ * Available since API level 29.
+ *
* \param iterator an iterator for the system fonts. Passing NULL is not allowed.
* \return a font. If no more font is available, returns nullptr. You need to release the returned
* font by ASystemFont_close when it is no longer needed.
diff --git a/include/android/trace.h b/include/android/trace.h
index bb7ff28..d59690a 100644
--- a/include/android/trace.h
+++ b/include/android/trace.h
@@ -74,7 +74,7 @@
#endif /* __ANDROID_API__ >= 23 */
-#if __ANDROID_API__ >= __ANDROID_API_Q__
+#if __ANDROID_API__ >= 29
/**
* Writes a trace message to indicate that a given section of code has
@@ -83,6 +83,8 @@
* asynchronous events do not need to be nested. The name and cookie used to
* begin an event must be used to end it.
*
+ * Available since API level 29.
+ *
* \param sectionName The method name to appear in the trace.
* \param cookie Unique identifier for distinguishing simultaneous events
*/
@@ -93,6 +95,8 @@
* Must be called exactly once for each call to {@link ATrace_beginAsyncSection}
* using the same name and cookie.
*
+ * Available since API level 29.
+ *
* \param methodName The method name to appear in the trace.
* \param cookie Unique identifier for distinguishing simultaneous events
*/
@@ -101,6 +105,8 @@
/**
* Writes trace message to indicate the value of a given counter.
*
+ * Available since API level 29.
+ *
* \param counterName The counter name to appear in the trace.
* \param counterValue The counter value.
*/