Publishing 2019 R1 content

[platform/upstream/dldt.git] / inference-engine / thirdparty / clDNN / api / C / broadcast.h

diff --git a/inference-engine/thirdparty/clDNN/api/C/broadcast.h b/inference-engine/thirdparty/clDNN/api/C/broadcast.h
index d431b5c..d820de2 100644 (file)
--- a/inference-engine/thirdparty/clDNN/api/C/broadcast.h
+++ b/inference-engine/thirdparty/clDNN/api/C/broadcast.h
@@ -1,4 +1,4 @@
-// Copyright (c) 2018 Intel Corporation
+// Copyright (c) 2019 Intel Corporation
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -30,14 +30,16 @@
 extern "C" {
 #endif
 
-/// @brief Broadcasts input to specified output size (broadcast size).
+/// @brief Broadcasts input to defined by @p broadcast_sizes output. @p broadcast_axes are used to
+///        reinterpret input (reshape) inside algorithm.
 ///
-/// @details Takes input and copies it to output once or multiple times, until output will
-///          reach the sizes specified in @p broadcast_sizes.
+/// @details Takes input, reinterpret it according to @p broadcast_axes
+///          and copies it to output once or multiple times.
 /// @n
-/// @n Lets assume that:
+/// @n Simple example with empty @p broadcast_axes. Lets assume that:
 /// @n      <tt>input_sizes = (in_b, in_f, in_y, in_x)</tt>
 /// @n      <tt>broadcast_sizes = (bs_b, bs_f, bs_y, bs_x)</tt>
+/// @n      <tt>broadcast_axes = () - empty</tt>
 /// @n The input is broadcasted on each dimension where <tt>bs_{dim} > in_{dim}</tt> and <tt>bs_{dim}</tt>
 ///    is dividable by <tt>in_{dim}</tt> (input is copied <tt>bs_{dim} / in_{dim}</tt> times).
 ///    The dimensions where <tt>bs_{dim}</tt> is equal to <tt>in_{dim}</tt> remain unchanged.
@@ -46,22 +48,36 @@ extern "C" {
 /// @n      <tt>output[(b, f, y, x)] = input[(b % in_b, f % in_f, y % in_y, x % in_x)]</tt>
 /// @n where <tt>(b, f, y, x)</tt> is a position of value in a primitive output.
 /// @n
+/// @n More complicated example with non empty @p broadcast_axes. Lets assume that:
+/// @n      <tt>broadcast_sizes = (bs_b, bs_f, bs_y, bs_x)</tt>
+/// @n      <tt>broadcast_axes = (2)</tt>
+/// @n Taking into account broadcast_axes size (=1) primitive's input must be (4 - 1 = 3):
+/// @n      <tt>primitive input = (1, in_b, in_f, in_x)</tt>
+/// @n Due to broadcast_axes = (2) primitive will interpret input as:
+/// @n      <tt>primitive input(internal representation) = (in_b, in_f, 1, in_x)</tt>
+/// @n Now, you can apply broadcast rules from previous example to modified (reinterpreted)
+///    input and output:
+/// @n      <tt>input_sizes = (in_b, in_f, 1, in_x)</tt>
+/// @n      <tt>output_shape = (bs_b, bs_f, bs_y, bs_x)</tt>
+/// @n      <tt>broadcast_axes = () - empty</tt>
+/// @n
 /// @n@b Requirements:
-/// @n - @p broadcast_sizes must be positive on all dimensions and compatible
-///      with size of input (describe the same dimensions).
-/// @n - @p broadcast_sizes must be greater than or equal to input sizes on
-///      all dimensions. (For any dimension, if @p broadcast_sizes is lower
-///      than input size on the dimension then @p broadcast_sizes will be replaced
-///      by input size on this dimension.)
-/// @n - For any dimension, if @p broadcast_sizes is greater than input size on
-///      the dimension then @p broadcast_sizes must be dividable by input size
-///      on this dimension.
-/// @n Breaking any of these conditions will raise an exeption.
+/// @n - @p broadcast_sizes must be positive on all dimensions.
+/// @n - @p broadcast_axes size (dimensions count) must be within (inclusive) range
+///      0 - 4.
+/// @n - @p broadcast_axes mustn't have duplicate values.
+/// @n - Values of @p broadcast_axes must be within (inclusive) range 0 - 3
+/// @n - @p output_shape must be greater (dividable) than or equal to reinterpreted
+///      input on all dimensions.
+/// @n Breaking any of these conditions will raise an exception.
 CLDNN_BEGIN_PRIMITIVE_DESC(broadcast)
 /// @brief Sizes of broadcast. Output size of current primitive will match broadcast sizes (layout type
 ///        will not change).
-///        If @p broadcast_sizes are not specified (all zeros), the input sizes are used as @p broadcast_sizes.
 cldnn_tensor broadcast_sizes;
+/// @brief Array of axes positions from output shape (0-based, from left to right)
+///        along which broadcast should happen.
+cldnn_uint16_t_arr broadcast_axes;
+
 CLDNN_END_PRIMITIVE_DESC(broadcast)