diff --git a/cscore/src/main/java/edu/wpi/cscore/AxisCamera.java b/cscore/src/main/java/edu/wpi/cscore/AxisCamera.java index 08dad5c362..8eef0b35cd 100644 --- a/cscore/src/main/java/edu/wpi/cscore/AxisCamera.java +++ b/cscore/src/main/java/edu/wpi/cscore/AxisCamera.java @@ -25,6 +25,7 @@ public class AxisCamera extends HttpCamera { /** * Create a source for an Axis IP camera. + * * @param name Source name (arbitrary unique identifier) * @param host Camera host IP or DNS name (e.g. "10.x.y.11") */ @@ -34,6 +35,7 @@ public class AxisCamera extends HttpCamera { /** * Create a source for an Axis IP camera. + * * @param name Source name (arbitrary unique identifier) * @param hosts Array of Camera host IPs/DNS names */ diff --git a/cscore/src/main/java/edu/wpi/cscore/CvSink.java b/cscore/src/main/java/edu/wpi/cscore/CvSink.java index 0e157890a5..c2c7d0e51b 100644 --- a/cscore/src/main/java/edu/wpi/cscore/CvSink.java +++ b/cscore/src/main/java/edu/wpi/cscore/CvSink.java @@ -17,6 +17,7 @@ public class CvSink extends VideoSink { * Create a sink for accepting OpenCV images. * WaitForFrame() must be called on the created sink to get each new * image. + * * @param name Source name (arbitrary unique identifier) */ public CvSink(String name) { @@ -38,6 +39,7 @@ public class CvSink extends VideoSink { /** * Set sink description. + * * @param description Description */ public void setDescription(String description) { @@ -48,6 +50,7 @@ public class CvSink extends VideoSink { * Wait for the next frame and get the image. * Times out (returning 0) after 0.225 seconds. * The provided image will have three 3-bit channels stored in BGR order. + * * @return Frame time, or 0 on error (call GetError() to obtain the error * message) */ @@ -59,6 +62,7 @@ public class CvSink extends VideoSink { * Wait for the next frame and get the image. * Times out (returning 0) after timeout seconds. * The provided image will have three 3-bit channels stored in BGR order. + * * @return Frame time, or 0 on error (call GetError() to obtain the error * message); the frame time is in 1 us increments. */ @@ -69,6 +73,7 @@ public class CvSink extends VideoSink { /** * Wait for the next frame and get the image. May block forever. * The provided image will have three 3-bit channels stored in BGR order. + * * @return Frame time, or 0 on error (call GetError() to obtain the error * message); the frame time is in 1 us increments. */ diff --git a/cscore/src/main/java/edu/wpi/cscore/CvSource.java b/cscore/src/main/java/edu/wpi/cscore/CvSource.java index 7d447d66d2..47cd409538 100644 --- a/cscore/src/main/java/edu/wpi/cscore/CvSource.java +++ b/cscore/src/main/java/edu/wpi/cscore/CvSource.java @@ -15,6 +15,7 @@ import org.opencv.core.Mat; public class CvSource extends VideoSource { /** * Create an OpenCV source. + * * @param name Source name (arbitrary unique identifier) * @param mode Video mode being generated */ @@ -28,6 +29,7 @@ public class CvSource extends VideoSource { /** * Create an OpenCV source. + * * @param name Source name (arbitrary unique identifier) * @param pixelFormat Pixel format * @param width width @@ -40,9 +42,11 @@ public class CvSource extends VideoSource { /** * Put an OpenCV image and notify sinks. - * Only 8-bit single-channel or 3-channel (with BGR channel order) images + * + *

Only 8-bit single-channel or 3-channel (with BGR channel order) images * are supported. If the format, depth or channel order is different, use * Mat.convertTo() and/or cvtColor() to convert it first. + * * @param image OpenCV image */ public void putFrame(Mat image) { @@ -59,6 +63,7 @@ public class CvSource extends VideoSource { /** * Set source connection status. Defaults to true. + * * @param connected True for connected, false for disconnected */ public void setConnected(boolean connected) { @@ -67,6 +72,7 @@ public class CvSource extends VideoSource { /** * Set source description. + * * @param description Description */ public void setDescription(String description) { @@ -75,6 +81,7 @@ public class CvSource extends VideoSource { /** * Create a property. + * * @param name Property name * @param kind Property kind * @param minimum Minimum value @@ -104,6 +111,7 @@ public class CvSource extends VideoSource { /** * Create an integer property. + * * @param name Property name * @param minimum Minimum value * @param maximum Maximum value @@ -131,6 +139,7 @@ public class CvSource extends VideoSource { /** * Create a boolean property. + * * @param name Property name * @param defaultValue Default value * @param value Current value @@ -150,6 +159,7 @@ public class CvSource extends VideoSource { /** * Create a string property. + * * @param name Property name * @param value Current value * @return Property @@ -170,6 +180,7 @@ public class CvSource extends VideoSource { /** * Configure enum property choices. + * * @param property Property * @param choices Choices */ @@ -179,6 +190,7 @@ public class CvSource extends VideoSource { /** * Configure enum property choices. + * * @param property Property * @param choices Choices * @deprecated Use {@code setEnumPropertyChoices} instead. diff --git a/cscore/src/main/java/edu/wpi/cscore/HttpCamera.java b/cscore/src/main/java/edu/wpi/cscore/HttpCamera.java index 43eeba3d22..4b700a98df 100644 --- a/cscore/src/main/java/edu/wpi/cscore/HttpCamera.java +++ b/cscore/src/main/java/edu/wpi/cscore/HttpCamera.java @@ -43,6 +43,7 @@ public class HttpCamera extends VideoCamera { /** * Create a source for a MJPEG-over-HTTP (IP) camera. + * * @param name Source name (arbitrary unique identifier) * @param url Camera URL (e.g. "http://10.x.y.11/video/stream.mjpg") */ @@ -52,6 +53,7 @@ public class HttpCamera extends VideoCamera { /** * Create a source for a MJPEG-over-HTTP (IP) camera. + * * @param name Source name (arbitrary unique identifier) * @param url Camera URL (e.g. "http://10.x.y.11/video/stream.mjpg") * @param kind Camera kind (e.g. kAxis) @@ -62,6 +64,7 @@ public class HttpCamera extends VideoCamera { /** * Create a source for a MJPEG-over-HTTP (IP) camera. + * * @param name Source name (arbitrary unique identifier) * @param urls Array of Camera URLs */ @@ -71,6 +74,7 @@ public class HttpCamera extends VideoCamera { /** * Create a source for a MJPEG-over-HTTP (IP) camera. + * * @param name Source name (arbitrary unique identifier) * @param urls Array of Camera URLs * @param kind Camera kind (e.g. kAxis) @@ -81,7 +85,8 @@ public class HttpCamera extends VideoCamera { /** * Get the kind of HTTP camera. - * Autodetection can result in returning a different value than the camera + * + *

Autodetection can result in returning a different value than the camera * was created with. */ public HttpCameraKind getHttpCameraKind() { diff --git a/cscore/src/main/java/edu/wpi/cscore/MjpegServer.java b/cscore/src/main/java/edu/wpi/cscore/MjpegServer.java index 03aa55aeab..67724f0ad6 100644 --- a/cscore/src/main/java/edu/wpi/cscore/MjpegServer.java +++ b/cscore/src/main/java/edu/wpi/cscore/MjpegServer.java @@ -13,6 +13,7 @@ package edu.wpi.cscore; public class MjpegServer extends VideoSink { /** * Create a MJPEG-over-HTTP server sink. + * * @param name Sink name (arbitrary unique identifier) * @param listenAddress TCP listen address (empty string for all addresses) * @param port TCP port number @@ -23,6 +24,7 @@ public class MjpegServer extends VideoSink { /** * Create a MJPEG-over-HTTP server sink. + * * @param name Sink name (arbitrary unique identifier) * @param port TCP port number */ diff --git a/cscore/src/main/java/edu/wpi/cscore/UsbCamera.java b/cscore/src/main/java/edu/wpi/cscore/UsbCamera.java index 6bfc844282..13689edbbf 100644 --- a/cscore/src/main/java/edu/wpi/cscore/UsbCamera.java +++ b/cscore/src/main/java/edu/wpi/cscore/UsbCamera.java @@ -13,6 +13,7 @@ package edu.wpi.cscore; public class UsbCamera extends VideoCamera { /** * Create a source for a USB camera based on device number. + * * @param name Source name (arbitrary unique identifier) * @param dev Device number (e.g. 0 for /dev/video0) */ @@ -22,6 +23,7 @@ public class UsbCamera extends VideoCamera { /** * Create a source for a USB camera based on device path. + * * @param name Source name (arbitrary unique identifier) * @param path Path to device (e.g. "/dev/video0" on Linux) */ @@ -31,6 +33,7 @@ public class UsbCamera extends VideoCamera { /** * Enumerate USB cameras on the local system. + * * @return Vector of USB camera information (one for each camera) */ public static UsbCameraInfo[] enumerateUsbCameras() { @@ -46,6 +49,7 @@ public class UsbCamera extends VideoCamera { /** * Set how verbose the camera connection messages are. + * * @param level 0=don't display Connecting message, 1=do display message */ void setConnectVerbose(int level) { diff --git a/cscore/src/main/java/edu/wpi/cscore/UsbCameraInfo.java b/cscore/src/main/java/edu/wpi/cscore/UsbCameraInfo.java index b00a4df32b..08c90b2c5e 100644 --- a/cscore/src/main/java/edu/wpi/cscore/UsbCameraInfo.java +++ b/cscore/src/main/java/edu/wpi/cscore/UsbCameraInfo.java @@ -13,6 +13,7 @@ package edu.wpi.cscore; public class UsbCameraInfo { /** * Create a new set of UsbCameraInfo. + * * @param dev Device number (e.g. N in '/dev/videoN' on Linux) * @param path Path to device if available (e.g. '/dev/video0' on Linux) * @param name Vendor/model name of the camera as provided by the USB driver diff --git a/cscore/src/main/java/edu/wpi/cscore/VideoListener.java b/cscore/src/main/java/edu/wpi/cscore/VideoListener.java index 187eae09d1..8dd62fa309 100644 --- a/cscore/src/main/java/edu/wpi/cscore/VideoListener.java +++ b/cscore/src/main/java/edu/wpi/cscore/VideoListener.java @@ -16,6 +16,7 @@ import java.util.function.Consumer; public class VideoListener implements AutoCloseable { /** * Create an event listener. + * * @param listener Listener function * @param eventMask Bitmask of VideoEvent.Type values * @param immediateNotify Whether callback should be immediately called with diff --git a/cscore/src/main/java/edu/wpi/cscore/VideoProperty.java b/cscore/src/main/java/edu/wpi/cscore/VideoProperty.java index 3115031277..eef86f6fa1 100644 --- a/cscore/src/main/java/edu/wpi/cscore/VideoProperty.java +++ b/cscore/src/main/java/edu/wpi/cscore/VideoProperty.java @@ -7,6 +7,9 @@ package edu.wpi.cscore; +/** + * A source or sink property. + */ public class VideoProperty { public enum Kind { kNone(0), kBoolean(1), kInteger(2), kString(4), kEnum(8); diff --git a/cscore/src/main/java/edu/wpi/cscore/VideoSink.java b/cscore/src/main/java/edu/wpi/cscore/VideoSink.java index 9c4b972b26..0e57928fb2 100644 --- a/cscore/src/main/java/edu/wpi/cscore/VideoSink.java +++ b/cscore/src/main/java/edu/wpi/cscore/VideoSink.java @@ -111,6 +111,7 @@ public class VideoSink implements AutoCloseable { /** * Get a property of the sink. + * * @param name Property name * @return Property (kind Property::kNone if no property with * the given name exists) @@ -136,6 +137,7 @@ public class VideoSink implements AutoCloseable { * Configure which source should provide frames to this sink. Each sink * can accept frames from only a single source, but a single source can * provide frames to multiple clients. + * * @param source Source */ public void setSource(VideoSource source) { @@ -148,6 +150,7 @@ public class VideoSink implements AutoCloseable { /** * Get the connected source. + * * @return Connected source; nullptr if no source connected. */ public VideoSource getSource() { @@ -158,6 +161,7 @@ public class VideoSink implements AutoCloseable { /** * Get a property of the associated source. + * * @param name Property name * @return Property (kind Property::kNone if no property with * the given name exists or no source connected) @@ -169,6 +173,7 @@ public class VideoSink implements AutoCloseable { /** * Enumerate all existing sinks. + * * @return Vector of sinks. */ @SuppressWarnings("PMD.AvoidInstantiatingObjectsInLoops") diff --git a/cscore/src/main/java/edu/wpi/cscore/VideoSource.java b/cscore/src/main/java/edu/wpi/cscore/VideoSource.java index ab43ebb1a8..dde32fbc02 100644 --- a/cscore/src/main/java/edu/wpi/cscore/VideoSource.java +++ b/cscore/src/main/java/edu/wpi/cscore/VideoSource.java @@ -127,6 +127,7 @@ public class VideoSource implements AutoCloseable { /** * Get a property. + * * @param name Property name * @return Property contents (of kind Property::kNone if no property with * the given name exists) @@ -169,6 +170,7 @@ public class VideoSource implements AutoCloseable { /** * Set the video mode. + * * @param pixelFormat desired pixel format * @param width desired width * @param height desired height @@ -181,6 +183,7 @@ public class VideoSource implements AutoCloseable { /** * Set the pixel format. + * * @param pixelFormat desired pixel format * @return True if set successfully */ @@ -190,6 +193,7 @@ public class VideoSource implements AutoCloseable { /** * Set the resolution. + * * @param width desired width * @param height desired height * @return True if set successfully @@ -200,6 +204,7 @@ public class VideoSource implements AutoCloseable { /** * Set the frames per second (FPS). + * * @param fps desired FPS * @return True if set successfully */ @@ -209,8 +214,10 @@ public class VideoSource implements AutoCloseable { /** * Get the actual FPS. - * CameraServerJNI#setTelemetryPeriod() must be called for this to be valid + * + *

CameraServerJNI#setTelemetryPeriod() must be called for this to be valid * (throws VisionException if telemetry is not enabled). + * * @return Actual FPS averaged over the telemetry period. */ public double getActualFPS() { @@ -220,8 +227,10 @@ public class VideoSource implements AutoCloseable { /** * Get the data rate (in bytes per second). - * CameraServerJNI#setTelemetryPeriod() must be called for this to be valid + * + *

CameraServerJNI#setTelemetryPeriod() must be called for this to be valid * (throws VisionException if telemetry is not enabled). + * * @return Data rate averaged over the telemetry period. */ public double getActualDataRate() { @@ -238,6 +247,7 @@ public class VideoSource implements AutoCloseable { /** * Enumerate all sinks connected to this source. + * * @return Vector of sinks. */ @SuppressWarnings("PMD.AvoidInstantiatingObjectsInLoops") @@ -252,6 +262,7 @@ public class VideoSource implements AutoCloseable { /** * Enumerate all existing sources. + * * @return Vector of sources. */ @SuppressWarnings("PMD.AvoidInstantiatingObjectsInLoops") diff --git a/cscore/src/main/native/include/cscore_c.h b/cscore/src/main/native/include/cscore_c.h index 182be3e7e5..345c011d7a 100644 --- a/cscore/src/main/native/include/cscore_c.h +++ b/cscore/src/main/native/include/cscore_c.h @@ -22,20 +22,29 @@ extern "C" { struct CvMat; -// -// The C API is handle-based. Sources and sinks are reference counted -// internally to the library. Any time a source or sink handle is returned -// or provided to a callback, the reference count is incremented. -// Calling CS_ReleaseSource() or CS_ReleaseSink() decrements the reference -// count, and when the reference count reaches zero, the object is destroyed. -// Connecting a source to a sink increments the reference count of the source, -// and when the sink is destroyed (its reference count reaches zero), the -// source reference count is decremented. -// +/** + * @defgroup cscore_c_api cscore C API + * + * Handle-based interface for C. + * + *

Sources and sinks are reference counted internally to the library. + * Any time a source or sink handle is returned or provided to a callback, + * the reference count is incremented. + * + *

Calling CS_ReleaseSource() or CS_ReleaseSink() decrements the reference + * count, and when the reference count reaches zero, the object is destroyed. + * + *

Connecting a source to a sink increments the reference count of the + * source, and when the sink is destroyed (its reference count reaches zero), + * the source reference count is decremented. + * + * @{ + */ -// -// Typedefs -// +/** + * @defgroup cscore_typedefs Typedefs + * @{ + */ typedef int CS_Bool; typedef int CS_Status; @@ -44,10 +53,11 @@ typedef CS_Handle CS_Property; typedef CS_Handle CS_Listener; typedef CS_Handle CS_Sink; typedef CS_Handle CS_Source; +/** @} */ -// -// Status values -// +/** + * Status values + */ enum CS_StatusValue { CS_PROPERTY_WRITE_FAILED = 2000, CS_OK = 0, @@ -62,9 +72,9 @@ enum CS_StatusValue { CS_TELEMETRY_NOT_ENABLED = -2008 }; -// -// Logging levels -// +/** + * Logging levels + */ enum CS_LogLevel { CS_LOG_CRITICAL = 50, CS_LOG_ERROR = 40, @@ -77,9 +87,9 @@ enum CS_LogLevel { CS_LOG_DEBUG4 = 6 }; -// -// Pixel formats -// +/** + * Pixel formats + */ enum CS_PixelFormat { CS_PIXFMT_UNKNOWN = 0, CS_PIXFMT_MJPEG, @@ -89,9 +99,9 @@ enum CS_PixelFormat { CS_PIXFMT_GRAY }; -// -// Frame formats -// +/** + * Video mode + */ typedef struct CS_VideoMode { int pixelFormat; int width; @@ -99,9 +109,9 @@ typedef struct CS_VideoMode { int fps; } CS_VideoMode; -// -// Property kinds -// +/** + * Property kinds + */ enum CS_PropertyKind { CS_PROP_NONE = 0, CS_PROP_BOOLEAN = 1, @@ -110,9 +120,9 @@ enum CS_PropertyKind { CS_PROP_ENUM = 8 }; -// -// Source kinds -// +/** + * Source kinds + */ enum CS_SourceKind { CS_SOURCE_UNKNOWN = 0, CS_SOURCE_USB = 1, @@ -120,9 +130,9 @@ enum CS_SourceKind { CS_SOURCE_CV = 4 }; -// -// HTTP Camera kinds -// +/** + * HTTP Camera kinds + */ enum CS_HttpCameraKind { CS_HTTP_UNKNOWN = 0, CS_HTTP_MJPGSTREAMER = 1, @@ -130,14 +140,14 @@ enum CS_HttpCameraKind { CS_HTTP_AXIS = 3 }; -// -// Sink kinds -// +/** + * Sink kinds + */ enum CS_SinkKind { CS_SINK_UNKNOWN = 0, CS_SINK_MJPEG = 2, CS_SINK_CV = 4 }; -// -// Listener event kinds -// +/** + * Listener event kinds + */ enum CS_EventKind { CS_SOURCE_CREATED = 0x0001, CS_SOURCE_DESTROYED = 0x0002, @@ -160,17 +170,17 @@ enum CS_EventKind { CS_SINK_PROPERTY_CHOICES_UPDATED = 0x40000 }; -// -// Telemetry kinds -// +/** + * Telemetry kinds + */ enum CS_TelemetryKind { CS_SOURCE_BYTES_RECEIVED = 1, CS_SOURCE_FRAMES_RECEIVED = 2 }; -// -// Listener event -// +/** + * Listener event + */ struct CS_Event { enum CS_EventKind kind; @@ -191,9 +201,10 @@ struct CS_Event { const char* valueStr; }; -// -// Property Functions -// +/** + * @defgroup cscore_property_cfunc Property Functions + * @{ + */ enum CS_PropertyKind CS_GetPropertyKind(CS_Property property, CS_Status* status); char* CS_GetPropertyName(CS_Property property, CS_Status* status); @@ -208,10 +219,12 @@ void CS_SetStringProperty(CS_Property property, const char* value, CS_Status* status); char** CS_GetEnumPropertyChoices(CS_Property property, int* count, CS_Status* status); +/** @} */ -// -// Source Creation Functions -// +/** + * @defgroup cscore_source_create_cfunc Source Creation Functions + * @{ + */ CS_Source CS_CreateUsbCameraDev(const char* name, int dev, CS_Status* status); CS_Source CS_CreateUsbCameraPath(const char* name, const char* path, CS_Status* status); @@ -222,10 +235,12 @@ CS_Source CS_CreateHttpCameraMulti(const char* name, const char** urls, CS_Status* status); CS_Source CS_CreateCvSource(const char* name, const CS_VideoMode* mode, CS_Status* status); +/** @} */ -// -// Source Functions -// +/** + * @defgroup cscore_source_cfunc Source Functions + * @{ + */ enum CS_SourceKind CS_GetSourceKind(CS_Source source, CS_Status* status); char* CS_GetSourceName(CS_Source source, CS_Status* status); char* CS_GetSourceDescription(CS_Source source, CS_Status* status); @@ -255,10 +270,12 @@ CS_Sink* CS_EnumerateSourceSinks(CS_Source source, int* count, CS_Status* status); CS_Source CS_CopySource(CS_Source source, CS_Status* status); void CS_ReleaseSource(CS_Source source, CS_Status* status); +/** @} */ -// -// Camera Source Common Property Fuctions -// +/** + * @defgroup cscore_source_prop_cfunc Camera Source Common Property Fuctions + * @{ + */ void CS_SetCameraBrightness(CS_Source source, int brightness, CS_Status* status); int CS_GetCameraBrightness(CS_Source source, CS_Status* status); @@ -269,24 +286,30 @@ void CS_SetCameraWhiteBalanceManual(CS_Source source, int value, void CS_SetCameraExposureAuto(CS_Source source, CS_Status* status); void CS_SetCameraExposureHoldCurrent(CS_Source source, CS_Status* status); void CS_SetCameraExposureManual(CS_Source source, int value, CS_Status* status); +/** @} */ -// -// UsbCamera Source Functions -// +/** + * @defgroup cscore_usbcamera_cfunc UsbCamera Source Functions + * @{ + */ char* CS_GetUsbCameraPath(CS_Source source, CS_Status* status); +/** @} */ -// -// HttpCamera Source Functions -// +/** + * @defgroup cscore_httpcamera_cfunc HttpCamera Source Functions + * @{ + */ enum CS_HttpCameraKind CS_GetHttpCameraKind(CS_Source source, CS_Status* status); void CS_SetHttpCameraUrls(CS_Source source, const char** urls, int count, CS_Status* status); char** CS_GetHttpCameraUrls(CS_Source source, int* count, CS_Status* status); +/** @} */ -// -// OpenCV Source Functions -// +/** + * @defgroup cscore_opencv_source_cfunc OpenCV Source Functions + * @{ + */ void CS_PutSourceFrame(CS_Source source, struct CvMat* image, CS_Status* status); void CS_NotifySourceError(CS_Source source, const char* msg, CS_Status* status); @@ -301,20 +324,24 @@ CS_Property CS_CreateSourceProperty(CS_Source source, const char* name, void CS_SetSourceEnumPropertyChoices(CS_Source source, CS_Property property, const char** choices, int count, CS_Status* status); +/** @} */ -// -// Sink Creation Functions -// +/** + * @defgroup cscore_sink_create_cfunc Sink Creation Functions + * @{ + */ CS_Sink CS_CreateMjpegServer(const char* name, const char* listenAddress, int port, CS_Status* status); CS_Sink CS_CreateCvSink(const char* name, CS_Status* status); CS_Sink CS_CreateCvSinkCallback(const char* name, void* data, void (*processFrame)(void* data, uint64_t time), CS_Status* status); +/** @} */ -// -// Sink Functions -// +/** + * @defgroup cscore_sink_cfunc Sink Functions + * @{ + */ enum CS_SinkKind CS_GetSinkKind(CS_Sink sink, CS_Status* status); char* CS_GetSinkName(CS_Sink sink, CS_Status* status); char* CS_GetSinkDescription(CS_Sink sink, CS_Status* status); @@ -328,16 +355,20 @@ CS_Property CS_GetSinkSourceProperty(CS_Sink sink, const char* name, CS_Source CS_GetSinkSource(CS_Sink sink, CS_Status* status); CS_Sink CS_CopySink(CS_Sink sink, CS_Status* status); void CS_ReleaseSink(CS_Sink sink, CS_Status* status); +/** @} */ -// -// MjpegServer Sink Functions -// +/** + * @defgroup cscore_mjpegserver_cfunc MjpegServer Sink Functions + * @{ + */ char* CS_GetMjpegServerListenAddress(CS_Sink sink, CS_Status* status); int CS_GetMjpegServerPort(CS_Sink sink, CS_Status* status); +/** @} */ -// -// OpenCV Sink Functions -// +/** + * @defgroup cscore_opencv_sink_cfunc OpenCV Sink Functions + * @{ + */ void CS_SetSinkDescription(CS_Sink sink, const char* description, CS_Status* status); uint64_t CS_GrabSinkFrame(CS_Sink sink, struct CvMat* image, CS_Status* status); @@ -345,10 +376,12 @@ uint64_t CS_GrabSinkFrameTimeout(CS_Sink sink, struct CvMat* image, double timeout, CS_Status* status); char* CS_GetSinkError(CS_Sink sink, CS_Status* status); void CS_SetSinkEnabled(CS_Sink sink, CS_Bool enabled, CS_Status* status); +/** @} */ -// -// Listener Functions -// +/** + * @defgroup cscore_listener_cfunc Listener Functions + * @{ + */ void CS_SetListenerOnStart(void (*onStart)(void* data), void* data); void CS_SetListenerOnExit(void (*onExit)(void* data), void* data); CS_Listener CS_AddListener( @@ -356,30 +389,40 @@ CS_Listener CS_AddListener( int eventMask, int immediateNotify, CS_Status* status); void CS_RemoveListener(CS_Listener handle, CS_Status* status); +/** @} */ int CS_NotifierDestroyed(void); -// -// Telemetry Functions -// +/** + * @defgroup cscore_telemetry_cfunc Telemetry Functions + * @{ + */ void CS_SetTelemetryPeriod(double seconds); double CS_GetTelemetryElapsedTime(void); int64_t CS_GetTelemetryValue(CS_Handle handle, enum CS_TelemetryKind kind, CS_Status* status); double CS_GetTelemetryAverageValue(CS_Handle handle, enum CS_TelemetryKind kind, CS_Status* status); +/** @} */ -// -// Logging Functions -// +/** + * @defgroup cscore_logging_cfunc Logging Functions + * @{ + */ typedef void (*CS_LogFunc)(unsigned int level, const char* file, unsigned int line, const char* msg); void CS_SetLogger(CS_LogFunc func, unsigned int min_level); void CS_SetDefaultLogger(unsigned int min_level); +/** @} */ -// -// Utility Functions -// +/** + * @defgroup cscore_utility_cfunc Utility Functions + * @{ + */ + +/** + * USB camera infomation + */ typedef struct CS_UsbCameraInfo { int dev; char* path; @@ -406,6 +449,9 @@ char* CS_GetHostname(); char** CS_GetNetworkInterfaces(int* count); void CS_FreeNetworkInterfaces(char** interfaces, int count); +/** @} */ + +/** @} */ #ifdef __cplusplus } // extern "C" diff --git a/cscore/src/main/native/include/cscore_cpp.h b/cscore/src/main/native/include/cscore_cpp.h index 6462404043..45a0fa40c2 100644 --- a/cscore/src/main/native/include/cscore_cpp.h +++ b/cscore/src/main/native/include/cscore_cpp.h @@ -26,23 +26,31 @@ class Mat; namespace cs { -// -// Handle-based interface for C++. Users are encouraged to use the -// object oriented interface instead; this interface is intended for use -// in applications such as JNI which require handle-based access. -// +/** + * @defgroup cscore_cpp_api cscore C++ function API + * + * Handle-based interface for C++. Users are encouraged to use the + * object oriented interface instead; this interface is intended for use + * in applications such as JNI which require handle-based access. + * + * @{ + */ -/// USB camera information +/** + * USB camera information + */ struct UsbCameraInfo { - /// Device number (e.g. N in '/dev/videoN' on Linux) + /** Device number (e.g. N in '/dev/videoN' on Linux) */ int dev; - /// Path to device if available (e.g. '/dev/video0' on Linux) + /** Path to device if available (e.g. '/dev/video0' on Linux) */ std::string path; - /// Vendor/model name of the camera as provided by the USB driver + /** Vendor/model name of the camera as provided by the USB driver */ std::string name; }; -/// Video mode +/** + * Video mode + */ struct VideoMode : public CS_VideoMode { enum PixelFormat { kUnknown = CS_PIXFMT_UNKNOWN, @@ -67,7 +75,9 @@ struct VideoMode : public CS_VideoMode { explicit operator bool() const { return pixelFormat == kUnknown; } }; -/// Listener event +/** + * Listener event + */ struct RawEvent { enum Kind { kSourceCreated = CS_SOURCE_CREATED, @@ -136,9 +146,10 @@ struct RawEvent { std::string valueStr; }; -// -// Property Functions -// +/** + * @defgroup cscore_property_func Property Functions + * @{ + */ CS_PropertyKind GetPropertyKind(CS_Property property, CS_Status* status); std::string GetPropertyName(CS_Property property, CS_Status* status); wpi::StringRef GetPropertyName(CS_Property property, @@ -158,10 +169,12 @@ void SetStringProperty(CS_Property property, wpi::StringRef value, CS_Status* status); std::vector GetEnumPropertyChoices(CS_Property property, CS_Status* status); +/** @} */ -// -// Source Creation Functions -// +/** + * @defgroup cscore_source_create_func Source Creation Functions + * @{ + */ CS_Source CreateUsbCameraDev(wpi::StringRef name, int dev, CS_Status* status); CS_Source CreateUsbCameraPath(wpi::StringRef name, wpi::StringRef path, CS_Status* status); @@ -171,10 +184,12 @@ CS_Source CreateHttpCamera(wpi::StringRef name, wpi::ArrayRef urls, CS_HttpCameraKind kind, CS_Status* status); CS_Source CreateCvSource(wpi::StringRef name, const VideoMode& mode, CS_Status* status); +/** @} */ -// -// Source Functions -// +/** + * @defgroup cscore_source_func Source Functions + * @{ + */ CS_SourceKind GetSourceKind(CS_Source source, CS_Status* status); std::string GetSourceName(CS_Source source, CS_Status* status); wpi::StringRef GetSourceName(CS_Source source, wpi::SmallVectorImpl& buf, @@ -205,10 +220,12 @@ wpi::ArrayRef EnumerateSourceSinks(CS_Source source, CS_Status* status); CS_Source CopySource(CS_Source source, CS_Status* status); void ReleaseSource(CS_Source source, CS_Status* status); +/** @} */ -// -// Camera Source Common Property Fuctions -// +/** + * @defgroup cscore_camera_property_func Camera Source Common Property Fuctions + * @{ + */ void SetCameraBrightness(CS_Source source, int brightness, CS_Status* status); int GetCameraBrightness(CS_Source source, CS_Status* status); void SetCameraWhiteBalanceAuto(CS_Source source, CS_Status* status); @@ -218,23 +235,29 @@ void SetCameraWhiteBalanceManual(CS_Source source, int value, void SetCameraExposureAuto(CS_Source source, CS_Status* status); void SetCameraExposureHoldCurrent(CS_Source source, CS_Status* status); void SetCameraExposureManual(CS_Source source, int value, CS_Status* status); +/** @} */ -// -// UsbCamera Source Functions -// +/** + * @defgroup cscore_usbcamera_func UsbCamera Source Functions + * @{ + */ std::string GetUsbCameraPath(CS_Source source, CS_Status* status); +/** @} */ -// -// HttpCamera Source Functions -// +/** + * @defgroup cscore_httpcamera_func HttpCamera Source Functions + * @{ + */ CS_HttpCameraKind GetHttpCameraKind(CS_Source source, CS_Status* status); void SetHttpCameraUrls(CS_Source source, wpi::ArrayRef urls, CS_Status* status); std::vector GetHttpCameraUrls(CS_Source source, CS_Status* status); +/** @} */ -// -// OpenCV Source Functions -// +/** + * @defgroup cscore_opencv_source_func OpenCV Source Functions + * @{ + */ void PutSourceFrame(CS_Source source, cv::Mat& image, CS_Status* status); void NotifySourceError(CS_Source source, wpi::StringRef msg, CS_Status* status); void SetSourceConnected(CS_Source source, bool connected, CS_Status* status); @@ -247,20 +270,24 @@ CS_Property CreateSourceProperty(CS_Source source, wpi::StringRef name, void SetSourceEnumPropertyChoices(CS_Source source, CS_Property property, wpi::ArrayRef choices, CS_Status* status); +/** @} */ -// -// Sink Creation Functions -// +/** + * @defgroup cscore_sink_create_func Sink Creation Functions + * @{ + */ CS_Sink CreateMjpegServer(wpi::StringRef name, wpi::StringRef listenAddress, int port, CS_Status* status); CS_Sink CreateCvSink(wpi::StringRef name, CS_Status* status); CS_Sink CreateCvSinkCallback(wpi::StringRef name, std::function processFrame, CS_Status* status); +/** @} */ -// -// Sink Functions -// +/** + * @defgroup cscore_sink_func Sink Functions + * @{ + */ CS_SinkKind GetSinkKind(CS_Sink sink, CS_Status* status); std::string GetSinkName(CS_Sink sink, CS_Status* status); wpi::StringRef GetSinkName(CS_Sink sink, wpi::SmallVectorImpl& buf, @@ -278,16 +305,20 @@ CS_Property GetSinkSourceProperty(CS_Sink sink, wpi::StringRef name, CS_Source GetSinkSource(CS_Sink sink, CS_Status* status); CS_Sink CopySink(CS_Sink sink, CS_Status* status); void ReleaseSink(CS_Sink sink, CS_Status* status); +/** @} */ -// -// MjpegServer Sink Functions -// +/** + * @defgroup cscore_mjpegserver_func MjpegServer Sink Functions + * @{ + */ std::string GetMjpegServerListenAddress(CS_Sink sink, CS_Status* status); int GetMjpegServerPort(CS_Sink sink, CS_Status* status); +/** @} */ -// -// OpenCV Sink Functions -// +/** + * @defgroup cscore_opencv_sink_func OpenCV Sink Functions + * @{ + */ void SetSinkDescription(CS_Sink sink, wpi::StringRef description, CS_Status* status); uint64_t GrabSinkFrame(CS_Sink sink, cv::Mat& image, CS_Status* status); @@ -297,10 +328,12 @@ std::string GetSinkError(CS_Sink sink, CS_Status* status); wpi::StringRef GetSinkError(CS_Sink sink, wpi::SmallVectorImpl& buf, CS_Status* status); void SetSinkEnabled(CS_Sink sink, bool enabled, CS_Status* status); +/** @} */ -// -// Listener Functions -// +/** + * @defgroup cscore_listener_func Listener Functions + * @{ + */ void SetListenerOnStart(std::function onStart); void SetListenerOnExit(std::function onExit); @@ -308,31 +341,37 @@ CS_Listener AddListener(std::function callback, int eventMask, bool immediateNotify, CS_Status* status); void RemoveListener(CS_Listener handle, CS_Status* status); +/** @} */ bool NotifierDestroyed(); -// -// Telemetry Functions -// +/** + * @defgroup cscore_telemetry_func Telemetry Functions + * @{ + */ void SetTelemetryPeriod(double seconds); double GetTelemetryElapsedTime(); int64_t GetTelemetryValue(CS_Handle handle, CS_TelemetryKind kind, CS_Status* status); double GetTelemetryAverageValue(CS_Handle handle, CS_TelemetryKind kind, CS_Status* status); +/** @} */ -// -// Logging Functions -// +/** + * @defgroup cscore_logging_func Logging Functions + * @{ + */ typedef std::function LogFunc; void SetLogger(LogFunc func, unsigned int min_level); void SetDefaultLogger(unsigned int min_level); +/** @} */ -// -// Utility Functions -// +/** + * @defgroup cscore_utility_func Utility Functions + * @{ + */ std::vector EnumerateUsbCameras(CS_Status* status); wpi::ArrayRef EnumerateSourceHandles( @@ -343,15 +382,24 @@ wpi::ArrayRef EnumerateSinkHandles(wpi::SmallVectorImpl& vec, std::string GetHostname(); std::vector GetNetworkInterfaces(); +/** @} */ + +/** @} */ } // namespace cs -// C functions taking a cv::Mat* for specific interop implementations +/** + * @defgroup cscore_cpp_opencv_special cscore C functions taking a cv::Mat* + * + * These are needed for specific interop implementations. + * @{ + */ extern "C" { uint64_t CS_GrabSinkFrameCpp(CS_Sink sink, cv::Mat* image, CS_Status* status); uint64_t CS_GrabSinkFrameTimeoutCpp(CS_Sink sink, cv::Mat* image, double timeout, CS_Status* status); void CS_PutSourceFrameCpp(CS_Source source, cv::Mat* image, CS_Status* status); } // extern "C" +/** @} */ #endif // CSCORE_CSCORE_CPP_H_ diff --git a/cscore/src/main/native/include/cscore_oo.h b/cscore/src/main/native/include/cscore_oo.h index 94b3ab95c6..937c356a4c 100644 --- a/cscore/src/main/native/include/cscore_oo.h +++ b/cscore/src/main/native/include/cscore_oo.h @@ -17,9 +17,15 @@ namespace cs { -// -// Object-oriented interface -// +/** + * @defgroup cscore_oo cscore C++ object-oriented API + * + * Recommended interface for C++, identical to Java API. + * + *

The classes are RAII and handle reference counting internally. + * + * @{ + */ // Forward declarations so friend declarations work correctly class CvSource; @@ -27,6 +33,9 @@ class VideoEvent; class VideoSink; class VideoSource; +/** + * A source or sink property. + */ class VideoProperty { friend class CvSource; friend class VideoEvent; @@ -82,7 +91,9 @@ class VideoProperty { Kind m_kind; }; -/// A source for video that provides a sequence of frames. +/** + * A source for video that provides a sequence of frames. + */ class VideoSource { friend class VideoEvent; friend class VideoSink; @@ -111,86 +122,134 @@ class VideoSource { bool operator!=(const VideoSource& other) const { return !(*this == other); } - /// Get the kind of the source. + /** + * Get the kind of the source. + */ Kind GetKind() const; - /// Get the name of the source. The name is an arbitrary identifier - /// provided when the source is created, and should be unique. + /** + * Get the name of the source. The name is an arbitrary identifier + * provided when the source is created, and should be unique. + */ std::string GetName() const; - /// Get the source description. This is source-kind specific. + /** + * Get the source description. This is source-kind specific. + */ std::string GetDescription() const; - /// Get the last time a frame was captured. - /// This uses the same time base as wpi::Now(). - /// @return Time in 1 us increments. + /** + * Get the last time a frame was captured. + * This uses the same time base as wpi::Now(). + * + * @return Time in 1 us increments. + */ uint64_t GetLastFrameTime() const; - /// Is the source currently connected to whatever is providing the images? + /** + * Is the source currently connected to whatever is providing the images? + */ bool IsConnected() const; - /// Get a property. - /// @param name Property name - /// @return Property contents (of kind Property::kNone if no property with - /// the given name exists) + /** Get a property. + * + * @param name Property name + * @return Property contents (of kind Property::kNone if no property with + * the given name exists) + */ VideoProperty GetProperty(wpi::StringRef name); - /// Enumerate all properties of this source. + /** + * Enumerate all properties of this source. + */ std::vector EnumerateProperties() const; - /// Get the current video mode. + /** + * Get the current video mode. + */ VideoMode GetVideoMode() const; - /// Set the video mode. - /// @param mode Video mode + /** + * Set the video mode. + * + * @param mode Video mode + */ bool SetVideoMode(const VideoMode& mode); - /// Set the video mode. - /// @param pixelFormat desired pixel format - /// @param width desired width - /// @param height desired height - /// @param fps desired FPS - /// @return True if set successfully + /** + * Set the video mode. + * + * @param pixelFormat desired pixel format + * @param width desired width + * @param height desired height + * @param fps desired FPS + * @return True if set successfully + */ bool SetVideoMode(VideoMode::PixelFormat pixelFormat, int width, int height, int fps); - /// Set the pixel format. - /// @param pixelFormat desired pixel format - /// @return True if set successfully + /** + * Set the pixel format. + * + * @param pixelFormat desired pixel format + * @return True if set successfully + */ bool SetPixelFormat(VideoMode::PixelFormat pixelFormat); - /// Set the resolution. - /// @param width desired width - /// @param height desired height - /// @return True if set successfully + /** + * Set the resolution. + * + * @param width desired width + * @param height desired height + * @return True if set successfully + */ bool SetResolution(int width, int height); - /// Set the frames per second (FPS). - /// @param fps desired FPS - /// @return True if set successfully + /** + * Set the frames per second (FPS). + * + * @param fps desired FPS + * @return True if set successfully + */ bool SetFPS(int fps); - /// Get the actual FPS. - /// SetTelemetryPeriod() must be called for this to be valid. - /// @return Actual FPS averaged over the telemetry period. + /** + * Get the actual FPS. + * + *

SetTelemetryPeriod() must be called for this to be valid. + * + * @return Actual FPS averaged over the telemetry period. + */ double GetActualFPS() const; - /// Get the data rate (in bytes per second). - /// SetTelemetryPeriod() must be called for this to be valid. - /// @return Data rate averaged over the telemetry period. + /** + * Get the data rate (in bytes per second). + * + *

SetTelemetryPeriod() must be called for this to be valid. + * + * @return Data rate averaged over the telemetry period. + */ double GetActualDataRate() const; - /// Enumerate all known video modes for this source. + /** + * Enumerate all known video modes for this source. + */ std::vector EnumerateVideoModes() const; CS_Status GetLastStatus() const { return m_status; } - /// Enumerate all sinks connected to this source. - /// @return Vector of sinks. + /** + * Enumerate all sinks connected to this source. + * + * @return Vector of sinks. + */ std::vector EnumerateSinks(); - /// Enumerate all existing sources. - /// @return Vector of sources. + /** + * Enumerate all existing sources. + * + * @return Vector of sources. + */ static std::vector EnumerateSources(); friend void swap(VideoSource& first, VideoSource& second) noexcept { @@ -206,7 +265,9 @@ class VideoSource { CS_Source m_handle; }; -/// A source that represents a video camera. +/** + * A source that represents a video camera. + */ class VideoCamera : public VideoSource { public: enum WhiteBalance { @@ -219,62 +280,96 @@ class VideoCamera : public VideoSource { VideoCamera() = default; - /// Set the brightness, as a percentage (0-100). + /** + * Set the brightness, as a percentage (0-100). + */ void SetBrightness(int brightness); - /// Get the brightness, as a percentage (0-100). + /** + * Get the brightness, as a percentage (0-100). + */ int GetBrightness(); - /// Set the white balance to auto. + /** + * Set the white balance to auto. + */ void SetWhiteBalanceAuto(); - /// Set the white balance to hold current. + /** + * Set the white balance to hold current. + */ void SetWhiteBalanceHoldCurrent(); - /// Set the white balance to manual, with specified color temperature. + /** + * Set the white balance to manual, with specified color temperature. + */ void SetWhiteBalanceManual(int value); - /// Set the exposure to auto aperature. + /** + * Set the exposure to auto aperature. + */ void SetExposureAuto(); - /// Set the exposure to hold current. + /** + * Set the exposure to hold current. + */ void SetExposureHoldCurrent(); - /// Set the exposure to manual, as a percentage (0-100). + /** + * Set the exposure to manual, as a percentage (0-100). + */ void SetExposureManual(int value); protected: explicit VideoCamera(CS_Source handle) : VideoSource(handle) {} }; -/// A source that represents a USB camera. +/** + * A source that represents a USB camera. + */ class UsbCamera : public VideoCamera { public: UsbCamera() = default; - /// Create a source for a USB camera based on device number. - /// @param name Source name (arbitrary unique identifier) - /// @param dev Device number (e.g. 0 for /dev/video0) + /** + * Create a source for a USB camera based on device number. + * + * @param name Source name (arbitrary unique identifier) + * @param dev Device number (e.g. 0 for /dev/video0) + */ UsbCamera(wpi::StringRef name, int dev); - /// Create a source for a USB camera based on device path. - /// @param name Source name (arbitrary unique identifier) - /// @param path Path to device (e.g. "/dev/video0" on Linux) + /** + * Create a source for a USB camera based on device path. + * + * @param name Source name (arbitrary unique identifier) + * @param path Path to device (e.g. "/dev/video0" on Linux) + */ UsbCamera(wpi::StringRef name, wpi::StringRef path); - /// Enumerate USB cameras on the local system. - /// @return Vector of USB camera information (one for each camera) + /** + * Enumerate USB cameras on the local system. + * + * @return Vector of USB camera information (one for each camera) + */ static std::vector EnumerateUsbCameras(); - /// Get the path to the device. + /** + * Get the path to the device. + */ std::string GetPath() const; - /// Set how verbose the camera connection messages are. - /// @param level 0=don't display Connecting message, 1=do display message + /** + * Set how verbose the camera connection messages are. + * + * @param level 0=don't display Connecting message, 1=do display message + */ void SetConnectVerbose(int level); }; -/// A source that represents a MJPEG-over-HTTP (IP) camera. +/** + * A source that represents a MJPEG-over-HTTP (IP) camera. + */ class HttpCamera : public VideoCamera { public: enum HttpCameraKind { @@ -284,59 +379,85 @@ class HttpCamera : public VideoCamera { kAxis = CS_HTTP_AXIS }; - /// Create a source for a MJPEG-over-HTTP (IP) camera. - /// @param name Source name (arbitrary unique identifier) - /// @param url Camera URL (e.g. "http://10.x.y.11/video/stream.mjpg") - /// @param kind Camera kind (e.g. kAxis) + /** + * Create a source for a MJPEG-over-HTTP (IP) camera. + * + * @param name Source name (arbitrary unique identifier) + * @param url Camera URL (e.g. "http://10.x.y.11/video/stream.mjpg") + * @param kind Camera kind (e.g. kAxis) + */ HttpCamera(wpi::StringRef name, wpi::StringRef url, HttpCameraKind kind = kUnknown); - /// Create a source for a MJPEG-over-HTTP (IP) camera. - /// @param name Source name (arbitrary unique identifier) - /// @param url Camera URL (e.g. "http://10.x.y.11/video/stream.mjpg") - /// @param kind Camera kind (e.g. kAxis) + /** + * Create a source for a MJPEG-over-HTTP (IP) camera. + * + * @param name Source name (arbitrary unique identifier) + * @param url Camera URL (e.g. "http://10.x.y.11/video/stream.mjpg") + * @param kind Camera kind (e.g. kAxis) + */ HttpCamera(wpi::StringRef name, const char* url, HttpCameraKind kind = kUnknown); - /// Create a source for a MJPEG-over-HTTP (IP) camera. - /// @param name Source name (arbitrary unique identifier) - /// @param url Camera URL (e.g. "http://10.x.y.11/video/stream.mjpg") - /// @param kind Camera kind (e.g. kAxis) + /** + * Create a source for a MJPEG-over-HTTP (IP) camera. + * + * @param name Source name (arbitrary unique identifier) + * @param url Camera URL (e.g. "http://10.x.y.11/video/stream.mjpg") + * @param kind Camera kind (e.g. kAxis) + */ HttpCamera(wpi::StringRef name, const std::string& url, HttpCameraKind kind = kUnknown); - /// Create a source for a MJPEG-over-HTTP (IP) camera. - /// @param name Source name (arbitrary unique identifier) - /// @param urls Array of Camera URLs - /// @param kind Camera kind (e.g. kAxis) + /** + * Create a source for a MJPEG-over-HTTP (IP) camera. + * + * @param name Source name (arbitrary unique identifier) + * @param urls Array of Camera URLs + * @param kind Camera kind (e.g. kAxis) + */ HttpCamera(wpi::StringRef name, wpi::ArrayRef urls, HttpCameraKind kind = kUnknown); - /// Create a source for a MJPEG-over-HTTP (IP) camera. - /// @param name Source name (arbitrary unique identifier) - /// @param urls Array of Camera URLs - /// @param kind Camera kind (e.g. kAxis) + /** + * Create a source for a MJPEG-over-HTTP (IP) camera. + * + * @param name Source name (arbitrary unique identifier) + * @param urls Array of Camera URLs + * @param kind Camera kind (e.g. kAxis) + */ template HttpCamera(wpi::StringRef name, std::initializer_list urls, HttpCameraKind kind = kUnknown); - /// Get the kind of HTTP camera. - /// Autodetection can result in returning a different value than the camera - /// was created with. + /** + * Get the kind of HTTP camera. + * + *

Autodetection can result in returning a different value than the camera + * was created with. + */ HttpCameraKind GetHttpCameraKind() const; - /// Change the URLs used to connect to the camera. + /** + * Change the URLs used to connect to the camera. + */ void SetUrls(wpi::ArrayRef urls); - /// Change the URLs used to connect to the camera. + /** + * Change the URLs used to connect to the camera. + */ template void SetUrls(std::initializer_list urls); - /// Get the URLs used to connect to the camera. + /** + * Get the URLs used to connect to the camera. + */ std::vector GetUrls() const; }; -/// A source that represents an Axis IP camera. +/** + * A source that represents an Axis IP camera. + */ class AxisCamera : public HttpCamera { static std::string HostToUrl(wpi::StringRef host); static std::vector HostToUrl(wpi::ArrayRef hosts); @@ -344,131 +465,186 @@ class AxisCamera : public HttpCamera { static std::vector HostToUrl(std::initializer_list hosts); public: - /// Create a source for an Axis IP camera. - /// @param name Source name (arbitrary unique identifier) - /// @param host Camera host IP or DNS name (e.g. "10.x.y.11") - /// @param kind Camera kind (e.g. kAxis) + /** + * Create a source for an Axis IP camera. + * + * @param name Source name (arbitrary unique identifier) + * @param host Camera host IP or DNS name (e.g. "10.x.y.11") + * @param kind Camera kind (e.g. kAxis) + */ AxisCamera(wpi::StringRef name, wpi::StringRef host); - /// Create a source for an Axis IP camera. - /// @param name Source name (arbitrary unique identifier) - /// @param host Camera host IP or DNS name (e.g. "10.x.y.11") - /// @param kind Camera kind (e.g. kAxis) + /** + * Create a source for an Axis IP camera. + * + * @param name Source name (arbitrary unique identifier) + * @param host Camera host IP or DNS name (e.g. "10.x.y.11") + * @param kind Camera kind (e.g. kAxis) + */ AxisCamera(wpi::StringRef name, const char* host); - /// Create a source for an Axis IP camera. - /// @param name Source name (arbitrary unique identifier) - /// @param host Camera host IP or DNS name (e.g. "10.x.y.11") - /// @param kind Camera kind (e.g. kAxis) + /** + * Create a source for an Axis IP camera. + * + * @param name Source name (arbitrary unique identifier) + * @param host Camera host IP or DNS name (e.g. "10.x.y.11") + * @param kind Camera kind (e.g. kAxis) + */ AxisCamera(wpi::StringRef name, const std::string& host); - /// Create a source for an Axis IP camera. - /// @param name Source name (arbitrary unique identifier) - /// @param hosts Array of Camera host IPs/DNS names - /// @param kind Camera kind (e.g. kAxis) + /** + * Create a source for an Axis IP camera. + * + * @param name Source name (arbitrary unique identifier) + * @param hosts Array of Camera host IPs/DNS names + * @param kind Camera kind (e.g. kAxis) + */ AxisCamera(wpi::StringRef name, wpi::ArrayRef hosts); - /// Create a source for an Axis IP camera. - /// @param name Source name (arbitrary unique identifier) - /// @param hosts Array of Camera host IPs/DNS names - /// @param kind Camera kind (e.g. kAxis) + /** + * Create a source for an Axis IP camera. + * + * @param name Source name (arbitrary unique identifier) + * @param hosts Array of Camera host IPs/DNS names + * @param kind Camera kind (e.g. kAxis) + */ template AxisCamera(wpi::StringRef name, std::initializer_list hosts); }; -/// A source for user code to provide OpenCV images as video frames. +/** + * A source for user code to provide OpenCV images as video frames. + */ class CvSource : public VideoSource { public: CvSource() = default; - /// Create an OpenCV source. - /// @param name Source name (arbitrary unique identifier) - /// @param mode Video mode being generated + /** + * Create an OpenCV source. + * + * @param name Source name (arbitrary unique identifier) + * @param mode Video mode being generated + */ CvSource(wpi::StringRef name, const VideoMode& mode); - /// Create an OpenCV source. - /// @param name Source name (arbitrary unique identifier) - /// @param pixelFormat Pixel format - /// @param width width - /// @param height height - /// @param fps fps + /** + * Create an OpenCV source. + * + * @param name Source name (arbitrary unique identifier) + * @param pixelFormat Pixel format + * @param width width + * @param height height + * @param fps fps + */ CvSource(wpi::StringRef name, VideoMode::PixelFormat pixelFormat, int width, int height, int fps); - /// Put an OpenCV image and notify sinks. - /// Only 8-bit single-channel or 3-channel (with BGR channel order) images - /// are supported. If the format, depth or channel order is different, use - /// cv::Mat::convertTo() and/or cv::cvtColor() to convert it first. - /// @param image OpenCV image + /** + * Put an OpenCV image and notify sinks. + * + *

Only 8-bit single-channel or 3-channel (with BGR channel order) images + * are supported. If the format, depth or channel order is different, use + * cv::Mat::convertTo() and/or cv::cvtColor() to convert it first. + * + * @param image OpenCV image + */ void PutFrame(cv::Mat& image); - /// Signal sinks that an error has occurred. This should be called instead - /// of NotifyFrame when an error occurs. + /** + * Signal sinks that an error has occurred. This should be called instead + * of NotifyFrame when an error occurs. + */ void NotifyError(wpi::StringRef msg); - /// Set source connection status. Defaults to true. - /// @param connected True for connected, false for disconnected + /** + * Set source connection status. Defaults to true. + * + * @param connected True for connected, false for disconnected + */ void SetConnected(bool connected); - /// Set source description. - /// @param description Description + /** + * Set source description. + * + * @param description Description + */ void SetDescription(wpi::StringRef description); - /// Create a property. - /// @param name Property name - /// @param kind Property kind - /// @param minimum Minimum value - /// @param maximum Maximum value - /// @param step Step value - /// @param defaultValue Default value - /// @param value Current value - /// @return Property + /** + * Create a property. + * + * @param name Property name + * @param kind Property kind + * @param minimum Minimum value + * @param maximum Maximum value + * @param step Step value + * @param defaultValue Default value + * @param value Current value + * @return Property + */ VideoProperty CreateProperty(wpi::StringRef name, VideoProperty::Kind kind, int minimum, int maximum, int step, int defaultValue, int value); - /// Create an integer property. - /// @param name Property name - /// @param minimum Minimum value - /// @param maximum Maximum value - /// @param step Step value - /// @param defaultValue Default value - /// @param value Current value - /// @return Property + /** + * Create an integer property. + * + * @param name Property name + * @param minimum Minimum value + * @param maximum Maximum value + * @param step Step value + * @param defaultValue Default value + * @param value Current value + * @return Property + */ VideoProperty CreateIntegerProperty(wpi::StringRef name, int minimum, int maximum, int step, int defaultValue, int value); - /// Create a boolean property. - /// @param name Property name - /// @param defaultValue Default value - /// @param value Current value - /// @return Property + /** + * Create a boolean property. + * + * @param name Property name + * @param defaultValue Default value + * @param value Current value + * @return Property + */ VideoProperty CreateBooleanProperty(wpi::StringRef name, bool defaultValue, bool value); - /// Create a string property. - /// @param name Property name - /// @param defaultValue Default value - /// @param value Current value - /// @return Property + /** + * Create a string property. + * + * @param name Property name + * @param defaultValue Default value + * @param value Current value + * @return Property + */ VideoProperty CreateStringProperty(wpi::StringRef name, wpi::StringRef value); - /// Configure enum property choices. - /// @param property Property - /// @param choices Choices + /** + * Configure enum property choices. + * + * @param property Property + * @param choices Choices + */ void SetEnumPropertyChoices(const VideoProperty& property, wpi::ArrayRef choices); - /// Configure enum property choices. - /// @param property Property - /// @param choices Choices + /** + * Configure enum property choices. + * + * @param property Property + * @param choices Choices + */ template void SetEnumPropertyChoices(const VideoProperty& property, std::initializer_list choices); }; -/// A sink for video that accepts a sequence of frames. +/** + * A sink for video that accepts a sequence of frames. + */ class VideoSink { friend class VideoEvent; friend class VideoSource; @@ -496,45 +672,68 @@ class VideoSink { bool operator!=(const VideoSink& other) const { return !(*this == other); } - /// Get the kind of the sink. + /** + * Get the kind of the sink. + */ Kind GetKind() const; - /// Get the name of the sink. The name is an arbitrary identifier - /// provided when the sink is created, and should be unique. + /** + * Get the name of the sink. The name is an arbitrary identifier + * provided when the sink is created, and should be unique. + */ std::string GetName() const; - /// Get the sink description. This is sink-kind specific. + /** + * Get the sink description. This is sink-kind specific. + */ std::string GetDescription() const; - /// Get a property of the sink. - /// @param name Property name - /// @return Property (kind Property::kNone if no property with - /// the given name exists) + /** + * Get a property of the sink. + * + * @param name Property name + * @return Property (kind Property::kNone if no property with + * the given name exists) + */ VideoProperty GetProperty(wpi::StringRef name); - /// Enumerate all properties of this sink. + /** + * Enumerate all properties of this sink. + */ std::vector EnumerateProperties() const; - /// Configure which source should provide frames to this sink. Each sink - /// can accept frames from only a single source, but a single source can - /// provide frames to multiple clients. - /// @param source Source + /** + * Configure which source should provide frames to this sink. Each sink + * can accept frames from only a single source, but a single source can + * provide frames to multiple clients. + * + * @param source Source + */ void SetSource(VideoSource source); - /// Get the connected source. - /// @return Connected source (empty if none connected). + /** + * Get the connected source. + * + * @return Connected source (empty if none connected). + */ VideoSource GetSource() const; - /// Get a property of the associated source. - /// @param name Property name - /// @return Property (kind Property::kNone if no property with - /// the given name exists or no source connected) + /** + * Get a property of the associated source. + * + * @param name Property name + * @return Property (kind Property::kNone if no property with + * the given name exists or no source connected) + */ VideoProperty GetSourceProperty(wpi::StringRef name); CS_Status GetLastStatus() const { return m_status; } - /// Enumerate all existing sinks. - /// @return Vector of sinks. + /** + * Enumerate all existing sinks. + * + * @return Vector of sinks. + */ static std::vector EnumerateSinks(); friend void swap(VideoSink& first, VideoSink& second) noexcept { @@ -550,141 +749,198 @@ class VideoSink { CS_Sink m_handle; }; -/// A sink that acts as a MJPEG-over-HTTP network server. +/** + * A sink that acts as a MJPEG-over-HTTP network server. + */ class MjpegServer : public VideoSink { public: MjpegServer() = default; - /// Create a MJPEG-over-HTTP server sink. - /// @param name Sink name (arbitrary unique identifier) - /// @param listenAddress TCP listen address (empty string for all addresses) - /// @param port TCP port number + /** + * Create a MJPEG-over-HTTP server sink. + * + * @param name Sink name (arbitrary unique identifier) + * @param listenAddress TCP listen address (empty string for all addresses) + * @param port TCP port number + */ MjpegServer(wpi::StringRef name, wpi::StringRef listenAddress, int port); - /// Create a MJPEG-over-HTTP server sink. - /// @param name Sink name (arbitrary unique identifier) - /// @param port TCP port number + /** + * Create a MJPEG-over-HTTP server sink. + * + * @param name Sink name (arbitrary unique identifier) + * @param port TCP port number + */ MjpegServer(wpi::StringRef name, int port) : MjpegServer(name, "", port) {} - /// Get the listen address of the server. + /** + * Get the listen address of the server. + */ std::string GetListenAddress() const; - /// Get the port number of the server. + /** + * Get the port number of the server. + */ int GetPort() const; - /// Set the stream resolution for clients that don't specify it. - /// - /// It is not necessary to set this if it is the same as the source - /// resolution. - /// - /// Setting this different than the source resolution will result in - /// increased CPU usage, particularly for MJPEG source cameras, as it will - /// decompress, resize, and recompress the image, instead of using the - /// camera's MJPEG image directly. - /// - /// @param width width, 0 for unspecified - /// @param height height, 0 for unspecified + /** + * Set the stream resolution for clients that don't specify it. + * + *

It is not necessary to set this if it is the same as the source + * resolution. + * + *

Setting this different than the source resolution will result in + * increased CPU usage, particularly for MJPEG source cameras, as it will + * decompress, resize, and recompress the image, instead of using the + * camera's MJPEG image directly. + * + * @param width width, 0 for unspecified + * @param height height, 0 for unspecified + */ void SetResolution(int width, int height); - /// Set the stream frames per second (FPS) for clients that don't specify it. - /// - /// It is not necessary to set this if it is the same as the source FPS. - /// - /// @param fps FPS, 0 for unspecified + /** + * Set the stream frames per second (FPS) for clients that don't specify it. + * + *

It is not necessary to set this if it is the same as the source FPS. + * + * @param fps FPS, 0 for unspecified + */ void SetFPS(int fps); - /// Set the compression for clients that don't specify it. - /// - /// Setting this will result in increased CPU usage for MJPEG source cameras - /// as it will decompress and recompress the image instead of using the - /// camera's MJPEG image directly. - /// - /// @param quality JPEG compression quality (0-100), -1 for unspecified + /** + * Set the compression for clients that don't specify it. + * + *

Setting this will result in increased CPU usage for MJPEG source cameras + * as it will decompress and recompress the image instead of using the + * camera's MJPEG image directly. + * + * @param quality JPEG compression quality (0-100), -1 for unspecified + */ void SetCompression(int quality); - /// Set the default compression used for non-MJPEG sources. If not set, - /// 80 is used. This function has no effect on MJPEG source cameras; use - /// SetCompression() instead to force recompression of MJPEG source images. - /// - /// @param quality JPEG compression quality (0-100) + /** + * Set the default compression used for non-MJPEG sources. If not set, + * 80 is used. This function has no effect on MJPEG source cameras; use + * SetCompression() instead to force recompression of MJPEG source images. + * + * @param quality JPEG compression quality (0-100) + */ void SetDefaultCompression(int quality); }; -/// A sink for user code to accept video frames as OpenCV images. +/** + * A sink for user code to accept video frames as OpenCV images. + */ class CvSink : public VideoSink { public: CvSink() = default; - /// Create a sink for accepting OpenCV images. - /// WaitForFrame() must be called on the created sink to get each new - /// image. - /// @param name Source name (arbitrary unique identifier) + /** + * Create a sink for accepting OpenCV images. + * + *

WaitForFrame() must be called on the created sink to get each new + * image. + * + * @param name Source name (arbitrary unique identifier) + */ explicit CvSink(wpi::StringRef name); - /// Create a sink for accepting OpenCV images in a separate thread. - /// A thread will be created that calls WaitForFrame() and calls the - /// processFrame() callback each time a new frame arrives. - /// @param name Source name (arbitrary unique identifier) - /// @param processFrame Frame processing function; will be called with a - /// time=0 if an error occurred. processFrame should call GetImage() - /// or GetError() as needed, but should not call (except in very - /// unusual circumstances) WaitForImage(). + /** + * Create a sink for accepting OpenCV images in a separate thread. + * + *

A thread will be created that calls WaitForFrame() and calls the + * processFrame() callback each time a new frame arrives. + * + * @param name Source name (arbitrary unique identifier) + * @param processFrame Frame processing function; will be called with a + * time=0 if an error occurred. processFrame should call GetImage() + * or GetError() as needed, but should not call (except in very + * unusual circumstances) WaitForImage(). + */ CvSink(wpi::StringRef name, std::function processFrame); - /// Set sink description. - /// @param description Description + /** + * Set sink description. + * + * @param description Description + */ void SetDescription(wpi::StringRef description); - /// Wait for the next frame and get the image. - /// Times out (returning 0) after timeout seconds. - /// The provided image will have three 8-bit channels stored in BGR order. - /// @return Frame time, or 0 on error (call GetError() to obtain the error - /// message); the frame time is in the same time base as wpi::Now(), - /// and is in 1 us increments. + /** + * Wait for the next frame and get the image. + * Times out (returning 0) after timeout seconds. + * The provided image will have three 8-bit channels stored in BGR order. + * + * @return Frame time, or 0 on error (call GetError() to obtain the error + * message); the frame time is in the same time base as wpi::Now(), + * and is in 1 us increments. + */ uint64_t GrabFrame(cv::Mat& image, double timeout = 0.225) const; - /// Wait for the next frame and get the image. May block forever. - /// The provided image will have three 8-bit channels stored in BGR order. - /// @return Frame time, or 0 on error (call GetError() to obtain the error - /// message); the frame time is in the same time base as wpi::Now(), - /// and is in 1 us increments. + /** + * Wait for the next frame and get the image. May block forever. + * The provided image will have three 8-bit channels stored in BGR order. + * + * @return Frame time, or 0 on error (call GetError() to obtain the error + * message); the frame time is in the same time base as wpi::Now(), + * and is in 1 us increments. + */ uint64_t GrabFrameNoTimeout(cv::Mat& image) const; - /// Get error string. Call this if WaitForFrame() returns 0 to determine - /// what the error is. + /** + * Get error string. Call this if WaitForFrame() returns 0 to determine + * what the error is. + */ std::string GetError() const; - /// Enable or disable getting new frames. - /// Disabling will cause processFrame (for callback-based CvSinks) to not - /// be called and WaitForFrame() to not return. This can be used to save - /// processor resources when frames are not needed. + /** + * Enable or disable getting new frames. + * + *

Disabling will cause processFrame (for callback-based CvSinks) to not + * be called and WaitForFrame() to not return. This can be used to save + * processor resources when frames are not needed. + */ void SetEnabled(bool enabled); }; -/// An event generated by the library and provided to event listeners. +/** + * An event generated by the library and provided to event listeners. + */ class VideoEvent : public RawEvent { public: - /// Get the source associated with the event (if any). + /** + * Get the source associated with the event (if any). + */ VideoSource GetSource() const; - /// Get the sink associated with the event (if any). + /** + * Get the sink associated with the event (if any). + */ VideoSink GetSink() const; - /// Get the property associated with the event (if any). + /** + * Get the property associated with the event (if any). + */ VideoProperty GetProperty() const; }; -/// An event listener. This calls back to a desigated callback function when -/// an event matching the specified mask is generated by the library. +/** + * An event listener. This calls back to a desigated callback function when + * an event matching the specified mask is generated by the library. + */ class VideoListener { public: VideoListener() : m_handle(0) {} - /// Create an event listener. - /// @param callback Callback function - /// @param eventMask Bitmask of VideoEvent::Kind values - /// @param immediateNotify Whether callback should be immediately called with - /// a representative set of events for the current library state. + /** + * Create an event listener. + * + * @param callback Callback function + * @param eventMask Bitmask of VideoEvent::Kind values + * @param immediateNotify Whether callback should be immediately called with + * a representative set of events for the current library state. + */ VideoListener(std::function callback, int eventMask, bool immediateNotify); @@ -703,6 +959,8 @@ class VideoListener { CS_Listener m_handle; }; +/** @} */ + } // namespace cs #include "cscore_oo.inl"