Enabled implicit stride in k4a_image_create (#819)

* Enabled implicit stride in k4a_image_create
* Added note on default parameters to standards.md

Author: Brent-A

docs/standards.md

@@ -46,6 +46,7 @@ allow the reader to quickly and easily tell the difference between internal and
  there is nothing the user can do to resolve the issue, then it is acceptable to crash. If there is action the
  user could take (not including an application restart or PC reboot), then returning an error specific to the recovery
  action is acceptable.
+* Don't use default parameters in public APIs (C++/C#)
 
 ## Clang-format
 

include/k4a/k4a.h

@@ -595,6 +595,7 @@ K4A_EXPORT float k4a_capture_get_temperature_c(k4a_capture_t capture_handle);
  *
  * \param stride_bytes
  * The number of bytes per horizontal line of the image.
+ * If set to 0, the stride will be set to the minimum size given the \p format and \p width_pixels.
  *
  * \param image_handle
  * Pointer to store image handle in.

src/csharp/SDK/Image.cs

@@ -46,7 +46,7 @@ public class Image : IMemoryOwner<byte>, IDisposable
         /// <param name="format">The pixel format of the image. Must be a format with a constant pixel size.</param>
         /// <param name="widthPixels">Width of the image in pixels.</param>
         /// <param name="heightPixels">Height of the image in pixels.</param>
-        /// <param name="strideBytes">Stride of the image in bytes. Must be as large as the width times the size of a pixel.</param>
+        /// <param name="strideBytes">Stride of the image in bytes. Must be as large as the width times the size of a pixel. Set to zero for the default if available for that format.</param>
         public Image(ImageFormat format, int widthPixels, int heightPixels, int strideBytes)
         {
             // Hook the native allocator and register this object.
@@ -69,26 +69,6 @@ public Image(ImageFormat format, int widthPixels, int heightPixels, int strideBy
         /// <param name="heightPixels">Height of the image in pixels.</param>
         public Image(ImageFormat format, int widthPixels, int heightPixels)
         {
-            int pixelSize;
-            switch (format)
-            {
-                case ImageFormat.ColorBGRA32:
-                    pixelSize = 4;
-                    break;
-                case ImageFormat.Depth16:
-                case ImageFormat.IR16:
-                case ImageFormat.Custom16:
-                    pixelSize = 2;
-                    break;
-                case ImageFormat.Custom8:
-                    pixelSize = 1;
-                    break;
-                default:
-                    throw new AzureKinectException($"Unable to allocate array for format {format}");
-            }
-
-            int stride_bytes = widthPixels * pixelSize;
-
             // Hook the native allocator and register this object.
             // .Dispose() will be called on this object when the allocator is shut down.
             Allocator.Singleton.RegisterForDisposal(this);
@@ -98,7 +78,7 @@ public Image(ImageFormat format, int widthPixels, int heightPixels)
                 format,
                 widthPixels,
                 heightPixels,
-                stride_bytes,
+                0,
                 image_handle: out this.handle));
 #pragma warning restore CA2000 // Dispose objects before losing scope
         }

src/image/image.c

@@ -186,6 +186,12 @@ k4a_result_t image_create(k4a_image_format_t format,
 
     case K4A_IMAGE_FORMAT_COLOR_NV12:
     {
+        if (stride_bytes == 0)
+        {
+            // If stride isn't specified, assume the minimum stride
+            stride_bytes = width_pixels;
+        }
+
         if (height_pixels % 2 != 0)
         {
             LOG_ERROR("NV12 requires an even number of lines. Height %d is invalid.", height_pixels);
@@ -215,6 +221,12 @@ k4a_result_t image_create(k4a_image_format_t format,
     // 1 Byte per pixel
     case K4A_IMAGE_FORMAT_CUSTOM8:
     {
+        if (stride_bytes == 0)
+        {
+            // If stride isn't specified, assume the minimum stride
+            stride_bytes = width_pixels;
+        }
+
         if (stride_bytes < 1 * width_pixels)
         {
             LOG_ERROR("Insufficient stride (%d bytes) to represent image width (%d pixels).",
@@ -235,6 +247,12 @@ k4a_result_t image_create(k4a_image_format_t format,
     case K4A_IMAGE_FORMAT_IR16:
     case K4A_IMAGE_FORMAT_CUSTOM16:
     {
+        if (stride_bytes == 0)
+        {
+            // If stride isn't specified, assume the minimum stride
+            stride_bytes = width_pixels * 2;
+        }
+
         if (stride_bytes < 2 * width_pixels)
         {
             LOG_ERROR("Insufficient stride (%d bytes) to represent image width (%d pixels).",
@@ -253,6 +271,12 @@ k4a_result_t image_create(k4a_image_format_t format,
     // 2 Bytes per pixel
     case K4A_IMAGE_FORMAT_COLOR_YUY2:
     {
+        if (stride_bytes == 0)
+        {
+            // If stride isn't specified, assume the minimum stride
+            stride_bytes = width_pixels * 2;
+        }
+
         if (width_pixels % 2 != 0)
         {
             LOG_ERROR("YUY2 requires an even number of pixels per line. Width of %d is invalid.", width_pixels);
@@ -276,6 +300,12 @@ k4a_result_t image_create(k4a_image_format_t format,
     // 4 Bytes per pixel
     case K4A_IMAGE_FORMAT_COLOR_BGRA32:
     {
+        if (stride_bytes == 0)
+        {
+            // If stride isn't specified, assume the minimum stride
+            stride_bytes = width_pixels * 4;
+        }
+
         if (stride_bytes < 4 * width_pixels)
         {
             LOG_ERROR("Insufficient stride (%d bytes) to represent image width (%d pixels).",

tests/UnitTests/allocator_ut/allocator.cpp

@@ -190,10 +190,6 @@ TEST(allocator_ut, image_api_validation)
         ASSERT_EQ(K4A_RESULT_FAILED,
                   image_create(K4A_IMAGE_FORMAT_COLOR_NV12, 10, 10, 1, ALLOCATION_SOURCE_USER, NULL));
 
-        // Stride of zero
-        ASSERT_EQ(K4A_RESULT_FAILED,
-                  image_create(K4A_IMAGE_FORMAT_COLOR_NV12, 10, 10, 0, ALLOCATION_SOURCE_USER, &image));
-
         // Stride length
         // Validate a valid length and an invalid length
 
@@ -217,6 +213,11 @@ TEST(allocator_ut, image_api_validation)
         //   Odd number of columns
         ASSERT_EQ(K4A_RESULT_FAILED,
                   image_create(K4A_IMAGE_FORMAT_COLOR_NV12, 11, 10, 20, ALLOCATION_SOURCE_USER, &image));
+        // Stride of zero (should succeed and infer the minimum stride)
+        ASSERT_EQ(K4A_RESULT_SUCCEEDED,
+                  image_create(K4A_IMAGE_FORMAT_COLOR_NV12, 10, 10, 0, ALLOCATION_SOURCE_USER, &image));
+        ASSERT_EQ(10, image_get_stride_bytes(image));
+        image_dec_ref(image);
 
         // YUY2
         //   Minimum stride
@@ -240,6 +241,11 @@ TEST(allocator_ut, image_api_validation)
         //   Odd number of columns
         ASSERT_EQ(K4A_RESULT_FAILED,
                   image_create(K4A_IMAGE_FORMAT_COLOR_YUY2, 11, 10, 20, ALLOCATION_SOURCE_USER, &image));
+        // Stride of zero (should succeed and infer the minimum stride)
+        ASSERT_EQ(K4A_RESULT_SUCCEEDED,
+                  image_create(K4A_IMAGE_FORMAT_COLOR_YUY2, 10, 10, 0, ALLOCATION_SOURCE_USER, &image));
+        ASSERT_EQ(10 * 2, image_get_stride_bytes(image));
+        image_dec_ref(image);
 
         // BGRA32
         //   Minimum stride
@@ -250,6 +256,11 @@ TEST(allocator_ut, image_api_validation)
         //   Insufficient stride
         ASSERT_EQ(K4A_RESULT_FAILED,
                   image_create(K4A_IMAGE_FORMAT_COLOR_BGRA32, 10, 10, 39, ALLOCATION_SOURCE_USER, &image));
+        // Stride of zero (should succeed and infer the minimum stride)
+        ASSERT_EQ(K4A_RESULT_SUCCEEDED,
+                  image_create(K4A_IMAGE_FORMAT_COLOR_BGRA32, 10, 10, 0, ALLOCATION_SOURCE_USER, &image));
+        ASSERT_EQ(10 * 4, image_get_stride_bytes(image));
+        image_dec_ref(image);
 
         // MJPEG (no length is valid)
         ASSERT_EQ(K4A_RESULT_FAILED,
@@ -264,6 +275,11 @@ TEST(allocator_ut, image_api_validation)
         //   Insufficient stride
         ASSERT_EQ(K4A_RESULT_FAILED,
                   image_create(K4A_IMAGE_FORMAT_DEPTH16, 10, 10, 19, ALLOCATION_SOURCE_USER, &image));
+        // Stride of zero (should succeed and infer the minimum stride)
+        ASSERT_EQ(K4A_RESULT_SUCCEEDED,
+                  image_create(K4A_IMAGE_FORMAT_DEPTH16, 10, 10, 0, ALLOCATION_SOURCE_USER, &image));
+        ASSERT_EQ(10 * 2, image_get_stride_bytes(image));
+        image_dec_ref(image);
 
         // Custom8
         //   Minimum stride
@@ -274,6 +290,11 @@ TEST(allocator_ut, image_api_validation)
         //   Insufficient stride
         ASSERT_EQ(K4A_RESULT_FAILED,
                   (int)image_create(K4A_IMAGE_FORMAT_CUSTOM8, 10, 10, 9, ALLOCATION_SOURCE_USER, &image));
+        // Stride of zero (should succeed and infer the minimum stride)
+        ASSERT_EQ(K4A_RESULT_SUCCEEDED,
+                  image_create(K4A_IMAGE_FORMAT_CUSTOM8, 10, 10, 0, ALLOCATION_SOURCE_USER, &image));
+        ASSERT_EQ(10 * 1, image_get_stride_bytes(image));
+        image_dec_ref(image);
 
         // Height of zero
         ASSERT_EQ(K4A_RESULT_FAILED,