From f1bb1bf572371c470b91ed48d4fd716a90c1d540 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Thu, 3 Sep 2020 16:18:52 +0200 Subject: [PATCH] Doc: Describe using uniforms in custom effects and materials Fixes: QDS-2723 Change-Id: Iea02261220026ab210fc82fb27ceee0277abb62d Reviewed-by: Miikka Heikkinen --- ...dio-custom-material-uniform-properties.png | Bin 0 -> 5647 bytes ...ignstudio-3d-custom-effects-materials.qdoc | 64 ++++++++++++++++-- 2 files changed, 58 insertions(+), 6 deletions(-) create mode 100644 doc/qtdesignstudio/images/studio-custom-material-uniform-properties.png diff --git a/doc/qtdesignstudio/images/studio-custom-material-uniform-properties.png b/doc/qtdesignstudio/images/studio-custom-material-uniform-properties.png new file mode 100644 index 0000000000000000000000000000000000000000..b69d4561829e98d0c28e20fc009aca5ec57bb9dd GIT binary patch literal 5647 zcmeAS@N?(olHy`uVBq!ia0y~yVA5e=U}WN8Vqjnhik41gU=Y3L>EaktaqI2f|NTqK z9oav4IdrPcI3~|hr+9Ok_4>Un>zo&CSyVG~ve>HSo3z8cw2QCgRqx#$TD*Lsg0q6S zfrpE)8CPDt6jkZmz%g`9AsmOAS6Ad3|r+#>$s>qQjdzm*4wvx<5az;(_n>`Bi_d z9{YVhzH3>`tvw$e%=TYD=U3;~-h@L(x%=Ze{_Xnm;r!lj zM^3HXJHN8RIPOi5N%0|Pzch%=xxu2i6FZ=hg``{z#?DDxWJKyq7&E4_#>-!3m8@oRD z+f~`kczMVs`A)N#Bnf#QbLrugTrJC*?!k z-&-cEep@!qOo*+{iOrLjHhKE(`RcpLzmHvgVe?vGnobMfhl@5WiJuqAR}`wYOR4+m zaV#iQ{Br2}I#&Do57+(Ue=pbndtrUe8+Q3$H{RF&+PVM#r|orbuG@c{sb8bav0Qxr z>&5rW|GVeeeg7!F_w(YjiXvZER>prl`tU=P`PI{7gXVvaZ-WtEI&*cP|(0ttnnvm{j<2&7Vh04%M#u@Y(6O`OB)=-xSX; zIL0*DbZXbxXERk~XBn;AQh0Tv-%@A&oUE;NTJNQ|*++RReu&amS#$f)k#DQ!rRc6@ zXSG%gP~fcje@||bT#&B6gjDt6lh<$CNUUV_$@ShevuXQwb?$9phgl}h)w4e6 zp`pK^c6HvCFb@$H;ZP4TDc-`};ajI)H+r_PtNk!{(pVV-0okvBgfund+Yc0r#l&QEG$}C%)4-h z@ZM`zCU3Jl+R3hPF?R>&aYysC?>-qmYr~V0X9=9TuH5oqN6Upn`(_B#+y6d&|KEN8 z`fuF!KUcrs{nPjTt$$yP|9`rg&n7(o_TOudFZ7a(J3cY~Dk+JHLMY+Bff3xO~mq=eG-6e47$_ay zyFc*SmV4QUzvPBJKU#UJ{{ml;wIAC-Mc#$2wXW5N=HLJM*nexh!S%YCs`Ga|f80{Y zzl;0(mR0-rPTG_IH|fxiuh+^KTGYOoCX#;dzjNQGy<0AEEPC0^sk>h-t?`XV;^R$2BBZu9a;Q zkc#Eoy?1S(osd*~;6=VZuHa+m=3Gg%h?#YN-+8;1wwKRX7ca7yRsHersf;O8o|G9C zbiGp0SvdX9Wu17guX1%3`#0S5IwfzaBh-JqYGX=vi-62t0j<*fquhT2m)<`UcXe6I z=e|R~)hT65q9 zA35)rjt>HQT0ZUDXj>GuNNI1He6A{Eu+9$67PYAGEALazui!ubc1N2<=DBAXhgcM+ zsK&_U7vKIaX(#NJw^dAO$-`9LmQM=vvn%m7IQM&L=MJ6nWj+kz=W~MI^`3cBOhN z^X0YkpT6C3_pa9`mBUNEh$Yzxak(45OuuRKlJ{f~$I;NzRFhRbEn3}6!fj8gJ8|^I zak$1`KlOXsi^Pgwf6~l%#?4h|IdybNckiq&T|41f39&zAcDFx>PHkO#a(lYZx+$wt z*9&NUedSnp-)4X9{A`X?=A{)n;j+h4Cs%!4fBcGojz^wygnoHCo=$p5{^zp#sp?vV%0A9e9xdA8yG+&|x*uMi9T>TbSxWtZ>% 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 fyza30Kl}31ohu(yuwPbP0l+XkKHdT_E literal 0 HcmV?d00001 diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-custom-effects-materials.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-custom-effects-materials.qdoc index b5d03d9fb90..7d98babad7f 100644 --- a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-custom-effects-materials.qdoc +++ b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-custom-effects-materials.qdoc @@ -32,16 +32,27 @@ \title Creating Custom Effects and Materials + The \l{Applying 3D Effects}{Qt Quick 3D Effects} and \l{Using 3D Materials} + {Qt Quick 3D Materials} modules contain a set of ready-made effects and + materials that you can apply to 3D models. If the ready-made effects and + materials don't meet your needs, you can create custom effects and + materials. Each effect or material must have a fragment shader that + implements all the functions needed to calculate the shaded color. The + material system also offers ready-made functions to help you implement + the material. + + The material system supports dielectric, metallic, and transparent + materials, point lights, area lights, ambient occlusion, shadowing, + two-sided polygons, index-of-refraction, and fragment cutoff (masking). + For more information, see \l {Qt Quick 3D Custom Material Reference}. + You can use the QML types in the \uicontrol {Qt Quick 3D Custom Shader Utils} tab of \uicontrol Library to create custom effects and materials. To make the \uicontrol Effect and \uicontrol {Custom Material} types appear in the tab, you must select \uicontrol {Add Import} in the \uicontrol {QML Imports} tab, and then select \uicontrol QtQuick3D.Effects and - \uicontrol QtQuick3D.Materials to import the QML types in the - \l{Qt Quick 3D Effects QML Types}{Qt Quick 3D Effects} and - \l{Qt Quick 3D Materials QML Types}{Qt Quick 3D Materials} modules to your - project. These modules contain a set of ready-made effects and materials - that you can apply to 3D models. + \uicontrol QtQuick3D.Materials to import the QML types in those modules to + your project. For more information about the shader utilities and commands and their properties, see \l {Using Custom Shaders}. @@ -50,7 +61,10 @@ \note You must create the actual shader source files with some other tool and copy them to your project folder. You can then specify the source file - names in the custom effect or material properties. + names in the custom effect or material properties. To use custom \e uniforms + in the shader files, you must specify them as QML properties for the custom + effect or material component. \QDS automatically generates the uniforms for + the shaders based on the property values. \section1 Creating Custom Effects @@ -160,4 +174,42 @@ \uicontrol Properties. \image studio-qtquick-3d-shader-properties.png "Shader properties" \endlist + + \section1 Creating Shader Files + + The requirements set for shaders that you can use in custom effects and + materials are described in \l {Qt Quick 3D Custom Material Reference}. + + If you use custom uniforms in the shader files, you must specify them + as QML properties for the custom effect or material component. \QDS + automatically generates the uniforms based on the property values. + + For example, the following code snippet shows fragment shader code that + uses two uniforms: \c uTextureInUse and \c uInputTexture. + + \code + out vec4 fragColor; + + in vec3 pos; + in vec3 texCoord0; + + void main() { + + vec4 textCol; + if (uTextureInUse) + textCol = texture( uInputTexture, texCoord0.xy ); + + fragColor = vec4(pos.x * 0.02 * textCol.x, pos.y * 0.02 * textCol.y, pos.z * 0.02, 1.0); + } + \endcode + + To use the above fragment shader in a custom effect or material component, + you must remove the uniforms from the shader code and define them as + properties for the component in \uicontrol {Connection View} > + \uicontrol Properties. + + \image studio-custom-material-uniform-properties.png "Uniforms as properties in Connection View Properties tab" + + For more information about adding properties, see + \l{Specifying Dynamic Properties}. */