New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

document new behavior for smooth(), smooth(N), and noSmooth() #251

Closed
benfry opened this Issue Jun 6, 2015 · 6 comments

Comments

Projects
None yet
3 participants
@benfry
Member

benfry commented Jun 6, 2015

Very soon (next 48 hours) to be implemented...

The change is because smoothing, in most renderers (all future renderers—e.g. JavaFX and OpenGL) is a property of the drawing surface, not something to be enabled and disabled throughout a sketch's lifecycle. Changing the setting requires blowing up and rebuilding the drawing surface, so we're removing the instantaneous behavior from the API.

Main drawing surface:

  • smooth() is the default (and has been since 2.x)
  • noSmooth() and smooth(N) (where N is the renderer-specific smoothing level) can only be used in the settings() block. Which is to say, in the PDE those can only be used inside setup(), from which they'll be teleported to a settings() method that the user never sees (unless they export and look at the .java file). The existence of settings() is only for advanced (IDE-toting) users.
  • smooth(N) should use numbers, not variables, just like size() (otherwise something might break during the magical teleportation process).

With createGraphics():

  • the smoothing setting is inherited from the parent sketch
  • call noSmooth(), smooth(), or smooth(N) to override those settings before the first use of beginDraw() on that PGraphics object.
    • Internally, once drawing to the surface has started, we can't go rebuilding it (inside a begin/endDraw() pair).
    • We could support rebuilding it later, so long as it's outside begin/endDraw(), but why make things more difficult for ourselves than we already have?
@REAS

This comment has been minimized.

Show comment
Hide comment
@REAS

REAS Jun 6, 2015

Member

I can't figure out a reason to use smooth() without the "level" parameter, the smooth(N) situation.

Member

REAS commented Jun 6, 2015

I can't figure out a reason to use smooth() without the "level" parameter, the smooth(N) situation.

@shiffman

This comment has been minimized.

Show comment
Hide comment
@shiffman

shiffman Jun 6, 2015

Member

I think the only reason is that there are countless of old examples that start off:

void setup() {
  size(200, 200);
  smooth();
 // etc.
}

So maybe good to leave it is as the equivalent of smooth(1) to avoid breaking old code? Or do we want to enforce / remind people that smoothing is on by default and the call is only necessarily for specifying a non-default smoothing?

Member

shiffman commented Jun 6, 2015

I think the only reason is that there are countless of old examples that start off:

void setup() {
  size(200, 200);
  smooth();
 // etc.
}

So maybe good to leave it is as the equivalent of smooth(1) to avoid breaking old code? Or do we want to enforce / remind people that smoothing is on by default and the call is only necessarily for specifying a non-default smoothing?

@REAS

This comment has been minimized.

Show comment
Hide comment
@REAS

REAS Jun 6, 2015

Member

Yes, good plan. I'm working that into the reference XML file now.

Member

REAS commented Jun 6, 2015

Yes, good plan. I'm working that into the reference XML file now.

@benfry

This comment has been minimized.

Show comment
Hide comment
@benfry

benfry Jun 6, 2015

Member

Couple things:

  • Internally, smooth() just calls smooth(1), so that's already in place.
  • smooth(N) is for advanced users and is a very low priority to document
  • smooth(1) is an implementation detail and shouldn't be documented (just keep using smooth())
  • smooth() is in most cases essentially ignored, because it's already the default. Calling it again has no effect (and no warning is shown).
  • The only cases where folks really hit any of this is:
    1. If they were calling noSmooth() explicitly to have aliased graphics
    2. They knew about smooth(N) and used it in their code
    3. They were turning off smoothing temporarily for some situation (remove edges from solid rectangles, get perfect alignment, or something like that), and then turning it back on
Member

benfry commented Jun 6, 2015

Couple things:

  • Internally, smooth() just calls smooth(1), so that's already in place.
  • smooth(N) is for advanced users and is a very low priority to document
  • smooth(1) is an implementation detail and shouldn't be documented (just keep using smooth())
  • smooth() is in most cases essentially ignored, because it's already the default. Calling it again has no effect (and no warning is shown).
  • The only cases where folks really hit any of this is:
    1. If they were calling noSmooth() explicitly to have aliased graphics
    2. They knew about smooth(N) and used it in their code
    3. They were turning off smoothing temporarily for some situation (remove edges from solid rectangles, get perfect alignment, or something like that), and then turning it back on
@benfry

This comment has been minimized.

Show comment
Hide comment
@benfry

benfry Jun 6, 2015

Member

To the question by @REAS, I think the cases where smooth() are still used are:

  • older code that hasn't been updated since the 2.x change
  • if noSmooth() was used in the sketch and then someone wants smoothing with createGraphics() (wow, that's an edge case)
  • anyone who wants to be pedantic about it, harkening back to the 1.x days?

But I can understand that it's now a little weird to document smooth() with no arguments. Maybe it's partly just explaining "this is rarely necessary, but exists in a lot of old code".

Member

benfry commented Jun 6, 2015

To the question by @REAS, I think the cases where smooth() are still used are:

  • older code that hasn't been updated since the 2.x change
  • if noSmooth() was used in the sketch and then someone wants smoothing with createGraphics() (wow, that's an edge case)
  • anyone who wants to be pedantic about it, harkening back to the 1.x days?

But I can understand that it's now a little weird to document smooth() with no arguments. Maybe it's partly just explaining "this is rarely necessary, but exists in a lot of old code".

@shiffman shiffman referenced this issue Jun 6, 2015

Closed

smooth() #131

@processing processing locked and limited conversation to collaborators Jun 10, 2015

@REAS

This comment has been minimized.

Show comment
Hide comment
@REAS

REAS Jun 10, 2015

Member

This is finished.

Member

REAS commented Jun 10, 2015

This is finished.

@REAS REAS closed this Jun 10, 2015

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.