game engine render properties documentation #50589

New Issue

bill auger · 2017-02-04T09:04:33+01:00

bill auger commented

2017-02-04 09:04:33 +01:00

patch -->
manual-game_engine-settings-render.diff

the screenshots currently on this page are from a prior version and do not reflect the current version:

updated image: images/bge_camera_properties.png

replaced image: images/bge_camera_properties_game.jpg

        with: images/bge_camera_properties_embedded.png

replaced image: images/bge_camera_properties_standalone.jpg

        with: images/bge_camera_properties_standalone.png

updated image: images/bge_camera_properties_shading.png

repalced image: images/gameengine_performance_render_system.jpg

        with: images/gameengine_performance_render_system.png

deleted image: images/bge_camera_properties_performance.jpg
added image: images/gameengine_performance_render_bake.png

[RFC-1]
this page HTML title and numerous places in the document refer to "Camera Editing" and "Camera Properties" but the panel described on this page is labeled in the current GUI as the "Render" properties - the 'Display' section below also refers to this as the "Render tab" - and o/c the name of the documentation input file is render.rst - no changes of this nomenclanture were made in this patch - but for the sake of discussion it seems that this page was quite out-dated and the inconsistent image naming scheme is indicative of a transitional phase so perhaps "Camera Properties" is a legacy reference that should be replaced with something like: "Game Engine Render Properties"

[RFC-2]
regarding the resolution controls in the 'Embedded Player' section - especially, the line: "In fact, the Resolution controls seem to have no effect at all." - nothing i do to these controls results in any visible change - it is not at all clear what these actually control

[RFC-3]
regarding the 'Desktop' entry under the "Standalone Player" section - the behavior of this checkbox seems quirky - there is perhaps a GUI bug lurking here - when the 'Fullscreen' checkbox is unchecked, the 'Fullscreen' checkbox label is grey (this is consistent with the rest of the GUI) but the 'Desktop' checkbox is a yet darker shade of grey - when the 'Fullscreen' checkbox is checked, the 'Fullscreen' checkbox label is white (as expected) and the 'Desktop' checkbox turns the lighter shade of grey - according to the semantics, the 'Desktop' checkbox is only applicable when in 'Fullscreen' mode so perhaps this indicates that the 'Desktop' checkbox should be disabled unless the 'Fullscreen' checkbox is checked - but even when the 'Fullscreen' checkbox is unchecked, the 'Desktop' checkbox is still enabled (check-able) and turns the lighter grey when checked (the same color as the unchecked 'Fullscreen' checkbox) although it seems to have no effect - this same behavior was noted of the 'Clear' checkbox under the 'Bake' Section when the 'Bake to Vertex Color' checkbox is checked

[RFC-4]
the description for "AA Samples" under the "Quality" sub-section of the "Standalone Player" section was taken verbatim from the GUI tooltip so it is not very explanatory

[RFC-5]
the 'FPS' control described under the "Quality" sub-section of the "Standalone Player" section does not exist in version (2.78) but there is 'Refresh Rate' - it's entry for was renamed to 'Refresh Rate' assuming that the functionality of this control has not changed but only the label

[RFC-6]
the description for the "Framing" controls under the "Standalone Player" section was removed because they do not exist in version (2.78) but are actually under the "Display" section - also, duplicate entries for these control already exist on this page under the "Display" section - though it is not clear why these controls were moved as they seem to be relevent only to the standalone player and not generally applicable as are the other 'Display' controls - one could also make a solid arguement that the "hide mouse cursor" feature should apply only to the standalone player

[RFC-7]
regarding the description for the 'Single Texture' shading option: this option does not exist in version (2.78) so it's entry was removed

[RFC-8]
regarding the wording of the description for the 'GLSL' shading option: "GLSL should be used whenever possible for real-time image rendering." - this could be interpreted as a general reccommendation (as if to say: "GLSL is incontrovetibly superior for all purposes and so the other options should be used only as a last resort") - if this was the intention then it should probably be elaborated under which condition would GLSL not be practical or usable - however, i think the intention was more to say: "if the GLSL option is selected, then GLSL will be used whenever possible" - in any case, it should probably be clarified in which scenarios might this be possible or impossible and what is the fallback mechanism in the cases when it is impossible - in either case, neither "multitexture" nor "GLSL" are in the glossary so this manual currently offers no guidance as to which option is best suited for common or particular use cases - if it is indeed generally and strictly true that "GLSL should be used whenever possible" then that sentence should be moved into the descriptive section above and made more explicit - o/c that would raise the question of why is it not the default option

when one searches the docs for the term "multitexture" only two other mentions are found but they explain not much at all (only to say that shadows can be seen in the preview only when in GLSL mode)

 https://docs.blender.org/manual/en/dev/render/blender_render/materials/introduction.html
 https://docs.blender.org/manual/en/dev/render/blender_render/materials/properties/shadows.html

to make this issue more confusing, the materials/introduction page refers to this selection as "the texture method" and the shadows page refers to it as "the Display Mode" and this page refers to it as "the shading mode"

[RFC-9]
the entries for "Use Material Caching", "V-Sync", and "Storage" under the "System" section were taken verbatim from the GUI tooltips so they are not very explanatory

[RFC-10]
the "Performance" section does not exist in version (2.78) so it's documentation was removed - it contained only duplicate descriptions of controls that are now in the "System" section and were already described on this page - these descriptions were not strictly redundant though but offered more information and so were merged into the "System" entries above

[RFC-11]
the descriptions of 'Debug Properties' and 'Framerate and Profile' under the 'Display' section are a bit confusing - i tried to clarify the best as i could interpret them - the changes in markup here were because the documentation guidelines suggest: "Use italics for button/menu names."

[RFC-12]
regarding the "Framing" controls under the "Display" section - this section was quite confusing - i did my best to state clearly and deterministically the observed behaviors through experimentation but the Letterbox mode was particularly quirky to predict or explain - some of my experiments gave wild results and i was not able to find any resolution settings that would fill the screen (no bars) in Fullscreen Letterbox mode hence the recommendation to avoid the combination of Letterbox and Fullscreen modes

[RFC-13]
all of the entries under the "Bake" section were taken verbatim from the "Render Baking" page for the blender render engine - these panels are nearly identical so presumable the documentation is very close also - although the "Bake from Multires" checkbox is not covered there - the "Bake from Multires" description is from the GUI tooltip - no overall section description was added but a link was added to the "Render Baking" page for the blender render engine

patch --> [manual-game_engine-settings-render.diff](https://archive.blender.org/developer/F445687/manual-game_engine-settings-render.diff) the screenshots currently on this page are from a prior version and do not reflect the current version: updated image: images/bge_camera_properties.png ![bge_camera_properties.png](https://archive.blender.org/developer/F445688/bge_camera_properties.png) replaced image: images/bge_camera_properties_game.jpg ``` with: images/bge_camera_properties_embedded.png ``` ![bge_camera_properties_embedded.png](https://archive.blender.org/developer/F445690/bge_camera_properties_embedded.png) replaced image: images/bge_camera_properties_standalone.jpg ``` with: images/bge_camera_properties_standalone.png ``` ![bge_camera_properties_standalone.png](https://archive.blender.org/developer/F445691/bge_camera_properties_standalone.png) updated image: images/bge_camera_properties_shading.png ![bge_camera_properties_shading.png](https://archive.blender.org/developer/F445692/bge_camera_properties_shading.png) repalced image: images/gameengine_performance_render_system.jpg ``` with: images/gameengine_performance_render_system.png ``` ![gameengine_performance_render_system.png](https://archive.blender.org/developer/F445693/gameengine_performance_render_system.png) deleted image: images/bge_camera_properties_performance.jpg added image: images/gameengine_performance_render_bake.png ![gameengine_performance_render_bake.png](https://archive.blender.org/developer/F445694/gameengine_performance_render_bake.png) [RFC-1] this page HTML title and numerous places in the document refer to "Camera Editing" and "Camera Properties" but the panel described on this page is labeled in the current GUI as the "Render" properties - the 'Display' section below also refers to this as the "Render tab" - and o/c the name of the documentation input file is render.rst - no changes of this nomenclanture were made in this patch - but for the sake of discussion it seems that this page was quite out-dated and the inconsistent image naming scheme is indicative of a transitional phase so perhaps "Camera Properties" is a legacy reference that should be replaced with something like: "Game Engine Render Properties" [RFC-2] regarding the resolution controls in the 'Embedded Player' section - especially, the line: "In fact, the *Resolution* controls seem to have no effect at all." - nothing i do to these controls results in any visible change - it is not at all clear what these actually control [RFC-3] regarding the 'Desktop' entry under the "Standalone Player" section - the behavior of this checkbox seems quirky - there is perhaps a GUI bug lurking here - when the 'Fullscreen' checkbox is unchecked, the 'Fullscreen' checkbox label is grey (this is consistent with the rest of the GUI) but the 'Desktop' checkbox is a yet darker shade of grey - when the 'Fullscreen' checkbox is checked, the 'Fullscreen' checkbox label is white (as expected) and the 'Desktop' checkbox turns the lighter shade of grey - according to the semantics, the 'Desktop' checkbox is only applicable when in 'Fullscreen' mode so perhaps this indicates that the 'Desktop' checkbox should be disabled unless the 'Fullscreen' checkbox is checked - but even when the 'Fullscreen' checkbox is unchecked, the 'Desktop' checkbox is still enabled (check-able) and turns the lighter grey when checked (the same color as the unchecked 'Fullscreen' checkbox) although it seems to have no effect - this same behavior was noted of the 'Clear' checkbox under the 'Bake' Section when the 'Bake to Vertex Color' checkbox is checked [RFC-4] the description for "AA Samples" under the "Quality" sub-section of the "Standalone Player" section was taken verbatim from the GUI tooltip so it is not very explanatory [RFC-5] the 'FPS' control described under the "Quality" sub-section of the "Standalone Player" section does not exist in version (2.78) but there is 'Refresh Rate' - it's entry for was renamed to 'Refresh Rate' assuming that the functionality of this control has not changed but only the label [RFC-6] the description for the "Framing" controls under the "Standalone Player" section was removed because they do not exist in version (2.78) but are actually under the "Display" section - also, duplicate entries for these control already exist on this page under the "Display" section - though it is not clear why these controls were moved as they seem to be relevent only to the standalone player and not generally applicable as are the other 'Display' controls - one could also make a solid arguement that the "hide mouse cursor" feature should apply only to the standalone player [RFC-7] regarding the description for the 'Single Texture' shading option: this option does not exist in version (2.78) so it's entry was removed [RFC-8] regarding the wording of the description for the 'GLSL' shading option: "GLSL should be used whenever possible for real-time image rendering." - this could be interpreted as a general reccommendation (as if to say: "GLSL is incontrovetibly superior for all purposes and so the other options should be used only as a last resort") - if this was the intention then it should probably be elaborated under which condition would GLSL not be practical or usable - however, i think the intention was more to say: "if the GLSL option is selected, then GLSL will be used whenever possible" - in any case, it should probably be clarified in which scenarios might this be possible or impossible and what is the fallback mechanism in the cases when it is impossible - in either case, neither "multitexture" nor "GLSL" are in the glossary so this manual currently offers no guidance as to which option is best suited for common or particular use cases - if it is indeed generally and strictly true that "GLSL should be used whenever possible" then that sentence should be moved into the descriptive section above and made more explicit - o/c that would raise the question of why is it not the default option when one searches the docs for the term "multitexture" only two other mentions are found but they explain not much at all (only to say that shadows can be seen in the preview only when in GLSL mode) ``` https://docs.blender.org/manual/en/dev/render/blender_render/materials/introduction.html https://docs.blender.org/manual/en/dev/render/blender_render/materials/properties/shadows.html ``` to make this issue more confusing, the materials/introduction page refers to this selection as "the texture method" and the shadows page refers to it as "the Display Mode" and this page refers to it as "the shading mode" [RFC-9] the entries for "Use Material Caching", "V-Sync", and "Storage" under the "System" section were taken verbatim from the GUI tooltips so they are not very explanatory [RFC-10] the "Performance" section does not exist in version (2.78) so it's documentation was removed - it contained only duplicate descriptions of controls that are now in the "System" section and were already described on this page - these descriptions were not strictly redundant though but offered more information and so were merged into the "System" entries above [RFC-11] the descriptions of 'Debug Properties' and 'Framerate and Profile' under the 'Display' section are a bit confusing - i tried to clarify the best as i could interpret them - the changes in markup here were because the documentation guidelines suggest: "Use italics for button/menu names." [RFC-12] regarding the "Framing" controls under the "Display" section - this section was quite confusing - i did my best to state clearly and deterministically the observed behaviors through experimentation but the Letterbox mode was particularly quirky to predict or explain - some of my experiments gave wild results and i was not able to find any resolution settings that would fill the screen (no bars) in Fullscreen Letterbox mode hence the recommendation to avoid the combination of Letterbox and Fullscreen modes [RFC-13] all of the entries under the "Bake" section were taken verbatim from the "Render Baking" page for the blender render engine - these panels are nearly identical so presumable the documentation is very close also - although the "Bake from Multires" checkbox is not covered there - the "Bake from Multires" description is from the GUI tooltip - no overall section description was added but a link was added to the "Render Baking" page for the blender render engine

Aaron Carlisle was assigned by bill auger

2017-02-04 09:04:33 +01:00

bill auger commented

2017-02-04 09:04:33 +01:00

Changed status to: 'Open'