diff --git a/BuildingOgre.md b/BuildingOgre.md index 8681246b6a2..b61fd662841 100644 --- a/BuildingOgre.md +++ b/BuildingOgre.md @@ -77,20 +77,27 @@ The optional dependencies will enable input handling and allow building the docu * SDL: https://www.libsdl.org/ * zlib: http://www.zlib.net * freetype: http://www.freetype.org +* googletest: https://github.com/google/googletest ### Optional dependencies * DirectX SDK: http://msdn.microsoft.com/en-us/directx/ * Vulkan SDK: https://vulkan.lunarg.com/ -* FreeImage: http://freeimage.sourceforge.net * Doxygen: http://doxygen.org -* Cg: http://developer.nvidia.com/object/cg_toolkit.html * Remotery: https://github.com/Celtoys/Remotery * SWIG: http://www.swig.org/ * %Assimp: https://www.assimp.org/ * Wayland: https://wayland.freedesktop.org/ +* Rust: https://www.rust-lang.org/ +* Bullet: https://pybullet.org/wordpress/ + +### Deprecated dependencies + +* FreeImage: http://freeimage.sourceforge.net +* Cg: http://developer.nvidia.com/object/cg_toolkit.html +* OpenEXR: http://www.openexr.com -Running CMake +Running CMake {#running-cmake} ------------- Now start the program cmake-gui by either typing the name in a console @@ -147,7 +154,7 @@ This will freshly generate the API documentation for Ogre's classes from the hea make OgreDoc -Installing +Installing {#installing-sdk} ---------- Once the build is complete, the libraries and headers must be copied to a clean location. @@ -177,8 +184,8 @@ The ogre port in vcpkg is kept up to date by Microsoft team members and communit # Cross-Compiling -Building on Ubuntu for Android --------------------------------------------- +Android +------- To build Ogre for Android, you need to specify the android cross toolchain to cmake as @@ -190,8 +197,8 @@ You can now import these projects in Android Studio or manually trigger the APK gradle assembleRelease -Building for WebAssembly (using Emscripten) ------------------------------------------ +WebAssembly / Emscripten +------------------------ Install the Emscripten SDK (see full documentation on [www.emscripten.org](https://emscripten.org/docs/getting_started/downloads.html)), and make sure that the environment variables are correctly set (eg. run `source /emsdk_env.sh` before attempting to build) @@ -207,8 +214,8 @@ This will not build the full SampleBrowser, but just a minimal Sample. The resul To prevent any cross-origin issues, start a local webserver as `python3 -m http.server 8000` and visit http://localhost:8000. -Building on Mac OS X for iOS OS -------------------------------- +iOS OS +------ To build Ogre for iOS, you need to specify the ios cross toolchain to cmake as @@ -233,8 +240,8 @@ the Info.plist file to match the App ID of the chosen code signing identity. This can be done from the Target Properties panel. It must match the bundle identifier of a valid developer certificate if you are building for devices. -Building as Windows Store or Windows Phone application -------------------------------------------------------------------- +WinRT / UWP +------------------------------ You need Windows 8.0 or later, Windows 10 is recommended. diff --git a/Docs/src/high-level-programs.md b/Docs/src/high-level-programs.md index ae4b635e9b2..3e64735d88b 100644 --- a/Docs/src/high-level-programs.md +++ b/Docs/src/high-level-programs.md @@ -227,7 +227,7 @@ The available varyings are: The following features are only available when using the legacy OpenGL profile. Notably they are not available with GL3+ or GLES2. ### OpenGL state -GLSL can access most of the GL states directly so you do not need to pass these states through [param\_named\_auto](#param_005fnamed_005fauto) in the material script. This includes lights, material state, and all the matrices used in the openGL state i.e. model view matrix, worldview projection matrix etc. +GLSL can access most of the GL states directly so you do not need to pass these states through [param_named_auto](#param_005fnamed_005fauto) in the material script. This includes lights, material state, and all the matrices used in the openGL state i.e. model view matrix, worldview projection matrix etc. ### Built-in attributes GLSL natively supports automatic binding of the most common incoming per-vertex attributes (e.g. `gl_Vertex`, `gl_Normal`, `gl_MultiTexCoord0` etc) @@ -557,11 +557,11 @@ At runtime, when myVertexProgram or myFragmentProgram are used, OGRE automatical Parameters can be specified using one of 4 commands as shown below. The same syntax is used whether you are defining a parameter just for this particular use of the program, or when specifying the @ref Default-Program-Parameters. Parameters set in the specific use of the program override the defaults. -- [param\_indexed](#param_005findexed) -- [param\_indexed\_auto](#param_005findexed_005fauto) -- [param\_named](#param_005fnamed) -- [param\_named\_auto](#param_005fnamed_005fauto) -- [shared\_params\_ref](#shared_005fparams_005fref) +- [param_indexed](#param_005findexed) +- [param_indexed_auto](#param_005findexed_005fauto) +- [param_named](#param_005fnamed) +- [param_named_auto](#param_005fnamed_005fauto) +- [shared_params_ref](#shared_005fparams_005fref) @@ -595,7 +595,7 @@ Format: param\_indexed\_auto <index> <autoConstType> <extraInfo&g Example: param\_indexed\_auto 0 worldviewproj\_matrix @param index -has the same meaning as [param\_indexed](#param_005findexed); note this time you do not have to specify the size of the parameter because the engine knows this already. In the example, the world/view/projection matrix is being used so this is implicitly a matrix4x4. +has the same meaning as [param_indexed](#param_005findexed); note this time you do not have to specify the size of the parameter because the engine knows this already. In the example, the world/view/projection matrix is being used so this is implicitly a matrix4x4. @param autoConstType, extraInfo is one of Ogre::GpuProgramParameters::AutoConstantType without the `ACT_` prefix. E.g. `ACT_WORLD_MATRIX` becomes `world_matrix`. @@ -623,7 +623,7 @@ Format: param\_named\_auto <name> <autoConstType> <extraInfo> @par Example: param\_named\_auto worldViewProj worldviewproj\_matrix -The allowed @c autoConstType and the meaning of @c extraInfo are detailed in [param\_indexed\_auto](#param_005findexed_005fauto). +The allowed @c autoConstType and the meaning of @c extraInfo are detailed in [param_indexed_auto](#param_005findexed_005fauto). @@ -649,7 +649,7 @@ shared_params YourSharedParamsName } ``` -As you can see, you need to use the keyword ’shared\_params’ and follow it with the name that you will use to identify these shared parameters. Inside the curly braces, you can define one parameter per line, in a way which is very similar to the [param\_named](#param_005fnamed) syntax. The definition of these lines is: +As you can see, you need to use the keyword ’shared\_params’ and follow it with the name that you will use to identify these shared parameters. Inside the curly braces, you can define one parameter per line, in a way which is very similar to the [param_named](#param_005fnamed) syntax. The definition of these lines is: @par Format: shared\_param\_named <param\_name> <param\_type> \[<\[array\_size\]>\] \[<initial\_values>\] @@ -658,7 +658,7 @@ Format: shared\_param\_named <param\_name> <param\_type> \[<\[arr @param array_size allows you to define arrays of param\_type should you wish, and if present must be a number enclosed in square brackets (and note, must be separated from the param\_type with whitespace). @param initial_values If you wish, you can also initialise the parameters by providing a list of values. -Once you have defined the shared parameters, you can reference them inside default\_params and params blocks using [shared\_params\_ref](#shared_005fparams_005fref). You can also obtain a reference to them in your code via Ogre::GpuProgramManager::getSharedParameters, and update the values for all instances using them. +Once you have defined the shared parameters, you can reference them inside default\_params and params blocks using [shared_params_ref](#shared_005fparams_005fref). You can also obtain a reference to them in your code via Ogre::GpuProgramManager::getSharedParameters, and update the values for all instances using them. ## Hardware Support diff --git a/Docs/src/manual.md b/Docs/src/manual.md index da7b04fc5d6..52054856ec0 100644 --- a/Docs/src/manual.md +++ b/Docs/src/manual.md @@ -391,7 +391,7 @@ mSceneMgr->setShadowTechnique(SHADOWTYPE_STENCIL_ADDITIVE); 2. Create one or more lights. Note that not all light types are necessarily supported by all shadow techniques, you should check the sections about each technique to check. Note that if certain lights should not cast shadows, you can turn that off by calling setCastShadows(false) on the light, the default is true. 3. Disable shadow casting on objects which should not cast shadows. Call setCastShadows(false) on objects you don’t want to cast shadows, the default for all objects is to cast shadows. 4. Configure shadow far distance. You can limit the distance at which shadows are considered for performance reasons, by calling Ogre::SceneManager::setShadowFarDistance. -5. Turn off the receipt of shadows on materials that should not receive them. You can turn off the receipt of shadows (note, not the casting of shadows - that is done per-object) by calling Material::setReceiveShadows or using the receive\_shadows material attribute. This is useful for materials which should be considered self-illuminated for example. Note that transparent materials are typically excluded from receiving and casting shadows, although see the [transparency\_casts\_shadows](#transparency_005fcasts_005fshadows) option for exceptions. +5. Turn off the receipt of shadows on materials that should not receive them. You can turn off the receipt of shadows (note, not the casting of shadows - that is done per-object) by calling Material::setReceiveShadows or using the receive\_shadows material attribute. This is useful for materials which should be considered self-illuminated for example. Note that transparent materials are typically excluded from receiving and casting shadows, although see the [transparency_casts_shadows](#transparency_005fcasts_005fshadows) option for exceptions. # Opting out of shadows {#Opting-out-of-shadows} diff --git a/Docs/src/material-scripts.md b/Docs/src/material-scripts.md index b778aaa805f..a57dd5017e6 100644 --- a/Docs/src/material-scripts.md +++ b/Docs/src/material-scripts.md @@ -90,7 +90,7 @@ Default: lod\_strategy distance_sphere ## lod\_values -This attribute defines the values used to control the LOD transition for this material. By setting this attribute, you indicate that you want this material to alter the Technique that it uses based on some metric, such as the distance from the camera, or the approximate screen space coverage. The exact meaning of these values is determined by the option you select for [lod\_strategy](#lod_005fstrategy) - it is a list of distances for the @c distance_sphere strategy, and a list of pixel counts for the @c pixel_count strategy, for example. You must give it a list of values, in order from highest LOD value to lowest LOD value, each one indicating the point at which the material will switch to the next LOD. All materials automatically activate LOD index 0 for values less than the first entry, so you don't have to explicitly specify this. Additionally, if there is no technique that matches the active LOD index, a technique with a lower LOD index will be used instead. Therefore, it is important to always have at least one technique with LOD index 0. +This attribute defines the values used to control the LOD transition for this material. By setting this attribute, you indicate that you want this material to alter the Technique that it uses based on some metric, such as the distance from the camera, or the approximate screen space coverage. The exact meaning of these values is determined by the option you select for [lod_strategy](#lod_005fstrategy) - it is a list of distances for the @c distance_sphere strategy, and a list of pixel counts for the @c pixel_count strategy, for example. You must give it a list of values, in order from highest LOD value to lowest LOD value, each one indicating the point at which the material will switch to the next LOD. All materials automatically activate LOD index 0 for values less than the first entry, so you don't have to explicitly specify this. Additionally, if there is no technique that matches the active LOD index, a technique with a lower LOD index will be used instead. Therefore, it is important to always have at least one technique with LOD index 0. @par Format: lod\_values <value0> <value1> <value2> ... @@ -106,7 +106,7 @@ The above example would cause the material to use the best Technique at lod\_ind ## lod\_distances -@deprecated This option is deprecated in favour of [lod\_values](#lod_005fvalues) now. +@deprecated This option is deprecated in favour of [lod_values](#lod_005fvalues) now. @@ -148,7 +148,7 @@ A "technique" section in your material script encapsulates a single method of re When a material is used for the first time, it is ’compiled’. That involves scanning the techniques which have been defined, and marking which of them are supportable using the current rendering API and graphics card. If no techniques are supportable, your material will render as blank white. The compilation examines a number of things, such as: -- The number of texture\_unit entries in each pass
Note that if the number of texture\_unit entries exceeds the number of texture units in the current graphics card, the technique may still be supportable so long as a fragment program is not being used. In this case, Ogre will split the pass which has too many entries into multiple passes for the less capable card, and the multitexture blend will be turned into a multipass blend (See [colour\_op\_multipass\_fallback](#colour_005fop_005fmultipass_005ffallback)). +- The number of texture\_unit entries in each pass
Note that if the number of texture\_unit entries exceeds the number of texture units in the current graphics card, the technique may still be supportable so long as a fragment program is not being used. In this case, Ogre will split the pass which has too many entries into multiple passes for the less capable card, and the multitexture blend will be turned into a multipass blend (See [colour_op_multipass_fallback](#colour_005fop_005fmultipass_005ffallback)). - Whether vertex, geometry or fragment programs are used, and if so which syntax they use (e.g. vs\_1\_1, ps\_2\_x, arbfp1 etc.) - Other effects like cube mapping and dot3 blending - Whether the vendor or device name of the current graphics card matches some user-specified rules @@ -165,11 +165,11 @@ Format: technique name Techniques have only a small number of attributes of their own: - [scheme](#scheme) -- [lod\_index](#lod_005findex) (and also see [lod\_distances](#lod_005fdistances) in the parent material) -- [shadow\_caster\_material](#shadow_005fcaster_005fmaterial) -- [shadow\_receiver\_material](#shadow_005freceiver_005fmaterial) -- [gpu\_vendor\_rule](#gpu_005fvendor_005frule) -- [gpu\_device\_rule](#gpu_005fdevice_005frule) +- [lod_index](#lod_005findex) (and also see [lod_distances](#lod_005fdistances) in the parent material) +- [shadow_caster_material](#shadow_005fcaster_005fmaterial) +- [shadow_receiver_material](#shadow_005freceiver_005fmaterial) +- [gpu_vendor_rule](#gpu_005fvendor_005frule) +- [gpu_device_rule](#gpu_005fdevice_005frule) @@ -260,37 +260,37 @@ Here are the attributes you can use in a ’pass’ section of a .material scrip - [diffuse](#diffuse) - [specular](#specular) - [emissive](#emissive) -- [scene\_blend](#scene_005fblend) -- [separate\_scene\_blend](#separate_005fscene_005fblend) -- [scene\_blend\_op](#scene_005fblend_005fop) -- [separate\_scene\_blend\_op](#separate_005fscene_005fblend_005fop) -- [depth\_check](#depth_005fcheck) -- [depth\_write](#depth_005fwrite) -- [depth\_func](#depth_005ffunc) -- [depth\_bias](#depth_005fbias) -- [iteration\_depth\_bias](#iteration_005fdepth_005fbias) -- [alpha\_rejection](#alpha_005frejection) -- [alpha\_to\_coverage](#alpha_005fto_005fcoverage) -- [light\_scissor](#light_005fscissor) -- [light\_clip\_planes](#light_005fclip_005fplanes) -- [illumination\_stage](#illumination_005fstage) -- [transparent\_sorting](#transparent_005fsorting) -- [cull\_hardware](#cull_005fhardware) -- [cull\_software](#cull_005fsoftware) +- [scene_blend](#scene_005fblend) +- [separate_scene_blend](#separate_005fscene_005fblend) +- [scene_blend_op](#scene_005fblend_005fop) +- [separate_scene_blend_op](#separate_005fscene_005fblend_005fop) +- [depth_check](#depth_005fcheck) +- [depth_write](#depth_005fwrite) +- [depth_func](#depth_005ffunc) +- [depth_bias](#depth_005fbias) +- [iteration_depth_bias](#iteration_005fdepth_005fbias) +- [alpha_rejection](#alpha_005frejection) +- [alpha_to_coverage](#alpha_005fto_005fcoverage) +- [light_scissor](#light_005fscissor) +- [light_clip_planes](#light_005fclip_005fplanes) +- [illumination_stage](#illumination_005fstage) +- [transparent_sorting](#transparent_005fsorting) +- [cull_hardware](#cull_005fhardware) +- [cull_software](#cull_005fsoftware) - [lighting](#lighting) - [shading](#shading) -- [polygon\_mode](#polygon_005fmode) -- [polygon\_mode\_overrideable](#polygon_005fmode_005foverrideable) -- [fog\_override](#fog_005foverride) -- [colour\_write](#colour_005fwrite) -- [max\_lights](#max_005flights) -- [start\_light](#start_005flight) +- [polygon_mode](#polygon_005fmode) +- [polygon_mode_overrideable](#polygon_005fmode_005foverrideable) +- [fog_override](#fog_005foverride) +- [colour_write](#colour_005fwrite) +- [max_lights](#max_005flights) +- [start_light](#start_005flight) - [iteration](#iteration) -- [point\_size](#point_005fsize) -- [point\_sprites](#point_005fsprites) -- [point\_size\_attenuation](#point_005fsize_005fattenuation) -- [point\_size\_min](#point_005fsize_005fmin) -- [point\_size\_max](#point_005fsize_005fmax) +- [point_size](#point_005fsize) +- [point_sprites](#point_005fsprites) +- [point_size_attenuation](#point_005fsize_005fattenuation) +- [point_size_min](#point_005fsize_005fmin) +- [point_size_max](#point_005fsize_005fmax) - [line_width](#line_width) @@ -419,25 +419,25 @@ Example: scene\_blend one one\_minus\_dest\_alpha @par Default: scene\_blend one zero (opaque) -Also see [separate\_scene\_blend](#separate_005fscene_005fblend). +Also see [separate_scene_blend](#separate_005fscene_005fblend). ## separate\_scene\_blend -This option operates in exactly the same way as [scene\_blend](#scene_005fblend), except that it allows you to specify the operations to perform between the rendered pixel and the frame buffer separately for colour and alpha components. By nature this option is only useful when rendering to targets which have an alpha channel which you’ll use for later processing, such as a render texture. +This option operates in exactly the same way as [scene_blend](#scene_005fblend), except that it allows you to specify the operations to perform between the rendered pixel and the frame buffer separately for colour and alpha components. By nature this option is only useful when rendering to targets which have an alpha channel which you’ll use for later processing, such as a render texture. @par Format1: separate\_scene\_blend <simple\_colour\_blend> <simple\_alpha\_blend> @par Example: separate\_scene\_blend add modulate -This example would add colour components but multiply alpha components. The blend modes available are as in [scene\_blend](#scene_005fblend). The more advanced form is also available: +This example would add colour components but multiply alpha components. The blend modes available are as in [scene_blend](#scene_005fblend). The more advanced form is also available: @par Format2: separate\_scene\_blend <colour\_src\_factor> <colour\_dest\_factor> <alpha\_src\_factor> <alpha\_dest\_factor> @par Example: separate\_scene\_blend one one\_minus\_dest\_alpha one one -Again the options available in the second format are the same as those in the second format of [scene\_blend](#scene_005fblend). +Again the options available in the second format are the same as those in the second format of [scene_blend](#scene_005fblend). @@ -457,7 +457,9 @@ You may change this to ’add’, ’subtract’, ’reverse_subtract’, ’min This directive is as scene\_blend\_op, except that you can set the operation for colour and alpha separately. @par -Format: separate\_scene\_blend\_op <colourOp> <alphaOp> Default: separate\_scene\_blend\_op add add +Format: separate\_scene\_blend\_op <colourOp> <alphaOp> +@par +Default: separate\_scene\_blend\_op add add @@ -510,13 +512,13 @@ Format: depth\_bias <constantBias> \[<slopeScaleBias>\] @copydetails Ogre::Pass::setDepthBias -Also see [iteration\_depth\_bias](#iteration_005fdepth_005fbias) +Also see [iteration_depth_bias](#iteration_005fdepth_005fbias) ## iteration\_depth\_bias -Sets an additional bias derived from the number of times a given pass has been iterated. Operates just like [depth\_bias](#depth_005fbias) except that it applies an additional bias factor to the base depth\_bias value, multiplying the provided value by the number of times this pass has been iterated before, through one of the [iteration](#iteration) variants. So the first time the pass will get the depth\_bias value, the second time it will get depth\_bias + iteration\_depth\_bias, the third time it will get depth\_bias + iteration\_depth\_bias \* 2, and so on. The default is zero. +Sets an additional bias derived from the number of times a given pass has been iterated. Operates just like [depth_bias](#depth_005fbias) except that it applies an additional bias factor to the base depth\_bias value, multiplying the provided value by the number of times this pass has been iterated before, through one of the [iteration](#iteration) variants. So the first time the pass will get the depth\_bias value, the second time it will get depth\_bias + iteration\_depth\_bias, the third time it will get depth\_bias + iteration\_depth\_bias \* 2, and so on. The default is zero. @par Format: iteration\_depth\_bias <bias\_per\_iteration> @@ -670,7 +672,7 @@ Default: polygon\_mode solid ## polygon\_mode\_overrideable -Sets whether or not the [polygon\_mode](#polygon_005fmode) set on this pass can be downgraded by the camera +Sets whether or not the [polygon_mode](#polygon_005fmode) set on this pass can be downgraded by the camera @par Format: polygon\_mode\_overrideable <override> @@ -921,7 +923,7 @@ Default: point\_size\_attenuation off ## point\_size\_min -Sets the minimum point size after attenuation ([point\_size\_attenuation](#point_005fsize_005fattenuation)). For details on the size metrics, See [point\_size](#point_005fsize). +Sets the minimum point size after attenuation ([point_size_attenuation](#point_005fsize_005fattenuation)). For details on the size metrics, See [point_size](#point_005fsize). @par Format: point\_size\_min <size> @par @@ -931,7 +933,7 @@ Default: point\_size\_min 0 ## point\_size\_max -Sets the maximum point size after attenuation ([point\_size\_attenuation](#point_005fsize_005fattenuation)). For details on the size metrics, See [point\_size](#point_005fsize). A value of 0 means the maximum is set to the same as the max size reported by the current card. +Sets the maximum point size after attenuation ([point_size_attenuation](#point_005fsize_005fattenuation)). For details on the size metrics, See [point_size](#point_005fsize). A value of 0 means the maximum is set to the same as the max size reported by the current card. @par Format: point\_size\_max <size> @par @@ -954,24 +956,24 @@ Here are the attributes you can use in a @c texture_unit section of a .material ## Available Texture Unit Attributes -- [texture\_alias](#texture_005falias) +- [texture_alias](#texture_005falias) - [texture](#texture) -- [anim\_texture](#anim_005ftexture) -- [cubic\_texture](#cubic_005ftexture) -- [tex\_coord\_set](#tex_005fcoord_005fset) -- [colour\_op](#colour_005fop) -- [colour\_op\_ex](#colour_005fop_005fex) -- [colour\_op\_multipass\_fallback](#colour_005fop_005fmultipass_005ffallback) -- [alpha\_op\_ex](#alpha_005fop_005fex) -- [env\_map](#env_005fmap) +- [anim_texture](#anim_005ftexture) +- [cubic_texture](#cubic_005ftexture) +- [tex_coord_set](#tex_005fcoord_005fset) +- [colour_op](#colour_005fop) +- [colour_op_ex](#colour_005fop_005fex) +- [colour_op_multipass_fallback](#colour_005fop_005fmultipass_005ffallback) +- [alpha_op_ex](#alpha_005fop_005fex) +- [env_map](#env_005fmap) - [scroll](#scroll) -- [scroll\_anim](#scroll_005fanim) +- [scroll_anim](#scroll_005fanim) - [rotate](#rotate) -- [rotate\_anim](#rotate_005fanim) +- [rotate_anim](#rotate_005fanim) - [scale](#scale) -- [wave\_xform](#wave_005fxform) +- [wave_xform](#wave_005fxform) - [transform](#transform) -- [content\_type](#content_005ftype) +- [content_type](#content_005ftype) - [sampler_ref](#sampler_ref) - [unordered_access_mip](#unordered_access_mip) @@ -1096,7 +1098,7 @@ This is no longer supported and behaves like combinedUVW. ## content_type -Tells this texture unit where it should get its content from. The default is to get texture content from a named texture, as defined with the [texture](#texture), [cubic\_texture](#cubic_005ftexture), [anim\_texture](#anim_005ftexture) attributes. However you can also pull texture information from other automated sources. +Tells this texture unit where it should get its content from. The default is to get texture content from a named texture, as defined with the [texture](#texture), [cubic_texture](#cubic_005ftexture), [anim_texture](#anim_005ftexture) attributes. However you can also pull texture information from other automated sources. @par Format: content\_type <type> \[<compositorName>\] \[<textureName>\] \[<mrtIndex>\] @@ -1113,7 +1115,7 @@ This option allows you to pull in a shadow texture, and is only valid when you u
compositor
-@copybrief Ogre::TextureUnitState::CONTENT_COMPOSITOR This can be either in a render\_scene directive inside a compositor script, or in a general pass in a viewport that has a compositor attached. Note that this is a reference only, meaning that it does not change the render order. You must make sure that the order is reasonable for what you are trying to achieve (for example, texture pooling might cause the referenced texture to be overwritten by something else by the time it is referenced). +@copybrief Ogre::TextureUnitState::CONTENT_COMPOSITOR This can be either in a @c render_scene directive inside a compositor script, or in a general pass in a viewport that has a compositor attached. Note that this is a reference only, meaning that it does not change the render order. You must make sure that the order is reasonable for what you are trying to achieve (for example, texture pooling might cause the referenced texture to be overwritten by something else by the time it is referenced).
@@ -1399,10 +1401,10 @@ sampler mySampler ## Available parameters - [filtering](#filtering) -- [max\_anisotropy](#max_005fanisotropy) -- [tex\_address\_mode](#tex_005faddress_005fmode) -- [tex\_border\_colour](#tex_005fborder_005fcolour) -- [mipmap\_bias](#mipmap_005fbias) +- [max_anisotropy](#max_005fanisotropy) +- [tex_address_mode](#tex_005faddress_005fmode) +- [tex_border_colour](#tex_005fborder_005fcolour) +- [mipmap_bias](#mipmap_005fbias) - [compare_test](#compare_test) - [comp_func](#comp_func) @@ -1423,7 +1425,7 @@ Default: tex\_address\_mode wrap ## tex\_border\_colour -Sets the border colour of border texture address mode (see [tex\_address\_mode](#tex_005faddress_005fmode)). +Sets the border colour of border texture address mode (see [tex_address_mode](#tex_005faddress_005fmode)). @par Format: tex\_border\_colour <red> <green> <blue> \[<alpha>\]
NB valid colour values are between 0.0 and 1.0. @par diff --git a/Docs/src/particle-scripts.md b/Docs/src/particle-scripts.md index 34c984c3fc7..98bc8645172 100644 --- a/Docs/src/particle-scripts.md +++ b/Docs/src/particle-scripts.md @@ -18,24 +18,24 @@ This section describes to attributes which you can set on every particle system - [quota](#quota) - [material](#particle_005fmaterial) -- [particle\_width](#particle_005fwidth) -- [particle\_height](#particle_005fheight) -- [cull\_each](#cull_005feach) +- [particle_width](#particle_005fwidth) +- [particle_height](#particle_005fheight) +- [cull_each](#cull_005feach) - [renderer](#particle_005frenderer) - [sorted](#particle_005fsorted) -- [local\_space](#particle_005flocalspace) -- [iteration\_interval](#iteration_005finterval) -- [nonvisible\_update\_timeout](#nonvisible_005fupdate_005ftimeout) +- [local_space](#particle_005flocalspace) +- [iteration_interval](#iteration_005finterval) +- [nonvisible_update_timeout](#nonvisible_005fupdate_005ftimeout) @par Billboard Renderer Attributes -- [billboard\_type](#billboard_005ftype) -- [billboard\_origin](#billboard_005forigin) -- [billboard\_rotation\_type](#billboard_005frotation_005ftype) -- [common\_direction](#common_005fdirection) -- [common\_up\_vector](#common_005fup_005fvector) -- [point\_rendering](#particle_005fpoint_005frendering) -- [accurate\_facing](#particle_005faccurate_005ffacing) +- [billboard_type](#billboard_005ftype) +- [billboard_origin](#billboard_005forigin) +- [billboard_rotation_type](#billboard_005frotation_005ftype) +- [common_direction](#common_005fdirection) +- [common_up_vector](#common_005fup_005fvector) +- [point_rendering](#particle_005fpoint_005frendering) +- [accurate_facing](#particle_005faccurate_005ffacing) @see @ref Particle-Emitters @see @ref Particle-Affectors @@ -144,7 +144,7 @@ The default arrangement, this approximates spherical particles and the billboard
oriented\_common
-Particles are oriented around a common, typically fixed direction vector (see [common\_direction](#common_005fdirection)), which acts as their local Y axis. The billboard rotates only around this axis, giving the particle some sense of direction. Good for rainstorms, starfields etc where the particles will traveling in one direction - this is slightly faster than oriented\_self (see below). +Particles are oriented around a common, typically fixed direction vector (see [common_direction](#common_005fdirection)), which acts as their local Y axis. The billboard rotates only around this axis, giving the particle some sense of direction. Good for rainstorms, starfields etc where the particles will traveling in one direction - this is slightly faster than oriented\_self (see below).
oriented\_self
@@ -152,11 +152,11 @@ Particles are oriented around their own direction vector, which acts as their lo
perpendicular\_common
-Particles are perpendicular to a common, typically fixed direction vector (see [common\_direction](#common_005fdirection)), which acts as their local Z axis, and their local Y axis coplanar with common direction and the common up vector (see [common\_up\_vector](#common_005fup_005fvector)). The billboard never rotates to face the camera, you might use double-side material to ensure particles never culled by back-facing. Good for aureolas, rings etc where the particles will perpendicular to the ground - this is slightly faster than perpendicular\_self (see below). +Particles are perpendicular to a common, typically fixed direction vector (see [common_direction](#common_005fdirection)), which acts as their local Z axis, and their local Y axis coplanar with common direction and the common up vector (see [common_up_vector](#common_005fup_005fvector)). The billboard never rotates to face the camera, you might use double-side material to ensure particles never culled by back-facing. Good for aureolas, rings etc where the particles will perpendicular to the ground - this is slightly faster than perpendicular\_self (see below).
perpendicular\_self
-Particles are perpendicular to their own direction vector, which acts as their local Z axis, and their local Y axis coplanar with their own direction vector and the common up vector (see [common\_up\_vector](#common_005fup_005fvector)). The billboard never rotates to face the camera, you might use double-side material to ensure particles never culled by back-facing. Good for rings stack etc where the particles will perpendicular to their traveling direction. +Particles are perpendicular to their own direction vector, which acts as their local Z axis, and their local Y axis coplanar with their own direction vector and the common up vector (see [common_up_vector](#common_005fup_005fvector)). The billboard never rotates to face the camera, you might use double-side material to ensure particles never culled by back-facing. Good for rings stack etc where the particles will perpendicular to their traveling direction.
@@ -191,7 +191,7 @@ Billboard particles will rotate the texture coordinates to according with partic ### common\_direction -Only required if [billboard\_type](#billboard_005ftype) is set to oriented\_common or perpendicular\_common, this vector is the common direction vector used to orient all particles in the system. +Only required if [billboard_type](#billboard_005ftype) is set to oriented\_common or perpendicular\_common, this vector is the common direction vector used to orient all particles in the system. format: common\_direction <x> <y> <z>
example: common\_direction 0 -1 0
default: 0 0 1
@@ -199,7 +199,7 @@ format: common\_direction <x> <y> <z>
example: common\_dir ### common\_up\_vector -Only required if [billboard\_type](#billboard_005ftype) is set to perpendicular\_self or perpendicular\_common, this vector is the common up vector used to orient all particles in the system. +Only required if [billboard_type](#billboard_005ftype) is set to perpendicular\_self or perpendicular\_common, this vector is the common up vector used to orient all particles in the system. format: common\_up\_vector <x> <y> <z>
example: common\_up\_vector 0 1 0
default: 0 1 0
@@ -260,24 +260,24 @@ This section describes the common attributes of all particle emitters. Specific - [angle](#angle) - [colour](#colour) -- [colour\_range\_start](#colour_005frange_005fstart) -- [colour\_range\_end](#colour_005frange_005fend) +- [colour_range_start](#colour_005frange_005fstart) +- [colour_range_end](#colour_005frange_005fend) - [direction](#direction) -- [direction\_position\_reference](#direction_005fposition_005freference) -- [emission\_rate](#emission_005frate) +- [direction_position_reference](#direction_005fposition_005freference) +- [emission_rate](#emission_005frate) - [position](#position) - [velocity](#velocity) -- [velocity\_min](#velocity_005fmin) -- [velocity\_max](#velocity_005fmax) -- [time\_to\_live](#time_005fto_005flive) -- [time\_to\_live\_min](#time_005fto_005flive_005fmin) -- [time\_to\_live\_max](#time_005fto_005flive_005fmax) +- [velocity_min](#velocity_005fmin) +- [velocity_max](#velocity_005fmax) +- [time_to_live](#time_005fto_005flive) +- [time_to_live_min](#time_005fto_005flive_005fmin) +- [time_to_live_max](#time_005fto_005flive_005fmax) - [duration](#duration) -- [duration\_min](#duration_005fmin) -- [duration\_max](#duration_005fmax) -- [repeat\_delay](#repeat_005fdelay) -- [repeat\_delay\_min](#repeat_005fdelay_005fmin) -- [repeat\_delay\_max](#repeat_005fdelay_005fmax) +- [duration_min](#duration_005fmin) +- [duration_max](#duration_005fmax) +- [repeat_delay](#repeat_005fdelay) +- [repeat_delay_min](#repeat_005fdelay_005fmin) +- [repeat_delay_max](#repeat_005fdelay_005fmax) @@ -371,7 +371,7 @@ format: as time\_to\_live
example:
    time\_to\_live\_min 2
  ## duration -Sets the number of seconds the emitter is active. The emitter can be started again, see [repeat\_delay](#repeat_005fdelay). +Sets the number of seconds the emitter is active. The emitter can be started again, see [repeat_delay](#repeat_005fdelay). See also the duration\_min and duration\_max attributes which let you set a duration range instead of a fixed one. format: duration <seconds>
example:
    duration 2.5
default: 0

diff --git a/Docs/src/scripts.md b/Docs/src/scripts.md index 8c39bca6875..e02795f459b 100644 --- a/Docs/src/scripts.md +++ b/Docs/src/scripts.md @@ -279,7 +279,7 @@ As Target, but this is the single final result of all operations. The size and p
Target Section
-A Target may be rendered to many times in the course of a composition effect. In particular if you ’ping pong’ a convolution between a couple of textures, you will have more than one Target Sections per Target. Target Sections are declared in the script using a [target or target\_output line](#Compositor-Target-Passes), the latter being the final output of which there can be only one. +A Target may be rendered to many times in the course of a composition effect. In particular if you ’ping pong’ a convolution between a couple of textures, you will have more than one Target Sections per Target. Target Sections are declared in the script using a [target or target_output line](#Compositor-Target-Passes), the latter being the final output of which there can be only one. @note Internally this is referred to as Ogre::CompositionTargetPass
Pass
@@ -315,11 +315,11 @@ Format: technique { } Techniques can have the following nested elements: - [texture](#compositor-texture) -- [texture\_ref](#compositor_005ftexture_005fref) +- [texture_ref](#compositor_005ftexture_005fref) - [scheme](#compositor_005fscheme) -- [compositor\_logic](#compositor_005flogic) +- [compositor_logic](#compositor_005flogic) - [target](#Compositor-Target-Passes) -- [target\_output](#Compositor-Target-Passes) +- [target_output](#Compositor-Target-Passes) @@ -368,7 +368,7 @@ When present, this directive has to be followed by an integer. This directive is - Ignored with depth pixel formats. @param scope -If present, this directive sets the scope for the texture for being accessed by other compositors using the [texture\_ref](#compositor_005ftexture_005fref) directive. There are three options : +If present, this directive sets the scope for the texture for being accessed by other compositors using the [texture_ref](#compositor_005ftexture_005fref) directive. There are three options: 1. @c local_scope (which is also the default) means that only the compositor defining the texture can access it. 2. @c chain_scope means that the compositors after this compositor in the chain can reference its textures, and 3. @c global_scope means that the entire application can access the texture. This directive also affects the creation of the textures (global textures are created once and thus can’t be used with the pooled directive, and can’t rely on viewport size). @@ -451,9 +451,9 @@ Note, the target entry can refer to @ref Cube-map-textures. Therefore, it takes Here are the attributes you can use in a ’target’ or ’target\_output’ section of a .compositor script: - [input](#compositor_005ftarget_005finput) -- [only\_initial](#only_005finitial) -- [visibility\_mask](#visibility_005fmask) -- [lod\_bias](#compositor_005flod_005fbias) +- [only_initial](#only_005finitial) +- [visibility_mask](#visibility_005fmask) +- [lod_bias](#compositor_005flod_005fbias) - [material_scheme](#material_005fscheme) - [shadows](#compositor_005fshadows) @@ -546,7 +546,7 @@ This kind of pass configures stencil operations for the subsequent passes. It ca
render\_scene
-This kind of pass performs a regular rendering of the scene. It will use the [visibility\_mask](#visibility_005fmask), [lod\_bias](#compositor_005flod_005fbias), and [material\_scheme](#material_005fscheme) from the parent target pass. +This kind of pass performs a regular rendering of the scene. It will use the [visibility_mask](#visibility_005fmask), [lod_bias](#compositor_005flod_005fbias), and [material_scheme](#material_005fscheme) from the parent target pass.
render\_quad
@@ -641,9 +641,9 @@ Format: thread_groups <groups_x> <groups_y> <groups_z> Here are the attributes you can use in a @c render_scene section of a .compositor script: -- [first\_render\_queue](#first_005frender_005fqueue) -- [last\_render\_queue](#last_005frender_005fqueue) -- [material\_scheme](#compositor_005fpass_005fmaterial_005fscheme) +- [first_render_queue](#first_005frender_005fqueue) +- [last_render_queue](#last_005frender_005fqueue) +- [material_scheme](#compositor_005fpass_005fmaterial_005fscheme) - [camera](#camera) @@ -699,9 +699,9 @@ Format: pass clear { } Here are the attributes you can use in a ’clear’ section of a .compositor script: - [buffers](#compositor_005fclear_005fbuffers) -- [colour\_value](#compositor_005fclear_005fcolour_005fvalue) -- [depth\_value](#compositor_005fclear_005fdepth_005fvalue) -- [stencil\_value](#compositor_005fclear_005fstencil_005fvalue) +- [colour_value](#compositor_005fclear_005fcolour_005fvalue) +- [depth_value](#compositor_005fclear_005fdepth_005fvalue) +- [stencil_value](#compositor_005fclear_005fstencil_005fvalue) ### buffers @@ -756,13 +756,13 @@ Format: pass stencil { } Here are the attributes you can use in a ’stencil’ section of a .compositor script: - [check](#compositor_005fstencil_005fcheck) -- [comp\_func](#compositor_005fstencil_005fcomp_005ffunc) -- [ref\_value](#compositor_005fstencil_005fref_005fvalue) +- [comp_func](#compositor_005fstencil_005fcomp_005ffunc) +- [ref_value](#compositor_005fstencil_005fref_005fvalue) - [mask](#compositor_005fstencil_005fmask) -- [fail\_op](#compositor_005fstencil_005ffail_005fop) -- [depth\_fail\_op](#compositor_005fstencil_005fdepth_005ffail_005fop) -- [pass\_op](#compositor_005fstencil_005fpass_005fop) -- [two\_sided](#compositor_005fstencil_005ftwo_005fsided) +- [fail_op](#compositor_005fstencil_005ffail_005fop) +- [depth_fail_op](#compositor_005fstencil_005fdepth_005ffail_005fop) +- [pass_op](#compositor_005fstencil_005fpass_005fop) +- [two_sided](#compositor_005fstencil_005ftwo_005fsided) ### check @@ -967,9 +967,9 @@ Must be a name unique among all other elements / containers by which to identify The properties which can be included within the braces depend on the custom type. However the following are always valid: -- [metrics\_mode](#metrics_005fmode) -- [horz\_align](#horz_005falign) -- [vert\_align](#vert_005falign) +- [metrics_mode](#metrics_005fmode) +- [horz_align](#horz_005falign) +- [vert_align](#vert_005falign) - [left](#left) - [top](#overlaytopelement) - [width](#width) @@ -1228,7 +1228,7 @@ This is a slightly more advanced version of Panel, where instead of just a singl ## TextArea (element) {#TextArea} -This is a generic element that you can use to render text. It uses fonts which can be defined in code using the FontManager and Font classes, or which have been predefined in .fontdef files. See the font definitions section for more information. +This is a generic element that you can use to render text. It uses fonts which can be defined in code using the Ogre::FontManager and0Ogre:: Font classes, or which have been predefined in @c .fontdef files. See the font definitions section for more information. @param font\_name <name> The name of the font to use. This font must be defined in a .fontdef file to ensure it is available at scripting time. @@ -1270,16 +1270,16 @@ font # Using an existing font texture -If you have one or more artists working with you, no doubt they can produce you a very nice font texture. OGRE supports full colour font textures, or alternatively you can keep them monochrome / greyscale and use TextArea’s colouring feature. Font textures should always have an alpha channel, preferably an 8-bit alpha channel such as that supported by TGA and PNG files, because it can result in much nicer edges. To use an existing texture, here are the settings you need: +If you have one or more artists working with you, no doubt they can produce you a very nice font texture. OGRE supports full colour font textures, or alternatively you can keep them monochrome / greyscale and use the colouring feature of Ogre::TextAreaOverlayElement. Font textures should always have an alpha channel, preferably an 8-bit alpha channel such as that supported by TGA and PNG files, because it can result in much nicer edges. To use an existing texture, here are the settings you need: @param type image This just tells OGRE you want a pre-drawn font. @param source <filename> This is the name of the image file you want to load. This will be loaded from the standard resource locations and can be of any type OGRE supports, although JPEG is not recommended because of the lack of alpha and the lossy compression. I recommend PNG format which has both good lossless compression and an 8-bit alpha channel. @param glyph <character> <u1> <v1> <u2> <v2> This provides the texture coordinates for the specified character. You must repeat this for every character you have in the texture. The first 2 numbers are the x and y of the top-left corner, the second two are the x and y of the bottom-right corner. Note that you really should use a common height for all characters, but widths can vary because of proportional fonts. -’character’ is either an ASCII character for non-extended 7-bit ASCII, or for extended glyphs, a unicode decimal value, which is identified by preceding the number with a ’u’ - e.g. ’u0546’ denotes unicode value 546. +’character’ is either an ASCII character for non-extended 7-bit ASCII, or for extended glyphs, a unicode decimal value, which is identified by preceding the number with a ’u’ - e.g. @c u0546 denotes unicode value 546. -A note for Windows users: I recommend using [BitmapFontBuilder](), a free tool which will generate a texture and export character widths for you, you can find a tool for converting the binary output from this into ’glyph’ lines in the Tools folder.
+You can use [font2bitmap](https://stmn.github.io/font2bitmap/), a web tool which will generate a texture for you. You will still have to manually create the @c glyph entries, but it will give you a good starting point. @@ -1299,4 +1299,4 @@ Here are the attributes you need to supply: @param code\_points nn-nn \[nn-nn\] .. This directive allows you to specify which unicode code points should be generated as glyphs into the font texture. If you don’t specify this, code points 32-126 will be generated by default which covers the ASCII glyphs. If you use this flag, you should specify a space-separated list of inclusive code point ranges of the form ’start-end’. Numbers must be decimal. -You can also create new fonts at runtime by using the FontManager if you wish. +You can also create new fonts at runtime by using the Ogre::FontManager if you wish.