Flutter Impeller
switches.cc
Go to the documentation of this file.
1 // Copyright 2013 The Flutter Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
6 
7 #include <algorithm>
8 #include <cctype>
9 #include <filesystem>
10 #include <map>
11 
12 #include "flutter/fml/file.h"
13 #include "fml/command_line.h"
16 
17 namespace impeller {
18 namespace compiler {
19 
20 static const std::map<std::string, TargetPlatform> kKnownPlatforms = {
21  {"metal-desktop", TargetPlatform::kMetalDesktop},
22  {"metal-ios", TargetPlatform::kMetalIOS},
23  {"vulkan", TargetPlatform::kVulkan},
24  {"opengl-es", TargetPlatform::kOpenGLES},
25  {"opengl-desktop", TargetPlatform::kOpenGLDesktop},
26 };
27 
28 static const std::map<std::string, TargetPlatform> kKnownRuntimeStages = {
29  {"sksl", TargetPlatform::kSkSL},
30  {"runtime-stage-metal", TargetPlatform::kRuntimeStageMetal},
31  {"runtime-stage-gles", TargetPlatform::kRuntimeStageGLES},
32  {"runtime-stage-gles3", TargetPlatform::kRuntimeStageGLES3},
33  {"runtime-stage-vulkan", TargetPlatform::kRuntimeStageVulkan},
34 };
35 
36 static const std::map<std::string, SourceType> kKnownSourceTypes = {
37  {"vert", SourceType::kVertexShader},
40 };
41 
42 void Switches::PrintHelp(std::ostream& stream) {
43  // clang-format off
44  const std::string optional_prefix = "[optional] ";
45  const std::string optional_multiple_prefix = "[optional,multiple] ";
46  // clang-format on
47 
48  stream << std::endl;
49  stream << "ImpellerC is an offline shader processor and reflection engine."
50  << std::endl;
51  stream << "---------------------------------------------------------------"
52  << std::endl;
53  stream << "Expected invocation is:" << std::endl << std::endl;
54  stream << "./impellerc <One platform or multiple runtime stages> "
55  "--input=<source_file> --sl=<sl_output_file> <optional arguments>"
56  << std::endl
57  << std::endl;
58 
59  stream << "Valid platforms are:" << std::endl << std::endl;
60  stream << "One of [";
61  for (const auto& platform : kKnownPlatforms) {
62  stream << " --" << platform.first;
63  }
64  stream << " ]" << std::endl << std::endl;
65 
66  stream << "Valid runtime stages are:" << std::endl << std::endl;
67  stream << "At least one of [";
68  for (const auto& platform : kKnownRuntimeStages) {
69  stream << " --" << platform.first;
70  }
71  stream << " ]" << std::endl << std::endl;
72 
73  stream << "Optional arguments:" << std::endl << std::endl;
74  stream << optional_prefix
75  << "--spirv=<spirv_output_file> (ignored for --shader-bundle)"
76  << std::endl;
77  stream << optional_prefix << "--input-type={";
78  for (const auto& source_type : kKnownSourceTypes) {
79  stream << source_type.first << ", ";
80  }
81  stream << "}" << std::endl;
82  stream << optional_prefix << "--source-language=glsl|hlsl (default: glsl)"
83  << std::endl;
84  stream << optional_prefix
85  << "--entry-point=<entry_point_name> (default: main; "
86  "ignored for glsl)"
87  << std::endl;
88  stream << optional_prefix
89  << "--iplr (causes --sl file to be emitted in "
90  "iplr format)"
91  << std::endl;
92  stream << optional_prefix
93  << "--shader-bundle=<bundle_spec> (causes --sl "
94  "file to be "
95  "emitted in Flutter GPU's shader bundle format)"
96  << std::endl;
97  stream << optional_prefix << "--reflection-json=<reflection_json_file>"
98  << std::endl;
99  stream << optional_prefix << "--reflection-header=<reflection_header_file>"
100  << std::endl;
101  stream << optional_prefix << "--reflection-cc=<reflection_cc_file>"
102  << std::endl;
103  stream << optional_multiple_prefix << "--include=<include_directory>"
104  << std::endl;
105  stream << optional_multiple_prefix << "--define=<define>" << std::endl;
106  stream << optional_prefix << "--depfile=<depfile_path>" << std::endl;
107  stream << optional_prefix << "--gles-language-version=<number>" << std::endl;
108  stream << optional_prefix << "--json" << std::endl;
109  stream << optional_prefix
110  << "--use-half-textures (force openGL semantics when "
111  "targeting metal)"
112  << std::endl;
113  stream << optional_prefix << "--require-framebuffer-fetch" << std::endl;
114 }
115 
116 Switches::Switches() = default;
117 
118 Switches::~Switches() = default;
119 
121  const fml::CommandLine& command_line) {
122  auto target = TargetPlatform::kUnknown;
123  for (const auto& platform : kKnownPlatforms) {
124  if (command_line.HasOption(platform.first)) {
125  // If the platform has already been determined, the caller may have
126  // specified multiple platforms. This is an error and only one must be
127  // selected.
128  if (target != TargetPlatform::kUnknown) {
130  }
131  target = platform.second;
132  // Keep going to detect duplicates.
133  }
134  }
135  return target;
136 }
137 
138 static std::vector<TargetPlatform> RuntimeStagesFromCommandLine(
139  const fml::CommandLine& command_line) {
140  std::vector<TargetPlatform> stages;
141  for (const auto& platform : kKnownRuntimeStages) {
142  if (command_line.HasOption(platform.first)) {
143  stages.push_back(platform.second);
144  }
145  }
146  return stages;
147 }
148 
150  const fml::CommandLine& command_line) {
151  auto source_type_option =
152  command_line.GetOptionValueWithDefault("input-type", "");
153  auto source_type_search = kKnownSourceTypes.find(source_type_option);
154  if (source_type_search == kKnownSourceTypes.end()) {
155  return SourceType::kUnknown;
156  }
157  return source_type_search->second;
158 }
159 
160 Switches::Switches(const fml::CommandLine& command_line)
161  : working_directory(std::make_shared<fml::UniqueFD>(fml::OpenDirectory(
162  Utf8FromPath(std::filesystem::current_path()).c_str(),
163  false, // create if necessary,
164  fml::FilePermission::kRead))),
165  source_file_name(command_line.GetOptionValueWithDefault("input", "")),
166  input_type(SourceTypeFromCommandLine(command_line)),
167  sl_file_name(command_line.GetOptionValueWithDefault("sl", "")),
168  iplr(command_line.HasOption("iplr")),
169  shader_bundle(
170  command_line.GetOptionValueWithDefault("shader-bundle", "")),
171  spirv_file_name(command_line.GetOptionValueWithDefault("spirv", "")),
172  reflection_json_name(
173  command_line.GetOptionValueWithDefault("reflection-json", "")),
174  reflection_header_name(
175  command_line.GetOptionValueWithDefault("reflection-header", "")),
176  reflection_cc_name(
177  command_line.GetOptionValueWithDefault("reflection-cc", "")),
178  depfile_path(command_line.GetOptionValueWithDefault("depfile", "")),
179  json_format(command_line.HasOption("json")),
180  gles_language_version(
181  stoi(command_line.GetOptionValueWithDefault("gles-language-version",
182  "0"))),
183  metal_version(
184  command_line.GetOptionValueWithDefault("metal-version", "1.2")),
185  entry_point(
186  command_line.GetOptionValueWithDefault("entry-point", "main")),
187  use_half_textures(command_line.HasOption("use-half-textures")),
188  require_framebuffer_fetch(
189  command_line.HasOption("require-framebuffer-fetch")),
190  target_platform_(TargetPlatformFromCommandLine(command_line)),
191  runtime_stages_(RuntimeStagesFromCommandLine(command_line)) {
192  auto language = ToLowerCase(
193  command_line.GetOptionValueWithDefault("source-language", "glsl"));
194 
195  source_language = ToSourceLanguage(language);
196 
197  if (!working_directory || !working_directory->is_valid()) {
198  return;
199  }
200 
201  for (const auto& include_dir_path : command_line.GetOptionValues("include")) {
202  if (!include_dir_path.data()) {
203  continue;
204  }
205 
206  // fml::OpenDirectoryReadOnly for Windows doesn't handle relative paths
207  // beginning with `../` well, so we build an absolute path.
208 
209  // Get the current working directory as a utf8 encoded string.
210  // Note that the `include_dir_path` is already utf8 encoded, and so we
211  // mustn't attempt to double-convert it to utf8 lest multi-byte characters
212  // will become mangled.
213  std::filesystem::path include_dir_absolute;
214  if (std::filesystem::path(include_dir_path).is_absolute()) {
215  include_dir_absolute = std::filesystem::path(include_dir_path);
216  } else {
217  auto cwd = Utf8FromPath(std::filesystem::current_path());
218  include_dir_absolute = std::filesystem::absolute(
219  std::filesystem::path(cwd) / include_dir_path);
220  }
221 
222  auto dir = std::make_shared<fml::UniqueFD>(fml::OpenDirectoryReadOnly(
223  *working_directory, include_dir_absolute.string().c_str()));
224  if (!dir || !dir->is_valid()) {
225  continue;
226  }
227 
228  IncludeDir dir_entry;
229  dir_entry.name = include_dir_path;
230  dir_entry.dir = std::move(dir);
231 
232  include_directories.emplace_back(std::move(dir_entry));
233  }
234 
235  for (const auto& define : command_line.GetOptionValues("define")) {
236  defines.emplace_back(define);
237  }
238 }
239 
240 bool Switches::AreValid(std::ostream& explain) const {
241  // When producing a shader bundle, all flags related to single shader inputs
242  // and outputs such as `--input` and `--spirv-file-name` are ignored. Instead,
243  // input files are read from the shader bundle spec and a single flatbuffer
244  // containing all compiled shaders and reflection state is output to `--sl`.
245  const bool shader_bundle_mode = !shader_bundle.empty();
246 
247  bool valid = true;
248  if (target_platform_ == TargetPlatform::kUnknown && runtime_stages_.empty() &&
249  !shader_bundle_mode) {
250  explain << "Either a target platform was not specified, or no runtime "
251  "stages were specified."
252  << std::endl;
253  valid = false;
254  }
255 
256  if (source_language == SourceLanguage::kUnknown && !shader_bundle_mode) {
257  explain << "Invalid source language type." << std::endl;
258  valid = false;
259  }
260 
261  if (!working_directory || !working_directory->is_valid()) {
262  explain << "Could not open the working directory: \""
263  << Utf8FromPath(std::filesystem::current_path()).c_str() << "\""
264  << std::endl;
265  valid = false;
266  }
267 
268  if (source_file_name.empty() && !shader_bundle_mode) {
269  explain << "Input file name was empty." << std::endl;
270  valid = false;
271  }
272 
273  if (sl_file_name.empty()) {
274  explain << "Target shading language file name was empty." << std::endl;
275  valid = false;
276  }
277 
278  if (spirv_file_name.empty() && !shader_bundle_mode) {
279  explain << "Spirv file name was empty." << std::endl;
280  valid = false;
281  }
282 
283  if (iplr && shader_bundle_mode) {
284  explain << "--iplr and --shader-bundle flag cannot be specified at the "
285  "same time"
286  << std::endl;
287  valid = false;
288  }
289 
290  return valid;
291 }
292 
293 std::vector<TargetPlatform> Switches::PlatformsToCompile() const {
294  if (target_platform_ == TargetPlatform::kUnknown) {
295  return runtime_stages_;
296  }
297  return {target_platform_};
298 }
299 
301  if (target_platform_ == TargetPlatform::kUnknown &&
302  !runtime_stages_.empty()) {
303  return runtime_stages_.front();
304  }
305  return target_platform_;
306 }
307 
309  std::optional<TargetPlatform> target_platform) const {
310  SourceOptions options;
311  options.target_platform =
312  target_platform.value_or(SelectDefaultTargetPlatform());
316  } else {
317  options.type = input_type;
318  }
320  options.file_name = source_file_name;
322  options.defines = defines;
324  source_file_name, options.type, options.source_language, entry_point);
325  options.json_format = json_format;
327  options.metal_version = metal_version;
330  return options;
331 }
332 
333 } // namespace compiler
334 } // namespace impeller
std::vector< TargetPlatform > PlatformsToCompile() const
A vector containing at least one valid platform.
Definition: switches.cc:293
SourceLanguage source_language
Definition: switches.h:40
std::vector< std::string > defines
Definition: switches.h:38
std::shared_ptr< fml::UniqueFD > working_directory
Definition: switches.h:23
SourceOptions CreateSourceOptions(std::optional< TargetPlatform > target_platform=std::nullopt) const
Definition: switches.cc:308
std::string spirv_file_name
Definition: switches.h:33
bool AreValid(std::ostream &explain) const
Definition: switches.cc:240
static void PrintHelp(std::ostream &stream)
Definition: switches.cc:42
std::string source_file_name
Definition: switches.h:25
std::vector< IncludeDir > include_directories
Definition: switches.h:24
TargetPlatform SelectDefaultTargetPlatform() const
Definition: switches.cc:300
std::string ToLowerCase(std::string_view string)
Definition: utilities.cc:62
static const std::map< std::string, TargetPlatform > kKnownPlatforms
Definition: switches.cc:20
static std::vector< TargetPlatform > RuntimeStagesFromCommandLine(const fml::CommandLine &command_line)
Definition: switches.cc:138
SourceType SourceTypeFromFileName(const std::string &file_name)
Definition: types.cc:30
std::string EntryPointFunctionNameFromSourceName(const std::string &file_name, SourceType type, SourceLanguage source_language, const std::string &entry_point_name)
Definition: types.cc:113
static const std::map< std::string, TargetPlatform > kKnownRuntimeStages
Definition: switches.cc:28
std::string Utf8FromPath(const std::filesystem::path &path)
Converts a native format path to a utf8 string.
Definition: utilities.cc:30
static TargetPlatform TargetPlatformFromCommandLine(const fml::CommandLine &command_line)
Definition: switches.cc:120
SourceLanguage ToSourceLanguage(const std::string &source_language)
Definition: types.cc:64
static const std::map< std::string, SourceType > kKnownSourceTypes
Definition: switches.cc:36
static SourceType SourceTypeFromCommandLine(const fml::CommandLine &command_line)
Definition: switches.cc:149
Definition: comparable.h:95
std::shared_ptr< fml::UniqueFD > dir
Definition: include_dir.h:17
bool use_half_textures
Whether half-precision textures should be supported, requiring opengl semantics. Only used on metal t...
std::vector< IncludeDir > include_dirs
bool require_framebuffer_fetch
Whether the GLSL framebuffer fetch extension will be required.
std::shared_ptr< fml::UniqueFD > working_directory
std::vector< std::string > defines