From 344fd20d2cd4902fe4dbdf5c3192ed8ab162eca2 Mon Sep 17 00:00:00 2001 From: Igor Murashkin Date: Thu, 29 Nov 2012 13:35:15 -0800 Subject: [PATCH] Camera: Metadata docs HTML generated from XML: DO NOT MERGE Change-Id: Ic39249d7019dab0a6c5f5daf5d54074f6cc9c0d4 --- camera/docs/html.mako | 275 +++++++++++++++++++++++++++++++ camera/docs/metadata-parser-sanity-check | 2 +- camera/docs/metadata_model.py | 62 ++++++- camera/docs/metadata_parser_xml.py | 11 +- camera/docs/metadata_properties.xml | 27 +-- 5 files changed, 351 insertions(+), 26 deletions(-) create mode 100644 camera/docs/html.mako diff --git a/camera/docs/html.mako b/camera/docs/html.mako new file mode 100644 index 00000000..a3a90423 --- /dev/null +++ b/camera/docs/html.mako @@ -0,0 +1,275 @@ +## -*- coding: utf-8 -*- + + + + + + Android Camera HAL2.0 Properties + + + +<%! + # insert word break hints for the browser + # e.g. X/Y/Z -> X/Y//Z. also for X.Y.Z, X_Y_Z. + def wbr(text): + replace_chars=['.', '/', '_', ','] + new_txt = text + for i in replace_chars: + new_txt = new_txt.replace(i, i + "") + + return new_txt +%> + + + +

Android Camera HAL2.0 Properties

+ +

Table of Contents

+ + +

Properties

+ + + + + + + + + + + + + +% for root in metadata.outer_namespaces: + + % for section in root.sections: + + + % if section.description is not None: + + % endif + + % for kind in section.kinds: # dynamic,static,controls + + + + + + + + + + + + + + + + + <%def name="insert_body(node)"> + % for nested in node.namespaces: + ${insert_namespace(nested)} + % endfor + + % for entry in node.merged_entries: + ${insert_entry(entry)} + % endfor + + + <%def name="insert_namespace(namespace)"> + ${insert_body(namespace)} + + + <%def name="insert_entry(prop)"> + % if False: #prop.is_clone(): + + + % if prop.notes is not None: + ${prop.notes | h,wbr} + % endif + + % for tag in prop.tags: + + % endfor + + + % else: + + + + + + + + + + + + + + + + % endif + + + ${insert_body(kind)} + + + + % endfor # for each kind + + + % endfor + +% endfor +
Property NameTypeDescriptionUnitsRangeNotesTags
${section.name}
${section.description}
${kind.name}
Property NameTypeDescriptionUnitsRangeNotesTags
${prop.name | wbr} + ${prop.type} + % if prop.container is not None: + x + % endif + + % if prop.container == 'array': + + ${" x ".join(prop.container_sizes)} + + % elif prop.container == 'tuple': +
    + % for val in prop.tuple_values: +
  • ${val}
    • + % endfor +
+ % endif + + % if prop.type_notes is not None: +
${prop.type_notes | wbr}
+ % endif + + % if prop.type == 'enum': +
    + % for value in prop.enum.values: +
  • + ${value.name} + % if value.optional: + optional + % endif: + % if value.id is not None: + ${value.id} + % endif + % if value.notes is not None: + ${value.notes | wbr} + % endif +
    • + % endfor +
+ % endif + + 		+ % if prop.description is not None: + ${prop.description | wbr} + % endif + + % if prop.units is not None: + ${prop.units | wbr} + % endif + + % if prop.range is not None: + ${prop.range | wbr} + % endif + + % if prop.notes is not None: + ${prop.notes | wbr} + % endif + + % if list(prop.tags): +
    + % for tag in prop.tags: +
  • ${tag.id}
    • + % endfor +
+ % endif +
+ +
+

Tags

+ +
+ + [ top ] + + + diff --git a/camera/docs/metadata-parser-sanity-check b/camera/docs/metadata-parser-sanity-check index dfb83d0f..e47ec0ba 100755 --- a/camera/docs/metadata-parser-sanity-check +++ b/camera/docs/metadata-parser-sanity-check @@ -34,7 +34,7 @@ tmp_out=$(mktemp) tmp_tidy1=$(mktemp) tmp_tidy2=$(mktemp) -$thisdir/metadata_parser_xml.py $thisdir/metadata_properties.xml > $tmp_out +$thisdir/metadata_parser_xml.py $thisdir/metadata_properties.xml $thisdir/metadata_template.mako > $tmp_out tidy -indent -xml -quiet $thisdir/metadata_properties.xml > $tmp_tidy1 tidy -indent -xml -quiet $tmp_out > $tmp_tidy2 diff --git a/camera/docs/metadata_model.py b/camera/docs/metadata_model.py index 03dacad7..b6215aed 100644 --- a/camera/docs/metadata_model.py +++ b/camera/docs/metadata_model.py @@ -342,6 +342,9 @@ class Metadata(Node): if tag not in p._tags: p._tags.append(tag) + if p not in tag.entries: + tag._entries.append(p) + def _construct_clones(self): for p in self._clones: target_kind = p.target_kind @@ -553,7 +556,7 @@ class Tag(Node): self._parent = parent # all entries that have this tag, including clones - self._entries = [] + self._entries = [] # filled in by Metadata#construct_tags @property def id(self): @@ -641,6 +644,7 @@ class Kind(Node): parent: An edge to the parent, which is always a Section instance. namespaces: A sequence of InnerNamespace children. entries: A sequence of Entry/Clone children. + merged_entries: A sequence of MergedEntry virtual nodes from entries """ def __init__(self, name, parent): self._name = name @@ -658,6 +662,11 @@ class Kind(Node): def entries(self): return self._entries + @property + def merged_entries(self): + for i in self.entries: + yield i.merge() + def sort_children(self): self._namespaces.sort(key=self._get_name()) self._entries.sort(key=self._get_name()) @@ -678,6 +687,7 @@ class InnerNamespace(Node): parent: An edge to the parent, which is an InnerNamespace or a Kind. namespaces: A sequence of InnerNamespace children. entries: A sequence of Entry/Clone children. + merged_entries: A sequence of MergedEntry virtual nodes from entries """ def __init__(self, name, parent): self._name = name @@ -694,6 +704,11 @@ class InnerNamespace(Node): def entries(self): return self._entries + @property + def merged_entries(self): + for i in self.entries: + yield i.merge() + def sort_children(self): self._namespaces.sort(key=self._get_name()) self._entries.sort(key=self._get_name()) @@ -934,9 +949,18 @@ class Entry(Node): if self._type == 'enum': self._enum = Enum(self, enum_values, enum_ids, enum_optionals, enum_notes) + else: + self._enum = None self._property_keys = kwargs + def merge(self): + """ + Copy the attributes into a new entry, merging it with the target entry + if it's a clone. + """ + return MergedEntry(self) + # Helpers for accessing less than the fully qualified name def get_name_as_list(self): @@ -1077,6 +1101,42 @@ class Clone(Entry): """ return True +class MergedEntry(Entry): + """ + A MergedEntry has all the attributes of a Clone and its target Entry merged + together. + + Remarks: + Useful when we want to 'unfold' a clone into a real entry by copying out + the target entry data. In this case we don't care about distinguishing + a clone vs an entry. + """ + def __init__(self, entry): + """ + Create a new instance of MergedEntry. + Args: + entry: An Entry or Clone instance + """ + props_distinct = ['description', 'units', 'range', 'notes', 'tags', 'kind'] + for p in props_distinct: + if entry.is_clone(): + setattr(self, '_' + p, getattr(entry, p) or getattr(entry.entry, p)) + else: + setattr(self, '_' + p, getattr(entry, p)) + + props_common = ['parent', 'name', 'name_short', 'container', + 'container_sizes', 'enum', + 'tuple_values', + 'type', + 'type_notes', + 'enum' + ] + + for p in props_common: + if entry.is_clone(): + setattr(self, '_' + p, getattr(entry.entry, p)) + else: + setattr(self, '_' + p, getattr(entry, p)) diff --git a/camera/docs/metadata_parser_xml.py b/camera/docs/metadata_parser_xml.py index 5390cc45..05953d4f 100755 --- a/camera/docs/metadata_parser_xml.py +++ b/camera/docs/metadata_parser_xml.py @@ -21,7 +21,7 @@ A parser for metadata_properties.xml can also render the resulting model over a Mako template. Usage: - metadata_parser_xml.py + metadata_parser_xml.py - outputs the resulting template to stdout Module: @@ -43,6 +43,7 @@ from bs4 import NavigableString from mako.template import Template from metadata_model import * +import metadata_model from metadata_validate import * class MetadataParserXml: @@ -216,7 +217,7 @@ class MetadataParserXml: output_name: path to the output file, or None to use stdout """ tpl = Template(filename=template) - tpl_data = tpl.render(metadata=self.metadata) + tpl_data = tpl.render(metadata=self.metadata, metadata_model=metadata_model) if output_name is None: print tpl_data @@ -228,11 +229,13 @@ class MetadataParserXml: if __name__ == "__main__": if len(sys.argv) <= 1: - print >> sys.stderr, "Usage: %s " % (sys.argv[0]) + print >> sys.stderr, "Usage: %s " \ + % (sys.argv[0]) sys.exit(0) file_name = sys.argv[1] + template_name = sys.argv[2] parser = MetadataParserXml(file_name) - parser.render("metadata_template.mako") + parser.render(template_name) sys.exit(0) diff --git a/camera/docs/metadata_properties.xml b/camera/docs/metadata_properties.xml index 360cbfc2..0c80cec5 100644 --- a/camera/docs/metadata_properties.xml +++ b/camera/docs/metadata_properties.xml @@ -89,7 +89,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata Enum for controlling antibanding - Enum android.control.aeAvailableAntibandingModes @@ -114,7 +113,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata Whether AE is currently locked to its latest calculated values - Enum Note that even when AE is locked, the flash may be fired if the AE mode is ON_AUTO_FLASH / ON_ALWAYS_FLASH / ON_AUTO_FLASH_REDEYE. @@ -146,7 +144,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata Whether AE is currently updating the sensor exposure and sensitivity fields - Enum android.control.aeAvailableModes Only effective if android.control.mode = AUTO @@ -154,7 +151,8 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata - 5 per area + 5 + area_count List of areas to use for metering @@ -251,12 +249,12 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata Whether AF is currently enabled, and what mode it is set to - Enum - 5 per area + 5 + area_count List of areas to use for focus estimation @@ -288,7 +286,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata Whether AWB is currently locked to its latest calculated values - Enum Note that AWB lock is only meaningful for AUTO mode; in other modes, AWB is already fixed to a specific setting @@ -309,14 +306,14 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata Whether AWB is currently setting the color transform fields, and what its illumination target is - Enum [BC - AWB lock,AWB modes] - 5 per area + 5 + area_count List of areas to use for illuminant estimation @@ -363,7 +360,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata Information to 3A routines about the purpose of this capture, to help decide optimal 3A strategy - Enum all must be supported Only used if android.control.mode != OFF. @@ -382,7 +378,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata Whether any special color effect is in use. Only used if android.control.mode != OFF - Enum android.control.availableEffects @@ -408,7 +403,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata Overall mode of 3A control routines - Enum all must be supported @@ -442,7 +436,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata Which scene mode is active when android.control.mode = SCENE_MODE - Enum android.control.availableSceneModes @@ -453,7 +446,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata Whether video stabilization is active - Enum If enabled, video stabilization can modify the android.scaler.cropRegion to keep the video stream stabilized @@ -552,7 +544,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata - List of enums + List of enums (android.control.awbMode) OFF, AUTO must be included @@ -631,7 +623,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata FLASH_REQUIRED as appropriate Current state of AE algorithm - Enum Whenever the AE algorithm state changes, a MSG_AUTOEXPOSURE notification must be send if a notification callback is registered. @@ -667,7 +658,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata locked Current state of AF algorithm - Enum Whenever the AF algorithm state changes, a MSG_AUTOFOCUS notification must be send if a notification callback is registered. @@ -698,7 +688,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata LOCKED) Current state of AWB algorithm - Enum Whenever the AWB algorithm state changes, a MSG_AUTOWHITEBALANCE notification must be send if a notification callback is registered. @@ -1684,7 +1673,6 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata Arrangement of color filters on sensor; represents the colors in the top-left 2x2 section of the sensor, in reading order - Enum -- 2.11.0