oyPixelAccess_s Struct Reference
Description: C source code API documentation for the Oyranos project.
Keywords: Oyranos,Color Management,Color Management,ICC,CMS,C,doxygen,API,documentation

| Oyranos Color Management System API - Version 0.9.6

Public Member Functions | Data Fields
oyPixelAccess_s Struct Reference
Conversion

Control pixel access order. More...

`#include <oyPixelAccess_s.h>`

Inheritance diagram for oyPixelAccess_s:
Collaboration diagram for oyPixelAccess_s:

## Public Member Functions
OYAPI oyPixelAccess_s *OYEXPORT | oyPixelAccess_New (oyObject_s object)
| allocate a new PixelAccess object More...
| oyPixelAccess_Copy
| Copy or Reference a PixelAccess object. More...
OYAPI int OYEXPORT | oyPixelAccess_Release (oyPixelAccess_s **pixelaccess)
| release and possibly deallocate a oyPixelAccess_s object More...
int | oyPixelAccess_ChangeRectangle (oyPixelAccess_s *pixel_access, double start_x, double start_y, oyRectangle_s *output_rectangle)
| Change the ticket for a conversion graph. More...
int | oyPixelAccess_ArrayIsFocussed (oyPixelAccess_s *pixel_access)
| Tell if array has changed focus as of changed output_rectangle. More...
oyPixelAccess_s * | oyPixelAccess_Create (int32_t start_x, int32_t start_y, oyFilterPlug_s *plug, oyPIXEL_ACCESS_TYPE_e type, oyObject_s object)
| Allocate iand initialise a basic oyPixelAccess_s object. More...
oyImage_s * | oyPixelAccess_GetOutputImage (oyPixelAccess_s *pixel_access)
| Access oyPixelAccess_s::output_image. More...
int | oyPixelAccess_SetOutputImage (oyPixelAccess_s *pixel_access, oyImage_s *image)
| Set oyPixelAccess_s::output_image. More...
int | oyPixelAccess_SynchroniseROI (oyPixelAccess_s *pixel_access_new, oyPixelAccess_s *pixel_access_src)
| Set a new ticket according to old ticket geometries. More...
int | oyPixelAccess_SetArrayFocus (oyPixelAccess_s *pixel_access, int undo)
| Ensure that the array is in output ROI focus. More...
const char * | oyPixelAccess_Show (oyPixelAccess_s *pixel_access)
| Print ticket geometries. More...
oyRectangle_s * | oyPixelAccess_GetArrayROI (oyPixelAccess_s *pixel_access)
| Access oyPixelAccess_s::output_array_roi. More...
int | oyPixelAccess_RoiToPixels (oyPixelAccess_s *pixel_access, oyRectangle_s *roi, oyRectangle_s **pixel_rectangle)
| Calculate pixel rectangle from ROI. More...
int | oyPixelAccess_PixelsToRoi (oyPixelAccess_s *pixel_access, oyRectangle_s *pixel_rectangle, oyRectangle_s **roi)
| Calculate ROI rectangle from pixel rectangle. More...
oyFilterGraph_s * | oyPixelAccess_GetGraph (oyPixelAccess_s *pixel_access)
| Access oyPixelAccess_s::graph. More...
oyOptions_s * | oyPixelAccess_GetRequestQueue (oyPixelAccess_s *pixel_access)
| Access oyPixelAccess_s::request_queue. More...
oyArray2d_s * | oyPixelAccess_GetArray (oyPixelAccess_s *pixel_access)
| Access oyPixelAccess_s::array. More...
int | oyPixelAccess_SetArray (oyPixelAccess_s *pixel_access, oyArray2d_s *array, int has_roi_focus)
| Set oyPixelAccess_s::array. More...
oyStruct_s * | oyPixelAccess_GetUserData (oyPixelAccess_s *pixel_access)
| Access oyPixelAccess_s::user_data. More...
int | oyPixelAccess_SetUserData (oyPixelAccess_s *pixel_access, oyStruct_s *user_data)
| Set oyPixelAccess_s::user_data. More...
int32_t | oyPixelAccess_GetWorkspaceID (oyPixelAccess_s *pixel_access)
| Access oyPixelAccess_s::workspace_id. More...
int | oyPixelAccess_SetWorkspaceID (oyPixelAccess_s *pixel_access, int32_t workspace_id)
| Set oyPixelAccess_s::workspace_id. More...
double | oyPixelAccess_GetStart (oyPixelAccess_s *pixel_access, int vertical)
| Access oyPixelAccess_s::start_xy. More...
double | oyPixelAccess_GetOldStart (oyPixelAccess_s *pixel_access, int vertical)
| Access oyPixelAccess_s::start_xy_old. More...
int | oyPixelAccess_SetOldStart (oyPixelAccess_s *pixel_access, int vertical, double start)
| Access oyPixelAccess_s::start_xy_old. More...
Public Member Functions inherited from oyStruct_s
const char * | oyStruct_GetTextFromModule (oyStruct_s *obj, oyNAME_e name_type, uint32_t flags)
| get object infos from a module More...
const char * | oyStruct_GetText (oyStruct_s *obj, oyNAME_e name_type, uint32_t flags)
| Get a text dump. More...
| oyStruct_RegisterStaticMessageFunc
| register a function for verbosity More...
| oyStruct_GetInfo
| get a additional string from a object More...
const char * | oyStructTypeToText (oyOBJECT_e type)
| Objects type to small string. More...

## Data Fields
const oyOBJECT_e | type_
| Type of object. More...
oyStruct_Copy_f | copy
| Copy function. More...
oyStruct_Release_f | release
| Release function. More...
oyObject_s | oy_
| Oyranos internal object. More...
Data Fields inherited from oyStruct_s
const oyOBJECT_e | type_
| Type of object. More...
oyStruct_Copy_f | copy
| Copy function. More...
oyStruct_Release_f | release
| Release function. More...
oyObject_s | oy_
| Oyranos internal object. More...

## Detailed Description

Control pixel access order.

A struct to control pixel access. It is a kind of flexible pixel iterator. The order or pattern of access is defined by the [array_xy and] start_[x,y] variables.

oyPixelAccess_s is like a job ticket. Goal is to maintain all intermediate and processing dependend memory references in this structure.

[The index variable specifies the iterator position in the array_xy index array.]

[pixels_n says how many pixels are to be processed for the cache. pixels_n is used to calculate the buffers located with getBuffer and freeBuffer. The amount of pixel specified in pixels_n must be processed by each filter, because other filters are relying on a properly filled cache. This variable also determins the size of the next iteration.]

[The relation of pixels_n to array_xy and start_[x,y] is that a minimum of pixels_n must be processed by starting with start_[x,y] and processing pixels_n through array_xy. array_xy specifies the offset pixel distance to a next pixel in x and y directions. In case pixels_n is larger than array_n the array_xy has to be continued at array_xy[0,1] after reaching its end (array_n).
Example:
Thus a line iterator behaviour can be specified by simply setting array_xy = {1,0}, for a advancement in x direction of one, array_n = 1, as we need just this type of advancement and pixels_n = image_width, for saying how often the pattern descibed in array_xy has to be applied.]

Handling of pixel access is to be supported by a filter in a function of type oyCMMFilter_GetNext_f() in oyCMMapi4_s::oyCMMConnector_GetNext().

Access to the buffers by concurrenting threads is handled by passing different oyPixelAccess_s objects per thread.

From the module point of view it is a requirement to obtain the intermediate buffers from somewhere. These are the ones to read from and to write computed results into.
Pixel in- and output buffers separation:

- Copy the output area and request to manipulate it by each filter. There is no overwriting of results. Reads a bit fixed. How can filters decide upon the input size? However, if a filter works on more than one dimension, it can opt to get its area directly from a input mediator. -[Provide a opaque output and input area and request to copy by each filter. Filters would overwrite previous manipulations or some mechanism of swapping the input with the output side is needed.]
- Some filters want different input and output areas. They see the mediator as the previous, or the input, element in the graph.
- Will the mediators always be visible in order to get all informations about the image? During setting up the graph this should be handled.

Access to input and output buffers:

- The output oyArray2d_s is to be reserved only.
- The input oyArray2d_s is to be provided for multi dimensional manipulators directly from the input mediator.

Thread synchronisation:

- The oyArray2d_s is a opaque memory blob. So different filters can act upon this resource. It would be in the resposiblity of the graph to avoid conflicts like using the same output for different manipulations. Given that the output is acting actively, the potential is small anyway.
- The input should be neutral and not directly manipulated. What can happen is that different threads request the same input area and the according data is to be rendered first. So this easily could end in rendering two times for the same result. Some scheduling in the mediators may help solving this and improove on performance.

Area dimensions:

- One point is very simple to provide. It may easily require additional preparations for area manipulations like blur.
- Line is the next hard. The advantage it is still simple and speed efficient. Programming is a bit more demanding.
- Areas of pixel are easy to provide through oyArray2d_s. It can include the above two cases.
- Pattern accessors are very flexible for manipulators. It's not clear how the resulting complexity of translating the pattern to a array with known pixel positions can be hidden from other filters, which need to know about positions. One strategy would be to use mediators. They can request the according pixels from previous filters. A function to convert the pattern to a list of positions should be provided. Very elegant, but probably better to do later after oyArray2d_s.

Possible strategies are (old text):

- Use mediators to convert between different pixel layouts and areas. These could cache the record of a successful query. Mediators are Nodes in the graph. As the graph and thus mediators can be accessed over concurrenting entries a cache tends to be expensive.
- The oyPixelAccess_s could hold caches instead of mediators. It is the structure, which is owned by a given thread anyway. oyPixelAccess_s needs two buffers one for input and one for output. As the graph is asked to provide the next pixel via a oyPixelAccess_s struct, this struct must be associated with source and destination buffers. The mediator on output has to search through the chain for the previous mediator and ask there for the input buffer. The ouput buffer is provided by this mediator itself. These two buffers are set as the actual ones for processing by the normal filters. It must be clear, what is a mediator, for this scheme to work. As a mediator is reached in the processing graph, its task is not only to convert between buffers but as well to update the oyPixelAccess_s struct with the next mediators and its own buffer. Thus the next inbetween filters can process on their part. One advantage is that the mediators can pass their buffers to oyPixelAccess_s, which are independent to threads and can be shared.
- Each filter obtains a buffer being asked to fill it with the pixels positions described in oyPixelAccess_s. A filter is free to create a new oyPixelAccess_s description and obtain for instance the surounding of the requested pixels. There is no caching to be expected other than in the oyPixelAccess_s own output buffer.

Todo:
  clear about pixel buffer copying, how to reach the buffers, thread synchronisation, simple or complex pixel areas (point, line, area, pattern )

     Relation of positional parameters:

                 start_xy relative to original image width
                    |
              +-----|------------------------------+
     original |     |                              |
     image ---+     |                              |
              |  ---+-----------------------+      |
              |     |                       +---------- output_array
              |     |   +---------------+   |      |
              |     |   |               |   |      |
              |     |   |               |   |      |
              |     |   +------+--------+   |      |
              |     |           \           |      |
              |     +------------\----------+      |
              |                   \                |
              +--------------------\---------------+
                                 output_array_roi relative to array width/channels

Rectangles are passed in relative units. start_xy and output_array_roi are of type oyRectangle_s and are defined in relative units to the enclosing images/array data width. start_xy::x 0.1 means 0.1 x original_image::width . output_roi::0.3333,0.0,0.333,0.333 in a array of data size 9x3 / 3 channels means the upper middle pixel.

Version
  Oyranos: 0.9.6

Date
  2016/09/15

Since
  2008/07/04 (Oyranos: 0.1.8)

Examples:
  oyranos_cmm_oJPG.c.

## Member Function Documentation

## ◆ oyPixelAccess_ArrayIsFocussed()

int oyPixelAccess_ArrayIsFocussed | ( | oyPixelAccess_s * | pixel_access | ) |

Tell if array has changed focus as of changed output_rectangle.

Function oyPixelAccess_ArrayIsFocussed

Parameters

  [in] | pixel_access | pixel iterator configuration

Returns
  0 - array needs focusing 1 - array has focus set from array_roi

Version
  Oyranos: 0.9.6

Date
  2016/09/14

Since
  2016/09/14 (Oyranos: 0.9.6)

Referenced by oyPixelAccess_SetArrayFocus(), and oyPixelAccess_Show().

## ◆ oyPixelAccess_ChangeRectangle()

int oyPixelAccess_ChangeRectangle | ( | oyPixelAccess_s * | pixel_access,
|  | double | start_x,
|  | double | start_y,
|  | oyRectangle_s * | output_rectangle
| ) |  |

Change the ticket for a conversion graph.

Function oyPixelAccess_ChangeRectangle

Parameters

  [in,out] | pixel_access | optional pixel iterator configuration
  [in] | start_x | x position relative to virtual source image
  [in] | start_y | y position relative to virtual source image
  [in] | output_rectangle | the region in the output image; optional

Returns
  0 on success, else error

The output_rectangle is absolute to oyPixelAccess_GetArray(). A passed in output_rectangle will call oyPixelAccess_SetArrayFocus( pixel_access(::array), undo=1 ).

Version
  Oyranos: 0.9.6

Date
  2016/09/26

Since
  2011/04/17 (Oyranos: 0.3.0)

References oyCHANS, oyImage_s::oyImage_GetPixelLayout(), oyImage_s::oyImage_GetWidth(), oyPixelAccess_SetArrayFocus(), and oyRectangle_s::oyRectangle_SetByRectangle().

## ◆ oyPixelAccess_Copy()

oyPixelAccess_Copy

Copy or Reference a PixelAccess object.

The function is for copying and for referencing. The reference is the most often used way, which saves resourcs and time.

Parameters

  [in] | pixelaccess | PixelAccess struct object
  | object | NULL - means reference, the optional object triggers a real copy

## ◆ oyPixelAccess_Create()

oyPixelAccess_s * oyPixelAccess_Create | ( | int32_t | start_x,
|  | int32_t | start_y,
|  | oyFilterPlug_s * | plug,
|  | oyPIXEL_ACCESS_TYPE_e | type,
|  | oyObject_s | object
| ) |  |

Allocate iand initialise a basic oyPixelAccess_s object.

Function oyPixelAccess_Create

// conversion->out_ has to be linear, so we access only the first plug
node = oyConversion_GetNode( conversion, OY_OUTPUT );
plug = oyFilterNode_GetPlug( node, 0 );
oyFilterNode_Release( &node );
// create a very simple pixel iterator
if(plug)
pixel_access = oyPixelAccess_Create( 0,0, plug,
oyPIXEL_ACCESS_IMAGE, 0 );

Version
  Oyranos: 0.1.10

Since
  2008/07/07 (Oyranos: 0.1.8)

Date
  2009/06/10

The filters have no obligation to pass end to end informations. The ticket must hold all pices of interesst.

Todo:
  how can we know about the various module capabilities
  - back report the processed number of pixels in the passed pointer
  - restrict for a line interface only, would fit to oyArray2d_s
  - + handle inside an to be created function oyConversion_RunPixels()

## ◆ oyPixelAccess_GetArray()

oyArray2d_s * oyPixelAccess_GetArray | ( | oyPixelAccess_s * | pixel_access | ) |

Access oyPixelAccess_s::array.

Function oyPixelAccess_GetArray

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

References oyArray2d_s::oyArray2d_Copy(), and oyOBJECT_PIXEL_ACCESS_S.

Referenced by oyPixelAccess_SetArrayFocus(), and oyPixelAccess_Show().

## ◆ oyPixelAccess_GetArrayROI()

oyRectangle_s * oyPixelAccess_GetArrayROI | ( | oyPixelAccess_s * | pixel_access | ) |

Access oyPixelAccess_s::output_array_roi.

Function oyPixelAccess_GetArrayROI

The rectangle unit is normalised to array::width/channels.

Version
  Oyranos: 0.9.6

Date
  2016/03/26

Since
  2012/09/06 (Oyranos: 0.5.0)

References oyOBJECT_PIXEL_ACCESS_S, and oyRectangle_s::oyRectangle_Copy().

Referenced by oyPixelAccess_Show().

## ◆ oyPixelAccess_GetGraph()

oyFilterGraph_s * oyPixelAccess_GetGraph | ( | oyPixelAccess_s * | pixel_access | ) |

Access oyPixelAccess_s::graph.

Function oyPixelAccess_GetGraph

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

References oyFilterGraph_s::oyFilterGraph_Copy(), and oyOBJECT_PIXEL_ACCESS_S.

## ◆ oyPixelAccess_GetOldStart()

double oyPixelAccess_GetOldStart | ( | oyPixelAccess_s * | pixel_access,
|  | int | vertical
| ) |  |

Access oyPixelAccess_s::start_xy_old.

Function oyPixelAccess_GetOldStart

Version
  Oyranos: 0.5.0

Date
  2012/09/10

Since
  2012/09/10 (Oyranos: 0.5.0)

References oyOBJECT_PIXEL_ACCESS_S.

## ◆ oyPixelAccess_GetOutputImage()

oyImage_s * oyPixelAccess_GetOutputImage | ( | oyPixelAccess_s * | pixel_access | ) |

Access oyPixelAccess_s::output_image.

Function oyPixelAccess_GetOutputImage

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

Examples:
  oyranos_cmm_oJPG.c.

References oyImage_s::oyImage_Copy(), and oyOBJECT_PIXEL_ACCESS_S.

Referenced by oyPixelAccess_SetArrayFocus(), oyPixelAccess_Show(), and oyPixelAccess_SynchroniseROI().

## ◆ oyPixelAccess_GetRequestQueue()

oyOptions_s * oyPixelAccess_GetRequestQueue | ( | oyPixelAccess_s * | pixel_access | ) |

Access oyPixelAccess_s::request_queue.

Function oyPixelAccess_GetRequestQueue

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

References oyOBJECT_PIXEL_ACCESS_S, and oyOptions_s::oyOptions_Copy().

## ◆ oyPixelAccess_GetStart()

double oyPixelAccess_GetStart | ( | oyPixelAccess_s * | pixel_access,
|  | int | vertical
| ) |  |

Access oyPixelAccess_s::start_xy.

Function oyPixelAccess_GetStart

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

References oyOBJECT_PIXEL_ACCESS_S.

Referenced by oyPixelAccess_Show(), and oyPixelAccess_SynchroniseROI().

## ◆ oyPixelAccess_GetUserData()

oyStruct_s * oyPixelAccess_GetUserData | ( | oyPixelAccess_s * | pixel_access | ) |

Access oyPixelAccess_s::user_data.

Function oyPixelAccess_GetUserData

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

References copy, and oyOBJECT_PIXEL_ACCESS_S.

## ◆ oyPixelAccess_GetWorkspaceID()

int32_t oyPixelAccess_GetWorkspaceID | ( | oyPixelAccess_s * | pixel_access | ) |

Access oyPixelAccess_s::workspace_id.

Function oyPixelAccess_GetWorkspaceID

A ID for distinct resources.

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

## ◆ oyPixelAccess_New()

OYAPI oyPixelAccess_s *OYEXPORT oyPixelAccess_New | ( | oyObject_s | object | ) |

allocate a new PixelAccess object

Function oyPixelAccess_New

References oyOBJECT_OBJECT_S.

## ◆ oyPixelAccess_PixelsToRoi()

int oyPixelAccess_PixelsToRoi | ( | oyPixelAccess_s * | pixel_access,
|  | oyRectangle_s * | pixel_rectangle,
|  | oyRectangle_s ** | roi
| ) |  |

Calculate ROI rectangle from pixel rectangle.

Function oyPixelAccess_PixelsToRoi

For obtaining the oyPixelAccess_s::output_array_roi see oyPixelAccess_GetArrayROI().

See also
  oyPixelAccess_RoiToPixels()

Parameters

  [in] | pixel_access | pixel iterator configuration
  [in] | pixel_rectangle | pixel rectangle; optional scale pixel_rectangle -> roi or use output_array_roi > 0 or fall back to scaled (array::data_area -> pixel) fall back to scaled output_image size
  [in,out] | roi | returns a rectangle with ROI

Returns
  error

Version
  Oyranos: 0.9.6

Date
  2016/09/27

Since
  2016/09/27 (Oyranos: 0.9.6)

References oyArray2d_s::oyArray2d_GetDataGeo1(), oyCHANS, oyImage_s::oyImage_GetHeight(), oyImage_s::oyImage_GetPixelLayout(), oyImage_s::oyImage_GetWidth(), oyOBJECT_PIXEL_ACCESS_S, oyRectangle_s::oyRectangle_CountPoints(), oyRectangle_s::oyRectangle_New(), oyRectangle_s::oyRectangle_Round(), oyRectangle_s::oyRectangle_Scale(), oyRectangle_s::oyRectangle_SetByRectangle(), oyRectangle_s::oyRectangle_SetGeo(), and type_.

Referenced by oyPixelAccess_SynchroniseROI().

## ◆ oyPixelAccess_Release()

OYAPI int OYEXPORT oyPixelAccess_Release | ( | oyPixelAccess_s ** | pixelaccess | ) |

release and possibly deallocate a oyPixelAccess_s object

Function oyPixelAccess_Release

Parameters

  [in,out] | pixelaccess | PixelAccess struct object

References oyOBJECT_PIXEL_ACCESS_S.

## ◆ oyPixelAccess_RoiToPixels()

int oyPixelAccess_RoiToPixels | ( | oyPixelAccess_s * | pixel_access,
|  | oyRectangle_s * | roi,
|  | oyRectangle_s ** | pixel_rectangle
| ) |  |

Calculate pixel rectangle from ROI.

Function oyPixelAccess_RoiToPixels

See also
  oyPixelAccess_PixelsToRoi()

Parameters

  [in] | pixel_access | pixel iterator configuration
  [in] | roi | alternative ROI in array::width/channels == 1.0 unit; optional, default: is pixel_access::output_array_roi
  [in,out] | pixel_rectangle | rectangle for pixel results in pixels

Returns
  error

Version
  Oyranos: 0.9.6

Date
  2016/09/27

Since
  2016/09/27 (Oyranos: 0.9.6)

References oyArray2d_s::oyArray2d_GetDataGeo1(), oyCHANS, oyImage_s::oyImage_GetHeight(), oyImage_s::oyImage_GetPixelLayout(), oyImage_s::oyImage_GetWidth(), oyOBJECT_PIXEL_ACCESS_S, oyRectangle_s::oyRectangle_CountPoints(), oyRectangle_s::oyRectangle_New(), oyRectangle_s::oyRectangle_Round(), oyRectangle_s::oyRectangle_Scale(), oyRectangle_s::oyRectangle_SetByRectangle(), oyRectangle_s::oyRectangle_SetGeo(), and type_.

Referenced by oyPixelAccess_SetArrayFocus(), and oyPixelAccess_SynchroniseROI().

## ◆ oyPixelAccess_SetArray()

int oyPixelAccess_SetArray | ( | oyPixelAccess_s * | pixel_access,
|  | oyArray2d_s * | array,
|  | int | has_roi_focus
| ) |  |

Set oyPixelAccess_s::array.

Function oyPixelAccess_SetArray

Parameters

  [in,out] | pixel_access | pixel iterator configuration; optional
  [in] | array | channel data
  [in] | has_roi_focus | 0 - the supplied array is not yet focused for the pixel_access::output_array_roi 1 - the array is already in focus for pixel_access::output_array_roi

Version
  Oyranos: 0.9.6

Date
  2016/10/01

Since
  2012/09/06 (Oyranos: 0.5.0)

References oyArray2d_s::oyArray2d_Copy(), oyArray2d_s::oyArray2d_GetDataGeo1(), oyArray2d_s::oyArray2d_Release(), oyCHANS, oyImage_s::oyImage_GetPixelLayout(), oyImage_s::oyImage_GetWidth(), oyOBJECT_PIXEL_ACCESS_S, oyPixelAccess_SetArrayFocus(), oyRectangle_s::oyRectangle_Round(), and oyRectangle_s::oyRectangle_Scale().

## ◆ oyPixelAccess_SetArrayFocus()

int oyPixelAccess_SetArrayFocus | ( | oyPixelAccess_s * | pixel_access,
|  | int | undo
| ) |  |

Ensure that the array is in output ROI focus.

Function oyPixelAccess_SetArrayFocus

The output_array_roi is a absolute rectangle. The unit is relative to a existing oyPixelAccess_GetArray() or to the output image. Undoing will change the oyPixelAccess_GetArray() back to it's data area (oyArray2d_GetDataGeo1()).

After calling this function the oyPixelAccess_GetArray() obtained array might be changed through oyArray2d_SetFocus().

Parameters

  [in,out] | pixel_access | pixel iterator configuration
  | undo | undo a previously possibly set focus

Returns
  0 - no action, -1 - focus changed, 1 - error

Version
  Oyranos: 0.9.6

Date
  2016/09/14

Since
  2016/03/14 (Oyranos: 0.9.6)

References oy_debug, oyArray2d_s::oyArray2d_SetFocus(), oyCHANS, oyImage_s::oyImage_GetPixelLayout(), oyImage_s::oyImage_PixelsToSamples(), oyOBJECT_RECTANGLE_S, oyPixelAccess_ArrayIsFocussed(), oyPixelAccess_GetArray(), oyPixelAccess_GetOutputImage(), oyPixelAccess_RoiToPixels(), and oyRectangle_s::oyRectangle_New().

Referenced by oyPixelAccess_ChangeRectangle(), and oyPixelAccess_SetArray().

## ◆ oyPixelAccess_SetOldStart()

int oyPixelAccess_SetOldStart | ( | oyPixelAccess_s * | pixel_access,
|  | int | vertical,
|  | double | start
| ) |  |

Access oyPixelAccess_s::start_xy_old.

Function oyPixelAccess_SetOldStart

Version
  Oyranos: 0.5.0

Date
  2012/09/10

Since
  2012/09/10 (Oyranos: 0.5.0)

References oyOBJECT_PIXEL_ACCESS_S.

## ◆ oyPixelAccess_SetOutputImage()

int oyPixelAccess_SetOutputImage | ( | oyPixelAccess_s * | pixel_access,
|  | oyImage_s * | image
| ) |  |

Set oyPixelAccess_s::output_image.

Function oyPixelAccess_SetOutputImage

Version
  Oyranos: 0.5.0

Date
  2012/10/04

Since
  2012/10/04 (Oyranos: 0.5.0)

References oyImage_s::oyImage_Copy(), oyImage_s::oyImage_Release(), and oyOBJECT_PIXEL_ACCESS_S.

## ◆ oyPixelAccess_SetUserData()

int oyPixelAccess_SetUserData | ( | oyPixelAccess_s * | pixel_access,
|  | oyStruct_s * | user_data
| ) |  |

Set oyPixelAccess_s::user_data.

Function oyPixelAccess_SetUserData

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

References oyStruct_s::copy, oyOBJECT_PIXEL_ACCESS_S, and release.

## ◆ oyPixelAccess_SetWorkspaceID()

int oyPixelAccess_SetWorkspaceID | ( | oyPixelAccess_s * | pixel_access,
|  | int32_t | workspace_id
| ) |  |

Set oyPixelAccess_s::workspace_id.

Function oyPixelAccess_SWorkspaceID

A ID for distinct resources.

Version
  Oyranos: 0.5.0

Date
  2012/09/06

Since
  2012/09/06 (Oyranos: 0.5.0)

## ◆ oyPixelAccess_Show()

const char * oyPixelAccess_Show | ( | oyPixelAccess_s * | pixel_access | ) |

Print ticket geometries.

Function oyPixelAccess_Show

This function is not thread safe.

Parameters

  [in] | pixel_access | pixel iterator configuration

Returns
  0 on success, else error

Version
  Oyranos: 0.9.6

Date
  2016/04/04

Since
  2016/04/04 (Oyranos: 0.9.6)

References oyArray2d_s::oyArray2d_GetDataGeo1(), oyImage_s::oyImage_GetPixelLayout(), oyImage_s::oyImage_GetWidth(), oyLAYOUT, oyOBJECT_RECTANGLE_S, oyPixelAccess_ArrayIsFocussed(), oyPixelAccess_GetArray(), oyPixelAccess_GetArrayROI(), oyPixelAccess_GetOutputImage(), oyPixelAccess_GetStart(), oyRectangle_s::oyRectangle_Scale(), oyRectangle_s::oyRectangle_SetByRectangle(), and oyToChannels_m.

## ◆ oyPixelAccess_SynchroniseROI()

int oyPixelAccess_SynchroniseROI | ( | oyPixelAccess_s * | pixel_access_new,
|  | oyPixelAccess_s * | pixel_access_src
| ) |  |

Set a new ticket according to old ticket geometries.

Function oyPixelAccess_SynchroniseROI

After a new ticket is generated, the old geometries might become invalid, as channel counts change or the array sizes becomes different. This function convinently changes the ROI and start_xy dimensions after such critical changes.

Parameters

  [in,out] | pixel_access_new | to be modified pixel iterator configuration
  [in] | pixel_access_src | pixel iterator configuration pattern

Returns
  0 on success, else error

Version
  Oyranos: 0.9.6

Date
  2016/10/03

Since
  2016/03/29 (Oyranos: 0.9.6)

References oy_debug, oyImage_s::oyImage_GetWidth(), oyPixelAccess_GetOutputImage(), oyPixelAccess_GetStart(), oyPixelAccess_PixelsToRoi(), and oyPixelAccess_RoiToPixels().

## Field Documentation

## ◆ copy

oyStruct_Copy_f oyPixelAccess_s::copy

Copy function.

Referenced by oyPixelAccess_GetUserData().

## ◆ oy_

oyObject_s oyPixelAccess_s::oy_

Oyranos internal object.

Features name and hash. Do not change during object life time.

## ◆ release

oyStruct_Release_f oyPixelAccess_s::release

Release function.

Referenced by oyPixelAccess_SetUserData().

## ◆ type_

const oyOBJECT_e oyPixelAccess_s::type_

Type of object.

The struct type tells Oyranos how to interprete hidden fields.

Referenced by oyPixelAccess_PixelsToRoi(), and oyPixelAccess_RoiToPixels().