aom_image: add allocation guidance for aom_img_wrap

This change is the same as the one made in libvpx with 'vpx_' replaced
with 'aom_':
8d00aca6 vpx_image: add allocation guidance for vpx_img_wrap
The image data buffer provided to `vpx_img_wrap()` must have a minimum
allocation size that satisfies the requirements of the `fmt`, `d_w`,
`d_h`` and `stride_align` parameters. This change adds a description of
how to calculate the size based on the one done in `img_alloc_helper()`.

Bug: 442142951
Change-Id: I8d282623ca697ab42ebec9e08efaf3b0dc4a64e3

aom/aom_image.h

diff --git a/aom/aom_image.h b/aom/aom_image.h
index 7100a20..87a2d61 100644
--- a/aom/aom_image.h
+++ b/aom/aom_image.h
@@ -301,6 +301,35 @@
  * \return Returns a pointer to the initialized image descriptor. If the img
  *         parameter is non-null, the value of the img parameter will be
  *         returned.
+ *
+ * \note \a img_data is required to have a minimum allocation size that
+ *       satisfies the requirements of the \a fmt, \a d_w, \a d_h and \a
+ *       stride_align parameters. This size can be calculated as follows (see
+ *       \c img_alloc_helper in the aom_image.c file in the libaom source tree
+ *       for more detail):
+ * \code
+ * align = (1 << x_chroma_shift) - 1;
+ * w = (d_w + align) & ~align;
+ * align = (1 << y_chroma_shift) - 1;
+ * h = (d_h + align) & ~align;
+ *
+ * s = (fmt & AOM_IMG_FMT_PLANAR) ? w : (uint64_t)bps * w / 8;
+ * s = (fmt & AOM_IMG_FMT_HIGHBITDEPTH) ? s * 2 : s;
+ * s = (s + stride_align - 1) & ~((uint64_t)stride_align - 1);
+ * s = (fmt & AOM_IMG_FMT_HIGHBITDEPTH) ? s / 2 : s;
+ * alloc_size = (fmt & AOM_IMG_FMT_PLANAR) ? (uint64_t)h * s * bps / 8
+ *                                         : (uint64_t)h * s;
+ * \endcode
+ * \a x_chroma_shift, \a y_chroma_shift and \a bps can be obtained by calling
+ * \ref aom_img_wrap with a non-\c NULL \a img_data parameter. The \c
+ * aom_image_t pointer should \em not be used in other API calls until \em after
+ * a successful call to \ref aom_img_wrap with a valid image buffer. For
+ * example:
+ * \code
+ * aom_img_wrap(img, fmt, d_w, d_h, stride_align, (unsigned char *)1);
+ * ... calculate buffer size and allocate buffer as desribed earlier
+ * aom_img_wrap(img, fmt, d_w, d_h, stride_align, img_data);
+ * \endcode
  */
 aom_image_t *aom_img_wrap(aom_image_t *img, aom_img_fmt_t fmt, unsigned int d_w,
                           unsigned int d_h, unsigned int stride_align,