비디오 디코딩

이 섹션에서는 비디오 디코딩 기능을 가진 TouchGFX HAL을 생성하기 위해 TouchGFX Generator를 구성하는 방법을 보여줍니다.

이 시나리오를 읽기 전에 먼저 TouchGFX의 MJPEG 비디오 사용에 대한 설명서와 비디오 위젯에 대한 설명서를 읽어보시기 바랍니다.

아래 시나리오는 TouchGFX HAL을 활성화하여 소프트웨어(LibJPEG)나 하드웨어(JPEG)를 통해 비디오 디코딩을 지원하는 방법을 자세히 설명한 것입니다.

특정 프로젝트에 대해 MCU를 구성하기 전에 이 문서의 모든 섹션을 읽어 보시기 바랍니다.

일반적으로 LibJPEG 및 JPEG 구성은 Middleware 및 Multimedia 범주의 STM32CubeMX에서 확인할 수 있습니다.

STM32CubeMX의 JPEG 및 LibJPEG 설정

Tip
Several of the TouchGFX Board Setups (TBSs) in TouchGFX Designer include support for MJPEG video decoding.
Use the STM32CubeMX configurations found in these example projects as inspiration to enable MJPEG video decoding on your specific MCU.
An example of software decoding can be found in the TBS for STM32H735G-DK, while hardware decoding is used in the TBS for STM32U5G9J-DK2.

RTOS 지원

The Generator User Guide mentions that Single- and Double buffer video decoding strategies require a CMSIS compliant RTOS, such as FreeRTOS. TouchGFX Generator는 비디오 디코딩 테스크에 연결해야 하는 엔트리 포인트 함수 videoTaskFunc()를 생성합니다. STM32CubeMX는 FreeRTOS 미들웨어 구성의 Tasks and queues 탭에서 테스크 및 엔트리 포인트 함수를 정의하여 이 구성을 생성할 수 있습니다.

두 가지 중요한 요소로 비디오 테스크 스택 크기(CMSIS V2의 경우 단어로 정의)와 RTOS 힙 크기가 있습니다.

For software decoding, the stack size must be carefully set because LibJPEG uses dynamic memory allocation. This means that the FreeRTOS heap should be large enough to accommodate your general application + 0xA000 (~41kB). For hardware decoding, the stack size can be substantially lower because there is no software stack that dynamically allocates memory.

FreeRTOS 태스크 구성

FreeRTOS 힙 크기 구성

위의 구성을 기반으로 STM32CubeMX는 비디오 테스크에 대해 다음 코드를 생성합니다.

main.c

/* Definitions for VideoTask */
osThreadId_t VideoTaskHandle;
const osThreadAttr_t VideoTask_attributes = {
  .name = "VideoTask",
  .stack_size = 1000 * 4,
  .priority = (osPriority_t) osPriorityLow,
};
...
void main()
{
    ...
    /* creation of VideoTask */
    VideoTaskHandle = osThreadNew(videoTaskFunc, NULL, &VideoTask_attributes);
    ...
}

FreeRTOSConfig.h

#define configTOTAL_HEAP_SIZE                    ((size_t)75000)

소프트웨어 디코딩

소프트웨어 디코딩 솔루션을 사용하려면 Generator User Guide에 나와 있는대로, STM32CubeMX에서 LibJPEG 미들웨어가 활성화되어 있어야 합니다. 소프트웨어 디코딩 설정은 LibJPEG를 지원하는 MCU(예: STM32F4, STM32F7, STM32H7)에서 모두 동일합니다.

TouchGFX 소프트웨어 디코더는 LibJPEG에서 디코딩되는 데이터를 BGR 픽셀 순서로 설정합니다. 이 설정이 RGB로 남아 있다면 R 색상 성분과 B 색상 성분이 애플리케이션에서 서로 자리를 바꿉니다.

또한, 각 픽셀의 크기는 16비트 또는 24비트 비디오 RGB 버퍼를 사용하는 경우에는 3바이트, 32비트 비디오 RGB 버퍼를 사용하는 경우에는 4바이트여야 합니다.

16비트 또는 24비트 비디오 RGB 버퍼를 위한 LibJPEG 구성

Caution
The RGB_ORDERING setting must be configured as BGR, and the pixel size must be set according to which video RGB buffer format is used.
If your application uses Direct to Framebuffer strategy in a ARGB8888 (32-bit) application the pixel size must be set to 4.

비디오 데이터

TouchGFX links the video data to the ExtFlashSection, which needs to be defined in the linker script. If ExtFlashSection is placed in non-memory-mapped flash, the data must be read from the flash memory using a data reader and handed to the decoder.

For projects with video data in non-memory-mapped memory, please refer to the FileReader section later in this article in this article.

하드웨어 디코딩

The Generator User Guide mentions that the JPEG IP must be enabled in STM32CubeMX to enable hardware decoding.

JPEG 구성에 있는 RGB_FORMAT 설정은 TouchGFX 프레임 버퍼의 픽셀 형식(아래 예제의 경우 JPEG_RGB565)을 준수해야 합니다.

JPEG IP Parameter Settings

When using hardware decoding, a DMA is used to transfer data to (memory-to-peripheral) and from (peripheral-to-memory) the JPEG IP. Which DMA to use and how to configure it differs between MCU families.

Tip
Here are some examples of TouchGFX Board Setups available in TouchGFX Designer that demonstrate how to set up JPEG decoding with different types of DMAs:STM32U5G9J-DK2: JPEG + GPDMA
STM32H750B-DK: JPEG + MDMA
STM32H7S78-DK: JPEG + HPDMA

STM32H750 example

Here is an example of how to set up the DMA on STM32H750 for JPEG decoding. For the STM32H750, the JPEG peripheral must be configured to use the MDMA peripheral instead of the regular DMA peripherals. Add an MDMA configuration for both the input and output FIFO threshold signals, as shown in the image below. The configuration is identical for both the input and output buffers.

JPEG DMA settings for STM32H750

`FileReader` 인터페이스

개발자가 MJPEG 비디오를 메모리 매핑이 되지 않는 메모리에 저장하는 경우에는 TouchGFX 비디오 컨트롤러가 디코딩할 데이터를 구성된 디코더(소프트웨어/하드웨어)로 전달할 때 사용할 touchgfx::VideoDataReader 구현체를 지정할 수 있습니다. 아래는 비디오 데이터를 버퍼에서 다른 버퍼로 복사하는 인터페이스의 예시입니다.

VideoView.cpp

class MyReader : public touchgfx::VideoDataReader
{
public:
    MyReader() : position(0) { }
    virtual uint32_t getDataLength() { return video_len; }
    virtual void seek(uint32_t pos) { position = pos; }
    virtual bool readData(void* dst, uint32_t bytes)
    {
        memcpy(dst, &video_data[position], bytes);
        position += bytes;
        return true;
    }
    private:
        uint32_t position;
} myReader;

개발자는 Video 위젯에게 매핑 메모리에서 비디오 시작 방향으로 향하는 대신, 데이터 리더를 사용하도록 구성할 수 있습니다.

VideoView.cpp

video.setVideoData(myReader);

TBS 마이그레이션을 통한 비디오 디코딩 지원

비디오 디코딩이 지원되기 전의 TouchGFX Designer 버전에서 비디오 디코딩을 지원하는 MCU로 TouchGFX Board Setups(TBS)에서 생성된 프로젝트를 마이그레이션하고 싶고, 해당 프로젝트에서 TouchGFX Designer에서 'Run Target'을 사용하고 싶은 경우에는 GCC Makefile에 대한 약간의 수동 변경이 필요합니다.

필요한 변경 사항과 그 이유에 대해서는 다음 섹션에서 설명하겠습니다. 항상 적용이 되어야 하는 몇 가지 일반적인 변경 사항이 있으며, LibJPEG(소프트웨어 디코딩) 및 JPEG(하드웨어 디코딩) 고유의 몇몇 변경 사항은 개발자 애플리케이션에서 사용되는 디코딩에 따라 달라집니다. 이전 TBS에서 이미 존재하는 GCC Makefile로 확장하는 변경이 필요합니다.

Makefile을 업데이트하는 것 외에도 위의 시나리오에서 설명한 것처럼 STM32CubeMX에서 비디오 디코딩을 설정해야 합니다.

일반 변경 사항

프로젝트에서 LIBJPEG 경로를 정의합니다.

# LibJPEG path
libjpeg_path := $(cubemx_middlewares_path)/Third_Party/LibJPEG

그런 다음 비디오 애셋 입력 경로를 정의해야 합니다.

asset_texts_input  := TouchGFX/assets/texts

asset_videos_input := TouchGFX/assets/videos

비디오 애셋 출력 경로가 기존의 애셋 출력 경로 아래에 정의되어 있어야 합니다.

asset_images_output := $(asset_root_path)/images
asset_fonts_output := $(asset_root_path)/fonts
asset_texts_output := $(asset_root_path)/texts
asset_videos_output := $(asset_root_path)/videos

비디오 출력 애셋을 구성요소 목록에 추가합니다.

all_components := $(components) \
    $(asset_fonts_output) \
    $(asset_images_output) \
    $(asset_texts_output)
    $(asset_texts_output) \
    $(asset_videos_output)

비디오 객체 파일을 정의해야 합니다. 비디오 객체 파일은 기존 객체와 분리되어 있습니다.

c_source_files := $(call find, $(source_paths),*.c) $(os_source_files) $(board_c_files)
source_files += $(board_cpp_files)

video_object_files := $(call find, $(asset_videos_output),*.o)

비디오 변환 도구 스크립트에 대한 경로를 정의해야 합니다.

textconvert_script_path := $(touchgfx_path)/framework/tools/textconvert
textconvert_executable := $(call find, $(textconvert_script_path), *.rb)
videoconvert_script_path := $(touchgfx_path)/framework/tools/videoconvert

모든 비디오 객체 파일을 볼 수 있도록 echo 옵션을 추가할 수 있습니다. 이때 비디오 객체 파일을 연결 단계에 추가해야 합니다. 이 행에는 나머지 객체 파일과 함께 $(video_object_files)가 추가됩니다.

$(binary_output_path)/$(target_executable): $(object_files) $(object_asm_files)
    @echo Video Objects: $(video_object_files)
    @echo Linking $(@)
    @mkdir -p $(@D)
    @mkdir -p $(object_output_path)
    @$(file >$(build_root_path)/objects.tmp) $(foreach F,$(object_files) $(video_object_files),$(file >>$(build_root_path)/objects.tmp,$F))

비디오 규칙을 기존 애셋과 .PHONY에 추가합니다.

_assets_: BitmapDatabase TextKeysAndLanguages Videos

.PHONY: BitmapDatabase TextKeysAndLanguages Videos

비디오 규칙이 비디오 변환 추가와 함께 추가됩니다.

Videos:
    @ruby $(videoconvert_script_path)/videoconvert.rb $(asset_videos_input) $(asset_videos_output)

마지막으로 비디오 관련 출력도 삭제할 수 있도록 삭제 규칙을 업데이트합니다.

_clean_:
    @echo Cleaning: $(board_name)
    @rm -rf $(build_root_path)
    # Do not remove gui_generated
    @rm -rf $(asset_images_output)
    @rm -rf $(asset_fonts_output)
    @rm -rf $(asset_texts_output)
    @rm -rf $(asset_videos_output)
    # Create directory to avoid error if it does not exist
    @mkdir -p $(asset_root_path)
    # Remove assets folder if it is empty (i.e. no gui_generated folder)
    @rmdir --ignore-fail-on-non-empty $(asset_root_path)
    # Clean bootloader project
    @$(MAKE) -r -f ExtMem_Boot/gcc/Makefile -s $(MFLAGS) clean

소프트웨어 변경 사항

모든 LIBJPEG 경로를 include 경로에 추가합니다.

include_paths := $(library_includes) \
    $(foreach comp, $(all_components), $(comp)/include) \
    $(foreach comp, $(cubemx_components), $(comp)/Inc) \
    $(foreach comp, $(touchgfx_generator_components), $(comp)/generated) \
    $(framework_includes) \
    $(cubemx_middlewares_path) \
    $(touchgfx_middlewares_path) \
    $(touchgfx_generator_components) \
    LIBJPEG/Target \
    $(libjpeg_path)/include \
    LIBJPEG/App

LIBJPEG 소스 경로를 정의해야 합니다.

c_source_files := $(call find, $(source_paths),*.c) $(os_source_files) $(board_c_files)
source_files += $(board_cpp_files)

libjpeg_source_path = Middlewares/Third_Party/LibJPEG/source

그런 다음 모든 LIBJPEG 소스 파일을 board_c_files에 추가해야 합니다.

board_c_files := \
    $(Drivers_path)/BSP/STM32H750B-DK/stm32h750b_discovery_bus.c \
    $(Drivers_path)/BSP/STM32H750B-DK/stm32h750b_discovery_qspi.c \
    $(Drivers_path)/BSP/STM32H750B-DK/stm32h750b_discovery_sdram.c \
    $(Drivers_path)/BSP/STM32H750B-DK/stm32h750b_discovery_ts.c \
    $(Drivers_path)/BSP/Components/ft5336/ft5336.c \
    $(Drivers_path)/BSP/Components/ft5336/ft5336_reg.c \
    $(Drivers_path)/BSP/Components/mt25tl01g/mt25tl01g.c \
    $(Drivers_path)/BSP/Components/mt48lc4m32b2/mt48lc4m32b2.c \
    $(libjpeg_source_path)/jaricom.c \
    $(libjpeg_source_path)/jcomapi.c \
    $(libjpeg_source_path)/jdapimin.c \
    $(libjpeg_source_path)/jdapistd.c \
    $(libjpeg_source_path)/jdarith.c \
    $(libjpeg_source_path)/jdatasrc.c \
    $(libjpeg_source_path)/jdcoefct.c \
    $(libjpeg_source_path)/jdcolor.c \
    $(libjpeg_source_path)/jddctmgr.c \
    $(libjpeg_source_path)/jdhuff.c \
    $(libjpeg_source_path)/jdinput.c \
    $(libjpeg_source_path)/jdmainct.c \
    $(libjpeg_source_path)/jdmarker.c \
    $(libjpeg_source_path)/jdmaster.c \
    $(libjpeg_source_path)/jdmerge.c \
    $(libjpeg_source_path)/jdpostct.c \
    $(libjpeg_source_path)/jdsample.c \
    $(libjpeg_source_path)/jdtrans.c \
    $(libjpeg_source_path)/jerror.c \
    $(libjpeg_source_path)/jidctflt.c \
    $(libjpeg_source_path)/jidctfst.c \
    $(libjpeg_source_path)/jidctint.c \
    $(libjpeg_source_path)/jmemmgr.c \
    $(libjpeg_source_path)/jmemnobs.c \
    $(libjpeg_source_path)/jquant1.c \
    $(libjpeg_source_path)/jquant2.c \
    $(libjpeg_source_path)/jutils.c \
    LIBJPEG/App/libjpeg.c

그러면 LIBJPEG 소스 파일이 나머지 미들웨어 소스 파일과 동일한 방식으로 기존 객체 파일에 추가됩니다.

# Start converting paths
object_files := $(object_files:$(touchgfx_path)/%.cpp=$(object_output_path)/touchgfx/%.o)
object_files := $(object_files:%.cpp=$(object_output_path)/%.o)
object_files := $(object_files:$(touchgfx_middlewares_path)/%.c=$(object_output_path)/$(touchgfx_middlewares_path)/%.o)
object_files := $(object_files:$(cubemx_middlewares_path)/%.c=$(object_output_path)/$(cubemx_middlewares_path)/%.o)
object_files := $(object_files:$(libjpeg_source_path)/%.c=$(object_output_path)/$(libjpeg_source_path)/%.o)
object_files := $(object_files:$(Drivers_path)/%.c=$(object_output_path)/Drivers/%.o)
object_files := $(object_files:%.c=$(object_output_path)/%.o)

하드웨어 변경 사항

모든 JPEG 경로를 include 경로에 추가합니다.

include_paths := $(library_includes) \
    $(foreach comp, $(all_components), $(comp)/include) \
    $(foreach comp, $(cubemx_components), $(comp)/Inc) \
    $(foreach comp, $(touchgfx_generator_components), $(comp)/generated) \
    $(framework_includes) \
    $(cubemx_middlewares_path) \
    $(touchgfx_middlewares_path) \
    $(touchgfx_generator_components) \
    Utilities/JPEG

그런 다음 모든 JPEG 소스 파일을 board_c_files에 추가해야 합니다.

board_c_files := \
    $(Drivers_path)/BSP/STM32H750B-DK/stm32h750b_discovery_bus.c \
    $(Drivers_path)/BSP/STM32H750B-DK/stm32h750b_discovery_qspi.c \
    $(Drivers_path)/BSP/STM32H750B-DK/stm32h750b_discovery_sdram.c \
    $(Drivers_path)/BSP/STM32H750B-DK/stm32h750b_discovery_ts.c \
    $(Drivers_path)/BSP/Components/ft5336/ft5336.c \
    $(Drivers_path)/BSP/Components/ft5336/ft5336_reg.c \
    $(Drivers_path)/BSP/Components/mt25tl01g/mt25tl01g.c \
    $(Drivers_path)/BSP/Components/mt48lc4m32b2/mt48lc4m32b2.c \
    Utilities/JPEG/jpeg_utils.c

비디오 버퍼를 외부 메모리에 저장하기

When developers create new projects with STM32CubeMX, the linker scripts associated with the generated projects do not contain default regions used by TouchGFX. Because of this, 'ExtFlashSection' where the video is stored is placed in internal flash by default. It will often be required to place 'ExtFlashSection' in external flash memory to avoid running out of internal flash memory.

Tip
The following TBSs are examples of preconfigured TBSs that are ready to decode videos from external memory:STM32F746-DISCO
STM32H735G-DK
STM32H750-DK
STM32U5G9J-DK2

If the video strategy selected is not direct to framebuffer, an RGB buffer dedicated to JPEG decoding is generated by TouchGFX Generator when video is enabled. 정의는 링커에게 버퍼를 저장할 섹션을 알려주는 location pragma로 계측됩니다. 링커가 링커 스크립트에서 이 메모리 영역을 찾지 못하면 버퍼가 내부 메모리에 저장됩니다.

LOCATION_PRAGMA_NOLOAD("Video_RGB_Buffer")
uint32_t videoRGBBuffer[57600] LOCATION_ATTRIBUTE_NOLOAD("Video_RGB_Buffer");

The following compiler-specific subsections describe an example of the modifications that developers can make to achieve placing the buffer in SDRAM on STM32F746G-DISCO. Video_RGB_Buffer는 비디오 디코딩에 사용되는 버퍼를 말합니다. 링커 스크립트 예제에서는 TouchGFX 프레임 버퍼를 위해 SDRAM에 일부 공간(0xC0000000에서 시작)을 남겨두었습니다.

EWARM
STM32CubeIDE
MDK-ARM

EWARM (IAR)

stm32f746xx_flash.icf

define symbol __ICFEDIT_region_SDRAM_start__   = 0xC00FF000;
define symbol __ICFEDIT_region_SDRAM_end__     = 0xC0700FFF;

define region SDRAM_region    = mem:[from __ICFEDIT_region_SDRAM_start__ to __ICFEDIT_region_SDRAM_end__];

place in SDRAM_region    { first section Video_RGB_Buffer };

연결을 마치면 EWARM\STM32F746G_DISCO\List\STM32F746G_DISCO.map에 다음과 같이 Video_RGB_Buffer 저장 정보가 포함됩니다.

STM32F746G_DISCO.map

Video_RGB_Buffer        zero     0xc00f'f000   0x3'8400  TouchGFXGeneratedHAL.o [2]
                               - 0xc013'7400   0x3'8400

STM32CubeIDE

STM32F746NGHX_FLASH.ld

MEMORY
{
  ...
  SDRAM      (xrw)    : ORIGIN = 0xC00FF000,   LENGTH = 8M
}

BufferSection (NOLOAD) :
{
  *(Video_RGB_Buffer Video_RGB_Buffer.*)
  *(.gnu.linkonce.r.*)
  . = ALIGN(0x4);
} >SDRAM

컴파일을 마치면 STM32CubeIDE\Debug\STM32F746G_DISCO.map에 다음과 같이 Video_RGB_Buffer 저장 정보가 포함됩니다.

STM32F746G_DISCO.map

BufferSection   0x00000000c00ff000    0x1c200
 *(Video_RGB_Buffer Video_RGB_Buffer.*)
 Video_RGB_Buffer
                0x00000000c00ff000    0x1c200 Application/User/TouchGFX/target/generated/TouchGFXGeneratedHAL.o
                0x00000000c00ff000                videoRGBBuffer

MDK-ARM (Keil)

STM32F746G_DISCO.sct

LR_IROM1 0x08000000 0x00200000  {    ; load region size_region
  ER_IROM1 0x08000000 0x00200000  {  ; load address = execution address
    *.o (RESET, +First)
    *(InRoot$$Sections)
    .ANY (+RO)
  }
  RW_IRAM1 0x20000000 0x00050000  {  ; RW data
    .ANY (+RW +ZI)
  }
  RW_SDRAM 0xC00FF000 UNINIT 0xC0700FFF  {
    *.o (Video_RGB_Buffer)
  }
}

비디오 버퍼를 보유하고 있는 섹션에 UNINIT 속성을 포함시켜야 합니다. 이렇게 하면 메모리 영역이 초기화되지 않은 데이터로 남게 됩니다. 연결을 마치면 MDK-ARM\STM32F746G_DISCO\STM32F746G_DISCO.map에 다음과 같이 Video_RGB_Buffer 저장 정보가 포함됩니다.

STM32F746G_DISCO.map

Video_RGB_Buffer                         0xc00ff000   Section    115200  touchgfxgeneratedhal.o(Video_RGB_Buffer)

Tip

RTOS 지원​

main.c

FreeRTOSConfig.h

소프트웨어 디코딩​

Caution

비디오 데이터​

하드웨어 디코딩​

Tip

STM32H750 example​

FileReader 인터페이스​

VideoView.cpp

VideoView.cpp

TBS 마이그레이션을 통한 비디오 디코딩 지원​

일반 변경 사항​

소프트웨어 변경 사항​

하드웨어 변경 사항​

비디오 버퍼를 외부 메모리에 저장하기​

Tip

Further reading

Tip

EWARM (IAR)​

stm32f746xx_flash.icf

STM32F746G_DISCO.map

STM32CubeIDE​

STM32F746NGHX_FLASH.ld

STM32F746G_DISCO.map

MDK-ARM (Keil)​

STM32F746G_DISCO.sct

STM32F746G_DISCO.map

RTOS 지원

소프트웨어 디코딩

비디오 데이터

하드웨어 디코딩

STM32H750 example

`FileReader` 인터페이스

TBS 마이그레이션을 통한 비디오 디코딩 지원

일반 변경 사항

소프트웨어 변경 사항

하드웨어 변경 사항

비디오 버퍼를 외부 메모리에 저장하기

EWARM (IAR)

STM32CubeIDE

MDK-ARM (Keil)