GoWebScan API
 All Classes Files Functions Variables Typedefs Macros Modules Pages
GoWebScanProcess.h
Go to the documentation of this file.
1 /**
2 * @file GoWebScanProcess.h
3 * @brief Declares a GoWebScanProcess object.
4 *
5 * @internal
6 * Copyright (C) 2017-2018 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 
11 #ifndef GO_WEB_SCAN_PROCESS_H
12 #define GO_WEB_SCAN_PROCESS_H
13 
17 
18 kBeginHeader()
19 
20 /**
21 * @class GoWebScanProcess
22 * @extends kObject
23 * @ingroup GoWebScanSdk-Control
24 * @brief Represents a task for processing raw sensor data to produce system web tiles (Web
25 * mode) or detected objects (Detection mode).
26 * The GoWebScanProcess class accepts configuration via a GoWebScanConfig instance, and
27 * provides a simple API to initialize the processor, pass sensor data to the processor,
28 * retrieve completed system messages, and clear the processor. Internally, the
29 * processor delegates processing responsibilities to the Task classes in the Control
30 * group. A GoWebScanProcess object can optionally run processing tasks concurrently.
31 * Tasks are run when they receive messages, and messages are passed from task to task
32 * as processing steps execute. Task execution and message exchange are supported by
33 * the classes in the Pipe group.
34 *
35 * A GoWebScanProcess object has a GoWebScanPipe object, and each GoWebScanProcess Task
36 * object (e.g. GoWebScanProfileSampleTask) has an associated GoWebScanPipeTask.
37 * Individual processor tasks are passed references to downstream tasks (receivers) at
38 * initialization time (e.g a GoWebScanProfileSampleTask has a reference to the
39 * GoWebScanSyncTask to which it sends messages).
40 *
41 * Following initialization, the user application should pass inbound sensor messages
42 * to the GoWebScanProcess. The GoWebScanProcess handles the initial dispatch to various
43 * data sampling tasks. From there, messages flow from task to task, eventually
44 * resulting in outbound messages sent back to the GoWebScanProcess. Outbound messages
45 * are queued by the GoWebScanProcess object and can be accepted by the user application
46 * at any time.
47 
48 */
50 
51 /**
52 * Constructs a GoWebScanProcess object.
53 *
54 * @public @memberof GoWebScanProcess
55 * @param process Receives the constructed GoWebScanProcess object.
56 * @param config System configuration.
57 * @param allocator Memory allocator (or kNULL for default).
58 * @return Operation status.
59 */
60 GoWebScanFx(kStatus) GoWebScanProcess_Construct(GoWebScanProcess* process, GoWebScanConfig config, kAlloc allocator);
61 
62 /**
63  * Accepts inbound sensor messages and dispatches these messages to data processing tasks. The
64  * messages are cloned into internal message objects. As such, the GoDataSet object is still
65  * owned by the calling function and must be destroyed by it.
66  *
67  * @public @memberof GoWebScanProcess
68  * @param process GoWebScanProcess object.
69  * @param dataSet Sensor message. Must be of type GO_DATA_MESSAGE_TYPE_PROFILE for profile,
70  * GO_DATA_MESSAGE_TYPE_TRACHEID for tracheid, or GO_DATA_MESSAGE_TYPE_VIDEO for
71  * vision.
72  * @return Operation status.
73  */
74 GoWebScanFx(kStatus) GoWebScanProcess_Process(GoWebScanProcess process, GoDataSet dataSet);
75 
76 /**
77  * Returns outbound processed results if any are available. The function will return an error if
78  * the outbound queue is empty (no new result available), and so the function can be run in a
79  * loop until it fails to receieve all results in the queue. Ownership of the result is passed
80  * to the calling function. The result will be of type GoWebScanSystemMsg and will contain tiles
81  * for all data types (profile, tracheid, or vision) and planes (top or bottom) in the system.
82  * GoWebScanSystemMsg_TileAt() can be used to retrieve the system tiles for a specific data type
83  * and plane.
84  *
85  * @public @memberof GoWebScanProcess
86  * @param process GoWebScanProcess object.
87  * @param msg Receives the outbound processed result. Should be cast into a GoWebScanSystemMsg.
88  * @param timeout Timeout for receiving result.
89  * @return Operation status.
90  */
91 GoWebScanFx(kStatus) GoWebScanProcess_Receive(GoWebScanProcess process, GoWebScanPipeMsg* msg, k64s timeout);
92 
93 /**
94  * Initializes the processing tasks. Should be called prior to GoWebScanProcess_Process().
95  *
96  * @public @memberof GoWebScanProcess
97  * @param process GoWebScanProcess object.
98  * @return Operation status.
99  */
100 GoWebScanFx(kStatus) GoWebScanProcess_Start(GoWebScanProcess process);
101 
102 /**
103  * Aborts all outstanding processing and resets the state.
104  *
105  * @public @memberof GoWebScanProcess
106  * @param process GoWebScanProcess object.
107  * @return Operation status.
108  */
109 GoWebScanFx(kStatus) GoWebScanProcess_Clear(GoWebScanProcess process);
110 
111 /**
112  * Gets the current count of errors in the processor.
113  *
114  * @public @memberof GoWebScanProcess
115  * @param process GoWebScanProcess object.
116  * @return Error count.
117  */
118 GoWebScanFx(kSSize) GoWebScanProcess_ErrorCount(GoWebScanProcess process);
119 
120 kEndHeader()
121 #include <GoWebScanSdk/GoWebScanProcess.x.h>
122 
123 #endif
Represents a task for processing raw sensor data to produce system web tiles (Web mode) or detected o...
kStatus GoWebScanProcess_Receive(GoWebScanProcess process, GoWebScanPipeMsg *msg, k64s timeout)
Returns outbound processed results if any are available.
kStatus GoWebScanProcess_Clear(GoWebScanProcess process)
Aborts all outstanding processing and resets the state.
kStatus GoWebScanProcess_Start(GoWebScanProcess process)
Initializes the processing tasks.
Declares the GoWebScanPipeMsg class.
Essential GoWebScan declarations.
kSSize GoWebScanProcess_ErrorCount(GoWebScanProcess process)
Gets the current count of errors in the processor.
kStatus GoWebScanProcess_Construct(GoWebScanProcess *process, GoWebScanConfig config, kAlloc allocator)
Constructs a GoWebScanProcess object.
Base class for a msg that can be processed with a GoWebScanPipeTask and submitted to the GoWebScanPip...
kStatus GoWebScanProcess_Process(GoWebScanProcess process, GoDataSet dataSet)
Accepts inbound sensor messages and dispatches these messages to data processing tasks.
Represents a container for system-level parameters which are translated from user parameters set in G...
Declares a GoWebScanConfig object.