diff --git a/src/bindings/python/src/pyopenvino/core/remote_context.cpp b/src/bindings/python/src/pyopenvino/core/remote_context.cpp index e10bb3512900c9..ca8648ce77074f 100644 --- a/src/bindings/python/src/pyopenvino/core/remote_context.cpp +++ b/src/bindings/python/src/pyopenvino/core/remote_context.cpp @@ -16,13 +16,33 @@ namespace py = pybind11; void regclass_RemoteContext(py::module m) { py::class_> cls(m, "RemoteContext"); - cls.def("get_device_name", [](RemoteContextWrapper& self) { - return self.context.get_device_name(); - }); + cls.def( + "get_device_name", + [](RemoteContextWrapper& self) { + return self.context.get_device_name(); + }, + R"( + Returns name of a device on which the context is allocated. + + :return: A device name string in fully specified format `[.[.]]`. + :rtype: str + )"); + + cls.def( + "get_params", + [](RemoteContextWrapper& self) { + return self.context.get_params(); + }, + R"( + Returns a dict of device-specific parameters required for low-level + operations with the underlying context. + Parameters include device/context handles, access flags, etc. + Content of the returned dict depends on remote execution context that is + currently set on the device (working scenario). - cls.def("get_params", [](RemoteContextWrapper& self) { - return self.context.get_params(); - }); + :return: A dictionary of device-specific parameters. + :rtype: dict + )"); cls.def( "create_tensor", @@ -35,7 +55,21 @@ void regclass_RemoteContext(py::module m) { }, py::arg("type"), py::arg("shape"), - py::arg("properties")); + py::arg("properties"), + R"( + Allocates memory tensor in device memory or wraps user-supplied memory handle + using the specified tensor description and low-level device-specific parameters. + Returns the object that implements the RemoteTensor interface. + + :param type: Defines the element type of the tensor. + :type type: openvino.Type + :param shape: Defines the shape of the tensor. + :type shape: openvino.Shape + :param properties: dict of the low-level tensor object parameters. + :type properties: dict + :return: A remote tensor instance. + :rtype: openvino.RemoteTensor + )"); cls.def( "create_host_tensor", @@ -43,7 +77,20 @@ void regclass_RemoteContext(py::module m) { return self.context.create_host_tensor(type, shape); }, py::arg("type"), - py::arg("shape")); + py::arg("shape"), + R"( + This method is used to create a host tensor object friendly for the device in + current context. For example, GPU context may allocate USM host memory + (if corresponding extension is available), which could be more efficient + than regular host memory. + + :param type: Defines the element type of the tensor. + :type type: openvino.Type + :param shape: Defines the shape of the tensor. + :type shape: openvino.Shape + :return: A tensor instance with device friendly memory. + :rtype: openvino.Tensor + )"); } void regclass_VAContext(py::module m) { @@ -59,7 +106,20 @@ void regclass_VAContext(py::module m) { }), py::arg("core"), py::arg("display"), - py::arg("target_tile_id") = -1); + py::arg("target_tile_id") = -1, + R"( + Constructs remote context object from valid VA display handle. + + :param core: OpenVINO Runtime Core object. + :type core: openvino.Core + :param device: A valid `VADisplay` to create remote context from. + :type device: Any + :param target_tile_id: Desired tile id within given context for multi-tile system. + Default value (-1) means that root device should be used. + :type target_tile_id: int + :return: A context instance. + :rtype: openvino.VAContext + )"); cls.def( "create_tensor_nv12", @@ -75,7 +135,20 @@ void regclass_VAContext(py::module m) { }, py::arg("height"), py::arg("width"), - py::arg("nv12_surface")); + py::arg("nv12_surface"), + R"( + This function is used to obtain a NV12 tensor from NV12 VA decoder output. + The result contains two remote tensors for Y and UV planes of the surface. + + :param height: A height of Y plane. + :type height: int + :param width: A width of Y plane + :type width: int + :param nv12_surface: NV12 `VASurfaceID` to create NV12 from. + :type nv12_surface: int + :return: A pair of remote tensors for each plane. + :rtype: Tuple[openvino.VASurfaceTensor, openvino.VASurfaceTensor] + )"); cls.def( "create_tensor", @@ -92,5 +165,19 @@ void regclass_VAContext(py::module m) { py::arg("type"), py::arg("shape"), py::arg("surface"), - py::arg("plane") = 0); + py::arg("plane") = 0, + R"( + Create remote tensor from VA surface handle. + + :param type: Defines the element type of the tensor. + :type type: openvino.Type + :param shape: Defines the shape of the tensor. + :type shape: openvino.Shape + :param surface: `VASurfaceID` to create tensor from. + :type surface: int + :param plane: An index of a plane inside `VASurfaceID` to create tensor from. Default: 0 + :type plane: int + :return: A remote tensor instance wrapping `VASurfaceID`. + :rtype: openvino.VASurfaceTensor + )"); } diff --git a/src/bindings/python/src/pyopenvino/core/remote_tensor.cpp b/src/bindings/python/src/pyopenvino/core/remote_tensor.cpp index dbe50135590976..034b9b425b7634 100644 --- a/src/bindings/python/src/pyopenvino/core/remote_tensor.cpp +++ b/src/bindings/python/src/pyopenvino/core/remote_tensor.cpp @@ -16,21 +16,51 @@ void regclass_RemoteTensor(py::module m) { "RemoteTensor", py::base()); - cls.def("get_device_name", [](RemoteTensorWrapper& self) { - return self.tensor.get_device_name(); - }); + cls.def( + "get_device_name", + [](RemoteTensorWrapper& self) { + return self.tensor.get_device_name(); + }, + R"( + Returns name of a device on which the tensor is allocated. - cls.def("get_params", [](RemoteTensorWrapper& self) { - return self.tensor.get_params(); - }); + :return: A device name string in fully specified format `[.[.]]`. + :rtype: str + )"); - cls.def("copy_to", [](RemoteTensorWrapper& self, py::object& dst) { - Common::utils::raise_not_implemented(); - }); + cls.def( + "get_params", + [](RemoteTensorWrapper& self) { + return self.tensor.get_params(); + }, + R"( + Returns a dict of device-specific parameters required for low-level + operations with the underlying tensor. + Parameters include device/context/surface/buffer handles, access flags, etc. + Content of the returned dict depends on remote execution context that is + currently set on the device (working scenario). + + :return: A dictionary of device-specific parameters. + :rtype: dict + )"); + + cls.def( + "copy_to", + [](RemoteTensorWrapper& self, py::object& dst) { + Common::utils::raise_not_implemented(); + }, + R"( + This method is not implemented. + )"); - cls.def_property_readonly("data", [](RemoteTensorWrapper& self) { - Common::utils::raise_not_implemented(); - }); + cls.def_property_readonly( + "data", + [](RemoteTensorWrapper& self) { + Common::utils::raise_not_implemented(); + }, + R"( + This property is not implemented. + )"); cls.def_property( "bytes_data", @@ -39,7 +69,10 @@ void regclass_RemoteTensor(py::module m) { }, [](RemoteTensorWrapper& self, py::object& other) { Common::utils::raise_not_implemented(); - }); + }, + R"( + This property is not implemented. + )"); cls.def_property( "str_data", @@ -48,7 +81,10 @@ void regclass_RemoteTensor(py::module m) { }, [](RemoteTensorWrapper& self, py::object& other) { Common::utils::raise_not_implemented(); - }); + }, + R"( + This property is not implemented. + )"); cls.def("__repr__", [](const RemoteTensorWrapper& self) { std::stringstream ss; @@ -64,17 +100,38 @@ void regclass_VASurfaceTensor(py::module m) { m, "VASurfaceTensor"); - cls.def_property_readonly("surface_id", [](VASurfaceTensorWrapper& self) { - return self.surface_id(); - }); + cls.def_property_readonly( + "surface_id", + [](VASurfaceTensorWrapper& self) { + return self.surface_id(); + }, + R"( + Returns ID of underlying video decoder surface. - cls.def_property_readonly("plane_id", [](VASurfaceTensorWrapper& self) { - return self.plane_id(); - }); + :return: VASurfaceID of the tensor. + :rtype: int + )"); - cls.def_property_readonly("data", [](VASurfaceTensorWrapper& self) { - Common::utils::raise_not_implemented(); - }); + cls.def_property_readonly( + "plane_id", + [](VASurfaceTensorWrapper& self) { + return self.plane_id(); + }, + R"( + Returns plane ID of underlying video decoder surface. + + :return: Plane ID of underlying video decoder surface. + :rtype: int + )"); + + cls.def_property_readonly( + "data", + [](VASurfaceTensorWrapper& self) { + Common::utils::raise_not_implemented(); + }, + R"( + This property is not implemented. + )"); cls.def("__repr__", [](const VASurfaceTensorWrapper& self) { std::stringstream ss;