mirror of
https://github.com/opencv/opencv.git
synced 2026-09-25 04:09:57 +03:00
Muditya Raghav
3b580381f1
doc: document the bit layout of Mat::type() - #29981 ### Pull Request Readiness Checklist See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request - [x] I agree to contribute to the project under Apache 2 License. - [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV - [x] The PR is proposed to the proper branch - [x] There is a reference to the original bug report and related work - [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable - [ ] The feature is well documented and sample code can be built with the project CMake ### Description Fixes #24901. #### Problem `cv::Mat::type()` returns a packed bit-field, but the encoding was not documented. Users had to reverse-engineer the layout from the `CV_*` macros to answer questions such as how many channels fit, how to build a type from a depth and channel count, and which bits are reserved for the matrix flags. #### Change Expanded the Doxygen for `Mat::type()` in `modules/core/include/opencv2/core/mat.hpp` to describe the layout used by the 5.x branch: - bits 0-4 (`CV_MAT_DEPTH_MASK`) – element depth (5 bits); - bits 5-11 (`CV_MAT_CN_MASK`) – number of channels minus one (7 bits), i.e. 1..`CV_CN_MAX` (128); - together these occupy the lowest 12 bits (`CV_MAT_TYPE_MASK`). The description also points to `CV_MAT_DEPTH()`, `CV_MAT_CN()` and `CV_MAKETYPE()`, and notes that the continuity (`CV_MAT_CONT_FLAG`) and submatrix (`CV_SUBMAT_FLAG`) bits of `Mat::flags` are not part of the returned value. #### Branch note This PR targets `5.x` only. The encoding changed between branches: 5.x uses `CV_CN_SHIFT == 5` (5-bit depth, 7-bit channel count), whereas 4.x uses `CV_CN_SHIFT == 3`. As requested in the issue, a separate `4.x` PR would be needed for that branch. #### Verification Documentation-only change; no code or behavior is modified. The bit ranges and macro names were checked against `modules/core/include/opencv2/core/hal/interface.h` and `modules/core/include/opencv2/core/cvdef.h`: ``` CV_CN_MAX 128 CV_CN_SHIFT 5 CV_DEPTH_MAX (1 << CV_CN_SHIFT) // 32 CV_MAT_DEPTH_MASK (CV_DEPTH_MAX - 1) // 0x1F -> bits 0-4 CV_MAT_CN_MASK ((CV_CN_MAX - 1) << 5) // 0xFE0 -> bits 5-11 CV_MAT_TYPE_MASK (CV_DEPTH_MAX*CV_CN_MAX-1) // 0xFFF ```