doc: revise statements regarding pixel_aspect

Since the margins are taken into account and the isotropic-scaling
factor cancels out during PAR calculation, calling ass_set_pixel_aspect
is only required if the preferable ass_set_storage_size was not called
or potentially if non-isotropic scaling is involved.

1 files changed, 6 insertions, 9 deletions

diff --git a/libass/ass.h b/libass/ass.h
index 8a8613a..60b8453 100644
--- a/libass/ass.h
+++ b/libass/ass.h
@@ -353,8 +353,10 @@ void ass_renderer_done(ASS_Renderer *priv);
  * \brief Set the frame size in pixels, including margins.
  * The renderer will never return images that are outside of the frame area.
  * The value set with this function can influence the pixel aspect ratio used
- * for rendering. If the frame size doesn't equal to the video size, you may
- * have to use ass_set_pixel_aspect().
+ * for rendering.
+ * If after compensating for configured margins the frame size
+ * is not an isotropicly scaled version of the video display size,
+ * you may have to use ass_set_pixel_aspect().
  * @see ass_set_pixel_aspect()
  * @see ass_set_margins()
  * \param priv renderer handle
@@ -409,10 +411,6 @@ void ass_set_shaper(ASS_Renderer *priv, ASS_ShapingLevel level);
  * the bottom "black bar" between video bottom screen border when playing 16:9
  * video on a 4:3 screen.)
  *
- * When using this function, it is recommended to calculate and set your own
- * aspect ratio with ass_set_pixel_aspect(), as the defaults won't make any
- * sense.
- * @see ass_set_pixel_aspect()
  * \param priv renderer handle
  * \param t top margin
  * \param b bottom margin
@@ -439,9 +437,8 @@ void ass_set_use_margins(ASS_Renderer *priv, int use);
  * If the pixel aspect ratio is 0, or if the aspect ratio has never been set
  * by calling this function, libass will calculate a default pixel aspect ratio
  * out of values set with ass_set_frame_size() and ass_set_storage_size(). Note
- * that this is useful only if the frame size corresponds to the video display
- * size. Keep in mind that the margins set with ass_set_margins() are ignored
- * for aspect ratio calculations as well.
+ * that this default assumes the frame size after compensating for margins
+ * corresponds to an isotropicly scaled version of the video display size.
  * If the storage size has not been set, a pixel aspect ratio of 1 is assumed.
  * \param priv renderer handle
  * \param par pixel aspect ratio (1.0 means square pixels, 0 means default)