From: MyungJoo Ham Date: Thu, 21 Jun 2018 02:18:06 +0000 (+0900) Subject: [Doxygen] Add doxygen entries for common headers and conveter X-Git-Tag: v0.0.1~141 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=3d2f3661bdf3453ec261979a8f276c14f1cda54b;p=platform%2Fupstream%2Fnnstreamer.git [Doxygen] Add doxygen entries for common headers and conveter To comply with doxygen, a few more entires are added. Hope this will help developers using common headers. Signed-off-by: MyungJoo Ham --- diff --git a/gst/tensor_converter/tensor_converter.c b/gst/tensor_converter/tensor_converter.c index 878592f2..96583bfa 100644 --- a/gst/tensor_converter/tensor_converter.c +++ b/gst/tensor_converter/tensor_converter.c @@ -41,7 +41,8 @@ * License along with this library; if not, write to the * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. - * + */ +/** * @file tensor_converter.c * @date 26 Mar 2018 * @brief GStreamer plugin to convert media types to tensors (as a filter for other general neural network filters) @@ -189,7 +190,6 @@ gst_tensor_converter_class_init (GstTensor_ConverterClass * g_class) gst_static_pad_template_get (&src_factory)); gst_element_class_add_pad_template (gstelement_class, gst_static_pad_template_get (&sink_factory)); - /* Refer: https://gstreamer.freedesktop.org/documentation/design/element-transform.html */ trans_class->passthrough_on_same_caps = FALSE; @@ -211,7 +211,8 @@ gst_tensor_converter_class_init (GstTensor_ConverterClass * g_class) */ } -/* initialize the new element +/** + * @brief initialize the new element (G_DEFINE_TYPE requires this) * instantiate pads and add them to element * set pad calback functions * initialize instance structure @@ -226,6 +227,9 @@ gst_tensor_converter_init (GstTensor_Converter * filter) filter->disableInPlace = FALSE; } +/** + * @brief Set property (gst element vmethod) + */ static void gst_tensor_converter_set_property (GObject * object, guint prop_id, const GValue * value, GParamSpec * pspec) @@ -245,6 +249,9 @@ gst_tensor_converter_set_property (GObject * object, guint prop_id, } } +/** + * @brief Get property (gst element vmethod) + */ static void gst_tensor_converter_get_property (GObject * object, guint prop_id, GValue * value, GParamSpec * pspec) @@ -264,7 +271,10 @@ gst_tensor_converter_get_property (GObject * object, guint prop_id, } } -/* @brief Return 1 if we need to remove stride per row from the stream data */ +/** + * @brief Determine if we need zero-padding (internal static function) + * @return 1 if we need to remove stride per row from the stream data. 0 otherwise. + */ static int remove_stride_padding_per_row (const gchar * format, int width) { @@ -286,7 +296,10 @@ remove_stride_padding_per_row (const gchar * format, int width) return FALSE; \ ; /** - * @brief Configure tensor metadata from sink caps + * @brief Configure tensor metadata from sink caps (internal static function) + * @param caps the sink cap. + * @param filter "this" pointer to be configured. + * @return FALSE if error. TRUE if ok. */ static gboolean gst_tensor_converter_configure_tensor (const GstCaps * caps, @@ -373,7 +386,8 @@ gst_tensor_converter_configure_tensor (const GstCaps * caps, } -/* entry point to initialize the plug-in +/** + * @brief entry point to initialize the plug-in * initialize the plug-in itself * register the element factories and other features */ @@ -391,7 +405,8 @@ tensor_converter_init (GstPlugin * tensor_converter) GST_RANK_NONE, GST_TYPE_TENSOR_CONVERTER); } -/* PACKAGE: this is usually set by autotools depending on some _INIT macro +/** + * PACKAGE: this is usually set by autotools depending on some _INIT macro * in configure.ac and then written into and defined in config.h, but we can * just set it ourselves here in case someone doesn't use autotools to * compile this code. GST_PLUGIN_DEFINE needs PACKAGE to be defined. @@ -411,6 +426,13 @@ GST_PLUGIN_DEFINE (GST_VERSION_MAJOR, tensor_converter_init, VERSION, "LGPL", "GStreamer", "http://gstreamer.net/"); +/** + * @brief copies sink pad buffer to src pad buffer (internal static function) + * @param filter "this" pointer + * @param inbuf sink pad buffer + * @param outbuf src pad buffer + * @return GST_FLOW_OK if ok. other values represents error + */ static GstFlowReturn gst_c2t_transformer_videoframe (GstTensor_Converter * filter, GstBuffer * inbuf, GstBuffer * outbuf) @@ -482,6 +504,9 @@ gst_c2t_transformer_videoframe (GstTensor_Converter * return GST_FLOW_ERROR; } +/** + * @breif non-ip transform. required vmethod for BaseTransform class. + */ static GstFlowReturn gst_tensor_converter_transform (GstBaseTransform * trans, GstBuffer * inbuf, GstBuffer * outbuf) @@ -521,6 +546,9 @@ unknown_type: return GST_FLOW_NOT_SUPPORTED; } +/** + * @breif in-place transform. required vmethod for BaseTransform class. + */ static GstFlowReturn gst_tensor_converter_transform_ip (GstBaseTransform * trans, GstBuffer * buf) { @@ -591,12 +619,12 @@ unknown_type: } /** - * @brief configure tensor-srcpad cap from "proposed" cap. + * @brief configure srcpad cap from "proposed" cap. (required vmethod for BaseTransform) * - * @trans ("this" pointer) - * @direction (why do we need this?) - * @caps sinkpad cap - * @filter this element's cap (don't know specifically.) + * @param trans ("this" pointer) + * @param direction (why do we need this?) + * @param caps sinkpad cap + * @param filter this element's cap (don't know specifically.) */ static GstCaps * gst_tensor_converter_transform_caps (GstBaseTransform * trans, @@ -758,6 +786,9 @@ gst_tensor_converter_transform_caps (GstBaseTransform * trans, return NULL; } +/** + * @brief fixate caps. required vmethod of BaseTransform + */ static GstCaps * gst_tensor_converter_fixate_caps (GstBaseTransform * trans, GstPadDirection direction, GstCaps * caps, GstCaps * othercaps) @@ -790,6 +821,9 @@ gst_tensor_converter_fixate_caps (GstBaseTransform * trans, return result; } +/** + * @brief set caps. required vmethod of BaseTransform + */ static gboolean gst_tensor_converter_set_caps (GstBaseTransform * trans, GstCaps * incaps, GstCaps * outcaps) diff --git a/gst/tensor_converter/tensor_converter.h b/gst/tensor_converter/tensor_converter.h index 95522eb6..bf17ba24 100644 --- a/gst/tensor_converter/tensor_converter.h +++ b/gst/tensor_converter/tensor_converter.h @@ -111,7 +111,7 @@ struct _GstTensor_Converter tensor_type type; /**< Type of each element in the tensor. User must designate this. Otherwise, this is UINT8 for video/x-raw byte stream */ gint framerate_numerator; /**< framerate is in fraction, which is numerator/denominator */ gint framerate_denominator; /**< framerate is in fraction, which is numerator/denominator */ - gsize tensorFrameSize; + gsize tensorFrameSize; /**< Size of a single tensor frame in # bytes */ }; /* diff --git a/include/tensor_common.h b/include/tensor_common.h index ebff9fc3..b832d352 100644 --- a/include/tensor_common.h +++ b/include/tensor_common.h @@ -1,4 +1,4 @@ -/* +/** * NNStreamer Common Header * Copyright (C) 2018 MyungJoo Ham * @@ -39,7 +39,8 @@ * License along with this library; if not, write to the * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. - * + */ +/** * @file tensor_common.h * @date 23 May 2018 * @brief Common header file for NNStreamer, the GStreamer plugin for neural networks @@ -48,7 +49,6 @@ * @author MyungJoo Ham * */ - #ifndef __GST_TENSOR_COMMON_H__ #define __GST_TENSOR_COMMON_H__ @@ -76,11 +76,11 @@ G_BEGIN_DECLS * There is no restrictions for the outputs. */ typedef enum _nns_media_type { - _NNS_VIDEO = 0, - _NNS_AUDIO, /* Not Supported Yet */ - _NNS_STRING, /* Not Supported Yet */ + _NNS_VIDEO = 0, /**< supposedly video/x-raw */ + _NNS_AUDIO, /**< Not Supported Yet */ + _NNS_STRING, /**< Not Supported Yet */ - _NNS_MEDIA_END, + _NNS_MEDIA_END, /**< End Marker */ } media_type; /** @@ -131,6 +131,9 @@ extern int get_tensor_dimension(const gchar* param, tensor_dim dim); */ extern size_t get_tensor_element_count(tensor_dim dim); +/** + * @brief Make str(xyz) ==> "xyz" with macro expansion + */ #define str(s) xstr(s) #define xstr(s) #s @@ -143,6 +146,10 @@ extern size_t get_tensor_element_count(tensor_dim dim); g_message(__VA_ARGS__); \ } while (0) #endif + +/** + * @brief Debug message print. In Tizen, it uses dlog; otherwise,m it uses g_message(). + */ #define debug_print(cond, ...) \ do { \ if ((cond) == TRUE) { \ @@ -150,6 +157,9 @@ extern size_t get_tensor_element_count(tensor_dim dim); } \ } while (0) +/** + * @brief Error message print. In Tizen, it uses dlog; otherwise,m it uses g_message(). + */ #define err_print(...) dlog_print(DLOG_ERROR, "nnstreamer", __VA_ARGS__) G_END_DECLS diff --git a/include/tensor_filter_custom.h b/include/tensor_filter_custom.h index 86bd14f3..fd35ffaa 100644 --- a/include/tensor_filter_custom.h +++ b/include/tensor_filter_custom.h @@ -39,7 +39,8 @@ * License along with this library; if not, write to the * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. - * + */ +/** * @file tensor_filter_custom.h * @date 01 Jun 2018 * @brief Custom tensor post-processing interface for NNStreamer suite for post-processing code developers. @@ -113,13 +114,17 @@ typedef int (*NNS_custom_invoke)(void *private_data, const GstTensor_Filter_Prop * Note that exery function pointer is MANDATORY! */ struct _NNStreamer_custom_class { - NNS_custom_init_func initfunc; - NNS_custom_exit_func exitfunc; - NNS_custom_get_input_dimension getInputDim; - NNS_custom_get_output_dimension getOutputDim; - NNS_custom_invoke invoke; + NNS_custom_init_func initfunc; /**< called before any other callbacks from tensor_filter_custom.c */ + NNS_custom_exit_func exitfunc; /**< will not call other callbacks after this call */ + NNS_custom_get_input_dimension getInputDim; /**< a custom filter is required to provide input tensor dimension */ + NNS_custom_get_output_dimension getOutputDim; /**< a custom filter is require dto provide output tensor dimension */ + NNS_custom_invoke invoke; /**< the main function, "invoke", that transforms input to output */ }; typedef struct _NNStreamer_custom_class NNStreamer_custom_class; + +/** + * @brief A custom filter MUST define NNStreamer_custom. This object represents the custom filter itself. + */ extern NNStreamer_custom_class *NNStreamer_custom; #endif /*__NNS_TENSOR_FILTER_CUSTOM_H__*/ diff --git a/include/tensor_typedef.h b/include/tensor_typedef.h index 6b704874..e18c6d65 100644 --- a/include/tensor_typedef.h +++ b/include/tensor_typedef.h @@ -1,4 +1,4 @@ -/* +/** * NNStreamer Common Header, Typedef part, for export as devel package. * Copyright (C) 2018 MyungJoo Ham * @@ -39,7 +39,8 @@ * License along with this library; if not, write to the * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. - * + */ +/** * @file tensor_common_typedef.h * @date 01 Jun 2018 * @brief Common header file for NNStreamer, the GStreamer plugin for neural networks @@ -51,7 +52,6 @@ * * This fils it to be packaged as "devel" package for NN developers. */ - #ifndef __GST_TENSOR_TYPEDEF_H__ #define __GST_TENSOR_TYPEDEF_H__ @@ -76,15 +76,15 @@ typedef enum _nns_tensor_type { } tensor_type; /** - * @brief NN Frameworks + * @brief NN Frameworks available for the tensor_filter element. */ typedef enum _nnfw_type { - _T_F_UNDEFINED = 0, /* Not defined or supported. Cannot proceed in this status */ + _T_F_UNDEFINED = 0, /**< Not defined or supported. Cannot proceed in this status */ - _T_F_CUSTOM, /* NYI. Custom other/tensor -> other/tensor shared object (dysym) */ - _T_F_TENSORFLOW_LITE, /* NYI */ - _T_F_TENSORFLOW, /* NYI */ - _T_F_CAFFE2, /* NYI */ + _T_F_CUSTOM, /**< Custom filter provided as a shared object (dysym) */ + _T_F_TENSORFLOW_LITE, /**< In Progress */ + _T_F_TENSORFLOW, /**< NYI */ + _T_F_CAFFE2, /**< NYI */ _T_F_NNFW_END, } nnfw_type;