display.h 3.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114
  1. /*
  2. * Copyright (c) 2014 Vittorio Giovara <vittorio.giovara@gmail.com>
  3. *
  4. * This file is part of FFmpeg.
  5. *
  6. * FFmpeg is free software; you can redistribute it and/or
  7. * modify it under the terms of the GNU Lesser General Public
  8. * License as published by the Free Software Foundation; either
  9. * version 2.1 of the License, or (at your option) any later version.
  10. *
  11. * FFmpeg is distributed in the hope that it will be useful,
  12. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  14. * Lesser General Public License for more details.
  15. *
  16. * You should have received a copy of the GNU Lesser General Public
  17. * License along with FFmpeg; if not, write to the Free Software
  18. * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  19. */
  20. /**
  21. * @file
  22. * Display matrix
  23. */
  24. #ifndef AVUTIL_DISPLAY_H
  25. #define AVUTIL_DISPLAY_H
  26. #include <stdint.h>
  27. #include "common.h"
  28. /**
  29. * @addtogroup lavu_video
  30. * @{
  31. *
  32. * @defgroup lavu_video_display Display transformation matrix functions
  33. * @{
  34. */
  35. /**
  36. * @addtogroup lavu_video_display
  37. * The display transformation matrix specifies an affine transformation that
  38. * should be applied to video frames for correct presentation. It is compatible
  39. * with the matrices stored in the ISO/IEC 14496-12 container format.
  40. *
  41. * The data is a 3x3 matrix represented as a 9-element array:
  42. *
  43. * @code{.unparsed}
  44. * | a b u |
  45. * (a, b, u, c, d, v, x, y, w) -> | c d v |
  46. * | x y w |
  47. * @endcode
  48. *
  49. * All numbers are stored in native endianness, as 16.16 fixed-point values,
  50. * except for u, v and w, which are stored as 2.30 fixed-point values.
  51. *
  52. * The transformation maps a point (p, q) in the source (pre-transformation)
  53. * frame to the point (p', q') in the destination (post-transformation) frame as
  54. * follows:
  55. *
  56. * @code{.unparsed}
  57. * | a b u |
  58. * (p, q, 1) . | c d v | = z * (p', q', 1)
  59. * | x y w |
  60. * @endcode
  61. *
  62. * The transformation can also be more explicitly written in components as
  63. * follows:
  64. *
  65. * @code{.unparsed}
  66. * p' = (a * p + c * q + x) / z;
  67. * q' = (b * p + d * q + y) / z;
  68. * z = u * p + v * q + w
  69. * @endcode
  70. */
  71. /**
  72. * Extract the rotation component of the transformation matrix.
  73. *
  74. * @param matrix the transformation matrix
  75. * @return the angle (in degrees) by which the transformation rotates the frame
  76. * counterclockwise. The angle will be in range [-180.0, 180.0],
  77. * or NaN if the matrix is singular.
  78. *
  79. * @note floating point numbers are inherently inexact, so callers are
  80. * recommended to round the return value to nearest integer before use.
  81. */
  82. double av_display_rotation_get(const int32_t matrix[9]);
  83. /**
  84. * Initialize a transformation matrix describing a pure counterclockwise
  85. * rotation by the specified angle (in degrees).
  86. *
  87. * @param matrix an allocated transformation matrix (will be fully overwritten
  88. * by this function)
  89. * @param angle rotation angle in degrees.
  90. */
  91. void av_display_rotation_set(int32_t matrix[9], double angle);
  92. /**
  93. * Flip the input matrix horizontally and/or vertically.
  94. *
  95. * @param matrix an allocated transformation matrix
  96. * @param hflip whether the matrix should be flipped horizontally
  97. * @param vflip whether the matrix should be flipped vertically
  98. */
  99. void av_display_matrix_flip(int32_t matrix[9], int hflip, int vflip);
  100. /**
  101. * @}
  102. * @}
  103. */
  104. #endif /* AVUTIL_DISPLAY_H */