alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2025-08-09 12:35:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Provide CN translation for camera_driver.rst

Browse Source
This commit is contained in:
shenmengjing
2024-07-26 16:21:13 +08:00
parent ed91305d6a
commit f7232871b4
7 changed files with 268 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
docs/en/api-reference/peripherals/camera_driver.rst
View File

@@ -1,6 +1,8 @@
Camera Controller Driver
========================
:link_to_translation:`zh_CN:[中文]`
Introduction
------------
@@ -9,8 +11,9 @@ Introduction
.. list::
: SOC_MIPI_CSI_SUPPORTED : - MIPI Camera Serial Interface (CSI)
: SOC_ISP_DVP_SUPPORTED : - ISP Digital Video Port (ISP DVP)
The Camera Controller Driver is designed for this hardware peripheral.
The camera controller driver is designed for this hardware peripheral.
Functional Overview
@@ -18,14 +21,14 @@ Functional Overview
.. list::
- `Resource Allocation <#cam-resource-allocation>`__ - covers how to allocate camera controller instances with properly set of configurations. It also covers how to recycle the resources when they are no longer needed.
- `Enable and disable a camera controller <#cam-enable-disable>`__ - covers how to enable and disable a camera controller.
- `Start and stop a camera controller <#cam-start-stop>`__ - covers how to start and stop a camera controller.
- `Receive from a camera sensor or something else <#cam-receive>`__ - covers how to receive camera signal from a sensor or something else.
- `Register callback <#cam-callback>`__ - covers how to hook user specific code to camera controller driver event callback function.
- `Thread Safety <#cam-thread-safety>`__ - lists which APIs are guaranteed to be thread safe by the driver.
- `Kconfig Options <#cam-kconfig-options>`__ - lists the supported Kconfig options that can bring different effects to the driver.
- `IRAM SAFE <#cam-iram-safe>`__ - describes tips on how to make the CSI interrupt and control functions work better along with a disabled cache.
- :ref:`cam-resource-allocation` - covers how to allocate camera controller instances with properly set of configurations. It also covers how to recycle the resources when they are no longer needed.
- :ref:`cam-enable-disable` - covers how to enable and disable a camera controller.
- :ref:`cam-start-stop` - covers how to start and stop a camera controller.
- :ref:`cam-receive`- covers how to receive camera signal from a sensor or something else.
- :ref:`cam-callback`- covers how to hook user specific code to camera controller driver event callback function.
- :ref:`cam-thread-safety` - lists which APIs are guaranteed to be thread safe by the driver.
- :ref:`cam-kconfig-options` - lists the supported Kconfig options that can bring different effects to the driver.
- :ref:`cam-iram-safe` - describes tips on how to make the CSI interrupt and control functions work better along with a disabled cache.
.. _cam-resource-allocation:
@@ -37,7 +40,7 @@ Install Camera Controller Driver
.. only:: SOC_MIPI_CSI_SUPPORTED
A Camera Controller Driver can be implemented by the CSI peripheral, which requires the configuration that specified by :cpp:type:`esp_cam_ctlr_csi_config_t`.
A camera controller driver can be implemented by the CSI peripheral, which requires the configuration that specified by :cpp:type:`esp_cam_ctlr_csi_config_t`.
If the configurations in :cpp:type:`esp_cam_ctlr_csi_config_t` is specified, users can call :cpp:func:`esp_cam_new_csi_ctlr` to allocate and initialize a CSI camera controller handle. This function will return an CSI camera controller handle if it runs correctly. You can take following code as reference.
@@ -59,7 +62,7 @@ Install Camera Controller Driver
.. only:: SOC_ISP_DVP_SUPPORTED
A Camera Controller Driver can be implemented by the ISP DVP peripheral, which requires the configuration that specified by :cpp:type:`esp_cam_ctlr_isp_dvp_cfg_t`.
A camera controller driver can be implemented by the ISP DVP peripheral, which requires the configuration that specified by :cpp:type:`esp_cam_ctlr_isp_dvp_cfg_t`.
If the configurations in :cpp:type:`esp_cam_ctlr_isp_dvp_cfg_t` is specified, users can call :cpp:func:`esp_cam_new_isp_dvp_ctlr` to allocate and initialize a ISP DVP camera controller handle. This function will return an ISP DVP camera controller handle if it runs correctly. You can take following code as reference.
@@ -95,14 +98,14 @@ Install Camera Controller Driver
Uninstall Camera Controller Driver
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If a previously installed Camera Controller Driver is no longer needed, it's recommended to recycle the resource by calling :cpp:func:`esp_cam_ctlr_del`, so that to release the underlying hardware.
If a previously installed camera controller driver is no longer needed, it's recommended to recycle the resource by calling :cpp:func:`esp_cam_ctlr_del`, so that to release the underlying hardware.
.. _cam-enable-disable:
Enable and Disable Camera Controller Driver
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Before starting camera controller operation, you need to enable the camera controller controller first, by calling :cpp:func:`esp_cam_ctlr_enable`. This function:
Before starting camera controller operation, you need to enable the camera controller driver first, by calling :cpp:func:`esp_cam_ctlr_enable`. This function:
* Switches the driver state from **init** to **enable**.
@@ -121,9 +124,9 @@ Calling :cpp:func:`esp_cam_ctlr_disable` does the opposite, that is, put the dri
Start and Stop Camera Controller Driver
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Before receiving camera signal from camera sensor, you need to start the Camera Controller Driver first, by calling :cpp:func:`esp_cam_ctlr_start`. This function:
Before receiving camera signal from camera sensor, you need to start the camera controller driver first, by calling :cpp:func:`esp_cam_ctlr_start`. This function:
* Switches the driver stat from **enable** to **start**
* Switches the driver state from **enable** to **start**.
.. code:: c
@@ -137,7 +140,7 @@ Calling :cpp:func:`esp_cam_ctlr_stop` does the opposite, that is, put the driver
.. _cam-receive:
Receive from A Camera Sensor
Receive from a Camera Sensor
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now you can call :cpp:func:`esp_cam_ctlr_receive` to receive from a camera sensor or something else.
@@ -151,11 +154,11 @@ Now you can call :cpp:func:`esp_cam_ctlr_receive` to receive from a camera senso
Register Event Callbacks
^^^^^^^^^^^^^^^^^^^^^^^^
After the Camera Controller Driver starts receiving, it can generate a specific event dynamically. If you have some functions that should be called when the event happens, please hook your function to the interrupt service routine by calling :cpp:func:`esp_cam_ctlr_register_event_callbacks`. All supported event callbacks are listed in :cpp:type:`esp_cam_ctlr_evt_cbs_t`:
After the camera controller driver starts receiving, it can generate a specific event dynamically. If you have some functions that should be called when the event happens, please hook your function to the interrupt service routine by calling :cpp:func:`esp_cam_ctlr_register_event_callbacks`. All supported event callbacks are listed in :cpp:type:`esp_cam_ctlr_evt_cbs_t`:
- :cpp:member:`esp_cam_ctlr_evt_cbs_t::on_get_new_trans` sets a callback function when the Camera Controller Driver gets a new transaction which is passed from :cpp:func:`esp_cam_ctlr_receive`. As this function is called within the ISR context, you must ensure that the function does not attempt to block (e.g., by making sure that only FreeRTOS APIs with ``ISR`` suffix are called from within the function).
- :cpp:member:`esp_cam_ctlr_evt_cbs_t::on_get_new_trans` sets a callback function which will be called after the camera controller driver finishes previous transaction, and tries to get a new transaction descriptor. It will also be called when in :cpp:func:`s_ctlr_csi_start`. If this callback does not get a new transaction descriptor, the camera controller driver will use the internal backup buffer if ``bk_buffer_dis`` flag is set.
- :cpp:member:`esp_cam_ctlr_evt_cbs_t::on_trans_finished` sets a callback function when the Camera Controller Driver finishes a transaction. As this function is called within the ISR context, you must ensure that the function does not attempt to block (e.g., by making sure that only FreeRTOS APIs with ``ISR`` suffix are called from within the function).
- :cpp:member:`esp_cam_ctlr_evt_cbs_t::on_trans_finished` sets a callback function when the camera controller driver finishes a transaction. As this function is called within the ISR context, you must ensure that the function does not attempt to block (e.g., by making sure that only FreeRTOS APIs with ``ISR`` suffix are called from within the function).
.. _cam-thread-safety:
@@ -165,22 +168,24 @@ Thread Safety
The factory functions:
.. list::
:SOC_MIPI_CSI_SUPPORTED: - :cpp:func:`esp_cam_new_csi_ctlr`
:SOC_ISP_DVP_SUPPORTED: - :cpp:func:`esp_cam_new_isp_dvp_ctlr`
- :cpp:func:`esp_cam_ctlr_del`
are guaranteed to be thread safe by the driver, which means, user can call them from different RTOS tasks without protection by extra locks.
are guaranteed to be thread safe by the driver, which means, they can be called from different RTOS tasks without protection by extra locks.
.. _cam-kconfig-options:
Kconfig Options
^^^^^^^^^^^^^^^
The following kconfig options the behavior of the interrupt handler when cache is disabled:
The following Kconfig options affect the behavior of the interrupt handler when cache is disabled:
.. list::
:SOC_MIPI_CSI_SUPPORTED: - :ref:`CONFIG_CAM_CTLR_MIPI_CSI_ISR_IRAM_SAFE`, see `IRAM SAFE <#cam-iram-safe>`__ for more details.
:SOC_ISP_DVP_SUPPORTED: - :ref:`CONFIG_CAM_CTLR_ISP_DVP_ISR_IRAM_SAFE`, see `IRAM SAFE <#cam-iram-safe>`__ for more details.
:SOC_MIPI_CSI_SUPPORTED: - :ref:`CONFIG_CAM_CTLR_MIPI_CSI_ISR_IRAM_SAFE`, see :ref:`cam-thread-safety` for more details.
:SOC_ISP_DVP_SUPPORTED: - :ref:`CONFIG_CAM_CTLR_ISP_DVP_ISR_IRAM_SAFE`, see :ref:`cam-thread-safety` for more details.
.. _cam-iram-safe:
@@ -192,6 +197,7 @@ By default, the CSI interrupt will be deferred when the cache is disabled becaus
There are Kconfig options
.. list::
:SOC_MIPI_CSI_SUPPORTED: - :ref:`CONFIG_CAM_CTLR_MIPI_CSI_ISR_IRAM_SAFE`
:SOC_ISP_DVP_SUPPORTED: - :ref:`CONFIG_CAM_CTLR_ISP_DVP_ISR_IRAM_SAFE`
@@ -203,6 +209,11 @@ that
This allows the interrupt to run while the cache is disabled, but comes at the cost of increased IRAM consumption. So user callbacks need to notice that the code and data inside (the callback) should be IRAM-safe or DRAM-safe, when cache is disabled.
Application Examples
--------------------
* :example:`peripherals/camera/camera_dsi` demonstrates how to use the ``esp_driver_cam`` component to capture signals from a camera sensor and display it on an ILI9881C LCD screen via a DSI interface.
API Reference
-------------
@@ -210,3 +221,4 @@ API Reference
.. include-build-file:: inc/esp_cam_ctlr_types.inc
.. include-build-file:: inc/esp_cam_ctlr_csi.inc
.. include-build-file:: inc/esp_cam_ctlr_isp_dvp.inc
.. include-build-file:: inc/isp_core.inc

2
docs/en/api-reference/peripherals/usb_host/usb_host_notes_enum.rst
View File

@@ -1,3 +1,5 @@
.. Translation not required: According to the USB developers, all of the ``usb_host_notes_*`` files are just internal notes for ESP-IDF developers, not for our end users. So we don't need to translate them at all.
USB Host Enumeration Driver (Enum)
==================================

2
docs/en/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst
View File

@@ -1,3 +1,5 @@
.. Translation not required: According to the USB developers, all of the ``usb_host_notes_*`` files are just internal notes for ESP-IDF developers, not for our end users. So we don't need to translate them at all.
USB Host Driver (USBH)
======================