summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBehdad Esfahbod <behdad@gnome.org>2006-01-28 21:55:25 +0000
committerBehdad Esfahbod <behdad@src.gnome.org>2006-01-28 21:55:25 +0000
commit3932f8ef5723867ee726adcbc70b536317aa0f31 (patch)
tree363a2e90d849036d725dc1e00f67d62b09729a9b
parent54bc986fca7f0803571cadff036f129f0b6827af (diff)
downloadpango-3932f8ef5723867ee726adcbc70b536317aa0f31.tar.gz
Document PangoOTBuffer and PangoOTGlyph.
2006-01-28 Behdad Esfahbod <behdad@gnome.org> * doc/tmpl/opentype.sgml: Document PangoOTBuffer and PangoOTGlyph. * pango/pango-ot-buffer.c, pango/pango-ot-info.c, pango/pango-ot-ruleset.c: Document remaining symbols.
-rw-r--r--ChangeLog7
-rw-r--r--docs/tmpl/freetype-fonts.sgml2
-rw-r--r--docs/tmpl/glyphs.sgml2
-rw-r--r--docs/tmpl/modules.sgml2
-rw-r--r--docs/tmpl/opentype.sgml27
-rw-r--r--docs/tmpl/pango-renderer.sgml2
-rw-r--r--docs/tmpl/pangocairo.sgml3
-rw-r--r--docs/tmpl/pangofc-fontmap.sgml4
-rw-r--r--pango/pango-ot-buffer.c38
-rw-r--r--pango/pango-ot-info.c29
-rw-r--r--pango/pango-ot-ruleset.c9
-rw-r--r--pango/pango-ot.h2
12 files changed, 79 insertions, 48 deletions
diff --git a/ChangeLog b/ChangeLog
index 3f1dffed..66a42190 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
2006-01-28 Behdad Esfahbod <behdad@gnome.org>
+ * doc/tmpl/opentype.sgml: Document PangoOTBuffer and PangoOTGlyph.
+
+ * pango/pango-ot-buffer.c, pango/pango-ot-info.c,
+ pango/pango-ot-ruleset.c: Document remaining symbols.
+
+2006-01-28 Behdad Esfahbod <behdad@gnome.org>
+
* pango/opentype/pango-ot-*: Removed.
* pango/pango-ot-*: Added.
diff --git a/docs/tmpl/freetype-fonts.sgml b/docs/tmpl/freetype-fonts.sgml
index 9877c200..e39ba6bb 100644
--- a/docs/tmpl/freetype-fonts.sgml
+++ b/docs/tmpl/freetype-fonts.sgml
@@ -91,8 +91,6 @@ Function type for doing final config tweaking on prepared FcPatterns.
@dpi_x:
@dpi_y:
@Returns:
-<!-- # Unused Parameters # -->
-@dpi:
<!-- ##### FUNCTION pango_ft2_render ##### -->
diff --git a/docs/tmpl/glyphs.sgml b/docs/tmpl/glyphs.sgml
index 9c365968..1232cd36 100644
--- a/docs/tmpl/glyphs.sgml
+++ b/docs/tmpl/glyphs.sgml
@@ -177,8 +177,6 @@ horizontal origin.
@matrix:
@new_matrix:
-<!-- # Unused Parameters # -->
-@new:
<!-- ##### FUNCTION pango_matrix_get_font_scale_factor ##### -->
diff --git a/docs/tmpl/modules.sgml b/docs/tmpl/modules.sgml
index 2d74a8ad..e552e387 100644
--- a/docs/tmpl/modules.sgml
+++ b/docs/tmpl/modules.sgml
@@ -60,8 +60,6 @@ matches the language tag for this entry's map exactly or just approximately.
@map:
@script:
@Returns:
-<!-- # Unused Parameters # -->
-@wc:
<!-- ##### FUNCTION pango_map_get_engines ##### -->
diff --git a/docs/tmpl/opentype.sgml b/docs/tmpl/opentype.sgml
index 8cfe4405..d62bb3d9 100644
--- a/docs/tmpl/opentype.sgml
+++ b/docs/tmpl/opentype.sgml
@@ -35,21 +35,28 @@ use pango_ot_info_new().
<!-- ##### STRUCT PangoOTBuffer ##### -->
<para>
-
+The #PangoOTBuffer structure is used to store strings of glyphs associated
+with a #PangoFcFont, suitable for OpenType layout processing. It contains
+only private fields and should only be accessed via the
+<function>pango_ot_buffer_*</function> functions which are documented below.
+To obtain a #PangoOTBuffer, use pango_ot_buffer_new().
</para>
<!-- ##### STRUCT PangoOTGlyph ##### -->
<para>
-
+The #PangoOTGlyph structure represents a single glyph together with
+information used for OpenType layout processing of the glyph.
+It contains the following fields.
</para>
-@glyph:
-@properties:
-@cluster:
-@component:
-@ligID:
-@property_cache:
+@glyph: the glyph itself.
+@properties: the properties value, identifying which features should be
+ applied on this glyph. See pango_ruleset_add_feature().
+@cluster: the cluster that this glyph belongs to.
+@component: a component value, set by the OpenType layout engine.
+@ligID: a ligature index value, set by the OpenType layout engine.
+@property_cache: for internal use.
<!-- ##### STRUCT PangoOTRuleset ##### -->
<para>
@@ -81,8 +88,6 @@ identify the various OpenType tables in the
@face:
@Returns:
-<!-- # Unused Parameters # -->
-@font:
<!-- ##### FUNCTION pango_ot_info_find_script ##### -->
@@ -191,7 +196,7 @@ identify the various OpenType tables in the
</para>
@buffer:
-@glyph_index:
+@glyph:
@properties:
@cluster:
diff --git a/docs/tmpl/pango-renderer.sgml b/docs/tmpl/pango-renderer.sgml
index ba7fd16e..f5f2bd9c 100644
--- a/docs/tmpl/pango-renderer.sgml
+++ b/docs/tmpl/pango-renderer.sgml
@@ -130,8 +130,6 @@ The #GObject type for #PangoRenderPart.
@y2:
@x12:
@x22:
-<!-- # Unused Parameters # -->
-@y1:
<!-- ##### FUNCTION pango_renderer_draw_glyph ##### -->
diff --git a/docs/tmpl/pangocairo.sgml b/docs/tmpl/pangocairo.sgml
index 0c58c923..93172ac4 100644
--- a/docs/tmpl/pangocairo.sgml
+++ b/docs/tmpl/pangocairo.sgml
@@ -168,9 +168,6 @@ int main (int argc, char **argv)
@fontmap:
@dpi:
-<!-- # Unused Parameters # -->
-@dpi_x:
-@dpi_y:
<!-- ##### FUNCTION pango_cairo_font_map_get_resolution ##### -->
diff --git a/docs/tmpl/pangofc-fontmap.sgml b/docs/tmpl/pangofc-fontmap.sgml
index 34c99b77..68a349f1 100644
--- a/docs/tmpl/pangofc-fontmap.sgml
+++ b/docs/tmpl/pangofc-fontmap.sgml
@@ -78,8 +78,6 @@ Fontconfig-based backend involves deriving from both
@fcfontmap:
@Returns:
-<!-- # Unused Parameters # -->
-@fontmap:
<!-- ##### FUNCTION pango_fc_font_map_shutdown ##### -->
@@ -88,8 +86,6 @@ Fontconfig-based backend involves deriving from both
</para>
@fcfontmap:
-<!-- # Unused Parameters # -->
-@fontmap:
<!-- ##### FUNCTION pango_fc_font_map_add_decoder_find_func ##### -->
diff --git a/pango/pango-ot-buffer.c b/pango/pango-ot-buffer.c
index f649ae62..f415c6eb 100644
--- a/pango/pango-ot-buffer.c
+++ b/pango/pango-ot-buffer.c
@@ -30,6 +30,8 @@
* pango_ot_buffer_new
* @font: a #PangoFcFont
*
+ * Creates a new #PangoOTBuffer for the given OpenType font.
+ *
* Return value: the new #PangoOTBuffer
*
* Since: 1.4
@@ -63,6 +65,8 @@ pango_ot_buffer_new (PangoFcFont *font)
* pango_ot_buffer_destroy
* @buffer: a #PangoOTBuffer
*
+ * Destroys a #PangoOTBuffer and free all associated memory.
+ *
* Since: 1.4
**/
void
@@ -77,6 +81,8 @@ pango_ot_buffer_destroy (PangoOTBuffer *buffer)
* pango_ot_buffer_clear
* @buffer: a #PangoOTBuffer
*
+ * Empties a #PangoOTBuffer, make it ready to add glyphs to.
+ *
* Since: 1.4
**/
void
@@ -89,27 +95,33 @@ pango_ot_buffer_clear (PangoOTBuffer *buffer)
/**
* pango_ot_buffer_add_glyph
* @buffer: a #PangoOTBuffer
- * @glyph_index:
- * @properties:
- * @cluster:
+ * @glyph: the glyph index to add, like a #PangoGlyph
+ * @properties: the glyph properties
+ * @cluster: the cluster that this glyph belongs to
+ *
+ * Appends a glyph to a #PangoOTBuffer, with @properties identifying which
+ * features should be applied on this glyph. See pango_ruleset_add_feature().
*
* Since: 1.4
**/
void
pango_ot_buffer_add_glyph (PangoOTBuffer *buffer,
- guint glyph_index,
+ guint glyph,
guint properties,
guint cluster)
{
otl_buffer_add_glyph (buffer->buffer,
- glyph_index, properties, cluster);
+ glyph, properties, cluster);
}
/**
* pango_ot_buffer_set_rtl
* @buffer: a #PangoOTBuffer
- * @rtl: %TRUE for right-to-left
+ * @rtl: %TRUE for right-to-left text
+ *
+ * Sets whether glyphs will be rendered right-to-left. This setting
+ * is needed for proper horizontal positioning of right-to-left scripts.
*
* Since: 1.4
**/
@@ -121,7 +133,7 @@ pango_ot_buffer_set_rtl (PangoOTBuffer *buffer,
}
/**
- * pango_ot_buffer_set_zero_width_marks:
+ * pango_ot_buffer_set_zero_width_marks
* @buffer: a #PangoOTBuffer
* @zero_width_marks: %TRUE if characters with a mark class should
* be forced to zero width.
@@ -143,8 +155,12 @@ pango_ot_buffer_set_zero_width_marks (PangoOTBuffer *buffer,
/**
* pango_ot_buffer_get_glyphs
* @buffer: a #PangoOTBuffer
- * @glyphs:
- * @n_glyphs:
+ * @glyphs: location to store the array of glyphs, or %NULL
+ * @n_glyphs: location to store the number of glyphs, or %NULL
+ *
+ * Gets the glyph array contained in a #PangoOTBuffer. The glyphs are
+ * owned by the buffer and should not be freed, and are only valid as long
+ * as buffer is not modified.
*
* Since: 1.4
**/
@@ -255,6 +271,10 @@ apply_gpos_rtl (PangoGlyphString *glyphs,
* @buffer: a #PangoOTBuffer
* @glyphs: a #PangoGlyphString
*
+ * Exports the glyphs in a #PangoOTBuffer into a #PangoGlyphString. This is
+ * typically used after the OpenType layout processing is over, to convert the
+ * resulting glyphs into a generic Pango glyph string.
+ *
* Since: 1.4
**/
void
diff --git a/pango/pango-ot-info.c b/pango/pango-ot-info.c
index 7ea83933..8d3841a1 100644
--- a/pango/pango-ot-info.c
+++ b/pango/pango-ot-info.c
@@ -111,11 +111,12 @@ pango_ot_info_finalizer (void *object)
/**
* pango_ot_info_get:
* @face: a #FT_Face.
- * @returns: the #PangoOTInfo for @face. This object will
- * have the same lifetime as @face.
*
* Returns the #PangoOTInfo structure for the given FreeType font.
*
+ * Return value: the #PangoOTInfo for @face. This object will have
+ * the same lifetime as @face.
+ *
* Since: 1.2
**/
PangoOTInfo *
@@ -402,9 +403,10 @@ get_tables (PangoOTInfo *info,
* @table_type: the table type to obtain information about.
* @script_tag: the tag of the script to find.
* @script_index: location to store the index of the script, or %NULL.
- * @returns: %TRUE if the script was found.
*
* Finds the index of a script.
+ *
+ * Return value: %TRUE if the script was found.
**/
gboolean
pango_ot_info_find_script (PangoOTInfo *info,
@@ -443,9 +445,10 @@ pango_ot_info_find_script (PangoOTInfo *info,
* @language_index: location to store the index of the language, or %NULL.
* @required_feature_index: location to store the required feature index of
* the language, or %NULL.
- * @returns: %TRUE if the language was found.
*
* Finds the index of a language and its required feature index.
+ *
+ * Return value: %TRUE if the language was found.
**/
gboolean
pango_ot_info_find_language (PangoOTInfo *info,
@@ -492,9 +495,10 @@ pango_ot_info_find_language (PangoOTInfo *info,
* @language_index: the index of the language whose features are searched,
* or 0xffff to use the default language of the script.
* @feature_index: location to store the index of the feature, or %NULL.
- * @returns: %TRUE if the feature was found.
*
* Finds the index of a feature.
+ *
+ * Return value: %TRUE if the feature was found.
**/
gboolean
pango_ot_info_find_feature (PangoOTInfo *info,
@@ -548,10 +552,11 @@ pango_ot_info_find_feature (PangoOTInfo *info,
* pango_ot_info_list_scripts:
* @info: a #PangoOTInfo.
* @table_type: the table type to obtain information about.
- * @returns: a newly-allocated array containing the tags of the
- * available scripts.
*
* Obtains the list of available scripts.
+ *
+ * Return value: a newly-allocated array containing the tags of the
+ * available scripts.
**/
PangoOTTag *
pango_ot_info_list_scripts (PangoOTInfo *info,
@@ -582,10 +587,11 @@ pango_ot_info_list_scripts (PangoOTInfo *info,
* @table_type: the table type to obtain information about.
* @script_index: the index of the script to list languages for.
* @language_tag: unused parameter.
- * @returns: a newly-allocated array containing the tags of the
- * available languages.
*
* Obtains the list of available languages for a given script.
+ *
+ * Return value: a newly-allocated array containing the tags of the
+ * available languages.
**/
PangoOTTag *
pango_ot_info_list_languages (PangoOTInfo *info,
@@ -625,10 +631,11 @@ pango_ot_info_list_languages (PangoOTInfo *info,
* @script_index: the index of the script to obtain information about.
* @language_index: the indes of the language to list features for, or
* 0xffff, to list features for the default language of the script.
- * @returns: a newly-allocated array containing the tags of the available
- * features.
*
* Obtains the list of features for the given language of the given script.
+ *
+ * Return value: a newly-allocated array containing the tags of the
+ * available features.
**/
PangoOTTag *
pango_ot_info_list_features (PangoOTInfo *info,
diff --git a/pango/pango-ot-ruleset.c b/pango/pango-ot-ruleset.c
index f0517063..975ea5d2 100644
--- a/pango/pango-ot-ruleset.c
+++ b/pango/pango-ot-ruleset.c
@@ -96,9 +96,10 @@ pango_ot_ruleset_finalize (GObject *object)
/**
* pango_ot_ruleset_new:
* @info: a #PangoOTInfo.
- * @returns: a new #PangoOTRuleset.
*
* Creates a new #PangoOTRuleset for the given OpenType info.
+ *
+ * Return value: a new #PangoOTRuleset.
**/
PangoOTRuleset *
pango_ot_ruleset_new (PangoOTInfo *info)
@@ -144,6 +145,9 @@ pango_ot_ruleset_add_feature (PangoOTRuleset *ruleset,
* @ruleset: a #PangoOTRuleset.
* @buffer: a #PangoOTBuffer.
*
+ * Performs the OpenType GSUB substitution on @buffer using the features
+ * in @ruleset
+ *
* Since: 1.4
**/
void
@@ -184,6 +188,9 @@ pango_ot_ruleset_substitute (PangoOTRuleset *ruleset,
* @ruleset: a #PangoOTRuleset.
* @buffer: a #PangoOTBuffer.
*
+ * Performs the OpenType GPOS positionoing on @buffer using the features
+ * in @ruleset
+ *
* Since: 1.4
**/
void
diff --git a/pango/pango-ot.h b/pango/pango-ot.h
index 8663e101..a0f2efa9 100644
--- a/pango/pango-ot.h
+++ b/pango/pango-ot.h
@@ -91,7 +91,7 @@ void pango_ot_buffer_clear (PangoOTBuffer *buffer);
void pango_ot_buffer_set_rtl (PangoOTBuffer *buffer,
gboolean rtl);
void pango_ot_buffer_add_glyph (PangoOTBuffer *buffer,
- guint glyph_index,
+ guint glyph,
guint properties,
guint cluster);
void pango_ot_buffer_get_glyphs (PangoOTBuffer *buffer,