MIPI_Camera API Introduction

Arducam MIPI Camera SDK provides the following APIs for MIPI camera

• arducam_init_camera:  init camera
• arducam_init_camera2: init camera with specific interface
• arducam_set_resolution:  Set output resolution.
• arducam_set_mode:  brief Set sensor mode.
• arducam_get_format:  brief Get the current format.
• arducam_set_video_callback:  Set video data output callback.
• arducam_set_raw_callback:  Set raw data output callback.
• arducam_capture:  Get single frame data.
• arducam_release_buffer:  arducam_release_buffer.
• arducam_start_preview:  Turn on image preview.
• arducam_stop_preview:  Turn off image preview.
• arducam_close_camera:  Release all resources and turn off the camera.
• arducam_reset_control:  Set camera control to default value.
• arducam_set_control:  Set camera control.
• arducam_get_control: Get camera control value.
• arducam_get_support_formats: Get the resolution supported by the current camera
• arducam_get_support_controls: Get the control parameters supported by the current camera
• arducam_write_sensor_reg:  brief Write sensor register.
• arducam_read_sensor_reg: brief Read sensor register.
• arducam_software_auto_exposure:  brief Enable/Disable software auto exposure 
• arducam_software_auto_white_balance: brief Enable/Disable software auto white balance
• arducam_unpack_raw10_to_raw8: brief Helper function, use to unpack mipi raw10.
• arducam_unpack_raw10_to_raw16: brief Helper function, use to unpack mipi raw10.
• arducam_manual_set_awb_compensation: used to compensate the red channel gain and blue change gain.

/**

int arducam_init_camera(CAMERA_INSTANCE *camera_instance);

• init camera.
• @param: camera_instance Pointer of type CAMERA_INSTANCE, use to
  obtain CAMERA_INSTANCE.
• @return error code , 0 success, !0 error.
  • example:
    @code
    CAMERA_INStANCE camera_instance;
    arducam_init_camera(&camera_instance);
    @endcode
• */

/**

int arducam_init_camera2(CAMERA_INSTANCE *camera_instance, struct camera_interface cam_interface);

• init camera.
• @param camera_instance Pointer of type CAMERA_INSTANCE, use to obtain CAMERA_INSTANCE.
• @param camera_num Camera interface num.
• @return error code , 0 success, !0 error.
  • example:
    @code
    CAMERA_INStANCE camera_instance;
    arducam_init_camera(&camera_instance, 0);
    @endcode
    @note Some boards have multiple camera interfaces.
• */

/**

int arducam_set_resolution(CAMERA_INSTANCE camera_instance, int *width, int *height);

• Set output resolution.
• @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
• @param width Pointer of type int, Used to specify the width and return to the actual width.
• @param height Pointer of type int, Used to specify the height and return to the actual height.
• @return error code , 0 success, !0 error.
• example:
  @code
  Int width = 1920;
  Int height = 1080;
  Int res = arducam_set_resolution(camera_instance, &width, &height);
  @endcode
  @note Some boards have multiple camera interfaces.
• */

/**

int arducam_set_mode(CAMERA_INSTANCEcamera_instance, int mode);

 * @brief Set sensor mode

 *

 * @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.

 * @param mode Mode index.(You can use the list_format program to view the supported modes.)

 * @return error code , 0 success, !0 error.

 @code

    Int mode = 1;

    Int res = arducam_set_mode(camera_instance, mode);

 @endcode

 @note Some boards have multiple camera interfaces.

 * */

/**

int arducam_get_format(CAMERA_INSTANCE camera_instance, struct format *fmt);

• @brief Get the current format.
  • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
• @param fmt Pointer of type struct format, used to store format information.
• @return ierror code , 0 success, !0 error.
  */

/**

int arducam_set_video_callback(CAMERA_INSTANCE camera_instance,

VIDEO_ENCODER_STATE *encoder_state, OUTPUT_CALLBACK callback, void *userdata);

• Set video data output callback.
  • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
• @param encoder_state Used to specify encoding parameters. Use default parameters if NULL.
• @param callback Callback method, this method will be called when there is data return.
• @param userdata Userdata, which will be a member of the buffer parameter in the callback function.
• @return error code , 0 success, !0 error.
  • example:
    @code
    int video_callback(BUFFER *buffer) {
    buffer->userdata;
    }
    // start callback
    if(arducam_set_video_callback(camera_instance, NULL, video_callback, NULL)){
    printf(“set video callback failed.”);
    }
    // stop callback
    arducam_set_video_callback(camera_instance, NULL, NULL, NULL)
    @endcode
    @note Calling the arducam_set_resolution function before stopping video encoding will terminate the video encoding.
    @note The buffer will be automatically released after the callback function ends.
• */

/**

int arducam_set_raw_callback(CAMERA_INSTANCE camera_instance, OUTPUT_CALLBACK

callback, void *userdata);

• Set raw data output callback.
  • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
• @param callback Callback method, this method will be called when there is data return.
• @param userdata Userdata, which will be a member of the buffer parameter in the callback function.
• @return error code , 0 success, !0 error.
  • example:
    @code
    int raw_callback(BUFFER *buffer) {
    buffer->userdata;
    }
    // start callback
    if(arducam_set_raw_callback(camera_instance, raw_callback, NULL)){
    printf(“set raw data callback failed.”);
    }
    // stop callback
    arducam_set_raw_callback(camera_instance, NULL, NULL)
    @endcode
    @note If you do a time-consuming operation in the callback, it will affect other parts, such as preview, video encoding(This issue may be fixed in the future).
    @note The buffer will be automatically released after the callback function ends.
• */

/**

BUFFER *arducam_capture(CAMERA_INSTANCEcamera_instance, IMAGE_FORMAT *format, inttimeout);

• Get single frame data.
• @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
• @param format The data format to be obtained.
• @param timeout This method will return NULL if no data is obtained at this time.
• @return BUFFER structure pointer containing image data.
  • example:
    @code
    IMAGE_FORMAT fmt = {IMAGE_ENCODING_JPEG, 50};
    BUFFER *buffer = arducam_capture(camera_instance, &fmt, 3000);
    if (!buffer) {
    LOG(“capture timeout.”);
    return;
    }
    @endcode
    @note Currently supported image formats are:
    IMAGE_ENCODING_JPEG, IMAGE_ENCODING_I420, IMAGE_ENCODING_RAW_BAYER
    @note When the buffer is used, you need to call the arducam_release_buffer function to release it.
    @note The actual width and height of the raw bayer format and the yuv420 format are aligned, width 32 bytes aligned, and height 16 byte aligned.
• */

/**

void arducam_release_buffer(BUFFER *buffer);

• Used to release the memory occupied by the buffer.
  • @param buffer The buffer to be released.
• */

/**

int arducam_start_preview(CAMERA_INSTANCE camera_instance, PREVIEW_PARAMS 

*preview_params);

• Turn on image preview
  • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
• @param preview_params Preview parameter,Use default parameters if NULL.
• @return error code , 0 success, !0 error.
• */

/**

int arducam_stop_preview(CAMERA_INSTANCEcamera_instance);

• Turn off image preview
  • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
• @return error code , 0 success, !0 error.
• */

/**

int arducam_close_camera(CAMERA_INSTANCEcamera_instance);

• Release all resources and turn off the camera.
  • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
• @return error code , 0 success, !0 error.
• */

/**

int arducam_reset_control(CAMERA_INSTANCE *camera_instance, intctrl_id);

• Set camera control to default value.
  • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
• @param ctrl_id Control id.
• @return error code , 0 success, !0 error.
  • example:
    @code
    arducam_reset_control(camera_instance, V4L2_CID_EXPOSURE);
    @endcode
• */

/**

int arducam_set_control(CAMERA_INSTANCEcamera_instance, int ctrl_id, intvalue);

• Set camera control.
  • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
• @param ctrl_id Control id.
• @param value Control value.
• @return error code , 0 success, !0 error.
  • example:
    @code
    arducam_set_control(camera_instance, V4L2_CID_EXPOSURE, 3000);
    @endcode
• */

/**

int arducam_get_control(CAMERA_INSTANCE camera_instance, intctrl_id, int *value);

• Get camera control value.
  • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
• @param ctrl_id Control id.
• @param value Current control value.
• @return error code , 0 success, !0 error.
  • example:
    @code
    int exposure = 0;
    arducam_get_control(camera_instance, V4L2_CID_EXPOSURE, &exposure);
    printf(“Current exposure is %d\n”, exposure);
    @endcode
• */

/**

int arducam_get_support_formats(CAMERA_INSTANCEcamera_instance, struct format *fmt, int index);

• Get the resolution supported by the current camera
  • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
• @param fmt Used to return resolution parameters.
• @param index Format list index.
• @return error code , 0 success, !0 error.
  • example:
    @code
    struct format support_fmt;
    unsigned int index = 0;
    while (!arducam_get_support_formats(camera_instance, &support_fmt, index++)) {
    printf(“index: %d, width: %d, height: %d\n”, index, support_fmt.width,
    support_fmt.height);
    }
    @endcode
• */

/**

int arducam_get_support_controls(CAMERA_INSTANCEcamera_instance, struct camera_ctrl *cam_ctrl, int index);

• Get the control parameters supported by the current camera.
  • @param camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
• @param cam_ctrl Used to return control parameters.
• @param index Control list index.
• @return error code , 0 success, !0 error.
  • example:
    @code
    unsigned int index = 0;
    struct camera_ctrl support_cam_ctrl;
    while (!arducam_get_support_controls(camera_instance, &support_cam_ctrl, index++)) {
    int value = 0;
    if (arducam_get_control(camera_instance, support_cam_ctrl.id, &value)) {
    printf(“Get ctrl %s fail.\n”, support_cam_ctrl.desc);
    }
    printf(“index: %d, CID: 0x%08X, desc: %s, min: %d, max: %d, default: %d, current: %d\n”,
    index, support_cam_ctrl.id, support_cam_ctrl.desc, support_cam_ctrl.min_value,
    support_cam_ctrl.max_value, support_cam_ctrl.default_value, value);
    }
    @endcode
• */

/**

int arducam_write_sensor_reg(CAMERA_INSTANCE camera_instance, uint16_t address,

uint16_t value);

• @brief Write sensor register.
  • @param camera_instance camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
• @param address Sensor register address.
• @param value The value you want to write
• @return error code , 0 success, !0 error.
  */

/**

int arducam_read_sensor_reg(CAMERA_INSTANCE camera_instance, uint16_t address,

uint16_t *value);

• @brief Read sensor register.
  • @param camera_instance camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
• @param address Sensor register address.
• @param value The address of the variable that stores the result.
• @return error code , 0 success, !0 error.
  */

/**

int arducam_software_auto_exposure(CAMERA_INSTANCE camera_instance, int enable);

• @brief Enable/Disable software auto exposure.
  • @param camera_instance camera_instance Type CAMERA_INSTANCE, Obtained from
    arducam_init_camera function.
• @param enable 0 disable, !0 enable.
• @return error code , 0 success, !0 error.
  • @note Calling the arducam_set_resolution function will turn off this feature.
    */

/**

int arducam_software_auto_white_balance(CAMERA_INSTANCE camera_instance, intenable);

• @brief Enable/Disable software auto white balance.
  • @param camera_instance camera_instance Type CAMERA_INSTANCE, Obtained from arducam_init_camera function.
• @param enable 0 disable, !0 enable.
• @return error code , 0 success, !0 error.
  • @note Calling the arducam_set_resolution function will turn off this feature.
    */

/**

BUFFER *arducam_unpack_raw10_to_raw8(uint8_t *buff_in, int width, int height);

• @brief Helper function， use to unpack mipi raw10.
  • @param buff_in Raw10 data buffer.
• @param width Image width
• @param height Image height
• @return BUFFER structure pointer containing image data.
  • @note This function will remove the part that is filled because of the alignment,
• @note for example, the height is 1080, because the height needs 16 is the alignment,
• @note so the actual pixel height is 1088. After passing the height of 1080 using this
• @note function, the actual pixel height of the output is 1080.
  • @note The performance of this function is not very good.
    */

/**

BUFFER *arducam_unpack_raw10_to_raw16(uint8_t *buff_in, intwidth, int height);

• @brief Helper function， use to unpack mipi raw10.
  • @param buff_in Raw10 data buffer.
• @param width Image width
• @param height Image height
• @return BUFFER structure pointer containing image data.
  • @note This function will remove the part that is filled because of the alignment,
• @note for example, the height is 1080, because the height needs 16 is the alignment,
• @note so the actual pixel height is 1088. After passing the height of 1080 using this
• @note function, the actual pixel height of the output is 1080.
  • @note The performance of this function is not very good.
    */

/**

void arducam_manual_set_awb_compensation(uint32_t r_gain, uint32_t b_gain);

• @brief set awb function， use to compensation the rgain and bgain
  • @param r_gain the red channel compensation
• @param b_gain the blue channel compensation
  */