Oyranos Color Management System API
Public Member Functions | Data Fields
oyPixelAccess_s Struct Reference

Control pixel access order. More...

#include <oyPixelAccess_s.h>

Inheritance diagram for oyPixelAccess_s:
Inheritance graph
Collaboration diagram for oyPixelAccess_s:
Collaboration graph

Public Member Functions

OYAPI oyPixelAccess_s *OYEXPORT oyPixelAccess_New (oyObject_s object)
 allocate a new PixelAccess object More...
 
OYAPI oyPixelAccess_s *OYEXPORT oyPixelAccess_Copy (oyPixelAccess_s *pixelaccess, oyObject_s object)
 copy or reference a PixelAccess object More...
 
OYAPI int OYEXPORT oyPixelAccess_Release (oyPixelAccess_s **pixelaccess)
 release and possibly deallocate a oyPixelAccess_s object More...
 
oyPixelAccess_soyPixelAccess_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_soyPixelAccess_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...
 
oyRectangle_soyPixelAccess_GetOutputROI (oyPixelAccess_s *pixel_access)
 Access oyPixelAccess_s::output_image_roi. More...
 
oyFilterGraph_soyPixelAccess_GetGraph (oyPixelAccess_s *pixel_access)
 Access oyPixelAccess_s::graph. More...
 
oyOptions_soyPixelAccess_GetRequestQueue (oyPixelAccess_s *pixel_access)
 Access oyPixelAccess_s::request_queue. More...
 
oyArray2d_soyPixelAccess_GetArray (oyPixelAccess_s *pixel_access)
 Access oyPixelAccess_s::array. More...
 
int oyPixelAccess_SetArray (oyPixelAccess_s *pixel_access, oyArray2d_s *array)
 Set oyPixelAccess_s::array. More...
 
oyStruct_soyPixelAccess_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...
 

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:

Access to input and output buffers:

Thread synchronisation:

Area dimensions:

Possible strategies are (old text):

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         output_image_roi
                |                /
          +-----|---------------/--------------+
 original |     |              /               |
 image ---+     |             /                |
          |  ---+------------/----------+      |
          |     |           /           +---------- output_image
          |     |   +------+--------+   |      |
          |     |   |               |   |      |
          |     |   |               |   |      |
          |     |   +---------------+   |      |
          |     |                       |      |
          |     +-----------------------+      |
          |                                    |
          +------------------------------------+
Version
Oyranos: 0.1.10
Since
2008/07/04 (Oyranos: 0.1.8)
Date
2009/05/05

Member Function Documentation

◆ oyPixelAccess_Copy()

OYAPI oyPixelAccess_s *OYEXPORT oyPixelAccess_Copy ( oyPixelAccess_s pixelaccess,
oyObject_s  object 
)

copy or reference a PixelAccess object

Function oyPixelAccess_Copy

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

Parameters
[in]pixelaccessPixelAccess struct object
objectNULL - means reference, the optional object triggers a real copy

References oyOBJECT_PIXEL_ACCESS_S.

◆ 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()

References oyFilterGraph_s::oy_, oyBOOLEAN_INTERSECTION, oyFilterGraph_s::oyFilterGraph_FromNode(), oyImage_s::oyImage_Copy(), oyImage_s::oyImage_GetHeight(), oyImage_s::oyImage_GetWidth(), oyOptions_s::oyOptions_Filter(), oyPIXEL_ACCESS_LINE, oyPIXEL_ACCESS_POINT, oyPixelAccess_New(), and oyPixelAccess_Release().

◆ 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.

◆ 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)

References oyImage_s::oyImage_Copy(), and oyOBJECT_PIXEL_ACCESS_S.

◆ oyPixelAccess_GetOutputROI()

oyRectangle_s * oyPixelAccess_GetOutputROI ( oyPixelAccess_s pixel_access)

Access oyPixelAccess_s::output_image_roi.

Function oyPixelAccess_GetOutputROI

Version
Oyranos: 0.5.0
Date
2012/09/06
Since
2012/09/06 (Oyranos: 0.5.0)

References oyOBJECT_PIXEL_ACCESS_S, and oyRectangle_s::oyRectangle_Copy().

◆ 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.

◆ 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)

References oyOBJECT_PIXEL_ACCESS_S.

◆ oyPixelAccess_New()

OYAPI oyPixelAccess_s *OYEXPORT oyPixelAccess_New ( oyObject_s  object)

allocate a new PixelAccess object

Function oyPixelAccess_New

References oyOBJECT_OBJECT_S.

Referenced by oyPixelAccess_Create().

◆ oyPixelAccess_Release()

OYAPI int OYEXPORT oyPixelAccess_Release ( oyPixelAccess_s **  pixelaccess)

release and possibly deallocate a oyPixelAccess_s object

Function oyPixelAccess_Release

Parameters
[in,out]pixelaccessPixelAccess struct object

References oyOBJECT_PIXEL_ACCESS_S.

Referenced by oyPixelAccess_Create().

◆ oyPixelAccess_SetArray()

int oyPixelAccess_SetArray ( oyPixelAccess_s pixel_access,
oyArray2d_s array 
)

Set oyPixelAccess_s::array.

Function oyPixelAccess_SetArray

Version
Oyranos: 0.5.0
Date
2012/09/06
Since
2012/09/06 (Oyranos: 0.5.0)

References oyArray2d_s::oyArray2d_Copy(), oyArray2d_s::oyArray2d_Release(), and oyOBJECT_PIXEL_ACCESS_S.

◆ 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, and oyOBJECT_PIXEL_ACCESS_S.

◆ 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)

References oyOBJECT_PIXEL_ACCESS_S.

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.

◆ type_

const oyOBJECT_e oyPixelAccess_s::type_

Type of object.

The struct type tells Oyranos how to interprete hidden fields.