Eklenti Parametreleri

5 dakika okuma

İçindekiler

Parametre türleri
Parametreleri manipüle etme
Çıkış parametreleri ve PluginRef
Çalışma zamanı türleri
V-Ray sahne dosyası formatı
Varsayılan değerler
alt bölüm parametreleri

App SDK eklenti parametreleri, statik olarak tiplendirilmiş dillerde (C++, C#) Plugin türünün (veya onun alt somut eklenti türlerinin) özellikleri olarak veya dinamik dillerde (Python, JavaScript) çalışma zamanı eklenti nesneleri olarak sunulur . Ayrıca kod yorumlarında ve dokümanlarda da sıklıkla özellikler olarak anılırlar.

Destekleyen dillerde (C#, Python, JavaScript) basit özellikler ve tüm dillerde getter/setter metotları mevcuttur. İkincisi, animasyonlu bir eklenti parametresinin değerinin ne zaman okunacağını veya yazılacağını (isteğe bağlı olarak) belirtmenize olanak tanır .

Özellikler her zaman değer üzerinden okunur ve yazılır ve okuma işleminde her zaman değerlerinin tam bir kopyası alınır ve yazma işleminde gönderilir (birkaç istisna dışında, bkz. Optimizasyonlar bölümü, TypedLists, C++’da taşıma semantiği ve Node.js’de maxTypedListsCopyByteSize).

Parametre türleri #

Aşağıda, bir V-Ray sahnesinde tanınan türler listelenmiştir (aşağıdaki V-Ray sahne dosyası formatına bakın). Bunların farklı Uygulama SDK dil bağlamalarında karşılık gelen türleri vardır. SDK, mümkün olan her yerde ilgili temel dil türlerini kullanır ve geri kalanlar için özel tür sınıfları tanımlar.

Temel veri tipleri: int , bool , float , Color (3 float RGB), AColor (4 float ARGB), Vector (3 float), Matrix (3 Vector, sütun öncelikli), Transform (öteleme için bir Matrix ve bir Vector) ve string (UTF-8).
Nesneler: Diğer eklenti örneklerine yapılan referanslar ( Plugin ve PluginRef türleri).
Türlü listeler: App SDK’deki türlü listeler IntList , FloatList , ColorList , VectorList , TransformList ve PluginList’tir .
Genel heterojen listeler: C++ bağlaması, genel bir listedeki öğeler için ValueList (yani std::vector<Value> ) türünü kullanır. .Net bağlaması IList<object> kullanırken , Python ve Node.js kendi yerel heterojen dizilerini / listelerini kullanır . Genel listeler iç içe yerleştirilebilir.
Çıkış parametreleri: Bunlar, belirli bir eklenti tarafından oluşturulan ve diğerleri tarafından girdi olarak kullanılabilen ek değerlerdir. Örneğin, TexAColorOp eklentisi (Dokular derslerinde daha sonra ele alınacaktır) doğrudan bir doku olarak referans alınabilir ve varsayılan AColor doku çıktısını verir; ancak farklı sonuçlar için toplam, fark, maksimum vb. diğer çıktılarından herhangi birine de referans verebilirsiniz. Başka bir Eklenti özelliğinin (parametresinin) değeri olarak ayarlanan Eklenti nesnesinin kendisi, Eklentinin varsayılan çıktısına referans olarak kullanılabilir ve PluginRef türü alternatif bir çıktıya referans olarak kullanılır.

Parametreleri manipüle etme #

Önceki bölümde ele alınan Plugin türü, kullanışlı getter ve setter’lar sağlar. Güçlü tipli C++ ve C# bağlamalarında bunlar, temel Plugin sınıfından türetilen özel eklenti sınıflarının üyeleridir. Temel sınıfta ayrıca “genel” yöntemler de bulunur. Python’da eklenti nesneleri parametrelerini hem öznitelikler hem de sözlük benzeri anahtarlar olarak sunar. Node.js’de parametreler Plugin nesnelerinin özellikleri olarak sunulur. Parametre değerleriyle uğraşırken çok önemli bir nokta, tüm getter’ların render motorundaki temel verilerin kopyalarını döndürmesidir . Bunlarda değişiklik yaparsanız, gerçek sahnede değişiklik yapmazsınız. Değişiklikler yalnızca bunları setter’a geri gönderdiğinizde uygulanır.

renderView.transform = vray.Transform()
print(renderView.transform)
# prints Transform(Matrix(Vector(0, 0, 0), Vector(0, 0, 0), Vector(0, 0, 0)), Vector(0, 0, 0))
copyTransform = renderView.transform
copyTransform = copyTransform.replaceOffset(vray.Vector(5, copyTransform.offset.y, copyTransform.offset.z))
print(renderView.transform)
# prints Transform(Matrix(Vector(0, 0, 0), Vector(0, 0, 0), Vector(0, 0, 0)), Vector(0, 0, 0))
renderView.transform = copyTransform
print(renderView.transform)
# prints Transform(Matrix(Vector(0, 0, 0), Vector(0, 0, 0), Vector(0, 0, 0)), Vector(5, 0, 0))

// default Transform constructor in C++ leaves it uninitialized for performance
renderView.set_transform(VRay::Transform(0));
cout << renderView.get_transform() << endl;
// prints Transform(Matrix(Vector(0, 0, 0), Vector(0, 0, 0), Vector(0, 0, 0)), Vector(0, 0, 0))
// Vector, Matrix, Transform, Color etc. are mutable only in C++
renderView.get_transform().offset[0] = 5.0f;
cout << renderView.get_transform() << endl;
// prints Transform(Matrix(Vector(0, 0, 0), Vector(0, 0, 0), Vector(0, 0, 0)), Vector(0, 0, 0))
Transform tm = renderView.get_transform();
tm.offset[0] = 5.0f;
renderView.set_transform(tm);
cout << renderView.get_transform() << endl;
// prints Transform(Matrix(Vector(0, 0, 0), Vector(0, 0, 0), Vector(0, 0, 0)), Vector(5, 0, 0))

renderView.Transform = new Transform(0);
Console.WriteLine(renderView.Transform);
// prints Transform(Matrix(Vector(0, 0, 0), Vector(0, 0, 0), Vector(0, 0, 0)), Vector(0, 0, 0))
Transform copyTransform = renderView.Transform;
copyTransform = copyTransform.ReplaceOffset(new Vector(5, copyTransform.Offset.Y, copyTransform.Offset.Z));
Console.WriteLine(renderView.Transform);
// prints Transform(Matrix(Vector(0, 0, 0), Vector(0, 0, 0), Vector(0, 0, 0)), Vector(0, 0, 0))
renderView.Transform = copyTransform;
Console.WriteLine(renderView.Transform);
// prints Transform(Matrix(Vector(0, 0, 0), Vector(0, 0, 0), Vector(0, 0, 0)), Vector(5, 0, 0))

renderView.transform = vray.Transform();
console.log(renderView.transform);
// prints Transform(Matrix(Vector(0, 0, 0), Vector(0, 0, 0), Vector(0, 0, 0)), Vector(0, 0, 0))
var copyTransform = renderView.transform;
copyTransform = copyTransform.replaceOffset(vray.Vector(5, copyTransform.offset.y, copyTransform.offset.z));
console.log(renderView.transform);
// prints Transform(Matrix(Vector(0, 0, 0), Vector(0, 0, 0), Vector(0, 0, 0)), Vector(0, 0, 0))
renderView.transform = copyTransform;
console.log(renderView.transform);
// prints Transform(Matrix(Vector(0, 0, 0), Vector(0, 0, 0), Vector(0, 0, 0)), Vector(5, 0, 0))

Çıkış parametreleri ve PluginRef #

Doku eklentilerinin, üretebilecekleri ek değerler için (alfa, bir tür karışım vb.) çıkış parametreleri vardır. Bunlar, dokuların varsayılan çıktılarını kullanmak için bağlandığı şekilde, diğer eklentilere ( BRDF’ler gibi ) giriş olarak bağlanabilir. Varsayılan eklenti tanıtıcısı yerine, belirli çıktı için yalnızca bir PluginRef tanıtıcısı almanız yeterlidir.

PluginRef, PluginRef örneğini başka bir Plugin’e girdi olarak kullanırken kullanılacak çıktı hakkında bilgi içeren bir Plugin sınıfını genişleten bir türdür. Bu özellik v2 API’sinde eklendi. Başka bir deyişle, daha önce yalnızca bir Plugin’i doğrudan plugin türündeki bir parametreye atayabiliyorduk ve varsayılan çıktının kullanılmasını istemiyorsak çıktı parametresini belirtmek için özel bir dize tabanlı yöntem kullanmak zorundaydık. Şimdi PluginRef bu görevi daha doğal ve doğrudan hale getiriyor.

İşte bir çıktı parametresini nasıl ayarlayacağınıza dair bir örnek:

# brdfVRayMtl is a BRDFVRayMtl and texBitmap is a TexBitmap plugin
# "generic" syntax with string name parameter
brdfVRayMtl.opacity = texBitmap.getReference("out_alpha")
# alternative syntax
brdfVRayMtl.opacity = texBitmap.out_alpha
# now the material opacity will come from the bitmap alpha channel

// brdfVRayMtl is a BRDFVRayMtl and texBitmap is a TexBitmap plugin
// "generic" syntax with string name parameter
brdfVRayMtl.setValue("opacity", PluginRef(texBitmap, "out_alpha"));
// alternative syntax when using the concrete classes derived from Plugin
// (the out_ prefix is applied to all output paramters so it duplicates the name)
brdfVRayMtl.set_opacity(texBitmap.out_out_alpha());
// now the material opacity will come from the bitmap alpha channel

// brdfVRayMtl is a BRDFVRayMtl and texBitmap is a TexBitmap plugin
// "generic" syntax with string name parameter
brdfVRayMtl.SetValue("opacity", PluginRef.Create(texBitmap, "out_alpha"));
// alternative syntax when using the concrete classes derived from Plugin
// (the Out_ prefix is applied to all output parameters so it duplicates the name)
brdfVRayMtl.Opacity = texBitmap.Out_OutAlpha;
// now the material opacity will come from the bitmap alpha channel

// brdfVRayMtl is a BRDFVRayMtl and texBitmap is a TexBitmap plugin
// "generic" syntax with string name parameter
brdfVRayMtl.opacity = texBitmap.getReference("out_alpha");
// alternative syntax
brdfVRayMtl.opacity = texBitmap.out_alpha;
// now the material opacity will come from the bitmap alpha channel

Çalışma zamanı türleri #

Parametre polimorfizmi, V-Ray’in önemli bir özelliğidir. Doku parametreleri basit (temel) değerler kabul eder, bu nedenle tek bir renk üreten ek bir doku eklentisi oluşturmak yerine, doku yuvasına bir Color/AColor değeri atamanız yeterlidir. Aynı şey float dokular ve tek float değerleri için de geçerlidir. Ayrıca, yukarıda açıklandığı gibi bir doku parametresinin değerini bir çıktı parametresine de atayabilirsiniz.

Çeşitli V-Ray eklentilerinde bu konuda bazı tutarsızlıklar mevcuttur çünkü bunlar farklı zamanlarda yazılmıştır. Bazı eski eklentilerde ayrı tek değer ve doku değeri parametreleri bulunur. Örneğin, BRDFDiffuse’da bir renk ve bir color_tex parametresi vardır. Bu durumlarda, ayarlandığında doku parametresi yuvası tek değeri geçersiz kılar. Bu durumda bile doku yuvasına tek bir değer ayarlayabileceğinizi unutmayın.

Aşağıdaki örnek, bir eklenti parametresinin çalışma zamanı türünü nasıl kontrol edebileceğinizi göstermektedir:

meta = brdfVRayMtl.getMeta('diffuse')
# Output of this will depend on what is applied to this parameter slot
print(meta['type'], meta['runtimeType'])

# We can also check the size of lists from runtime meta information:
meta = brdfLayered.getMeta('brdfs')
print(meta['elementsCount'])

PropertyRuntimeMeta meta = brdfVRayMtl.getPropertyRuntimeMeta("diffuse");
// Output of these will depend on what is applied to this parameter slot
cout << meta.getType() << " " << meta.getRuntimeType() << endl; // enum
cout << meta.getTypeAsString()<< " " << meta.getRuntimeTypeAsString() << endl;

// We can also check the size of lists from runtime meta information:
meta = brdfLayered.getPropertyRuntimeMeta("brdfs");
cout << meta.getRuntimeElementsCount() << endl;

// We can also check the size of lists from runtime meta information:
meta = brdfLayered.GetPropertyRuntimeMeta("brdfs");
Console.WriteLine(meta.ElementsCount);

var meta = brdfVRayMtl.getMeta('diffuse');
// Output of this will depend on what is applied to this parameter slot
console.log(meta.type, meta.runtimeType);

// We can also check the size of lists from runtime meta information:
meta = brdfLayered.getMeta('brdfs');
console.log(meta.elementsCount);

V-Ray sahne dosyası formatı #

V-Ray, metin tabanlı bir sahne dosyası formatı (.vrscene) kullanır. Oldukça basit olması, hata ayıklamayı ve elle değiştirmeyi kolaylaştırır. Format büyük/küçük harf duyarlıdır ve JSON’a biraz benzer. Geometri tanımları gibi büyük veri değerleri sıkıştırılabilir (ve metin olarak kodlanabilir). Dosya, ardışık eklenti örneği tanımlarını içerir: tür, örnek adı, parametre listesi. İç içe yerleştirme desteklenmez. Başlıca kurallar şunlardır:

Her eklenti örneği, tür adıyla başlayan, ardından bir boşluk, örnek adı, başka bir boşluk ve açılış küme paranteziyle devam eden yeni bir satırda tanımlanır.
Her parametre, adıyla, her iki tarafında boşluk bulunmayan bir eşittir işaretiyle ve değeriyle birlikte yeni bir satıra yazılır. Satır noktalı virgülle biter. Uzun, virgülle ayrılmış değerler (örneğin listeler) için parametre tanımlama satırı birden fazla satıra bölünebilir.
Diğer eklentilere yapılan referanslar, örnek adlarının tırnak işaretleri olmadan yazılmasıyla tanımlanır. Çıkış parametreleri de aynı şekilde, ek olarak çift nokta üst üste ve parametre adı (instance_name::out_param_name) ile belirtilir.
Eklenti tanımının sonu, yeni bir satırda kapanış paranteziyle işaretlenir.
C++ tarzı tek satırlık yorumlar desteklenmektedir.
Dosyalar, C dilinde olduğu gibi `#include “another.vrscene”` yönergesiyle bir araya getirilebilir.
Dosyanın ilerleyen kısımlarında tanımlanacak olan eklentilere atıfta bulunulabilir.
Ayrıştırıcı, girintilere ve boş satırlara kayıtsızdır. Tek kural, parametreler için değer atama operatörünün (=) etrafında boşluk olmamasıdır.

Sahne dosyaları V-Ray tarafından oluşturulmalıdır. Bunları kendiniz yazmaya çalışmamalısınız, ancak elbette bunları elle değiştirmekte özgürsünüz.

Şunu belirtmekte fayda var ki, eklenti örneklerinin tanımlanma sırası genellikle önemli değildir. Bu durum, bir sahneyi dosyaya dışa aktarmasanız bile, bellekte oluşturulan sahneler için de geçerlidir. Kamera ile ilgili ayarlar eklentileri gibi birkaç istisna vardır; V-Ray bunları belirli bir sırayla işlemezse doğru çalışmayabilirler.

Varsayılan değerler #

Her parametrenin varsayılan bir değeri vardır, bu nedenle “boş” bir eklenti örneği oluşturduktan sonra bile aslında tamamen işlevseldir. Elbette, örneğin geometri eklentilerinde olduğu gibi veriye ihtiyaç duyabilir, ancak bir ışık hemen çalışır (0 koordinatına yerleştirilir). Bununla birlikte, bazı eklentilerin neredeyse her zaman değiştirilmesi gereken sakıncalı varsayılan değerleri vardır (örneğin, görüntü örnekleyici ayarları veya bazı gölge parametreleri gibi bazı ayar eklentileri). V-Ray’de varsayılan değerleri genellikle değiştiremeyiz, çünkü bu mevcut kullanıcı sahnelerini bozar. Bununla birlikte, ne yaptığınızı bilmiyorsanız, varsayılan değerlere bağlı kalmanız önerilir. Elbette deneme yapabilirsiniz, ancak anlamadığınız değerleri kullanmayın, çünkü bunlar performans veya kalite sorunlarına yol açabilir veya fiziksel mantığı bile bozabilir. Bir vrscene dosyasını dışa aktardığınızda (kaydettiğinizde), bunları siz oluşturmamış olsanız bile her zaman bir sürü ayar eklentisi içereceğini unutmayın. Bunların varsayılan parametre değerleri olacaktır. V-Ray dosyaları her zaman bu şekilde kaydeder.

alt bölüm parametreleri #

Birçok ışık ve BRDF eklentisinde subdivs (alt bölümler) parametrelerini göreceksiniz . Bunlar, malzemeler üzerindeki parlak ve dağınık efektleri hesaplamak için oluşturulan yeni ışınların sayısını veya ışık ve gölge değerlendirmelerinin sayısını vb. kontrol eder. Gerçek ışın sayısı, parametre değerinin karesiyle orantılıdır. Bunlar, ilgili ışık veya malzeme için örneklemeyi artırmak veya azaltmak için kullanılabilir, ancak bunları varsayılan değerlerde bırakmanızı şiddetle tavsiye ederiz. Ayrıca yerel subdivs değerlerini tamamen devre dışı bırakmanızı da öneririz – ayrıntılar için Ayarlar dersine bakın. Bazı ayar eklentilerinde de, örneğin Işınım Haritası ve Işık Önbelleği gibi, değiştirilmesi sorun olmayan subdivs parametreleri bulunur.

Not: Oluşturucunun parametre değerinin karesini kullanmasının nedeni, Monte Carlo entegrasyon yönteminin gürültüyü (varyansı) yarıya indirmek (1/2 gürültü) için dört kat daha fazla örnek (4x) gerektiği, varyansın 1/10’unu elde etmek için ise 100 kat daha fazla örnek gerektiği özelliğidir. Bu şekilde, alt bölüm parametrelerindeki doğrusal artışlardan doğrusal sonuçlar elde ederiz.