AFPhotoEditorContext Class Reference
Inherits from | NSObject |
Declared in | AFPhotoEditorContext.h |
Overview
Photo Editor Contexts are generated by calling the createContextWithImage: or createContextWithImage:maxSize: methods of AFPhotoEditorSession. A context encapsulates an input image and an output size. If not specified, the output size defaults to the image size. In the Basic SDK, the output size is scaled down to a maximum of 3MP (if necessary, maintaining aspect ratio). There is no such limitation in the Premium SDK.
Calling render: on a context causes all modifications tracked in the AFPhotoEditorSession (which tracks user generated photo-editing actions in
an AFPhotoEditorController) to be replayed on the context’s input image asynchronously. When rendering is complete, the completion block passed
into render: will be called with the finalized image, whose size will match the context’s size. If the session contains no tracked actions (i.e., the user made
no edits before pressing “Done” or pressed “Cancel”), the result image will be nil
. Note: render: may only be called once per context.
By default, contexts take advantage of GPU acceleration. If an input image is too large to be represented as an OpenGL texture, an attempt to render an image will cause the context to silently fall back to CPU rendering. Maximum texture size is measured by the maximum dimension of an image, and both the width and height of the input image must be less than this maximum dimension. iPhone 3GS, iPhone 4, and iPad 1 have a maximum texture dimension of 2048 (4MP for a square image), while iPhone 5, iPhone 4S, iPad 2, and new iPads have a maximum texture dimension of 4096 (16MP for a square image).
Behavior varies between GPU and CPU rendering when a context is created before a session is closed. If the context is able to use the GPU, it will wait until the session is closed before beginning to render the output image. This is because GPU processing is very fast for most user action sets, and waiting until the session is closed to begin rendering saves memory and processing power. If the context falls back to using the CPU, it will render actions on the image in the background as the user applies them in the SDK (by pressing the “Apply” button).
Some things to note about using contexts:
- We recommend choosing a maximum output resolution that suits the purposes of your application to provide the best experience for your users.
- Processing large images can consume a lot of memory and time. It may be necessary to free up resources and/or display an activity indicator while a context is executing.
- To calculate the approximate maximum amount of memory a context could use, multiply the dimensions of the output size and multiply the result by 4. For example, a context with a maximum output size of 1500x1500 will consume approximately 9mb of memory for the processing duration.
Tasks
-
session
The session that the context was generated from.
property -
size
The size that the context’s image will be output at.
property -
canceled
Specifies if the context’s rendering has been cancelled.
property -
modified
Specifies if the context’s session has been modified.
property -
hasBegunRendering
Specifies whether rendering has begun on the context.
property -
– render:
Replays all actions tracked by the generating AFPhotoEditorSession on the context’s image.
-
– cancelRendering
Cancels the context’s rendering.
-
– renderInputImage:completion:
Deprecated.
Properties
canceled
Specifies if the context’s rendering has been cancelled.
@property (nonatomic, assign, readonly, getter=isCanceled) BOOL canceled
Declared In
AFPhotoEditorContext.h
hasBegunRendering
Specifies whether rendering has begun on the context.
@property (nonatomic, assign, readonly) BOOL hasBegunRendering
Discussion
If YES, any render: call will have no effect.
Declared In
AFPhotoEditorContext.h
modified
Specifies if the context’s session has been modified.
@property (nonatomic, assign, readonly, getter=isModified) BOOL modified
Declared In
AFPhotoEditorContext.h
Instance Methods
cancelRendering
Cancels the context’s rendering.
- (void)cancelRendering
Discussion
Warning: Calling this method from any thread other in the main thread may result in undefined behavior.
Declared In
AFPhotoEditorContext.h
render:
Replays all actions tracked by the generating AFPhotoEditorSession on the context’s image.
- (void)render:(void ( ^ ) ( UIImage *result ))completion
Parameters
- completion
The block to be called when the image’s render is complete.
Discussion
The completion block will not be called until after the session
is closed, i.e. until the user has closed the AFPhotoEditorController that generated the
session
. If the user pressed “Cancel” or took no actions before pressing “Done”, the result
UImage in the completion block will be nil. Otherwise, it
will contain the rendered image. The context will try to render the image on the GPU, but it will fall back to the CPU if necessary. See the discussion in
AFPhotoEditorContext for more details.
Note: This method may be called once per context, as it would not make sense to run the same actions on the same image twice. Check hasBegunRendering to see if render has been called.
Warning: Calling this method from any thread other in the main thread may result in undefined behavior.
Declared In
AFPhotoEditorContext.h
renderInputImage:completion:
Deprecated.
- (void)renderInputImage:(UIImage *)image completion:(void ( ^ ) ( UIImage *result ))completion
Parameters
- image
The input image.
- completion
The completion block.
Discussion
Please create a context with AFPhotoEditorSession’s createContextWithImage: or createContextWithImage:maxSize: and use render: instead.
Declared In
AFPhotoEditorContext.h