It would help if you could better explain what your issue with this page is. It is one of the older pages on the Wiki, the original version and structure dating back to nearly a decade ago, so I'm open to the idea that it has problems. But it's hard to know what those are when your only criticism is "Reads like an autotranslated article." Alfonse (talk) 18:42, 30 June 2019 (UTC)
how do i use this thing
"Framebuffer Objects are OpenGL Objects" are a kind of, or *are* ?
"which allow for the creation of user-defined Framebuffers" this doesn't say if *this* is their purpose or if this is the *only* way to create userdefined framebuffers.
"With them" them? framebuffer objects or userdefined framebuffers?
"one can render to non-Default Framebuffer locations" is this the only way to render to non-default framebuffer locations? is a framebuffer *location* different to a framebuffer? to a framebuffer object? It doesn't explain if one can render to the *default* framebuffer.
", and thus render without disturbing the main screen." is this an option or is this the only way it works? using a framebuffer object prevents 'disturbing' the main screen? what is the 'main screen' ?
"Framebuffer objects are very complicated." uh... does this matter? Is this your personal opinion?
" As such, we need to explicitly define certain terminology." so, in short, the text from 'Semantics' to 'terminology.' means"DEFINITIONS:"
"For the purposes of this article, an image is a single 2D array of pixels. It has a specific format for these pixels." not sure what "with a specific format" means. Does this mean the format must be specified on creation? Or is it predetermined and all 'Images' use this format?
" images of a particular size and format. " again, what the hell does 'particular' mean?
"a texture is an object that contains some number of images" 'some' ? is this number a constant? can it be changed? what the hell does 'some' mean? just pffffrt pick a number 1.34423523e41 there, a number.
" Textures can be accessed from Shaders via various methods." 'via various methods' ? does this matter now? is 'two methods' enough for various? or ten thousand?
"A renderbuffer is an object that contains a single image." so if that's all it is, how is it different from an image? or is it an image with additional data?
"Renderbuffers cannot be accessed by Shaders in any way. " they sure can. indirectly, but that is *a way*.
"The only way to work with a renderbuffer, besides creating it, is to put it into an FBO." 'work with' ? you mean 'use' ? 'put it into' ? You mean 'attach it to'? Also, creation is not use. You create so you *can* use what you created.
"This term is used across all of OpenGL, but FBOs make the most use of the concept. " this is relevant, how?
"Objects are bound to the context; objects are attached to one another." still not clear on the difference.
"A named location within a framebuffer object that a framebuffer-attachable image or layered image can be attached to. " what's a "named location"?
"Any image, as previously described, that can be attached to a framebuffer object.": an image that one may attach to a framebuffer object. "that can be attached" is ambiguous. is it attached *now*, or is it possible *to* attach it?
"The default framebuffer has buffer names like GL_FRONT, GL_BACK, GL_AUXi, GL_ACCUM, and so forth. FBOs do not use these." you're kidding me, right? Please tell me english isn't your native language, i can accept that. This is no way to write documentation. This is how i used to write at university when i tried to pad my essays to fill the mandatory word count.
"Rectangle Textures contain a single 2D image, and thus is identified by mipmap level 0." is? the image is identified? or is this a typo? First sentence uses plural, second uses singular.
"You can attach images from any kind of texture to the framebuffer object. " any? last point says buffer textures cannot be attached. this is confusing.
i'm stopping here because this won't get us anywhere.
"Do not do this. What you will get is undefined behavior." what are you doing man, what are you doing.
- First, this discussion should take place on your talk page, not mine. Second, when writing any posts on a talk page, always sign your posts with four ~ characters in a row. That way, people can tell who said what.
- Third, I'm not going into thread-mode with you over every single sentence of that article. Your overall point seems to be that you disagree with the generally informal tone of the text on the page. You seem to prefer formal, technical writing rather than this more informal style, a style common to reference documentation, where information and terminology is endlessly repeated. That's not a thing that should happen here.
- Consider the distinction between "bound" and "attach". The OpenGL Object page goes into more detail on the distinction. Giving a perfunctory summary of the concept on the FBO page reduces repetition.
- I'm not saying that the current wording is perfect (you found an actual inaccuracy in that buffer textures cannot be attached to FBOs). But the majority of your points seem to be personal nit-picks and differences of style, rather than objective problems. For example, I don't think anyone is legitimately confused by "Framebuffer Objects are OpenGL Objects," much like nobody is confused by "frogs are amphibians". While "a type of" might be more specific, that doesn't mean that "are" is the wrong word.
- Similarly, I don't think "some number of images" is causing problems either. The point of the statement is to make it clear that a texture is not just a single image, that different textures can have different numbers of images. The phrase "some number" keeps the number indeterminate, because the exact number depends on the specific texture object. "Picking a number" would therefore be inaccurate.
- If you want to rewrite the page, feel free. But since I don't agree with most of your issues with it, I won't be doing it for you. Also, if you do rewrite the page, understand that I will probably revert it if your version lacks any of the informational content that the current version has, particularly any of the warnings about UB and the like. So if you're going to rewrite it, be comprehensive. Alfonse (talk) 15:32, 1 July 2019 (UTC)
- i would, if i knew the information necessary. But since i *need* this documentation, by default, *i can not write it*. I can only *ask* that you clarify, use PRECISE, UNAMBIGUOUS language even if YOU feel like it's clear. Avoid 'it' 'that' 'those' even if it appears verbose. Reader's guesswork should be minimized. When i'm reading the official wikipedia, i don't want to fill in ANY gaps. I want it to be DIFFICULT TO MISINTERPRET.
- answer me the following, then:
- 1) which allow for the creation of user-defined Framebuffers is it the only way to create one? is it their only purpose? ie, is this a one-to-one corresponcence?
- 2) With them them? "framebuffer objects", "userdefined framebuffers" or both?
- 3) one can render to non-Default Framebuffer locations again, is this a one-to-one relation? can i render to default? can i render to non-default in another way?
- 4) , and thus render without disturbing the main screen. is this an option or is this the only way it works?
- 5) For the purposes of this article, an image is a single 2D array of pixels. It has a specific format for these pixels. can the format be specified on creation, or is it predetermined and all 'Image' objects use this format?
- 6) images of a particular size and format. the size i can ASSUME it can be user configurable, but the format? Is it predetermined, or user-configurable?
- 7) a texture is an object that contains some number of images who determines this number? if the programmer can determine this, it should read "contains a user-configurable number of images". If it is implementation-specific it should say so. If it is a fixed number, it should say so.
- 8) Any image, as previously described, that can be attached to a framebuffer object.: "that can be attached" is ambiguous. Does it mean that the image IS attached or that it is possible TO attach it?
- 9) Rectangle Textures contain a single 2D image, and thus is identified by mipmap level 0. do you mean to write ", which must be assigned a mipmap level of 0" ?
- 10) You can attach images from any kind of texture to the framebuffer object. any? last point says buffer textures cannot be attached. this is confusing.
- Tsiros (talk) 09:05, 3 July 2019 (UTC)
- "Avoid 'it' 'that' 'those' even if it appears verbose." I'm afraid not. The use of pronouns is standard, and when read within context, can be used without ambiguity. For example "with them" only sounds ambiguous outside of the context of the statement. Remember: that phrase appears in the first paragraph on a page entitled "Framebuffer Object", a paragraph whose first sentence starts with "Framebuffer Objects" that was written in bold face. The subject of the paragraph is clearly "Framebuffer Objects", so any pronoun which could be referring to them definitely is.
- It only becomes ambiguous when you remove the phrase from its context.
- As I said before, I'm not going into thread mode with you on your issues here. That means I'm not going to give you a response to each example, so please stop posting long lists of things. If you have a general problem, explain the general problem, then give a few examples of where it manifests.
- One of your major issues seems to be wanting more detail in earlier parts of the article. Here's my issue with that: this is a page about Framebuffer Objects.
- Could there be other ways to render to non-default Framebuffers, user-defined framebuffers, or off-screen rendering? Maybe, but that's not the point of this article. Therefore, talking about alternatives to FBOs is not appropriate here. Or at the very least, it is definitely not appropriate on the introductory paragraph of the article. The intro exists to give a quick overview of what an FBO can do. Adding verbiage about PBuffers or other alternatives would only dilute the critical information about framebuffer objects: that they are a way to do off-screen rendering to user-defined images.
- A section on alternatives at the very end might be OK, but not in the intro paragraph.
- Similarly, how the number of images is assigned to a texture, or how an image gets its sizes, or which formats can be used and how they are assigned, is unimportant to the purpose of this article. Remember that the definition section is there to give the reader a quick grounding in what these terms mean, and only to the extent that it relates to framebuffer objects. Being comprehensive is not the point. Indeed, being comprehensive would get in the way of the necessary information. The key information being that images are 2D arrays of pixels of a particular size and format, and that textures contain one or more images. That's what the reader needs to know going about the relationship of these things to FBOs, because those are the only things that FBOs care about with regard to these concepts.
- This Wiki has plenty of information on the details of how the number of images in a texture is defined, how images get formats and sizes, etc. It's just not available here; links to that information are here, but not the details themselves. Adding irrelevant details to this section, even as a summary, only gets in the way of the important information.
- The thing to understand about teaching something is that most readers do not want breadth. Or at least, not immediately. You start with a high-level overview, then get down to the details. If a paragraph needs to mention something, it shouldn't switch topics to fully explain every aspect of that something before going back to the main topic. Inundating a reader with irrelevant information and options early on only slows down their ability to understand the primary concepts. Because of the complexity of FBOs, I needed a section that defines terms, but that section needs to be as short as possible, so as not to slow the reader down too much from getting to the important information.
- Also, I don't really understand how you go from "can be attached" to "is attached". "Can" refers to capability; "is" refers to the current status. Your confusion makes even less sense when taken in the context of a definition of the term "Framebuffer-attachable image". "Attachable" is clearly about capability; that's what the "able" suffix means. If the term was "Framebuffer-attached image", I might understand your statement.