schema_version: 0.3
type: producer
identifier: pango
title: Pango
version: 2
copyright: Meltytech, LLC
creator: Dan Dennedy
license: LGPLv2.1
language: en
tags:
  - Video
description: >
  A title generator that uses the Pango international text layout and Freetype2 
  font renderer.
notes: >
  Supplying a filename with extension ".txt" causes the loader producer to load 
  with pango. If the filename begins with "+" the pango producer interprets the 
  filename as pango text. This is a shortcut to embed titles in melt commands. 
  For MLT XML, it is recommended that you embed the title text in the property 
  value.
  
  Pango has builtin scaling. It will rescale the originally rendered title to
  whatever the consumer requests. Therefore, it will lose its aspect ratio if 
  so requested, and it is up to the consumer to request a proper width and 
  height that maintains the image aspect.
  
  Environment variable MLT_PANGO_PRODUCER_CACHE could be used to override and
  increase the size of cached converted images of simultaneous use.

  Fontset used by pango producer loaded once. That behavior prevents using new
  fonts till process used pango producer been restarted. To force fontmap reload
  you need to send signal "fontmap-reload" to pango producer:
    {
        mlt_profile profile = mlt_profile_init("dv_pal");
        mlt_producer producer = mlt_factory_producer(profile, "pango", NULL);
        mlt_events_fire(mlt_producer_properties(producer), "fontmap-reload", NULL );
        mlt_producer_close(producer);
        mlt_profile_close(profile);
    };


parameters:
  - identifier: resource
    title: File
    type: string
    description: |
      A text file containing Pango markup, see:
      https://developer.gnome.org/pango/stable/PangoMarkupFormat.html
      requires xml-like encoding special chars from:
      <, >, &   -to-   &lt;, &gt;, &amp;
    readonly: no
    argument: yes
    mutable: no
    widget: fileopen
    
  - identifier: markup
    title: Markup
    type: string
    description: |
      A string containing Pango markup see:
      http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
      requires xml-like encoding special chars from:
      <, >, &   -to-   &lt;, &gt;, &amp;
    readonly: no
    argument: yes
    mutable: yes
    widget: textbox
    
  - identifier: fgcolour
    title: Foreground color
    type: string
    description: >
      A color value is a hexadecimal representation of RGB plus alpha channel 
      as 0xrrggbbaa. Colors can also be the words: white, black, red, green,
      or blue. You can also use a HTML-style color values #rrggbb or #aarrggbb.
    readonly: no
    mutable: yes
    widget: color
    
  - identifier: bgcolour
    title: Background color
    type: string
    description: >
      A color value is a hexadecimal representation of RGB plus alpha channel 
      as 0xrrggbbaa. Colors can also be the words: white, black, red, green,
      or blue. You can also use a HTML-style color values #rrggbb or #aarrggbb.
    readonly: no
    mutable: yes
    widget: color
    
  - identifier: olcolour
    title: Outline color
    type: string
    description: >
      A color value is a hexadecimal representation of RGB plus alpha channel 
      as 0xrrggbbaa. Colors can also be the words: white, black, red, green,
      or blue. You can also use a HTML-style color values #rrggbb or #aarrggbb.
    readonly: no
    mutable: yes
    widget: color
    
  - identifier: outline
    title: Outline Width
    type: string
    description: >
      The width of the outline in pixels.
    readonly: no
    default: 0
    minimum: 0
    maximum: 3
    mutable: yes
    widget: spinner
    unit: pixels
    
  - identifier: align
    title: Paragraph alignment
    type: string
    description: >
      left, centre, right (also, numbers 0, 1 and 2 can be used respectively)
    readonly: no
    default: left
    mutable: yes
    widget: combo

  - identifier: pad
    title: Padding
    type: integer
    description: >
      The number of pixels to pad the background rectangle beyond edges of text.
    readonly: no
    default: 0
    mutable: yes
    widget: spinner
    unit: pixels
    
  - identifier: text
    title: Text
    type: string
    description: |
      A non-markup string in UTF-8 encoding 
      (can contain markup chars un-encoded)
    readonly: no
    mutable: yes
    widget: textbox

  - identifier: family
    title: Font family
    type: string
    description: >
      The default typeface to use when not using markup. 
    default: Sans
    readonly: no
    mutable: yes
    widget: combo
    
  - identifier: size
    title: Font size
    type: integer
    description: >
      The size in pixels of the font to use when not using markup. 
    default: 48
    readonly: no
    mutable: yes
    widget: spinner
    unit: pixels
    
  - identifier: style
    title: Font style
    type: string
    description: >
      The style of the font to use when not using markup.
    values:
      - normal
      - italic
      - oblique
    default: normal
    readonly: no
    mutable: yes
    widget: combo
    
  - identifier: weight
    title: Font weight
    type: integer
    description: The weight of the font.
    minimum: 100
    maximum: 1000
    default: 400
    readonly: no
    mutable: yes
    widget: spinner
    
  - identifier: encoding
    title: Encoding
    type: string
    description: >
      The text encoding type of the input if not UTF-8.
      See 'iconv --list' for a list of possible inputs.
    default: UTF-8
    readonly: no
    mutable: yes
    widget: combo

  - identifier: real_width
    title: Real width
    type: integer
    description: The original, unscaled width of the rendered title.
    readonly: yes
    unit: pixels
    
  - identifier: real_height
    title: Real height
    type: integer
    description: The original, unscaled height of the rendered title.
    readonly: yes
    unit: pixels

  - identifier: width
    title: Width
    type: integer
    description: The last requested scaled image width.
    readonly: yes
    unit: pixels
    
  - identifier: height
    title: Height
    type: integer
    description: The last requested scaled image height.
    readonly: yes
    unit: pixels
    
  - identifier: force_aspect_ratio
    title: Sample aspect ratio
    type: float
    description: Optionally override a (mis)detected aspect ratio
    mutable: yes

  - identifier: rotate
    title: Rotation angle
    type: integer
    description: >
      The angle of text rotation in degrees. Positive value is clockwise.
    default: 0
    readonly: no
    mutable: yes
    widget: spinner
    unit: degrees

  - identifier: width_crop
    title: Width to crop
    type: integer
    description: >
      Limit width of rendered image.
    default: 0
    readonly: no
    mutable: yes
    widget: spinner
    unit: pixels

  - identifier: width_fit
    title: Fit width
    type: integer
    description: >
      Scale pango layout to fit specified width.
    default: 0
    readonly: no
    mutable: yes
    widget: spinner
    unit: pixels

  - identifier: line_spacing
    title: Sets lines spacing
    type: integer
    description: >
      Sets the amount of spacing between the lines of the layout.
    default: 0
    readonly: no
    mutable: yes
    widget: spinner

  - identifier: stretch
    title: Font stretch
    type: integer
    description: >
      The stretch feature of pango's font description. Possible values:
        1 - ULTRA_CONDENSED
        2 - EXTRA_CONDENSED
        3 - CONDENSED
        4 - SEMI_CONDENSED
        5 - NORMAL
        6 - SEMI_EXPANDED
        7 - EXPANDED
        8 - EXTRA_EXPANDED
        9 - ULTRA_EXPANDED
    minimum: 0
    maximum: 9
    default: 4
    readonly: no
    mutable: yes
    widget: spinner

  - identifier: wrap_width
    title: Sets the width to wrap to
    type: integer
    description: >
      Sets the width to which the lines of the PangoLayout should wrap.
    default: 0
    readonly: no
    mutable: yes
    widget: spinner
    unit: pixels

  - identifier: wrap_type
    title: Sets the wrap mode
    type: integer
    description: >
      Sets the wrap mode; the wrap mode only has effect if a 'wrap_width' is set.
      Possible values:
          0 - wrap lines at word boundaries
          1 - wrap lines at character boundaries
          2 - wrap lines at word boundaries, but fall back to character
              boundaries if there is not enough space for a full word
    default: 0
    readonly: no
    mutable: yes
    widget: spinner
