summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2013-03-20 01:09:12 +0100
committerwm4 <wm4@nowhere>2013-03-29 23:06:28 +0100
commitd29915d067582a8fe307b67f7ad9aba2b05bb710 (patch)
tree73fcb13c2e231766b461570076d82b295e444795
parent35a62a5e6025c6807e1bdf86dd9abbc6fea74808 (diff)
downloadlibass-d29915d067582a8fe307b67f7ad9aba2b05bb710.tar.bz2
libass-d29915d067582a8fe307b67f7ad9aba2b05bb710.tar.xz
Add ass_set_pixel_aspect(), deprecate ass_set_aspect_ratio()
ass_set_aspect_ratio() is confusing, because it takes a DAR and SAR value, while libass just needs a single pixel aspect ratio. Introduce ass_set_pixel_aspect(), which sets the pixel aspect ratio directly. ass_set_aspect_ratio() is considered deprecated. There's no reason to remove it, but hopefully directing users to ass_set_pixel_aspect() will make for a simpler API. Improve the doxygen and document what ass_set_margins() actually does.
-rw-r--r--libass/ass.h62
-rw-r--r--libass/ass_render_api.c6
-rw-r--r--libass/libass.sym1
3 files changed, 58 insertions, 11 deletions
diff --git a/libass/ass.h b/libass/ass.h
index 1e662ba..303690e 100644
--- a/libass/ass.h
+++ b/libass/ass.h
@@ -160,6 +160,12 @@ 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().
+ * @see ass_set_pixel_aspect()
+ * @see ass_set_margins()
* \param priv renderer handle
* \param w width
* \param h height
@@ -168,10 +174,11 @@ void ass_set_frame_size(ASS_Renderer *priv, int w, int h);
/**
* \brief Set the source image size in pixels.
- * This is used to calculate the source aspect ratio and the blur scale. If
- * a custom pixel aspect ratio is set with ass_set_aspect_ratio(), the source
- * image size has no influence on the aspect ratio.
+ * This is used to calculate the source aspect ratio and the blur scale.
* The source image size can be reset to default by setting w and h to 0.
+ * The value set with this function can influence the pixel aspect ratio used
+ * for rendering.
+ * @see ass_set_pixel_aspect()
* \param priv renderer handle
* \param w width
* \param h height
@@ -187,7 +194,26 @@ void ass_set_shaper(ASS_Renderer *priv, ASS_ShapingLevel level);
/**
* \brief Set frame margins. These values may be negative if pan-and-scan
- * is used.
+ * is used. The margins are in pixels. Each value specifies the distance from
+ * the video rectangle to the renderer frame. If a given margin value is
+ * positive, there will be free space between renderer frame and video area.
+ * If a given margin value is negative, the frame is inside the video, i.e.
+ * the video has been cropped.
+ *
+ * The renderer will try to keep subtitles inside the frame area. If possible,
+ * text is layout so that it is inside the cropped area. Subtitle events
+ * that can't be moved are cropped against the frame area.
+ *
+ * ass_set_use_margins() can be used to allow libass to render subtitles into
+ * the empty areas if margins are positive, i.e. the video area is smaller than
+ * the frame. (Traditionally, this has been used to show subtitles in
+ * 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
@@ -204,13 +230,29 @@ void ass_set_margins(ASS_Renderer *priv, int t, int b, int l, int r);
void ass_set_use_margins(ASS_Renderer *priv, int use);
/**
+ * \brief Set pixel aspect ratio correction.
+ * This is the ratio of pixel width to pixel height.
+ *
+ * Generally, this is (s_w / s_h) / (d_w / d_h), where s_w and s_h is the
+ * video storage size, and d_w and d_h is the video display size. (Display
+ * and storage size can be different for anamorphic video, such as DVDs.)
+ *
+ * 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.
+ * 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)
+ */
+void ass_set_pixel_aspect(ASS_Renderer *priv, double par);
+
+/**
* \brief Set aspect ratio parameters.
- * You can also pass a pixel aspect ratio as dar, and set sar to 1.0. libass
- * uses dar/sar as final pixel aspect ratio, and doesn't use dar or sar for
- * anything else. If the pixel aspect ratio is 0 (setting dar=0 and sar=1), or
- * if the aspect ratio has never been set by calling this function, libass will
- * calculate a fallback value out of frame size and storage size. If the
- * storage size has not been set, a pixel aspect ratio of 1 is assumed.
+ * This calls ass_set_pixel_aspect(priv, dar / sar).
+ * @deprecated New code should use ass_set_pixel_aspect().
* \param priv renderer handle
* \param dar display aspect ratio (DAR), prescaled for output PAR
* \param sar storage aspect ratio (SAR)
diff --git a/libass/ass_render_api.c b/libass/ass_render_api.c
index 80af81f..5777aad 100644
--- a/libass/ass_render_api.c
+++ b/libass/ass_render_api.c
@@ -101,7 +101,11 @@ void ass_set_use_margins(ASS_Renderer *priv, int use)
void ass_set_aspect_ratio(ASS_Renderer *priv, double dar, double sar)
{
- double par = dar / sar;
+ ass_set_pixel_aspect(priv, dar / sar);
+}
+
+void ass_set_pixel_aspect(ASS_Renderer *priv, double par)
+{
if (priv->settings.par != par) {
priv->settings.par = par;
ass_reconfigure(priv);
diff --git a/libass/libass.sym b/libass/libass.sym
index 2dbbfbe..230cc29 100644
--- a/libass/libass.sym
+++ b/libass/libass.sym
@@ -37,3 +37,4 @@ ass_set_cache_limits
ass_flush_events
ass_set_shaper
ass_set_line_position
+ass_set_pixel_aspect