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      % if not value.hidden:
  64      * @see #${jenum_value(entry, value)}
  65      % endif
  66     % endfor
  67   % endif
  68   % if entry.deprecated:
  69      * @deprecated
  70   % endif
  71   % if entry.applied_visibility == 'hidden':
  72      * @hide
  73   % endif
  74      */
  75   % if entry.deprecated:
  76     @Deprecated
  77   % endif
  78   % if entry.applied_visibility == 'public':
  79     @PublicKey
  80   % endif
  81   % if entry.synthetic:
  82     @SyntheticKey
  83   % endif
  84     public static final Key<${jtype_boxed(entry)}> ${entry.name | jkey_identifier} =
  85             new Key<${jtype_boxed(entry)}>("${entry.name}", ${jkey_type_token(entry)});
  86 </%def>\
  87 ##
  88 ## Generate a list of only Static, Controls, or Dynamic properties.
  89 <%def name="single_kind_keys(java_name, xml_name)">\
  90 % for outer_namespace in metadata.outer_namespaces: ## assumes single 'android' namespace
  91   % for section in outer_namespace.sections:
  92     % if section.find_first(lambda x: isinstance(x, metadata_model.Entry) and x.kind == xml_name) and \
  93          any_visible(section, xml_name, ('public','hidden') ):
  94       % for inner_namespace in get_children_by_filtering_kind(section, xml_name, 'namespaces'):
  95 ## 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
  96 ## If we need to support more, we should use a recursive function here instead.. but the indentation gets trickier.
  97         % for entry in filter_visibility(inner_namespace.merged_entries, ('hidden','public')):
  98 ${generate_key(entry)}
  99        % endfor
 100     % endfor
 101     % for entry in filter_visibility( \
 102         get_children_by_filtering_kind(section, xml_name, 'merged_entries'), \
 103                                          ('hidden', 'public')):
 104 ${generate_key(entry)}
 105     % endfor
 106     % endif
 107   % endfor
 108 % endfor
 109 </%def>\
 110 ##
 111 ## Static properties only
 112 ##${single_kind_keys('CameraCharacteristicsKeys', 'static')}
 113 ##
 114 ## Controls properties only
 115 ##${single_kind_keys('CaptureRequestKeys', 'controls')}
 116 ##
 117 ## Dynamic properties only
 118 ##${single_kind_keys('CaptureResultKeys', 'dynamic')}
 119 ${single_kind_keys(java_class, xml_kind)}\
 120     /*~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~
 121      * End generated code
 122      *~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~@~O@*/