camera/docs/CameraMetadataKeys.mako

   1 ## -*- coding: utf-8 -*-
   2 ##
   3 ## Copyright (C) 2013 The Android Open Source Project
   4 ##
   5 ## Licensed under the Apache License, Version 2.0 (the "License");
   6 ## you may not use this file except in compliance with the License.
   7 ## You may obtain a copy of the License at
   8 ##
   9 ##      http://www.apache.org/licenses/LICENSE-2.0
  10 ##
  11 ## Unless required by applicable law or agreed to in writing, software
  12 ## distributed under the License is distributed on an "AS IS" BASIS,
  13 ## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 ## See the License for the specific language governing permissions and
  15 ## limitations under the License.
  16 ##
  17 \
  18 ## These sections of metadata Key definitions are inserted into the middle of
  19 ## android.hardware.camera2.CameraCharacteristics, CaptureRequest, and CaptureResult.
  20 <%page args="java_class, xml_kind" />\
  21     /*@O~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~
  22      * The key entries below this point are generated from metadata
  23      * definitions in /system/media/camera/docs. Do not modify by hand or
  24      * modify the comment blocks at the start or end.
  25      *~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~*/
  26
  27 <%!
  28   ##
  29   ## Generate extra text blocks for the details field
  30   def generate_extra_detail(entry):
  31     def inner(text):
  32       if entry.optional:
  33         text += '\n\n<b>Optional</b> - This value may be {@code null} on some devices.\n'
  34       if any(tag.name == 'FULL' for tag in entry.tags):
  35         text += \
  36           '\n<b>Full capability</b> - \n' + \
  37           'Present on all camera devices that report being {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_FULL HARDWARE_LEVEL_FULL} devices in the\n' + \
  38           'android.info.supportedHardwareLevel key\n'
  39       return text
  40     return inner
  41 %>
  42 ##
  43 ## Generate a single key and docs
  44 <%def name="generate_key(entry)">\
  45     /**
  46 <%
  47     # Dedent fixes markdown not to generate code blocks. Then do the rest.
  48     description = ""
  49     if entry.description:
  50         description = dedent(entry.description) + "\n\n"
  51     details = ""
  52     if entry.details:
  53         details = dedent(entry.details)
  54     # Unconditionally add extra information if necessary
  55     extra_detail = generate_extra_detail(entry)("")
  56
  57     concatenated_info = description + details + extra_detail
  58 %>\
  59 ## Glue description and details together before javadoc-izing. Otherwise @see in middle of javadoc.
  60 ${concatenated_info | javadoc(metadata)}\
  61   % if entry.enum and not (entry.typedef and entry.typedef.languages.get('java')):
  62     % for value in entry.enum.values:
  63      * @see #${jenum_value(entry, value)}
  64     % endfor
  65   % endif
  66   % if entry.applied_visibility == 'hidden':
  67      * @hide
  68   % endif
  69      */
  70     public static final Key<${jtype_boxed(entry)}> ${entry.name | jkey_identifier} =
  71             new Key<${jtype_boxed(entry)}>("${entry.name}", ${jclass(entry)});
  72 </%def>\
  73 ##
  74 ## Generate a list of only Static, Controls, or Dynamic properties.
  75 <%def name="single_kind_keys(java_name, xml_name)">\
  76 % for outer_namespace in metadata.outer_namespaces: ## assumes single 'android' namespace
  77   % for section in outer_namespace.sections:
  78     % if section.find_first(lambda x: isinstance(x, metadata_model.Entry) and x.kind == xml_name) and \
  79          any_visible(section, xml_name, ('public','hidden') ):
  80       % for inner_namespace in get_children_by_filtering_kind(section, xml_name, 'namespaces'):
  81 ## We only support 1 level of inner namespace, i.e. android.a.b and android.a.b.c works, but not android.a.b.c.d
  82 ## If we need to support more, we should use a recursive function here instead.. but the indentation gets trickier.
  83         % for entry in filter_visibility(inner_namespace.merged_entries, ('hidden','public')):
  84 ${generate_key(entry)}
  85        % endfor
  86     % endfor
  87     % for entry in filter_visibility( \
  88         get_children_by_filtering_kind(section, xml_name, 'merged_entries'), \
  89                                          ('hidden', 'public')):
  90 ${generate_key(entry)}
  91     % endfor
  92     % endif
  93   % endfor
  94 % endfor
  95 </%def>\
  96 ##
  97 ## Static properties only
  98 ##${single_kind_keys('CameraCharacteristicsKeys', 'static')}
  99 ##
 100 ## Controls properties only
 101 ##${single_kind_keys('CaptureRequestKeys', 'controls')}
 102 ##
 103 ## Dynamic properties only
 104 ##${single_kind_keys('CaptureResultKeys', 'dynamic')}
 105 ${single_kind_keys(java_class, xml_kind)}\
 106     /*~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~
 107      * End generated code
 108      *~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~O@*/