HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
filesystemDiscoveryHelpers.h
Go to the documentation of this file.
1 //
2 // Copyright 2018 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 
25 #ifndef PXR_USD_NDR_FILESYSTEM_DISCOVERY_HELPERS_H
26 #define PXR_USD_NDR_FILESYSTEM_DISCOVERY_HELPERS_H
27 
28 /// \file ndr/filesystemDiscoveryHelpers.h
29 
30 #include "pxr/pxr.h"
31 #include "pxr/usd/ndr/api.h"
32 #include "pxr/usd/ndr/declare.h"
34 
35 #include <functional>
36 
38 
40 
41 /// \file filesystemDiscoveryHelpers.h
42 ///
43 /// Provides utilities that the default filesystem discovery plugin uses. If
44 /// a custom filesystem discovery plugin is needed, these can be used to fill
45 /// in a large chunk of the functionality.
46 ///
47 
48 /// Type of a function that can be used to parse a discovery result's identifier
49 /// into its family, name, and version.
50 using NdrParseIdentifierFn = std::function<
51  bool (const TfToken &identifier,
52  TfToken *family,
53  TfToken *name,
55 
56 /// Given a shader's \p identifier token, computes the corresponding
57 /// NdrNode's family name, implementation name and shader version
58 /// (as NdrVersion).
59 ///
60 /// * \p family is the prefix of \p identifier up to and not
61 /// including the first underscore.
62 /// * \p version is the suffix of \p identifier comprised of one or
63 /// two integers representing the major and minor version numbers.
64 /// * \p name is the string we get by joining
65 /// <i>family</i> with everything that's in between <i>family</i>
66 /// and <i>version</i> with an underscore.
67 ///
68 /// Returns true if \p identifier is valid and was successfully split
69 /// into the different components.
70 ///
71 /// \note The python version of this function returns a tuple containing
72 /// (famiyName, implementationName, version).
73 NDR_API
74 bool
76  const TfToken &identifier,
77  TfToken *family,
78  TfToken *name,
80 
81 /// Returns a vector of discovery results that have been found while walking
82 /// the given search paths.
83 ///
84 /// Each path in \p searchPaths is walked recursively, optionally following
85 /// symlinks if \p followSymlinks is true, looking for files that match one of
86 /// the provided \p allowedExtensions. These files are represented in the
87 /// discovery results that are returned.
88 ///
89 /// The identifier for each discovery result is the base name of the represented
90 /// file with the extension removed. The \p parseIdentifierFn is used to parse
91 /// the family, name, and version from the identifier that will set in the
92 /// file's discovery result. By default, NdrFsHelpersSplitShaderIdentifier is
93 /// used to parse the identifier, but the family/name/version parsing behavior
94 /// can be changed by passing a custom parseIdentifierFn. Any identifiers that
95 /// cannot be parsed by whatever the parseIdentifierFn will be considered
96 /// invalid and not added as a discovery result. Note that the version for
97 /// every discovery result returned by this function will be naively marked as
98 /// being default even if multiple versions with the same name are found.
99 NDR_API
102  const NdrStringVec& searchPaths,
103  const NdrStringVec& allowedExtensions,
104  bool followSymlinks = true,
105  const NdrDiscoveryPluginContext* context = nullptr,
106  const NdrParseIdentifierFn &parseIdentifierFn =
108 );
109 
110 /// Struct for holding a URI and its resolved URI for a file discovered
111 /// by NdrFsHelpersDiscoverFiles
113 {
116 };
117 
118 /// A vector of URI/resolved URI structs.
119 using NdrDiscoveryUriVec = std::vector<NdrDiscoveryUri>;
120 
121 /// Returns a vector of discovered URIs (as both the unresolved URI and the
122 /// resolved URI) that are found while walking the given search paths.
123 ///
124 /// Each path in \p searchPaths is walked recursively, optionally following
125 /// symlinks if \p followSymlinks is true, looking for files that match one of
126 /// the provided \p allowedExtensions. These files' unresolved and resolved URIs
127 /// are returned in the result vector.
128 ///
129 /// This is an alternative to NdrFsHelpersDiscoverNodes for discovery plugins
130 /// that want to search for files that are not meant to be returned by discovery
131 /// themselves, but can be parsed to generate the discovery results.
132 NDR_API
135  const NdrStringVec& searchPaths,
136  const NdrStringVec& allowedExtensions,
137  bool followSymlinks = true
138 );
139 
141 
142 #endif // PXR_USD_NDR_FILESYSTEM_DISCOVERY_HELPERS_H
std::vector< NdrDiscoveryUri > NdrDiscoveryUriVec
A vector of URI/resolved URI structs.
NDR_API NdrDiscoveryUriVec NdrFsHelpersDiscoverFiles(const NdrStringVec &searchPaths, const NdrStringVec &allowedExtensions, bool followSymlinks=true)
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
std::vector< NdrNodeDiscoveryResult > NdrNodeDiscoveryResultVec
NDR_API bool NdrFsHelpersSplitShaderIdentifier(const TfToken &identifier, TfToken *family, TfToken *name, NdrVersion *version)
Definition: token.h:87
std::vector< std::string > NdrStringVec
Definition: declare.h:79
GLuint const GLchar * name
Definition: glcorearb.h:786
#define NDR_API
Definition: api.h:40
GT_API const UT_StringHolder version
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
std::function< bool(const TfToken &identifier, TfToken *family, TfToken *name, NdrVersion *version)> NdrParseIdentifierFn
NDR_API NdrNodeDiscoveryResultVec NdrFsHelpersDiscoverNodes(const NdrStringVec &searchPaths, const NdrStringVec &allowedExtensions, bool followSymlinks=true, const NdrDiscoveryPluginContext *context=nullptr, const NdrParseIdentifierFn &parseIdentifierFn=NdrFsHelpersSplitShaderIdentifier)