drm/rect: fix kernel-doc typos

Correct typos of "translated".

Cc: David Airlie <airlied@gmail.com>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: dri-devel@lists.freedesktop.org
Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
Cc: Maxime Ripard <mripard@kernel.org>
Cc: Thomas Zimmermann <tzimmermann@suse.de>
Reviewed-by: Simon Ser <contact@emersion.fr>
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Simon Ser <contact@emersion.fr>
Link: https://patchwork.freedesktop.org/patch/msgid/20240205054101.27929-1-rdunlap@infradead.org

drm/rect: Add DRM_RECT_INIT() macro

Add a helper macro to initialize a rectangle from x, y, width and
height information.

Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Reviewed-by: David Gow <davidgow@google.com>
Acked-by: Thomas Zimmermann <tzimmermann@suse.de>
Signed-off-by: José Expósito <jose.exposito89@gmail.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20220620160640.3790-2-jose.exposito89@gmail.com

drm/plane: remove drm_helper_get_plane_damage_clips

It's not used. Drivers should instead use the helpers anyway.

Currently both vbox and i915 hand-roll this and it's not the greatest.
vbox looks buggy, and i915 does a bit much that helpers would take
care of I think.

Also improve the kerneldocs while we're at it.

Reviewed-by: José Roberto de Souza <jose.souza@intel.com>
Cc: Ville Syrjälä <ville.syrjala@linux.intel.com>
Cc: Gwan-gyeong Mun <gwan-gyeong.mun@intel.com>
Cc: José Roberto de Souza <jose.souza@intel.com>
Cc: Hans de Goede <hdegoede@redhat.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
Cc: Maxime Ripard <mripard@kernel.org>
Cc: Thomas Zimmermann <tzimmermann@suse.de>
Cc: David Airlie <airlied@linux.ie>
Cc: Daniel Vetter <daniel@ffwll.ch>
Link: https://patchwork.freedesktop.org/patch/msgid/20210723083457.696939-1-daniel.vetter@ffwll.ch

drm: Add function to convert rect in 16.16 fixed format to regular format

Much more clear to read one function call than four lines doing this
conversion.

v7:
- function renamed
- calculating width and height before truncate
- inlined

v10:
- renamed parameters from source and destination to src and dst
to match sister functions

Cc: Ville Syrjälä <ville.syrjala@linux.intel.com>
Cc: dri-devel@lists.freedesktop.org
Cc: Gwan-gyeong Mun <gwan-gyeong.mun@intel.com>
Reviewed-by: Gwan-gyeong Mun <gwan-gyeong.mun@intel.com>
Signed-off-by: José Roberto de Souza <jose.souza@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20210104205654.238928-1-jose.souza@intel.com

drm: drm_rect.h: delete duplicated word in comment

Drop doubled word "the" in a comment.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: David Airlie <airlied@linux.ie>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: dri-devel@lists.freedesktop.org
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: https://patchwork.freedesktop.org/patch/msgid/20200715052349.23319-7-rdunlap@infradead.org

drm/selftests: Add drm_rect selftests

Add selftests for drm_rect. A few basic ones for clipped and unclipped
cases, and a few special ones for specific bugs we had in the code.

I'm too lazy to think of more corner cases to check at this time.
Maybe later.

Signed-off-by: Ville Syrjälä <ville.syrjala@linux.intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20191122175623.13565-5-ville.syrjala@linux.intel.com
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Reviewed-by: Benjamin Gaignard <benjamin.gaignard@st.com>

drm/rect: Add drm_rect_init()

Add a helper to initialize a rectangle from x/y/w/h information.

Signed-off-by: Ville Syrjälä <ville.syrjala@linux.intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20190930134214.24702-2-ville.syrjala@linux.intel.com
Reviewed-by: Jani Nikula <jani.nikula@intel.com>

drm/rect: Add drm_rect_translate_to()

Add a helper to translate a rectangle to an absolute position.

Signed-off-by: Ville Syrjälä <ville.syrjala@linux.intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20190930134214.24702-1-ville.syrjala@linux.intel.com
Reviewed-by: Jani Nikula <jani.nikula@intel.com>

drm: Nuke drm_calc_{h,v}scale_relaxed()

The fuzzy drm_calc_{h,v}scale_relaxed() helpers are no longer used.
Throw them in the bin.

Signed-off-by: Ville Syrjälä <ville.syrjala@linux.intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20190206183204.21127-1-ville.syrjala@linux.intel.com
Acked-by: Alex Deucher <alexander.deucher@amd.com>

drm/rect: Handle rounding errors in drm_rect_clip_scaled, v3.

Instead of relying on a scale which may increase rounding errors,
clip src by doing: src * (dst - clip) / dst and rounding the result
away from 1, so the new coordinates get closer to 1. We won't need
to fix up with a magic macro afterwards, because our scaling factor
will never go to the other side of 1.

Changes since v1:
- Adjust dst immediately, else drm_rect_width/height on dst gives bogus
results.
Change since v2:
- Get rid of macros and use 64-bits math.

Signed-off-by: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
[mlankhorst: Add Villes comment, and rename newsrc to tmp. (Ville)]
Reviewed-by: Ville Syrjälä <ville.syrjala@linux.intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20180503112217.37292-3-maarten.lankhorst@linux.intel.com

drm/doc: move printf helpers out of drmP.h

And document them lightly. Unfortunately kernel-doc isn't the most
awesome for documenting #defines that don't look like functions, it
makes functions out of them :-/

Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Reviewed-by: Neil Armstrong <narmstrong@baylibre.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20170524145212.27837-2-daniel.vetter@ffwll.ch
Link: http://patchwork.freedesktop.org/patch/msgid/20170524145212.27837-3-daniel.vetter@ffwll.ch

drm: Add "prefix" parameter to drm_rect_debug_print()

Allow the caller to specify a "prefix" string to drm_rect_debug_print()
to make it easier to see which drm_rect is being printed.

Signed-off-by: Ville Syrjälä <ville.syrjala@linux.intel.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>

drm: Add drm_rect rotation functions

Add some helper functions to move drm_rects between different rotated
coordinate spaces. One function does the forward transform and
another does the inverse.

Cc: dri-devel@lists.freedesktop.org
Signed-off-by: Ville Syrjälä <ville.syrjala@linux.intel.com>
Reviewed-by: Imre Deak <imre.deak@intel.com>
Acked-by: Dave Airlie <airlied@linux.ie>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>

drm: Fix drm_rect documentation

The 'struct' keyword was missing so struct drm_rect documentation never
ended up in the generated docs.

Also move the drm_rect documentations to a new section alognside the
various helper functions and add a short description about the intended
purpose of drm_rect.

v2: Move to new section and add general description

Signed-off-by: Ville Syrjälä <ville.syrjala@linux.intel.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>

drm: Add drm_rect_equals()

drm_rect_equals() tells whether two drm_rects are equal.

Reviewed-by: Chris Wilson <chris@chris-wilson.co.uk>
Signed-off-by: Ville Syrjälä <ville.syrjala@linux.intel.com>
Acked-by: Dave Airlie <airlied@gmail.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>

drm: Add drm_rect_debug_print()

Add a debug function to print the rectangle in a human readable format.

v2: Renamed drm_region to drm_rect, the function from drm_region_debug
to drm_rect_debug_print(), and use %+d instead of +%d in the format.
v3: Use %d format for width/height in the non fixed point case as well

Reviewed-by: Chris Wilson <chris@chris-wilson.co.uk>
Signed-off-by: Ville Syrjälä <ville.syrjala@linux.intel.com>
Acked-by: Dave Airlie <airlied@gmail.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>

drm: Add drm_rect_calc_{hscale, vscale}() utility functions

These functions calculate the scaling factor based on the source and
destination rectangles.

There are two version of the functions, the strict ones that will
return an error if the min/max scaling factor is exceeded, and the
relaxed versions that will adjust the src/dst rectangles in order to
keep the scaling factor withing the limits.

v2: Return error instead of adjusting regions, refactor common parts
into one function, and split into strict and relaxed versions.
v3: Renamed drm_region to drm_rect, add "_rect_" to the function
names.
v4: Fix "calculcate" typos

Reviewed-by: Chris Wilson <chris@chris-wilson.co.uk>
Signed-off-by: Ville Syrjälä <ville.syrjala@linux.intel.com>
Acked-by: Dave Airlie <airlied@gmail.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>

drm: Add struct drm_rect and assorted utility functions

struct drm_rect represents a simple rectangle. The utility
functions are there to help driver writers.

v2: Moved the region stuff into its own file, made the smaller funcs
static inline, used 64bit maths in the scaled clipping function to
avoid overflows (instead it will saturate to INT_MIN or INT_MAX).
v3: Renamed drm_region to drm_rect, drm_region_clip to
drm_rect_intersect, and drm_region_subsample to drm_rect_downscale.
v4: Renamed some function parameters, improve kernel-doc comments a bit,
and actually generate documentation for drm_rect.[ch].
v5: s/RETUTRNS/RETURNS/

Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Chris Wilson <chris@chris-wilson.co.uk>
Signed-off-by: Ville Syrjälä <ville.syrjala@linux.intel.com>
Acked-by: Dave Airlie <airlied@gmail.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>