diff --git a/src/acquire-device-kit/device/kit/camera.h b/src/acquire-device-kit/device/kit/camera.h index 9f554cc..741e480 100644 --- a/src/acquire-device-kit/device/kit/camera.h +++ b/src/acquire-device-kit/device/kit/camera.h @@ -9,25 +9,48 @@ extern "C" { #endif + /// @brief Represents and allows control of a camera device. struct Camera { struct Device device; enum DeviceState state; + /// @brief Attempts to set the given properties on the given camera. + /// @details Setting properties can partially succeed depending on + /// other property values or the state of the camera. + /// If you want to be certain that a specific property was + /// actually used, you should call get afterwards to check + /// that property value. enum DeviceStatusCode (*set)(struct Camera*, struct CameraProperties* settings); + + /// @brief Fills out the given properties from the given camera. enum DeviceStatusCode (*get)(const struct Camera*, struct CameraProperties* settings); + + /// @brief Fills out the given property metadata from the given camera. + /// @details These metadata or capabilities may depend on the camera's + /// current property values. enum DeviceStatusCode (*get_meta)(const struct Camera*, struct CameraPropertyMetadata* meta); + + /// @brief The shape of the next frame that the camera will capture. enum DeviceStatusCode (*get_shape)(const struct Camera*, struct ImageShape* shape); + /// @brief Starts acquiring frames. enum DeviceStatusCode (*start)(struct Camera*); + + /// @brief Stops acquiring frames. + /// @details This instructs the camera to stop and may block until it + /// actually has stopped acquiring frames. + /// The camera should also be restartable after calling this + /// (i.e. one call of start after one call of stop should succeed). enum DeviceStatusCode (*stop)(struct Camera*); - // Fire the software trigger if it's enabled. + /// @brief Execute the software trigger if it's enabled. enum DeviceStatusCode (*execute_trigger)(struct Camera*); + /// @brief Gets the next frame from the camera. enum DeviceStatusCode (*get_frame)(struct Camera*, void* im, size_t* nbytes, diff --git a/src/acquire-device-properties/device/props/camera.h b/src/acquire-device-properties/device/props/camera.h index e5ab537..6000b56 100644 --- a/src/acquire-device-properties/device/props/camera.h +++ b/src/acquire-device-properties/device/props/camera.h @@ -11,31 +11,61 @@ extern "C" { #endif + /// @brief Stores the properties of a camera. + /// @details Can be populated with values from a camera or + /// can be filled out to define new values that a camera should adopt. struct CameraProperties { + /// @brief Exposure time of a frame in microseconds. + /// @details Acquire assumes that exposure is always manually specified by this period of time. + /// It does not currently support auto-exposure or durations defined by trigger widths. float exposure_time_us; + float line_interval_us; enum Direction readout_direction; + + /// @brief Binning or downsample factor. + /// @details Determines how many pixels in each spatial dimension on the + /// sensor are aggregated to form pixels in an image. + /// For example, if we have a sensor of size 1920x1200 and a binning + /// factor of 2, one image should be 960x600. uint8_t binning; + + /// @brief Type of each image pixel or sample. enum SampleType pixel_type; + + /// @brief Offset of the region of interest on the sensor from its top-left corner. + /// @details Each value represents a number of aggregated pixels in the + /// frame after binning has been applied. struct camera_properties_offset_s { uint32_t x, y; } offset; + + /// @brief Shape or size of the region of interest on the sensor. + /// @details Each value represents a number of aggregated pixels in the + /// frame after binning has been applied. struct camera_properties_shape_s { uint32_t x, y; } shape; + + /// @brief State of the camera's input triggers. struct camera_properties_input_triggers_s { struct Trigger acquisition_start, frame_start, exposure; } input_triggers; + + /// @brief State of the camera's digital output lines. struct camera_properties_output_triggers_s { struct Trigger exposure, frame_start, trigger_wait; } output_triggers; }; + /// @brief Stores the metadata about camera properties. + /// @details Only used to request metadata from a camera, which expresses + /// capabilities of the camera and acceptable property values. struct CameraPropertyMetadata { struct Property exposure_time_us; @@ -51,17 +81,17 @@ extern "C" struct Property x, y; } shape; - /// bit field: bit i is 1 if SampleType(i) is supported, 0 otherwise + /// @brief The bits of this value describe the supported types. + /// @details Bit i is 1 if SampleType(i) is supported, 0 otherwise. uint64_t supported_pixel_types; struct CameraPropertyMetadataDigitalLineMetadata { - /// The number of supported digital IO lines - /// Must be less than 8. + /// @brief The number of supported digital IO lines. Must be less than 8. uint8_t line_count; - /// name[i] is a short, null terminated string naming line i. - /// Support describing up to 8 names for use with triggering. + /// @brief Support describing up to 8 names for use with triggering. + /// @details name[i] is a short, null terminated string naming line i. char names[8][64]; } digital_lines; @@ -69,9 +99,9 @@ extern "C" { struct camera_properties_metadata_trigger_capabilities_s { - /// Bit x is set if line x can be used as a trigger input. + /// @brief Bit i is set if line i can be used as a trigger input. uint8_t input; - /// Bit x is set if line x can be used as a trigger output. + /// @brief Bit i is set if line i can be used as a trigger output. uint8_t output; } acquisition_start, exposure, frame_start; } triggers;